RDF_CARD_TRACKING

The card tracking callback function installs an event handler to track card insertions and removals.

NTSTATUS 
  (*ReaderFunction[RDF_CARD_TRACKING])(
    PSMARTCARD_EXTENSION  SmartcardExtension
    );

Parameters

SmartcardExtension

For WDM device drivers, SmartcardExtension->OsData->NotificationIrp contains the IRP that is to be informed of the insertion/removal event.
For VxD device drivers, SmartcardExtension->OsData->NotificationOverlappedData points to the overlapped structure of the caller to be informed of the insertion/removal event.

Return Value

This function returns an NTSTATUS value. Possible values for WDM and VxD device drivers are the following.

Headers

Declared in smclib.h. Include smclib.h.

Comments

It is mandatory for card reader drivers to implement this callback function.

Upon receiving an IOCTL_SMARTCARD_IS_PRESENT request, the driver library checks to see if the card is already present. If it is, it completes the request with a status of STATUS_SUCCESS. If not, it calls the reader driver's card tracking callback function, and the reader driver starts card tracking. After initiating card tracking, the driver library marks the request as having a status of STATUS_PENDING.

The driver library handles the completion of the request in two different manners, depending on whether it is a WDM or a VxD driver.

WDM Device Drivers: In the case of WDM device drivers, the corresponding WDM driver library places a pointer to the request in SmartcardExtension->OsData->NotificationIrp. The reader driver must complete this request as soon as it detects an insertion or a removal. It completes the request by calling IoCompleteRequest. After the call to IoCompleteRequest, the reader driver must set the NotificationIrp member of SmartcardExtension -> OsData back to NULL. This tells the driver library that the reader driver can accept further card-tracking requests.

It is important to mark this IRP as cancelable, because this call can be of an indefinite duration, and the caller can terminate before this request can be completed.

VxD Device Drivers: In the case of VxD device drivers, the reader driver callback function must poll the structure member OsData->NotificationOverlappedData for a non-NULL value. A non-NULL value signals an insertion or removal. Once the value is non-NULL, the reader driver should call SmartcardCompleteCardTracking (VxD) to inform the driver library of the card insertion/removal event.

The following offers a code sample.

MyDriverCardSupervision(
SmartcardExtension, 
OtherParameters)
//
//    This function is called whenever the card status changes
//    For example, card has been inserted or card has been removed
//
{
    //
    // Do some other tasks here
    //
    if (SmartcardExtension->OsData->NotificationOverlappedData != NULL){

        SmartcardCompleteCardTracking(SmartcardExtension);
    }
    //
    // Do additional tasks
    //
}

See Also

SMARTCARD_EXTENSION