Smart Card Driver Library Callback Routines
The smart card architecture defines a set of standard callback routine types. For details about these routines, see Smart Card Driver Callbacks.
A reader driver must make these callback routines available for the driver library routine, SmartcardDeviceControl (WDM), to call by storing pointers to them in the smart card device extension, which is of type SMARTCARD_EXTENSION. These pointers are stored in an array that is located in the ReaderFunction member of SMARTCARD_EXTENSION structure. Individual callback routines can be identified by a series of constant values, which should be used as indexes 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 routine that services the IOCTL_SMARTCARD_POWER request.
If the member of the ReaderFunction array that corresponds to the IOCTL being processed is NULL, SmartcardDeviceControl returns a status of STATUS_NOT_SUPPORTED to the reader driver. In some cases, 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 routine is called.
The following table lists the constants that identify the various types of callback routines. These are the constants that you should use as indexes into the ReaderFunction array. The table also provides a brief description of each routine type and indicates whether it is mandatory or optional for a reader driver to implement the routine.
| Index | Description of corresponding callback routine | Implementation by the reader driver |
|---|---|---|
Resets or turns off an inserted smart card |
Mandatory |
|
Ejects an inserted smart card |
Optional |
|
Installs an event handler to track card insertions and removals |
Mandatory |
|
Performs vendor-specific IOCTL operations |
Optional |
|
Does a mechanical swallow |
Optional |
|
Selects a transmission protocol for the card that is in the card reader |
Mandatory |
|
Performs data transmissions |
Mandatory |
When the reader driver calls these routines, it should retrieve the calling parameters from the input buffers, as described in Smart Card Driver Callbacks. The reader driver should also store the output data in the appropriate buffer areas, as described in the same section.
When any callback routine other than the card-tracking callback routine returns STATUS_PENDING, the smart card library stops servicing any further calls from the reader driver. (For information about the card-tracking callback routine, see RDF_CARD_TRACKING.) If the reader driver attempts to use a driver library routine while the library is in this state, the library routine returns a status of STATUS_DEVICE_BUSY. This effectively prevents the reader driver from servicing IOCTL requests from the resource manager, because the reader driver cannot process IOCTL requests if it cannot call SmartcardDeviceControl.