Edit

SMARTCARD_EXTENSION structure (smclib.h)

  • Article

The SMARTCARD_EXTENSION structure is used by both the smart card reader driver and the smart card driver library to access all other smart card data structures.

Syntax

typedef struct _SMARTCARD_EXTENSION {
  ULONG                     Version;
  VENDOR_ATTR               VendorAttr;
  NTSTATUS(                 *ReaderFunction[16];
  SCARD_CARD_CAPABILITIES   CardCapabilities;
  ULONG                     LastError;
  struct {
    PULONG Information;
    PUCHAR RequestBuffer;
    ULONG  RequestBufferLength;
    PUCHAR ReplyBuffer;
    ULONG  ReplyBufferLength;
  } IoRequest;
  ULONG                     MajorIoControlCode;
  ULONG                     MinorIoControlCode;
  POS_DEP_DATA              OsData;
  SCARD_READER_CAPABILITIES ReaderCapabilities;
  PREADER_EXTENSION         ReaderExtension;
  SMARTCARD_REPLY           SmartcardReply;
  SMARTCARD_REQUEST         SmartcardRequest;
  T0_DATA                   T0;
  T1_DATA                   T1;
  PPERF_INFO                PerfInfo;
  ULONG                     Reserved[25 - sizeof(PPERF_INFO)];
} *PSMARTCARD_EXTENSION, SMARTCARD_EXTENSION;

Members

Version

Indicates the version of this structure.

VendorAttr

Contains information that identifies the reader driver, such as the vendor name, unit number, and serial number.

ReaderFunction[16]

The line in the syntax block should read NTSTATUS (*ReaderFunction[16])(PSMARTCARD_EXTENSION);

A pointer to an array of callback functions for readers. The callback functions that a vendor-supplied reader driver can implement. A reader driver makes these callback functions available for the smart card library routine, SmartcardDeviceControl, to call by storing pointers to them in the smart card device extension.

RDF_ATR_PARSE
RDF_CARD_EJECT
RDF_CARD_POWER
RDF_CARD_TRACKING
RDF_IOCTL_VENDOR
RDF_READER_SWALLOW
RDF_SET_PROTOCOL
RDF_TRANSMIT
For more information, see Remarks.

CardCapabilities

Contains capabilities of the inserted smart card.

LastError

Not used.

IoRequest

A structure with the following members:

IoRequest.Information

Contains the number of bytes returned.

IoRequest.RequestBuffer

A pointer to the data in the user's I/O request to be sent to the card.

IoRequest.RequestBufferLength

Indicates the number of bytes to send to the card.

IoRequest.ReplyBuffer

A pointer to the buffer that holds the data that is returned by the I/O request.

IoRequest.ReplyBufferLength

Indicates the number of bytes of the data that are returned by the I/O request.

MajorIoControlCode

Contains the major I/O control code.

MinorIoControlCode

Contains the minor I/O control code.

OsData

Contains information that is specific to the operating system and the driver type.

ReaderCapabilities

Contains the capabilities of the keyboard reader.

ReaderExtension

Contains data that is specific to the smart card reader.

SmartcardReply

Contains data that comes from the reader.

SmartcardRequest

Contains the current command and the data that is sent to the smart card.

T0

Contains the data for use with the T=0 protocol.

T1

Contains the data that is used with the T=1 protocol.

PerfInfo

Reserved[25 - sizeof(PPERF_INFO)]

Reserved for system use.

Remarks

This structure is passed to all callback functions.

Individual callback functions are identified by a series of constant values that should be used as indexes into the ReaderFunction array.

Index Description
RDF_ATR_PARSE Optional. The RDF_ATR_PARSE parse function parses an answer-to-reset (ATR) for the smart card driver library when the driver library is unable to recognize or parse the smart card driver library.
RDF_CARD_EJECT Optional. RDF_CARD_EJECT callback function

The RDF_CARD_EJECT callback function ejects an inserted smart card from the reader.
RDF_CARD_POWER The RDF_CARD_POWER callback function resets or turns off an inserted smart card.It is mandatory for smart card reader drivers to implement this callback function.

On input, the structure pointed to by SmartcardExtension should have the following member values:

MajorIoControlCode
Should have a value of IOCTL_SMARTCARD_POWER.
IoRequest.ReplyBufferLength
Should contain the length of the buffer.
MinorIoControlCode
Should have one of the following minor codes:
SCARD_COLD_RESET
Performs a cold reset of the smart card.
SCARD_WARM_RESET
Performs a warm reset of the smart card.
SCARD_POWER_DOWN
Turns off smart card power.
On output, the structure pointed to by SmartcardExtension should have the following values:
IoRequest.ReplyBuffer
Receives the ATR that is returned by the smart card. In addition, you must transfer the ATR to SmartcardExtension->CardCapabilities.ATR.Buffer so that the library can parse the ATR.
IoRequest.Information
Receives the length of the ATR.
CardCapabilities.ATR.Length
Contains the length of the ATR.
RDF_CARD_TRACKING The RDF_CARD_TRACKING callback function installs an event handler to track every time a card is inserted in or removed from a card reader.It is mandatory for smart card reader drivers to implement this callback function.

Upon receiving an IOCTL_SMARTCARD_IS_PRESENT request, the driver library determines if the smart card is already present. If the smart card is present, the driver library completes the request with a status of STATUS_SUCCESS. If there is no smart card present, the driver library calls the reader driver's smart card tracking callback function, and the reader driver starts looking for the smart card. After initiating smart card tracking, the driver library marks the request as having a status of STATUS_PENDING.

The driver library completes the request.

WDM Device Drivers

The corresponding WDM driver library adds a pointer to the request in SmartcardExtension->OsData->NotificationIrp. The reader driver must complete the request as soon as it detects that a smart card has been inserted or removed. The reader driver completes the request by calling IoCompleteRequest, after which, the reader driver must set the NotificationIrp member of SmartcardExtension -> OsData back to NULL to inform the driver library that the reader driver can accept further smart card tracking requests.

Because this call can have an indefinite duration and the caller can terminate the request before it is complete, it is important to mark this IRP as cancelable.

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

        SmartcardCompleteCardTracking(SmartcardExtension);
    }
    //
    // Do additional tasks
    //
}
RDF_IOCTL_VENDOR The RDF_IOCTL_VENDOR callback function performs vendor-specific IOCTL operations.It is optional for smart card reader drivers to implement this callback function.

On input, the caller must pass the following values to the function:

SmartcardExtension->MajorIoControlCode
Contains a vendor-specific IOCTL code. Refer to the macro SCARD_CTL_CODE in Winsmcrd.h for information about how to define a vendor-specific IOCTL code. Note that the code must be between 2048 and 4095.
SmartcardExtension->IoRequest.RequestBuffer
A pointer to the user's input buffer.
SmartcardExtension->IoRequest.RequestBufferLength
The size, in bytes, of the user's input buffer.
SmartcardExtension->IoRequest.ReplyBuffer
A pointer to the user's output buffer.
SmartcardExtension->IoRequest.ReplyBufferLength
The size, in bytes, of the user's output buffer.
SmartcardExtension->IoRequest.Information
The value supplied by the request. Must be set to the number of bytes returned.
As with all other IOCTLs, a user-mode application dispatches a vendor-defined IOCTL to a smart card reader device by calling the DeviceIoControl function. When the IOCTL is vendor-defined, however, the application must first open the reader device for "overlapped" (that is, asynchronous) access. The application must also define an OVERLAPPED structure and pass it to the system in the last argument of DeviceIoControl (The OVERLAPPED structure is also described in the Windows SDK documentation.). When the operating system calls the driver's I/O control dispatch routine, it passes a DIOCPARAMETERS structure to the driver. The lpoOverlapped member of the DIOCPARAMETERS structure contains a pointer to the OVERLAPPED structure.
RDF_READER_SWALLOW The RDF_READER_SWALLOW callback function performs a mechanical swallow, which is what happens when the smart card is fully inserted into the smart card reader.It is optional for smart card reader drivers to implement this callback function.
RDF_SET_PROTOCOL The RDF_SET_PROTOCOL callback function selects a transmission protocol for the inserted smart card.Smart card reader drivers must implement this callback function.

On input, the caller must pass the following values to the function:

SmartcardExtension->MajorIoControlCode
Contains IOCTL_SMARTCARD_SET_PROTOCOL.
SmartcardExtension->MinorIoControlCode
Contains a bitwise OR of one or more protocols than the caller accepts. The driver must select a protocol that the inserted smart card supports. We recommend that the T = 1 protocol is given precedence over the T = 0 protocol.
Value Meaning
SCARD_PROTOCOL_RAW Selects the raw protocol.
SCARD_PROTOCOL_T0 Selects the ISO T = 0 protocol.
SCARD_PROTOCOL_T1 Selects the ISO T = 1 protocol.
 
SmartcardExtension->IoRequest.ReplyBufferLength
Contains the length of the reply buffer.
SmartcardExtension->CardCapabilities.PtsData
Contains the required parameters to perform the PTS request. For more information, see PTS_DATA.
The request returns the following values:
SmartcardExtension->IoRequest.ReplyBuffer
Contains the selected protocol.
SmartcardExtension->IoRequest.Information
Set to sizeof(ULONG).
The caller can supply a mask of acceptable protocols. The driver's set protocol callback routine selects one of the protocols in the mask and returns the selected protocol in SmartcardExtension->IoRequest.ReplyBuffer.
RDF_TRANSMIT The RDF_TRANSMIT callback function performs data transmissions.Smart card reader drivers must implement this callback function.

On input, the caller must pass the following values to the function:

SmartcardExtension->MajorIoControlCode
Contains IOCTL_SMARTCARD_TRANSMIT.
SmartcardExtension->IoRequest.RequestBuffer
A pointer to an SCARD_IO_REQUEST structure followed by data to transmit to the card.
SmartcardExtension->IoRequest.RequestBufferLength
The number of bytes to transmit to the card.
SmartcardExtension->IoRequest.ReplyBufferLength
The size, in bytes, of the reply buffer.
The request returns the following values:
SmartcardExtension->IoRequest.ReplyBuffer
A pointer to the buffer that receives the SCARD_IO_REQUEST structure, plus the result of the card.
SmartcardExtension->IoRequest.Information
Receives the actual number of bytes returned by the smart card, plus the size of the SCARD_IO_REQUEST structure. For a definition of the SCARD_IO_REQUEST structure, see IOCTL_SMARTCARD_TRANSMIT.
When this function is called, SmartcardExtension->IoRequest.RequestBuffer points to an SCARD_IO_REQUEST structure followed by the data to transmit. 
typedef struct _SCARD_IO_REQUEST{
  DWORD  dwProtocol;   // Protocol identifier
  DWORD  cbPciLength;  // Protocol Control Information Length
} SCARD_IO_REQUEST, *PSCARD_IO_REQUEST, *LPSCARD_IO_REQUEST;

The dwProtocol member must contain the protocol identifier that is returned by a call to IOCTL_SMARTCARD_SET_PROTOCOL.

The cbPciLength member contains the size, in bytes, of the SCARD_IO_REQUEST structure. The size of this structure is usually 8 bytes.

The SCARD_IO_REQUEST structure is followed by (protocol) data to transmit to the card. Depending on the protocol to use for the transmission, the library offers several support functions. For more information about these support functions, see SmartcardT0Request (WDM) and SmartcardT1Request (WDM).

RequestBuffer and ReplyBuffer point to the same system buffer. If you use the library function SmartcardxxRequest and SmartcardxxReply, you will not overwrite the input buffer. If you do not use these functions, make a copy of the RequestBuffer before you start transmissions.

You must copy the SCARD_IO_REQUEST structure to the ReplyBuffer parameter, followed by the data received from the card. Again, if you use the SmartcardxxRequest and SmartcardxxReply functions, the library will copy the structure for you.

Requirements

Requirement Value
Header smclib.h (include Smclib.h)