SMARTCARD_EXTENSION 結構 (smclib.h)

發行項
02/29/2024

智慧卡閱讀機驅動程式和智慧卡驅動程序連結庫會使用 SMARTCARD_EXTENSION 結構來存取所有其他智慧卡數據結構。

語法

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;

成員

Version

表示這個結構的版本。

VendorAttr

包含可識別讀取器驅動程式的資訊，例如廠商名稱、單位號碼和序號。

ReaderFunction[16]

語法區塊中的行應該會讀取 NTSTATUS (*ReaderFunction[16])(PSMARTCARD_EXTENSION);

讀取器回呼函式陣列的指標。廠商提供的讀取器驅動程式可以實作的回呼函式。讀取器驅動程式可讓智慧卡連結庫例程 SmartcardDeviceControl 使用這些回呼函式，藉由將指標儲存在智慧卡裝置擴充功能中來呼叫。

RDF_ATR_PARSE

RDF_CARD_EJECT

RDF_CARD_POWER

RDF_CARD_TRACKING

RDF_IOCTL_VENDOR

RDF_READER_SWALLOW

RDF_SET_PROTOCOL

RDF_TRANSMIT

如需詳細資訊，請參閱＜備註＞。

CardCapabilities

包含插入智慧卡的功能。

LastError

未使用。

IoRequest

具有下列成員的結構：

IoRequest.Information

包含傳回的位元組數目。

IoRequest.RequestBuffer

要傳送至卡片之使用者 I/O 要求中數據的指標。

IoRequest.RequestBufferLength

指出要傳送至卡片的位元組數目。

IoRequest.ReplyBuffer

緩衝區的指標，其中包含 I/O 要求所傳回的數據。

IoRequest.ReplyBufferLength

指出 I/O 要求所傳回之數據的位元元組數目。

MajorIoControlCode

包含主要 I/O 控制件程式代碼。

MinorIoControlCode

包含次要 I/O 控制件程式代碼。

OsData

包含作業系統和驅動程序類型特有的資訊。

ReaderCapabilities

包含鍵盤助讀程式的功能。

ReaderExtension

包含智慧卡卡片閱讀機專屬的數據。

SmartcardReply

包含來自讀取器的數據。

SmartcardRequest

包含目前命令，以及傳送至智慧卡的數據。

T0

包含與 T=0 通訊協定搭配使用的資料。

T1

包含與 T=1 通訊協定搭配使用的資料。

PerfInfo

Reserved[25 - sizeof(PPERF_INFO)]

保留供系統使用。

備註

此結構會傳遞至所有回呼函式。

個別回呼函式是由一系列常數值所識別，這些常數值應該當做 ReaderFunction 陣列中的索引使用。

索引 Description

RDF_ATR_PARSE 選擇性。當驅動程式連結庫無法辨識或剖析智慧卡驅動程序連結庫時，RDF_ATR_PARSE剖析智慧卡驅動程序連結庫的回應重設 (ATR) 。

RDF_CARD_EJECT

選擇性。 RDF_CARD_EJECT回呼函式

RDF_CARD_EJECT回呼函式會從讀取器退出插入的智慧卡。

RDF_CARD_POWER

RDF_CARD_POWER回呼函式會重設或關閉插入的智慧卡。智慧卡閱讀機驅動程式必須實作此回呼函式。

在輸入時， SmartcardExtension 所指向的結構應該具有下列成員值：

MajorIoControlCode

值應為 IOCTL_SMARTCARD_POWER。

IoRequest.ReplyBufferLength

應該包含緩衝區的長度。

MinorIoControlCode

應該有下列其中一個次要代碼：

SCARD_COLD_RESET: 執行智慧卡的冷重設。
SCARD_WARM_RESET: 執行智慧卡的暖重設。
SCARD_POWER_DOWN: 關閉智慧卡電源。

輸出時， SmartcardExtension 所指向的結構應該具有下列值：

IoRequest.ReplyBuffer: 接收智慧卡所傳回的 ATR。此外，您必須將 ATR 傳送至 SmartcardExtension->CardCapabilities.ATR.Buffer ，讓連結庫可以剖析 ATR。
IoRequest.Information: 接收 ATR 的長度。
CardCapabilities.ATR.Length: 包含 ATR 的長度。

RDF_CARD_TRACKING

RDF_CARD_TRACKING回呼函式會安裝事件處理程式，以在卡片讀取器中插入或移除卡片時追蹤每次卡片。智慧卡閱讀機驅動程式必須實作此回呼函式。

收到 IOCTL_SMARTCARD_IS_PRESENT 要求時，驅動程序連結庫會判斷智慧卡是否已存在。如果智慧卡存在，驅動程序連結庫會以狀態STATUS_SUCCESS完成要求。如果沒有智慧卡，驅動程式連結庫會呼叫讀取器驅動程序的智慧卡追蹤回呼函式，而讀取器驅動程式會開始尋找智慧卡。起始智慧卡追蹤之後，驅動程序連結庫會將要求標示為狀態為STATUS_PENDING。

驅動程式連結庫會完成要求。

WDM 設備驅動器

對應的 WDM 驅動程式連結庫會將指標新增至 SmartcardExtension-OsData-NotificationIrp>> 中的要求。讀取器驅動程式在偵測到智慧卡已插入或移除時，必須立即完成要求。讀取器驅動程式會呼叫IoCompleteRequest來完成要求，之後，讀取器驅動程序必須設定SmartcardExtension -> OsData 的 NotificationIrp 成員回到 NULL，以通知驅動程式連結庫讀取器驅動程式可以接受進一步的智慧卡追蹤要求。

因為此呼叫可能會有無限期的持續時間，而且呼叫端可以在要求完成之前終止要求，所以請務必將此 IRP 標示為可取消。

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

RDF_IOCTL_VENDOR回呼函式會執行廠商特定的IOCTL作業。智慧卡閱讀機驅動程序實作此回呼函式是選擇性的。

在輸入時，呼叫端必須將下列值傳遞至函式：

SmartcardExtension->MajorIoControlCode: 包含廠商特定的 IOCTL 程式代碼。如需如何定義廠商特定 IOCTL 程式代碼的相關信息，請參閱 Winsmcrd.h 中的宏SCARD_CTL_CODE。請注意，程式代碼必須介於 2048 和 4095 之間。
SmartcardExtension->IoRequest.RequestBuffer: 使用者輸入緩衝區的指標。
SmartcardExtension->IoRequest.RequestBufferLength: 使用者輸入緩衝區的大小，以位元組為單位。
SmartcardExtension->IoRequest.ReplyBuffer: 用戶輸出緩衝區的指標。
SmartcardExtension->IoRequest.ReplyBufferLength: 用戶輸出緩衝區的大小，以位元組為單位。
SmartcardExtension->IoRequest.Information: 要求所提供的值。必須設定為傳回的位元組數目。

如同所有其他 IOCTL，使用者模式應用程式會藉由呼叫 DeviceIoControl 函式，將廠商定義的 IOCTL 分派給智慧卡閱讀機裝置。不過，當 IOCTL 為廠商定義時，應用程式必須先開啟讀取器裝置的「重疊」 (，也就是異步) 存取。應用程式也必須定義 OVERLAPPED 結構，並在 DeviceIoControl (THE OVERLAPPED 結構的最後一個自變數中傳遞至系統。Windows SDK documentation.) 。當操作系統呼叫驅動程式的 I/O 控制項分派例程時，它會將 DIOCPARAMETERS 結構傳遞給驅動程式。 DIOCPARAMETERS 結構的 lpoOverlapped 成員包含重疊結構的指標。

RDF_READER_SWALLOW RDF_READER_SWALLOW回呼函式會執行機械式機械式，也就是智慧卡完全插入智慧卡閱讀機時會發生什麼情況。智慧卡閱讀機驅動程序實作此回呼函式是選擇性的。

RDF_SET_PROTOCOL

RDF_SET_PROTOCOL回呼函式會選取插入智慧卡的傳輸通訊協定。智慧卡閱讀機驅動程式必須實作此回呼函式。

在輸入時，呼叫端必須將下列值傳遞至函式：

SmartcardExtension->MajorIoControlCode

包含 IOCTL_SMARTCARD_SET_PROTOCOL。

SmartcardExtension->MinorIoControlCode

包含一或多個通訊協定的位 OR，而不是呼叫端接受的通訊協定。驅動程式必須選取插入智慧卡支持的通訊協定。我們建議 T = 1 通訊協定的優先順序高於 T = 0 通訊協定。

值	意義
SCARD_PROTOCOL_RAW	選取原始通訊協定。
SCARD_PROTOCOL_T0	選取 ISO T = 0 通訊協定。
SCARD_PROTOCOL_T1	選取 ISO T = 1 通訊協定。

SmartcardExtension->IoRequest.ReplyBufferLength

包含回復緩衝區的長度。

SmartcardExtension->CardCapabilities.PtsData

包含執行 PTS 要求的必要參數。如需詳細資訊，請參閱 PTS_DATA。

要求會傳回下列值：

SmartcardExtension->IoRequest.ReplyBuffer: 包含選取的通訊協定。
SmartcardExtension->IoRequest.Information: 設定為 sizeof (ULONG) 。

呼叫端可以提供可接受的通訊協定遮罩。驅動程式的設定通訊協定回呼例程會選取遮罩中的其中一個通訊協定，並在 SmartcardExtension->IoRequest.ReplyBuffer 中傳回選取的通訊協定。

RDF_TRANSMIT

RDF_TRANSMIT回呼函式會執行數據傳輸。智慧卡閱讀機驅動程式必須實作此回呼函式。

在輸入時，呼叫端必須將下列值傳遞至函式：

SmartcardExtension->MajorIoControlCode: 包含 IOCTL_SMARTCARD_TRANSMIT。
SmartcardExtension->IoRequest.RequestBuffer: SCARD_IO_REQUEST 結構的指標，後面接著要傳輸至卡片的數據。
SmartcardExtension->IoRequest.RequestBufferLength: 要傳輸至卡片的位元元組數。
SmartcardExtension->IoRequest.ReplyBufferLength: 回復緩衝區的大小，以位元組為單位。

要求會傳回下列值：

SmartcardExtension->IoRequest.ReplyBuffer: 接收SCARD_IO_REQUEST結構的緩衝區指標，加上卡片的結果。
SmartcardExtension->IoRequest.Information: 接收智慧卡所傳回的實際位元組數目，加上SCARD_IO_REQUEST結構的大小。如需SCARD_IO_REQUEST結構的定義，請參閱IOCTL_SMARTCARD_TRANSMIT。

呼叫此函式時， SmartcardExtension->IoRequest.RequestBuffer 會指向SCARD_IO_REQUEST結構，後面接著要傳輸的數據。

typedef struct _SCARD_IO_REQUEST{
  DWORD  dwProtocol;   // Protocol identifier
  DWORD  cbPciLength;  // Protocol Control Information Length
} SCARD_IO_REQUEST, *PSCARD_IO_REQUEST, *LPSCARD_IO_REQUEST;

dwProtocol 成員必須包含呼叫IOCTL_SMARTCARD_SET_PROTOCOL所傳回的通訊協議標識碼。

cbPciLength 成員包含SCARD_IO_REQUEST結構的大小，以位元組為單位。此結構的大小通常是8個字節。

SCARD_IO_REQUEST結構後面接著 (通訊協定) 數據傳送至卡片。根據要用於傳輸的通訊協議，連結庫會提供數個支援功能。如需這些支援函式的詳細資訊，請參閱 SmartcardT0Request (WDM) 和 SmartcardT1Request (WDM) 。

RequestBuffer 和 ReplyBuffer 指向相同的系統緩衝區。如果您使用連結庫函式 SmartcardxxRequest 和 SmartcardxxReply，則不會覆寫輸入緩衝區。如果您未使用這些函式，請在開始傳輸之前，先建立 RequestBuffer 的複本。

您必須將SCARD_IO_REQUEST結構複製到 ReplyBuffer 參數，後面接著從卡片接收的數據。同樣地，如果您使用 SmartcardxxRequest 和 SmartcardxxReply 函式，連結庫會為您複製結構。

規格需求

需求	值
標頭	smclib.h (包含 Smclib.h)

共用方式為

SMARTCARD_EXTENSION 結構 (smclib.h)

語法

成員

備註

規格需求

意見反應

其他資源