[Pcsclite-cvs-commit] r4473 - /trunk/PCSC/src/PCSC/ifdhandler.h
rousseau at users.alioth.debian.org
rousseau at users.alioth.debian.org
Fri Oct 9 13:35:44 UTC 2009
Author: rousseau
Date: Fri Oct 9 13:35:44 2009
New Revision: 4473
URL: http://svn.debian.org/wsvn/pcsclite/?sc=1&rev=4473
Log:
Add Doxygen documentation of the IFD Handler API
Modified:
trunk/PCSC/src/PCSC/ifdhandler.h
Modified: trunk/PCSC/src/PCSC/ifdhandler.h
URL: http://svn.debian.org/wsvn/pcsclite/trunk/PCSC/src/PCSC/ifdhandler.h?rev=4473&op=diff
==============================================================================
--- trunk/PCSC/src/PCSC/ifdhandler.h (original)
+++ trunk/PCSC/src/PCSC/ifdhandler.h Fri Oct 9 13:35:44 2009
@@ -11,6 +11,210 @@
/**
* @file
* @brief This provides reader specific low-level calls.
+
+The routines specified hereafter will allow you to write an IFD handler
+for the PC/SC Lite resource manager. Please use the complement
+developer's kit complete with headers and Makefile at:
+http://www.musclecard.com/drivers.html.
+
+This gives a common API for communication to most readers in a
+homogeneous fashion. This document assumes that the driver developer is
+experienced with standards such as ISO-7816-(1, 2, 3, 4), EMV and MCT
+specifications. For listings of these specifications please access the
+above web site.
+
+ at section UsbReaders USB readers
+
+USB readers use the bundle approach so that the reader can be loaded
+and unloaded upon automatic detection of the device. The bundle
+approach is simple: the actual library is just embedded in a
+directory so additional information can be gathered about the device.
+
+A bundle looks like the following:
+
+ at verbatim
+GenericReader.bundle/
+ Contents/
+ Info.plist - XML file describing the reader
+ MacOS/ - Driver directory for OS X
+ Solaris/ - Driver directory for Solaris
+ Linux/ - Driver directory for Linux
+ HPUX/ - Driver directory for HPUX
+ at endverbatim
+
+The @c Info.plist file describes the driver and gives the loader
+all the necessary information. The following must be contained in the
+ at c Info.plist file:
+
+ at subsection ifdVendorID
+
+The vendor ID of the USB device.
+
+Example:
+
+ at verbatim
+ <key>ifdVendorID</key>
+ <string>0x04E6</string>
+ at endverbatim
+
+You may have an OEM of this reader in which an additional @c <string>
+can be used like in the below example:
+
+ at verbatim
+ <key>ifdVendorID</key>
+ <array>
+ <string>0x04E6</string>
+ <string>0x0973</string>
+ </array>
+ at endverbatim
+
+If multiples exist all the other parameters must have a second value
+also. You may chose not to support this feature but it is useful when
+reader vendors OEM products so you only distribute one driver.
+
+
+The CCID driver from Ludovic Rousseau
+http://pcsclite.alioth.debian.org/ccid.html uses this feature since the
+same driver supports many different readers.
+
+ at subsection ifdProductID
+
+ The product id of the USB device.
+
+ at verbatim
+ <key>ifdProductID</key>
+ <string>0x3437</string>
+ at endverbatim
+
+ at subsection ifdFriendlyName
+
+ Example:
+
+ at verbatim
+ <key>ifdFriendlyName</key>
+ <string>SCM Microsystems USB Reader</string>
+ at endverbatim
+
+ at subsection CFBundleExecutable
+
+ The executable name which exists in the particular platform's directory.
+
+ Example:
+
+ at verbatim
+ <key>CFBundleExecutable</key>
+ <string>libccid.so.0.4.2</string>
+ at endverbatim
+
+ at subsection ifdCapabilities
+
+ List of capabilities supported by the driver. This is a bit field. Possible values are:
+
+- 0
+ No special capabilities
+- 1 IFD_GENERATE_HOTPLUG
+ The driver supports the hot plug feature.
+
+Complete sample file:
+
+ at verbatim
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
+ "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+ <key>CFBundleDevelopmentRegion</key>
+ <string>English</string>
+ <key>CFBundleInfoDictionaryVersion</key>
+ <string>6.0</string>
+ <key>CFBundlePackageType</key>
+ <string>BNDL</string>
+ <key>CFBundleSignature</key>
+ <string>????</string>
+ <key>CFBundleVersion</key>
+ <string>0.0.1d1</string>
+ <key>ifdCapabilities</key>
+ <string>0x00000000</string>
+ <key>ifdProtocolSupport</key>
+ <string>0x00000001</string>
+ <key>ifdVersionNumber</key>
+ <string>0x00000001</string>
+
+ <key>CFBundleExecutable</key>
+ <string>libfoobar.so.x.y</string>
+
+ <key>ifdManufacturerString</key>
+ <string>Foo bar inc.</string>
+
+ <key>ifdProductString</key>
+ <string>Driver for Foobar reader, version x.y</string>
+
+ <key>ifdVendorID</key>
+ <string>0x1234</string>
+
+ <key>ifdProductID</key>
+ <string>0x5678</string>
+
+ <key>ifdFriendlyName</key>
+ <string>Foobar USB reader</string>
+</dict>
+</plist>
+ at endverbatim
+
+As indicated in the XML file the DTD is available at
+http://www.apple.com/DTDs/PropertyList-1.0.dtd.
+
+ at section SerialReaders Serial readers
+
+Serial drivers must be configured to operate on a particular port and
+respond to a particular name. The @c reader.conf file is used for this
+purpose.
+
+It has the following syntax:
+
+ at verbatim
+# Configuration file for pcsc-lite
+# David Corcoran <corcoran at musclecard.com>
+
+FRIENDLYNAME Generic Reader
+DEVICENAME /dev/ttyS0
+LIBPATH /usr/lib/pcsc/drivers/libgen_ifd.so
+CHANNELID 1
+ at endverbatim
+
+The pound sign # denotes a comment.
+
+ at subsection FRIENDLYNAME
+The FRIENDLYNAME field is an arbitrary text used to identify the reader.
+This text is displayed by commands like @c pcsc_scan
+http://ludovic.rousseau.free.fr/softwares/pcsc-tools/ that prints the
+names of all the connected and detected readers.
+
+ at subsection DEVICENAME
+The DEVICENAME field was not used for old drivers (using the IFD handler
+version 2.0 or previous). It is now (IFD handler version 3.0) used to
+identify the physical port on which the reader is connected. This is
+the device name of this port. It is dependent of the OS kernel. For
+example the first serial port device is called @c /dev/ttyS0 under Linux
+and @c /dev/cuaa0 under FreeBSD.
+
+ at subsection LIBPATH
+The LIBPATH field is the filename of the driver code. The driver is a
+dynamically loaded piece of code (generally a @c drivername.so* file).
+
+ at subsection CHANNELID
+The CHANNELID is no more used for recent drivers (IFD handler 3.0) and
+has been superseded by DEVICENAME. If you have an old driver this field
+is used to indicate the port to use. You should read your driver
+documentation to know what information is needed here. It should be the
+serial port number for a serial reader.
+
+ at subsection CHANNELID
+CHANNELID was the numeric version of the port in which the reader will
+be located. This may be done by a symbolic link where @c /dev/pcsc/1 is
+the first device which may be a symbolic link to @c /dev/ttyS0 or
+whichever location your reader resides.
+
*/
#ifndef _ifd_handler_h_
@@ -26,7 +230,6 @@
/*
* List of data structures available to ifdhandler
*/
-
typedef struct _DEVICE_CAPABILITIES
{
LPSTR Vendor_Name; /**< Tag 0x0100 */
@@ -75,6 +278,9 @@
}
PROTOCOL_OPTIONS, *PPROTOCOL_OPTIONS;
+ /**
+ * Use by SCardTransmit()
+ */
typedef struct _SCARD_IO_HEADER
{
DWORD Protocol;
@@ -83,26 +289,17 @@
SCARD_IO_HEADER, *PSCARD_IO_HEADER;
/*
- * End of structure list
- */
-
- /*
* The list of tags should be alot more but this is all I use in the
* meantime
*/
-
-#define TAG_IFD_ATR 0x0303
-#define TAG_IFD_SLOTNUM 0x0180
-#define TAG_IFD_SLOT_THREAD_SAFE 0x0FAC
-#define TAG_IFD_THREAD_SAFE 0x0FAD
-#define TAG_IFD_SLOTS_NUMBER 0x0FAE
-#define TAG_IFD_SIMULTANEOUS_ACCESS 0x0FAF
-#define TAG_IFD_POLLING_THREAD 0x0FB0
-#define TAG_IFD_POLLING_THREAD_KILLABLE 0x0FB1
-
- /*
- * End of tag list
- */
+#define TAG_IFD_ATR 0x0303 /**< ATR */
+#define TAG_IFD_SLOTNUM 0x0180 /**< select a slot */
+#define TAG_IFD_SLOT_THREAD_SAFE 0x0FAC /**< support access to different slots of the reader */
+#define TAG_IFD_THREAD_SAFE 0x0FAD /**< driver is thread safe */
+#define TAG_IFD_SLOTS_NUMBER 0x0FAE /**< number of slots of the reader */
+#define TAG_IFD_SIMULTANEOUS_ACCESS 0x0FAF /**< number of reader the driver can manage */
+#define TAG_IFD_POLLING_THREAD 0x0FB0 /**< driver uses a polling thread */
+#define TAG_IFD_POLLING_THREAD_KILLABLE 0x0FB1 /**< the polling thread can be killed */
/*
* IFD Handler version number enummerations
@@ -110,48 +307,49 @@
#define IFD_HVERSION_1_0 0x00010000
#define IFD_HVERSION_2_0 0x00020000
#define IFD_HVERSION_3_0 0x00030000
- /*
- * End of version number enummerations
- */
/*
* List of defines available to ifdhandler
*/
-
-#define IFD_POWER_UP 500
-#define IFD_POWER_DOWN 501
-#define IFD_RESET 502
-
-#define IFD_NEGOTIATE_PTS1 1
-#define IFD_NEGOTIATE_PTS2 2
-#define IFD_NEGOTIATE_PTS3 4
-
-#define IFD_SUCCESS 0
-#define IFD_ERROR_TAG 600
-#define IFD_ERROR_SET_FAILURE 601
-#define IFD_ERROR_VALUE_READ_ONLY 602
-#define IFD_ERROR_PTS_FAILURE 605
+#define IFD_POWER_UP 500 /**< power up the card */
+#define IFD_POWER_DOWN 501 /**< power down the card */
+#define IFD_RESET 502 /**< warm reset */
+
+#define IFD_NEGOTIATE_PTS1 1 /**< negotiate PTS1 */
+#define IFD_NEGOTIATE_PTS2 2 /**< negotiate PTS2 */
+#define IFD_NEGOTIATE_PTS3 4 /**< negotiate PTS3 */
+
+#define IFD_SUCCESS 0 /**< no error */
+#define IFD_ERROR_TAG 600 /**< tag unknown */
+#define IFD_ERROR_SET_FAILURE 601 /**< set failed */
+#define IFD_ERROR_VALUE_READ_ONLY 602 /**< value is read only */
+#define IFD_ERROR_PTS_FAILURE 605 /**< failed to negotiate PTS */
#define IFD_ERROR_NOT_SUPPORTED 606
-#define IFD_PROTOCOL_NOT_SUPPORTED 607
-#define IFD_ERROR_POWER_ACTION 608
+#define IFD_PROTOCOL_NOT_SUPPORTED 607 /**< requested protocol not supported */
+#define IFD_ERROR_POWER_ACTION 608 /**< power up failed */
#define IFD_ERROR_SWALLOW 609
#define IFD_ERROR_EJECT 610
#define IFD_ERROR_CONFISCATE 611
-#define IFD_COMMUNICATION_ERROR 612
-#define IFD_RESPONSE_TIMEOUT 613
-#define IFD_NOT_SUPPORTED 614
-#define IFD_ICC_PRESENT 615
-#define IFD_ICC_NOT_PRESENT 616
+#define IFD_COMMUNICATION_ERROR 612 /**< generic error */
+#define IFD_RESPONSE_TIMEOUT 613 /**< timeout */
+#define IFD_NOT_SUPPORTED 614 /**< request is not supported */
+#define IFD_ICC_PRESENT 615 /**< card is present */
+#define IFD_ICC_NOT_PRESENT 616 /**< card is absent */
+/**
+ * The \ref IFD_NO_SUCH_DEVICE error must be returned by the driver when
+ * it detects the reader is no more present. This will tell pcscd to
+ * remove the reader from the list of available readers.
+ */
#define IFD_NO_SUCH_DEVICE 617
-#define IFD_ERROR_INSUFFICIENT_BUFFER 618
+#define IFD_ERROR_INSUFFICIENT_BUFFER 618 /**< buffer is too small */
#ifndef RESPONSECODE_DEFINED_IN_WINTYPES_H
typedef long RESPONSECODE;
#endif
/*
- * If you want to compile a V2.0 IFDHandler, define IFDHANDLERv2 before you
- * include this file.
+ * If you want to compile a V2.0 IFDHandler, define IFDHANDLERv2
+ * before you include this file.
*
* By default it is setup for for most recent version of the API (V3.0)
*/
@@ -166,32 +364,405 @@
* IFDHControl() API changed
*/
- RESPONSECODE IFDHCreateChannelByName(DWORD, LPSTR);
- RESPONSECODE IFDHControl(DWORD, DWORD, PUCHAR, DWORD, PUCHAR,
- DWORD, LPDWORD);
+/**
+This function is required to open a communications channel to the port
+listed by @p DeviceName.
+
+Once the channel is opened the reader must be in a state in which it is
+possible to query IFDHICCPresence() for card status.
+
+ at param[in] Lun Logical Unit Number\n
+ Use this for multiple card slots or multiple readers. 0xXXXXYYYY -
+ XXXX multiple readers, YYYY multiple slots. The resource manager will
+ set these automatically. By default the resource manager loads a new
+ instance of the driver so if your reader does not have more than one
+ smart card slot then ignore the Lun in all the functions.\n
+ \n
+ PC/SC supports the loading of multiple readers through one instance of
+ the driver in which XXXX is important. XXXX identifies the unique
+ reader in which the driver communicates to. The driver should set up
+ an array of structures that asociate this XXXX with the underlying
+ details of the particular reader.
+
+ at param[in] DeviceName Filename to use by the driver.\n
+ For drivers configured by @p /etc/reader.conf this is the value of the
+ field \ref DEVICENAME.
+ \n
+ For USB drivers the @p DeviceName must start with @p usb:VID/PID. VID
+ is the Vendor ID and PID is the Product ID. Both are a 4-digits hex
+ number.
+
+Typically the string is generated by:
+
+ at code
+printf("usb:%04x/%04x", idVendor, idProduct);
+ at endcode
+
+The @p DeviceName string may also contain a more specialised
+identification string. This additional information is used to
+differentiate between two identical readers connected at the same time.
+In this case the driver can't differentiate the two readers using VID
+and PID and must use some additional information identifying the USB
+port used by each reader.
+
+- libusb
+
+ For USB drivers using libusb http://libusb.sourceforge.net/ for USB
+ abstraction the @p DeviceName the string may be generated by:
+
+ @code
+ printf("usb:%04x/%04x:libusb:%s:%s",
+ idVendor, idProduct,
+ bus->dirname, dev->filename)
+ @endcode
+
+ So it is something like: <tt>usb:08e6/3437:libusb:001:042</tt> under
+ GNU/Linux.
+
+- libhal
+
+ If pcscd is compiled with libhal support instead of libusb (default
+ since pcsc-lite 1.4.100) the string will look like:
+
+ @code
+ printf("usb:%04x/%04x:libhal:%s", idVendor, idProduct, udi)
+ @endcode
+
+ udi is the Universal Device Id at the HAL level.
+
+ So it is something like:
+ <tt>usb:08e6/3437:libhal:/org/freedesktop/Hal/devices/usb_device_8e6_3437_noserial_if0</tt>
+ under GNU/Linux.
+
+- other
+
+ If the driver does not understand the <tt>:libusb:</tt> or
+ <tt>:libhal:</tt> scheme or if a new scheme is used, the driver should
+ ignore the part it does not understand instead of failing.
+
+ The driver shall recognize the <tt>usb:VID/PID</tt> part and, only if
+ possible, the remaining of the DeviceName field.
+
+ It is the responsibility of the driver to correctly identify the reader.
+
+ at return Error codes
+ at retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
+ at retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
+ at retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
+ */
+RESPONSECODE IFDHCreateChannelByName(DWORD Lun, LPSTR DeviceName);
+
+/**
+This function performs a data exchange with the reader (not the card)
+specified by Lun. It is responsible for abstracting functionality such
+as PIN pads, biometrics, LCD panels, etc. You should follow the MCT and
+CTBCS specifications for a list of accepted commands to implement. This
+function is fully voluntary and does not have to be implemented unless
+you want extended functionality.
+
+ at param[in] Lun Logical Unit Number
+ at param[in] dwControlCode Control code for the operation\n
+ This value identifies the specific operation to be performed. This
+ value is driver specific.
+ at param[in] TxBuffer Transmit data
+ at param[in] TxLength Length of this buffer
+ at param[out] RxBuffer Receive data
+ at param[in] RxLength Length of the response buffer
+ at param[out] pdwBytesReturned Length of response\n
+ This function will be passed the length of the buffer RxBuffer in
+ RxLength and it must set the length of the received data in
+ pdwBytesReturned.
+
+ at note
+ @p *pdwBytesReturned should be set to zero on error.
+
+ at return Error codes
+ at retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
+ at retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
+ at retval IFD_RESPONSE_TIMEOUT The response timed out (\ref IFD_RESPONSE_TIMEOUT)
+ at retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
+ */
+RESPONSECODE IFDHControl(DWORD Lun, DWORD dwControlCode, PUCHAR
+ TxBuffer, DWORD TxLength, PUCHAR RxBuffer, DWORD RxLength,
+ LPDWORD pdwBytesReturned);
+
#else
- /*
- * List of Defined Functions Available to IFD_Handler 2.0
- */
-
- RESPONSECODE IFDHControl(DWORD, PUCHAR, DWORD, PUCHAR, PDWORD);
+/**
+ * Available in IFD_Handler 2.0
+ *
+ * @deprecated
+ * You should use the new form of IFDHControl()
+ */
+RESPONSECODE IFDHControl(DWORD Lun, PUCHAR TxBuffer, DWORD TxLength,
+ PUCHAR RxBuffer, PDWORD RxLength);
#endif
/*
* common functions in IFD_Handler 2.0 and 3.0
*/
- RESPONSECODE IFDHCreateChannel(DWORD, DWORD);
- RESPONSECODE IFDHCloseChannel(DWORD);
- RESPONSECODE IFDHGetCapabilities(DWORD, DWORD, PDWORD, PUCHAR);
- RESPONSECODE IFDHSetCapabilities(DWORD, DWORD, DWORD, PUCHAR);
- RESPONSECODE IFDHSetProtocolParameters(DWORD, DWORD, UCHAR,
- UCHAR, UCHAR, UCHAR);
- RESPONSECODE IFDHPowerICC(DWORD, DWORD, PUCHAR, PDWORD);
- RESPONSECODE IFDHTransmitToICC(DWORD, SCARD_IO_HEADER, PUCHAR,
- DWORD, PUCHAR, PDWORD, PSCARD_IO_HEADER);
- RESPONSECODE IFDHICCPresence(DWORD);
+/**
+This function is required to open a communications channel to the port
+listed by Channel. For example, the first serial reader on COM1 would
+link to @p /dev/pcsc/1 which would be a symbolic link to @p /dev/ttyS0
+on some machines This is used to help with inter-machine independence.
+
+On machines with no /dev directory the driver writer may choose to map
+their Channel to whatever they feel is appropriate.
+
+Once the channel is opened the reader must be in a state in which it is
+possible to query IFDHICCPresence() for card status.
+
+USB readers can ignore the @p Channel parameter and query the USB bus
+for the particular reader by manufacturer and product id.
+
+ at param[in] Lun Logical Unit Number\n
+ Use this for multiple card slots or multiple readers. 0xXXXXYYYY -
+ XXXX multiple readers, YYYY multiple slots. The resource manager will
+ set these automatically. By default the resource manager loads a new
+ instance of the driver so if your reader does not have more than one
+ smart card slot then ignore the Lun in all the functions.\n
+ \n
+ PC/SC supports the loading of multiple readers through one instance of
+ the driver in which XXXX is important. XXXX identifies the unique
+ reader in which the driver communicates to. The driver should set up
+ an array of structures that associate this XXXX with the underlying
+ details of the particular reader.
+ at param[in] Channel Channel ID
+ This is denoted by the following:
+ - 0x000001 @p /dev/pcsc/1
+ - 0x000002 @p /dev/pcsc/2
+ - 0x000003 @p /dev/pcsc/3
+ - 0x000004 @p /dev/pcsc/4
+
+ at return Error codes
+ at retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
+ at retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
+ at retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
+
+ */
+RESPONSECODE IFDHCreateChannel(DWORD Lun, DWORD Channel);
+
+/**
+This function should close the reader communication channel for the
+particular reader. Prior to closing the communication channel the reader
+should make sure the card is powered down and the terminal is also
+powered down.
+
+ at param[in] Lun Logical Unit Number
+
+ at return Error codes
+ at retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
+ at retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
+ at retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
+ */
+RESPONSECODE IFDHCloseChannel(DWORD Lun);
+
+/**
+This function should get the slot/card capabilities for a particular
+slot/card specified by Lun. Again, if you have only 1 card slot and
+don't mind loading a new driver for each reader then ignore Lun.
+
+ at param[in] Lun Logical Unit Number
+ at param[in] Tag Tag of the desired data value
+- \ref TAG_IFD_ATR
+ Return the ATR and its size (implementation is mandatory).
+- \ref SCARD_ATTR_ATR_STRING
+ Same as \ref TAG_IFD_ATR but this one is not mandatory. It is defined
+ in Microsoft PC/SC SCardGetAttrib().
+- \ref TAG_IFD_SIMULTANEOUS_ACCESS
+ Return the number of sessions (readers) the driver can handle in
+ <tt>Value[0]</tt>.
+ This is used for multiple readers sharing the same driver.
+- \ref TAG_IFD_THREAD_SAFE
+ If the driver supports more than one reader (see
+ \ref TAG_IFD_SIMULTANEOUS_ACCESS above) this tag indicates if the
+ driver supports access to multiple readers at the same time.\n
+ <tt>Value[0] = 1</tt> indicates the driver supports simultaneous accesses.
+- \ref TAG_IFD_SLOTS_NUMBER
+ Return the number of slots in this reader in <tt>Value[0]</tt>.
+- \ref TAG_IFD_SLOT_THREAD_SAFE
+ If the reader has more than one slot (see \ref TAG_IFD_SLOTS_NUMBER
+ above) this tag indicates if the driver supports access to multiple
+ slots of the same reader at the same time.\n
+ <tt>Value[0] = 1</tt> indicates the driver supports simultaneous slot
+ accesses.
+- \ref TAG_IFD_POLLING_THREAD
+ If the driver provide a polling thread then @p Value is a pointer to this function
+- \ref TAG_IFD_POLLING_THREAD_KILLABLE
+ Tell if the polling thread can be killed (SYS_ThreadCancel()) by pcscd
+ at param[in,out] Length Length of the desired data value
+ at param[out] Value Value of the desired data
+
+ at return Error codes
+ at retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
+ at retval IFD_ERROR_TAG Invalid tag given (\ref IFD_ERROR_TAG)
+ at retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
+ */
+RESPONSECODE IFDHGetCapabilities(DWORD Lun, DWORD Tag, PDWORD Length,
+ PUCHAR Value);
+
+/**
+This function should set the slot/card capabilities for a particular
+slot/card specified by @p Lun. Again, if you have only 1 card slot and
+don't mind loading a new driver for each reader then ignore @p Lun.
+
+ at param[in] Lun Logical Unit Number
+ at param[in] Tag Tag of the desired data value
+- \ref TAG_IFD_SLOTNUM
+ This is used in IFDHandler v1.0 to select the slot to use for the next
+ IFD_* command. This tag is no more used with versions 2.0 and 3.0 of
+ the IFD Handler.
+ at param[in,out] Length Length of the desired data value
+ at param[out] Value Value of the desired data
+
+This function is also called when the application uses the PC/SC
+SCardGetAttrib() function. The list of supported tags is not limited.
+
+ at return Error codes
+ at retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
+ at retval IFD_ERROR_TAG Invalid tag given (\ref IFD_ERROR_TAG)
+ at retval IFD_ERROR_SET_FAILURE Could not set value (\ref IFD_ERROR_SET_FAILURE)
+ at retval IFD_ERROR_VALUE_READ_ONLY Trying to set read only value (\ref IFD_ERROR_VALUE_READ_ONLY)
+ at retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
+ */
+RESPONSECODE IFDHSetCapabilities(DWORD Lun, DWORD Tag, DWORD Length, PUCHAR Value);
+
+/**
+This function should set the Protocol Type Selection (PTS) of a
+particular card/slot using the three PTS parameters sent
+
+ at param[in] Lun Logical Unit Number
+ at param[in] Protocol Desired protocol
+- \ref SCARD_PROTOCOL_T0
+ T=0 protocol
+- \ref SCARD_PROTOCOL_T1
+ T=1 protocol
+ at param[in] Flags Logical OR of possible values to determine which PTS values
+to negotiate
+- \ref IFD_NEGOTIATE_PTS1
+- \ref IFD_NEGOTIATE_PTS2
+- \ref IFD_NEGOTIATE_PTS3
+ at param[in] PTS1 1st PTS Value
+ at param[in] PTS2 2nd PTS Value
+ at param[in] PTS3 3rd PTS Value\n
+ See ISO 7816/EMV documentation.
+
+ at return Error codes
+ at retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
+ at retval IFD_ERROR_PTS_FAILURE Could not set PTS value (\ref IFD_ERROR_PTS_FAILURE)
+ at retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
+ at retval IFD_PROTOCOL_NOT_SUPPORTED Protocol is not supported (\ref IFD_PROTOCOL_NOT_SUPPORTED)
+ at retval IFD_NOT_SUPPORTED Action not supported (\ref IFD_NOT_SUPPORTED)
+ at retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
+ */
+RESPONSECODE IFDHSetProtocolParameters(DWORD Lun, DWORD Protocol, UCHAR Flags,
+ UCHAR PTS1, UCHAR PTS2, UCHAR PTS3);
+/**
+This function controls the power and reset signals of the smart card
+reader at the particular reader/slot specified by @p Lun.
+
+ at param[in] Lun Logical Unit Number
+ at param[in] Action Action to be taken on the card
+- \ref IFD_POWER_UP
+ Power up the card (store and return Atr and AtrLength)
+- \ref IFD_POWER_DOWN
+ Power down the card (Atr and AtrLength should be zeroed)
+- \ref IFD_RESET
+ Perform a warm reset of the card (no power down). If the card is not powered then power up the card (store and return Atr and AtrLength)
+ at param[out] Atr Answer to Reset (ATR) of the card\n
+ The driver is responsible for caching this value in case
+ IFDHGetCapabilities() is called requesting the ATR and its length. The
+ ATR length should not exceed \ref MAX_ATR_SIZE.
+ at param[in,out] AtrLength Length of the ATR\n
+ This should not exceed \ref MAX_ATR_SIZE.
+
+ at note
+Memory cards without an ATR should return \ref IFD_SUCCESS on reset but the
+Atr should be zeroed and the length should be zero Reset errors should
+return zero for the AtrLength and return \ref IFD_ERROR_POWER_ACTION.
+
+ at return Error codes
+ at retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
+ at retval IFD_ERROR_POWER_ACTION Error powering/resetting card (\ref IFD_ERROR_POWER_ACTION)
+ at retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
+ at retval IFD_NOT_SUPPORTED Action not supported (\ref IFD_NOT_SUPPORTED)
+ at retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
+ */
+RESPONSECODE IFDHPowerICC(DWORD Lun, DWORD Action, PUCHAR Atr, PDWORD
+ AtrLength);
+
+/**
+This function performs an APDU exchange with the card/slot specified by
+Lun. The driver is responsible for performing any protocol specific
+exchanges such as T=0, 1, etc. differences. Calling this function will
+abstract all protocol differences.
+
+ at param[in] Lun Logical Unit Number
+ at param[in] SendPci contains two structure members
+- Protocol 0, 1, ... 14\n
+ T=0 ... T=14
+- Length\n
+ Not used.
+ at param[in] TxBuffer Transmit APDU\n
+ Example: "\x00\xA4\x00\x00\x02\x3F\x00"
+ at param[in] TxLength Length of this buffer
+ at param[out] RxBuffer Receive APDU\n
+ Example: "\x61\x14"
+ at param[in,out] RxLength Length of the received APDU\n
+ This function will be passed the size of the buffer of RxBuffer and
+ this function is responsible for setting this to the length of the
+ received APDU response. This should be ZERO on all errors. The
+ resource manager will take responsibility of zeroing out any temporary
+ APDU buffers for security reasons.
+ at param[out] RecvPci contains two structure members
+- Protocol - 0, 1, ... 14\n
+ T=0 ... T=14
+- Length\n
+ Not used.
+
+ at note
+The driver is responsible for knowing what type of card it has. If the
+current slot/card contains a memory card then this command should ignore
+the Protocol and use the MCT style commands for support for these style
+cards and transmit them appropriately. If your reader does not support
+memory cards or you don't want to implement this functionality, then
+ignore this.
+ at par
+RxLength should be set to zero on error.
+ at par
+The driver is not responsible for doing an automatic Get Response
+command for received buffers containing 61 XX.
+
+ at return Error codes
+ at retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
+ at retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
+ at retval IFD_RESPONSE_TIMEOUT The response timed out (\ref IFD_RESPONSE_TIMEOUT)
+ at retval IFD_ICC_NOT_PRESENT ICC is not present (\ref IFD_ICC_NOT_PRESENT)
+ at retval IFD_NOT_SUPPORTED Action not supported (\ref IFD_NOT_SUPPORTED)
+ at retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
+ */
+RESPONSECODE IFDHTransmitToICC(DWORD Lun, SCARD_IO_HEADER SendPci,
+ PUCHAR TxBuffer, DWORD TxLength, PUCHAR RxBuffer, PDWORD
+ RxLength, PSCARD_IO_HEADER RecvPci);
+
+/**
+This function returns the status of the card inserted in the reader/slot
+specified by @p Lun. In cases where the device supports asynchronous
+card insertion/removal detection, it is advised that the driver manages
+this through a thread so the driver does not have to send and receive a
+command each time this function is called.
+
+ at param[in] Lun Logical Unit Number
+
+ at return Error codes
+ at retval IFD_SUCCESS Successful (\ref IFD_SUCCESS)
+ at retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR)
+ at retval IFD_ICC_NOT_PRESENT ICC is not present (\ref IFD_ICC_NOT_PRESENT)
+ at retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE)
+ */
+RESPONSECODE IFDHICCPresence(DWORD Lun);
#ifdef __cplusplus
}
More information about the Pcsclite-cvs-commit
mailing list