SMARTCARD_EXTENSION結構（smclib.h）

發行項
02/07/2025

智慧卡讀取器驅動程式和智慧卡驅動程序連結庫會使用 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 陣列。

指數描述

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 的 NotificationIrp 成員 -> OsData 回到 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 的最後一個自變數中（Windows SDK 檔也會說明重疊結構）。當作系統呼叫驅動程式的 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 （include Smclib.h）

共用方式為

SMARTCARD_EXTENSION結構（smclib.h）

語法

成員

言論

要求

意見反應

其他資源