Revision: 121 http://trac.macosforge.org/projects/smartcardservices/changeset/121 Author: ludovic.rousseau@gmail.com Date: 2010-03-27 03:40:50 -0700 (Sat, 27 Mar 2010) Log Message: ----------- Add Doxygen documentation (resync with pcsc-lite) Modified Paths: -------------- trunk/SmartCardServices/src/PCSC/ifdhandler.h Modified: trunk/SmartCardServices/src/PCSC/ifdhandler.h =================================================================== --- trunk/SmartCardServices/src/PCSC/ifdhandler.h 2010-03-26 19:36:14 UTC (rev 120) +++ trunk/SmartCardServices/src/PCSC/ifdhandler.h 2010-03-27 10:40:50 UTC (rev 121) @@ -31,14 +31,222 @@ * * Copyright (C) 1999-2004 * David Corcoran <corcoran@linuxnet.com> + * Copyright (C) 2003-2004 * Damien Sauveron <damien.sauveron@labri.fr> + * Copyright (C) 2002-2009 + * Ludovic Rousseau <ludovic.rousseau@free.fr> * * $Id: ifdhandler.h 2348 2007-01-20 15:12:19Z rousseau $ */ /** * @file + * @defgroup IFDHandler * @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. + +@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: + +@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 +@endverbatim + +The @c Info.plist file describes the driver and gives the loader +all the necessary information. The following must be contained in the +@c Info.plist file: + +@subsection ifdVendorID + +The vendor ID of the USB device. + +Example: + +@verbatim + <key>ifdVendorID</key> + <string>0x04E6</string> +@endverbatim + +You may have an OEM of this reader in which an additional @c <string> +can be used like in the below example: + +@verbatim + <key>ifdVendorID</key> + <array> + <string>0x04E6</string> + <string>0x0973</string> + </array> +@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. + +@subsection ifdProductID + + The product id of the USB device. + +@verbatim + <key>ifdProductID</key> + <string>0x3437</string> +@endverbatim + +@subsection ifdFriendlyName + + Example: + +@verbatim + <key>ifdFriendlyName</key> + <string>SCM Microsystems USB Reader</string> +@endverbatim + +@subsection CFBundleExecutable + + The executable name which exists in the particular platform's directory. + + Example: + +@verbatim + <key>CFBundleExecutable</key> + <string>libccid.so.0.4.2</string> +@endverbatim + +@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: + +@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> +@endverbatim + +As indicated in the XML file the DTD is available at +http://www.apple.com/DTDs/PropertyList-1.0.dtd. + +@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: + +@verbatim +# Configuration file for pcsc-lite +# David Corcoran <corcoran@musclecard.com> + +FRIENDLYNAME Generic Reader +DEVICENAME /dev/ttyS0 +LIBPATH /usr/lib/pcsc/drivers/libgen_ifd.so +CHANNELID 1 +@endverbatim + +The pound sign # denotes a comment. + +@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. + +@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. + +@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). + +@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. + +@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_ @@ -52,7 +260,6 @@ /* * List of data structures available to ifdhandler */ - typedef struct _DEVICE_CAPABILITIES { LPSTR Vendor_Name; /**< Tag 0x0100 */ @@ -101,6 +308,9 @@ } PROTOCOL_OPTIONS, *PPROTOCOL_OPTIONS; + /** + * Use by SCardTransmit() + */ typedef struct _SCARD_IO_HEADER { DWORD Protocol; @@ -109,72 +319,65 @@ 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 /**< 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 */ -#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 - */ - - /* * IFD Handler version number enummerations */ #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 /**< power up the card */ +#define IFD_POWER_DOWN 501 /**< power down the card */ +#define IFD_RESET 502 /**< warm reset */ -#define IFD_POWER_UP 500 -#define IFD_POWER_DOWN 501 -#define IFD_RESET 502 +#define IFD_NEGOTIATE_PTS1 1 /**< negotiate PTS1 */ +#define IFD_NEGOTIATE_PTS2 2 /**< negotiate PTS2 */ +#define IFD_NEGOTIATE_PTS3 4 /**< negotiate PTS3 */ -#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_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 /**< buffer is too small */ // typedef long RESPONSECODE; /* - * 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) */ @@ -189,33 +392,416 @@ * 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. + +@ingroup IFDHandler +@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. + +@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: + +@code +printf("usb:%04x/%04x", idVendor, idProduct); +@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. + +@return Error codes +@retval IFD_SUCCESS Successful (\ref IFD_SUCCESS) +@retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR) +@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. + +@ingroup IFDHandler +@param[in] Lun Logical Unit Number +@param[in] dwControlCode Control code for the operation\n + This value identifies the specific operation to be performed. This + value is driver specific. +@param[in] TxBuffer Transmit data +@param[in] TxLength Length of this buffer +@param[out] RxBuffer Receive data +@param[in] RxLength Length of the response buffer +@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. + +@note + @p *pdwBytesReturned should be set to zero on error. + +@return Error codes +@retval IFD_SUCCESS Successful (\ref IFD_SUCCESS) +@retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR) +@retval IFD_RESPONSE_TIMEOUT The response timed out (\ref IFD_RESPONSE_TIMEOUT) +@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 - */ +/** + * 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); - RESPONSECODE IFDHControl(DWORD, PUCHAR, DWORD, PUCHAR, PDWORD); - #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. + +@ingroup IFDHandler +@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. +@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 + +@return Error codes +@retval IFD_SUCCESS Successful (\ref IFD_SUCCESS) +@retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR) +@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. + +@ingroup IFDHandler +@param[in] Lun Logical Unit Number + +@return Error codes +@retval IFD_SUCCESS Successful (\ref IFD_SUCCESS) +@retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR) +@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. + +@ingroup IFDHandler +@param[in] Lun Logical Unit Number +@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 +@param[in,out] Length Length of the desired data value +@param[out] Value Value of the desired data + +@return Error codes +@retval IFD_SUCCESS Successful (\ref IFD_SUCCESS) +@retval IFD_ERROR_TAG Invalid tag given (\ref IFD_ERROR_TAG) +@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. + +@ingroup IFDHandler +@param[in] Lun Logical Unit Number +@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. +@param[in,out] Length Length of the desired data value +@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. + +@return Error codes +@retval IFD_SUCCESS Successful (\ref IFD_SUCCESS) +@retval IFD_ERROR_TAG Invalid tag given (\ref IFD_ERROR_TAG) +@retval IFD_ERROR_SET_FAILURE Could not set value (\ref IFD_ERROR_SET_FAILURE) +@retval IFD_ERROR_VALUE_READ_ONLY Trying to set read only value (\ref IFD_ERROR_VALUE_READ_ONLY) +@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 + +@ingroup IFDHandler +@param[in] Lun Logical Unit Number +@param[in] Protocol Desired protocol +- \ref SCARD_PROTOCOL_T0 + T=0 protocol +- \ref SCARD_PROTOCOL_T1 + T=1 protocol +@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 +@param[in] PTS1 1st PTS Value +@param[in] PTS2 2nd PTS Value +@param[in] PTS3 3rd PTS Value\n + See ISO 7816/EMV documentation. + +@return Error codes +@retval IFD_SUCCESS Successful (\ref IFD_SUCCESS) +@retval IFD_ERROR_PTS_FAILURE Could not set PTS value (\ref IFD_ERROR_PTS_FAILURE) +@retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR) +@retval IFD_PROTOCOL_NOT_SUPPORTED Protocol is not supported (\ref IFD_PROTOCOL_NOT_SUPPORTED) +@retval IFD_NOT_SUPPORTED Action not supported (\ref IFD_NOT_SUPPORTED) +@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. + +@ingroup IFDHandler +@param[in] Lun Logical Unit Number +@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) +@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. +@param[in,out] AtrLength Length of the ATR\n + This should not exceed \ref MAX_ATR_SIZE. + +@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. + +@return Error codes +@retval IFD_SUCCESS Successful (\ref IFD_SUCCESS) +@retval IFD_ERROR_POWER_ACTION Error powering/resetting card (\ref IFD_ERROR_POWER_ACTION) +@retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR) +@retval IFD_NOT_SUPPORTED Action not supported (\ref IFD_NOT_SUPPORTED) +@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. + +@ingroup IFDHandler +@param[in] Lun Logical Unit Number +@param[in] SendPci contains two structure members +- Protocol 0, 1, ... 14\n + T=0 ... T=14 +- Length\n + Not used. +@param[in] TxBuffer Transmit APDU\n + Example: "\x00\xA4\x00\x00\x02\x3F\x00" +@param[in] TxLength Length of this buffer +@param[out] RxBuffer Receive APDU\n + Example: "\x61\x14" +@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. +@param[out] RecvPci contains two structure members +- Protocol - 0, 1, ... 14\n + T=0 ... T=14 +- Length\n + Not used. + +@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. +@par +RxLength should be set to zero on error. +@par +The driver is not responsible for doing an automatic Get Response +command for received buffers containing 61 XX. + +@return Error codes +@retval IFD_SUCCESS Successful (\ref IFD_SUCCESS) +@retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR) +@retval IFD_RESPONSE_TIMEOUT The response timed out (\ref IFD_RESPONSE_TIMEOUT) +@retval IFD_ICC_NOT_PRESENT ICC is not present (\ref IFD_ICC_NOT_PRESENT) +@retval IFD_NOT_SUPPORTED Action not supported (\ref IFD_NOT_SUPPORTED) +@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. + +@ingroup IFDHandler +@param[in] Lun Logical Unit Number + +@return Error codes +@retval IFD_SUCCESS Successful (\ref IFD_SUCCESS) +@retval IFD_COMMUNICATION_ERROR Error has occurred (\ref IFD_COMMUNICATION_ERROR) +@retval IFD_ICC_NOT_PRESENT ICC is not present (\ref IFD_ICC_NOT_PRESENT) +@retval IFD_NO_SUCH_DEVICE The reader is no more present (\ref IFD_NO_SUCH_DEVICE) + */ +RESPONSECODE IFDHICCPresence(DWORD Lun); + /* * List of Defined Functions Available to IFD_Handler 1.0 */