|
|
|
The smart card architecture defines a set of standard callback function types that are discussed in the smart card reference documentation. See Smart Card Driver Callbacks for more information.
A reader driver must make these callback functions available for the driver library routine, SmartcardDeviceControl (WDM), to call by storing pointers to them in the smart card device extension, SMARTCARD_EXTENSION. These pointers are stored in an array of function pointers located in the ReaderFunction member of SMARTCARD_EXTENSION. Individual callback functions can be identified by means of a series of constant values that should be used as indices into the ReaderFunction array.
For instance, if you want SmartcardDeviceControl to call a callback routine in your reader driver named DriverCardPower whenever it finishes processing an IOCTL_SMARTCARD_POWER request, you must use the RDF_CARD_POWER constant to initialize the device extension in the following manner:
SmartcardExtension->ReaderFunction[RDF_CARD_POWER] = DriverCardPower;
RDF_CARD_POWER is a fixed system-defined constant that always corresponds to the callback that services the IOCTL_SMARTCARD_POWER request.
If the member of the ReaderFunction array corresponding to the IOCTL being processed is NULL, SmartcardDeviceControl returns a status of STATUS_NOT_SUPPORTED to the reader driver. There are cases where this behavior is useful. If, for example, your driver does not support card ejecting or card swallowing, simply assign the appropriate member of the ReaderFunction array to be NULL, and SmartcardDeviceControl will return STATUS_NOT_SUPPORTED whenever that member function is called.
The following table provides a list of the constant indices used to identify the various types of callback routines in the ReadFunction array. It also provides a brief description of each function type, and it indicates whether it is mandatory or optional for a reader driver to implement the function. This list applies to both WDM and VxD libraries.
| Index | Description of Corresponding Callback Routine | Implementation by the Reader Driver |
|---|---|---|
| RDF_CARD_POWER | Resets or powers down an inserted smart card. | Mandatory |
| RDF_CARD_EJECT | Ejects an inserted smart card. | Optional |
| RDF_CARD_TRACKING | Installs an event handler to track card insertions and removals. | Mandatory |
| RDF_IOCTL_VENDOR | Performs vendor-specific IOCTL operations. | Optional |
| RDF_READER_SWALLOW | Does a mechanical swallow. | Optional |
| RDF_SET_PROTOCOL | Selects a transmission protocol for the currently-inserted card. | Mandatory |
| RDF_TRANSMIT | Performs data transmissions. | Mandatory |
When calling these functions, the reader driver should retrieve calling parameters from the input buffers as described in Smart Card Driver Callbacks. It should also store output data in the appropriate buffer areas as described in the same section.
When any callback routine, other than the card tracking callback (see RDF_CARD_TRACKING), returns STATUS_PENDING, both the WDM and VxD versions of the smart card library will cease to service any further calls from the reader driver. If the reader driver attempts to use a driver library routine while the library is in this state, the library routine will return a status of STATUS_DEVICE_BUSY. This effectively prevents the reader driver from servicing IOCTL requests from the resource manager, because the reader driver can not process IOCTL requests if it can not call SmartcardDeviceControl.
Note If the reader driver is a VxD driver, it should call SmartcardCompleteRequest to complete a pending IOCTL request. This function informs the resource manager of the completion and unlocks memory that had been locked by the smart card driver library. It also enables further calls to the driver library.