RDF_CARD_TRACKING (Mandatory)

WDM driver version:

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

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

Parameters

SmartcardExtension

Points to the smart card extension of the device.

Input Values for WDM Device Drivers

SmarcardExtension->OsData->NotificationIrp

Contains the IRP that is to be informed of the insertion/removal event.

Input Values for VxD device Drivers

SmarcardExtension->OsData->NotificationOverlappedData

Points to the overlapped structure of the caller to be informed of the insertion/removal event.

Return Values

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

Remarks for WDM Device Drivers

Before the library calls RDF_CARD_TRACKING, it checks if the status already matches the current card status. (That is, a card is inserted and the caller sends an IOCTL_SMARTCARD_IS_PRESENT code.) In this case, the library returns STATUS_SUCCESS without calling this function.

Otherwise, the driver will be called and it should start card tracking. The smart card library fills SmarcardExtension->OsData->NotificationIrp in its extension because this is the IRP that will be informed of insertions or removals. Usually, the driver returns STATUS_PENDING to this call since the current card status does not match the status to check for. The driver must complete this call as soon as it detects the insertion or removal. This is done by a call to IoCompleteRequest. After the call to IoCompleteRequest, you must set the member NotificationIrp back to NULL. This tells the smart card library that your driver can accept further card-tracking requests.

Note 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 call can be satisfied.

Remarks for VxD Device Drivers

Before the library calls RDF_CARD_TRACKING, it checks if the status already matches the current card status. (That is, a card is inserted and the caller sends an IOCTL_SMARTCARD_IS_PRESENT code.) In this case, the library returns STATUS_SUCCESS without calling this function. Otherwise, the driver will be called and it should start card tracking.

Note Since this function will be called only when the current card status is the opposite of the status the caller wants to be informed of, your driver only needs to return STATUS_PENDING. In your driver function that is used to supervise the card, use the structure member OsData->NotificationOverlappedData and check it for a non-NULL value. If the value is non-NULL, call SmartcardCompleteCardTracking (VxD) to inform the caller of the card insertion/removal event.

Following is some sample code:

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
    //
}