SMARTCARD_EXTENSION-Struktur (smclib.h)

  • Artikel

Die SMARTCARD_EXTENSION-Struktur wird sowohl vom Smart Karte Readertreiber als auch von der Smart Karte Driver Library verwendet, um auf alle anderen smart Karte Datenstrukturen zuzugreifen.

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;

Member

Version

Gibt die Version dieser Struktur an.

VendorAttr

Enthält Informationen, die den Readertreiber identifizieren, z. B. Den Namen des Anbieters, die Einheitennummer und die Seriennummer.

ReaderFunction[16]

Die Zeile im Syntaxblock sollte lesen. NTSTATUS (*ReaderFunction[16])(PSMARTCARD_EXTENSION);

Ein Zeiger auf ein Array von Rückruffunktionen für Leser. Die Rückruffunktionen, die ein vom Anbieter bereitgestellter Readertreiber implementieren kann. Ein Readertreiber stellt diese Rückruffunktionen für die smart Karte-Bibliotheksroutine SmartcardDeviceControl zur Verfügung, die aufgerufen werden soll, indem Zeiger auf sie in der Geräteerweiterung smart Karte gespeichert werden.

RDF_ATR_PARSE
RDF_CARD_EJECT
RDF_CARD_POWER
RDF_CARD_TRACKING
RDF_IOCTL_VENDOR
RDF_READER_SWALLOW
RDF_SET_PROTOCOL
RDF_TRANSMIT
Weitere Informationen finden Sie in den Hinweisen.

CardCapabilities

Enthält Funktionen des eingefügten intelligenten Karte.

LastError

Wird nicht verwendet.

IoRequest

Eine -Struktur mit den folgenden Membern:

IoRequest.Information

Enthält die Anzahl der zurückgegebenen Bytes.

IoRequest.RequestBuffer

Ein Zeiger auf die Daten in der E/A-Anforderung des Benutzers, die an die Karte gesendet werden sollen.

IoRequest.RequestBufferLength

Gibt die Anzahl der Bytes an, die an den Karte gesendet werden sollen.

IoRequest.ReplyBuffer

Ein Zeiger auf den Puffer, der die Daten enthält, die von der E/A-Anforderung zurückgegeben werden.

IoRequest.ReplyBufferLength

Gibt die Anzahl der Byte der Daten an, die von der E/A-Anforderung zurückgegeben werden.

MajorIoControlCode

Enthält den Haupt-E/A-Steuerungscode.

MinorIoControlCode

Enthält den Neben-E/A-Steuerungscode.

OsData

Enthält informationen, die für das Betriebssystem und den Treibertyp spezifisch sind.

ReaderCapabilities

Enthält die Funktionen des Tastaturlesers.

ReaderExtension

Enthält Daten, die für den Leser des intelligenten Karte spezifisch sind.

SmartcardReply

Enthält Daten, die vom Reader stammen.

SmartcardRequest

Enthält den aktuellen Befehl und die Daten, die an die intelligente Karte gesendet werden.

T0

Enthält die Daten für die Verwendung mit dem T=0-Protokoll.

T1

Enthält die Daten, die mit dem T=1-Protokoll verwendet werden.

PerfInfo

Reserved[25 - sizeof(PPERF_INFO)]

Ist für das System reserviert.

Hinweise

Diese Struktur wird an alle Rückruffunktionen übergeben.

Einzelne Rückruffunktionen werden durch eine Reihe konstanter Werte identifiziert, die als Indizes im ReaderFunction-Array verwendet werden sollen.

Index BESCHREIBUNG
RDF_ATR_PARSE Optional. Die RDF_ATR_PARSE Analysefunktion analysiert eine ATR (Answer-to-Reset) für die smart Karte-Treiberbibliothek, wenn die Treiberbibliothek die Smart Karte-Treiberbibliothek nicht erkennen oder analysieren kann.
RDF_CARD_EJECT Optional. rückruffunktion RDF_CARD_EJECT

Die RDF_CARD_EJECT Rückruffunktion wirft eine eingefügte intelligente Karte aus dem Reader aus.
RDF_CARD_POWER Die RDF_CARD_POWER Rückruffunktion setzt eine eingefügte intelligente Karte zurück oder deaktiviert sie. Es ist obligatorisch, dass Treiber für intelligente Karte-Leser diese Rückruffunktion implementieren.

Bei der Eingabe sollte die Struktur, auf die smartcardExtension verweist, die folgenden Memberwerte aufweisen:

MajorIoControlCode
Sollte den Wert IOCTL_SMARTCARD_POWER haben.
IoRequest.ReplyBufferLength
Sollte die Länge des Puffers enthalten.
MinorIoControlCode
Sollte einen der folgenden Nebencodes haben:
SCARD_COLD_RESET
Führt eine Kaltrücksetzung der intelligenten Karte aus.
SCARD_WARM_RESET
Führt eine warm zurückgesetzte intelligente Karte aus.
SCARD_POWER_DOWN
Schaltet intelligente Karte aus.
In der Ausgabe sollte die Struktur, auf die smartcardExtension verweist, die folgenden Werte aufweisen:
IoRequest.ReplyBuffer
Empfängt die ATR, die vom intelligenten Karte zurückgegeben wird. Darüber hinaus müssen Sie atR in SmartcardExtension->CardCapabilities.ATR.Buffer übertragen, damit die Bibliothek die ATR analysieren kann.
IoRequest.Information
Empfängt die Länge der ATR.
CardCapabilities.ATR.Length
Enthält die Länge der ATR.
RDF_CARD_TRACKING Die RDF_CARD_TRACKING-Rückruffunktion installiert einen Ereignishandler, der jedes Mal nachverfolgt wird, wenn ein Karte in einen Karte Reader eingefügt oder daraus entfernt wird. Es ist obligatorisch, dass Treiber für intelligente Karte-Leser diese Rückruffunktion implementieren.

Nach Erhalt einer IOCTL_SMARTCARD_IS_PRESENT-Anforderung ermittelt die Treiberbibliothek, ob die intelligente Karte bereits vorhanden ist. Wenn die intelligente Karte vorhanden ist, schließt die Treiberbibliothek die Anforderung mit einem status STATUS_SUCCESS ab. Wenn kein intelligenter Karte vorhanden ist, ruft die Treiberbibliothek die Rückruffunktion smart Karte tracking des Lesertreibers auf, und der Readertreiber sucht nach dem intelligenten Karte. Nach dem Initiieren der intelligenten Karte-Nachverfolgung markiert die Treiberbibliothek die Anforderung als status STATUS_PENDING.

Die Treiberbibliothek schließt die Anforderung ab.

WDM-Gerätetreiber

Die entsprechende WDM-Treiberbibliothek fügt einen Zeiger auf die Anforderung in SmartcardExtension-OsData-NotificationIrp>> hinzu. Der Readertreiber muss die Anforderung abschließen, sobald er erkennt, dass eine intelligente Karte eingefügt oder entfernt wurde. Der Readertreiber schließt die Anforderung ab, indem er IoCompleteRequest aufruft. Danach muss der Readertreiber das NotificationIrp-Mitglied von SmartcardExtension –> OsData wieder auf NULL festlegen, um die Treiberbibliothek darüber zu informieren, dass der Readertreiber weitere intelligente Karte-Nachverfolgungsanforderungen akzeptieren kann.

Da dieser Aufruf eine unbegrenzte Dauer haben kann und der Aufrufer die Anforderung beenden kann, bevor er abgeschlossen ist, ist es wichtig, diesen IRP als abbruchfähig zu markieren.

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 Die RDF_IOCTL_VENDOR-Rückruffunktion führt herstellerspezifische IOCTL-Vorgänge aus. Smart Karte Reader-Treiber können diese Rückruffunktion optional implementieren.

Bei der Eingabe muss der Aufrufer die folgenden Werte an die Funktion übergeben:

SmartcardExtension->MajorIoControlCode
Enthält einen herstellerspezifischen IOCTL-Code. Informationen zum Definieren eines anbieterspezifischen IOCTL-Codes finden Sie im Makro SCARD_CTL_CODE in Winsmcrd.h . Beachten Sie, dass der Code zwischen 2048 und 4095 sein muss.
SmartcardExtension->IoRequest.RequestBuffer
Ein Zeiger auf den Eingabepuffer des Benutzers.
SmartcardExtension->IoRequest.RequestBufferLength
Die Größe des Eingabepuffers des Benutzers in Bytes.
SmartcardExtension->IoRequest.ReplyBuffer
Ein Zeiger auf den Ausgabepuffer des Benutzers.
SmartcardExtension->IoRequest.ReplyBufferLength
Die Größe des Ausgabepuffers des Benutzers in Bytes.
SmartcardExtension->IoRequest.Information
Der von der Anforderung angegebene Wert. Muss auf die Anzahl der zurückgegebenen Bytes festgelegt werden.
Wie bei allen anderen IOCTLs sendet eine Benutzermodusanwendung durch Aufrufen der DeviceIoControl-Funktion eine vom Hersteller definierte IOCTL an ein Smart Karte-Lesergerät. Wenn die IOCTL jedoch herstellerdefiniert ist, muss die Anwendung zuerst das Lesegerät für "überlappenden" (d. h. asynchronen) Zugriff öffnen. Die Anwendung muss auch eine OVERLAPPED-Struktur definieren und sie im letzten Argument von DeviceIoControl an das System übergeben (Die OVERLAPPED-Struktur wird auch in der Windows SDK Dokumentation beschrieben.) Wenn das Betriebssystem die E/A-Steuerungsverteilungsroutine des Treibers aufruft, übergibt es eine DIOCPARAMETERS-Struktur an den Treiber. Das lpoOverlapped-Element der DIOCPARAMETERS-Struktur enthält einen Zeiger auf die OVERLAPPED-Struktur.
RDF_READER_SWALLOW Die RDF_READER_SWALLOW Rückruffunktion führt eine mechanische Schwalbe aus, was passiert, wenn die intelligente Karte vollständig in den smart Karte Reader eingefügt wird. Smart Karte Reader-Treiber können diese Rückruffunktion optional implementieren.
RDF_SET_PROTOCOL Die rückruffunktion RDF_SET_PROTOCOL wählt ein Übertragungsprotokoll für die eingefügte smart Karte aus. Smart Karte Reader-Treiber müssen diese Rückruffunktion implementieren.

Bei der Eingabe muss der Aufrufer die folgenden Werte an die Funktion übergeben:

SmartcardExtension->MajorIoControlCode
Enthält IOCTL_SMARTCARD_SET_PROTOCOL.
SmartcardExtension->MinorIoControlCode
Enthält ein bitweises OR mit mindestens einem Protokoll, das vom Aufrufer akzeptiert wird. Der Treiber muss ein Protokoll auswählen, das vom eingefügten smart Karte unterstützt wird. Es wird empfohlen, dass das T = 1-Protokoll Vorrang vor dem T = 0-Protokoll hat.
Wert Bedeutung
SCARD_PROTOCOL_RAW Wählt das rohe Protokoll aus.
SCARD_PROTOCOL_T0 Wählt das ISO T = 0-Protokoll aus.
SCARD_PROTOCOL_T1 Wählt das ISO T = 1-Protokoll aus.
 
SmartcardExtension->IoRequest.ReplyBufferLength
Enthält die Länge des Antwortpuffers.
SmartcardExtension->CardCapabilities.PtsData
Enthält die erforderlichen Parameter zum Ausführen der PTS-Anforderung. Weitere Informationen finden Sie unter PTS_DATA.
Die Anforderung gibt die folgenden Werte zurück:
SmartcardExtension->IoRequest.ReplyBuffer
Enthält das ausgewählte Protokoll.
SmartcardExtension->IoRequest.Information
Legen Sie auf sizeof(ULONG) fest.
Der Aufrufer kann eine Maske akzeptabler Protokolle bereitstellen. Die Rückrufroutine zum Festlegen des Protokolls des Treibers wählt eines der Protokolle in der Maske aus und gibt das ausgewählte Protokoll in SmartcardExtension->IoRequest.ReplyBuffer zurück.
RDF_TRANSMIT Die RDF_TRANSMIT-Rückruffunktion führt Datenübertragungen durch. Smart Karte Reader-Treiber müssen diese Rückruffunktion implementieren.

Bei der Eingabe muss der Aufrufer die folgenden Werte an die Funktion übergeben:

SmartcardExtension->MajorIoControlCode
Enthält IOCTL_SMARTCARD_TRANSMIT.
SmartcardExtension->IoRequest.RequestBuffer
Ein Zeiger auf eine SCARD_IO_REQUEST-Struktur gefolgt von Daten, die an die Karte übertragen werden sollen.
SmartcardExtension->IoRequest.RequestBufferLength
Die Anzahl der Bytes, die an den Karte übertragen werden sollen.
SmartcardExtension->IoRequest.ReplyBufferLength
Die Größe des Antwortpuffers in Bytes.
Die Anforderung gibt die folgenden Werte zurück:
SmartcardExtension->IoRequest.ReplyBuffer
Ein Zeiger auf den Puffer, der die SCARD_IO_REQUEST-Struktur empfängt, sowie das Ergebnis der Karte.
SmartcardExtension->IoRequest.Information
Empfängt die tatsächliche Anzahl von Bytes, die vom intelligenten Karte zurückgegeben werden, sowie die Größe der SCARD_IO_REQUEST-Struktur. Eine Definition der SCARD_IO_REQUEST-Struktur finden Sie unter IOCTL_SMARTCARD_TRANSMIT.
Wenn diese Funktion aufgerufen wird, verweist SmartcardExtension->IoRequest.RequestBuffer auf eine SCARD_IO_REQUEST-Struktur, gefolgt von den zu übertragenden Daten. 
typedef struct _SCARD_IO_REQUEST{
  DWORD  dwProtocol;   // Protocol identifier
  DWORD  cbPciLength;  // Protocol Control Information Length
} SCARD_IO_REQUEST, *PSCARD_IO_REQUEST, *LPSCARD_IO_REQUEST;

Der dwProtocol-Member muss den Protokollbezeichner enthalten, der von einem Aufruf von IOCTL_SMARTCARD_SET_PROTOCOL zurückgegeben wird.

Das cbPciLength-Element enthält die Größe der SCARD_IO_REQUEST-Struktur in Bytes. Die Größe dieser Struktur beträgt in der Regel 8 Byte.

Auf die SCARD_IO_REQUEST-Struktur folgen (Protokoll-)Daten, die an die Karte übertragen werden. Abhängig vom Protokoll, das für die Übertragung verwendet werden soll, bietet die Bibliothek mehrere Unterstützungsfunktionen. Weitere Informationen zu diesen Unterstützungsfunktionen finden Sie unter SmartcardT0Request (WDM) und SmartcardT1Request (WDM).

RequestBuffer und ReplyBuffer zeigen auf denselben Systempuffer. Wenn Sie die Bibliotheksfunktion SmartcardxxRequest und SmartcardxxReply verwenden, überschreiben Sie den Eingabepuffer nicht. Wenn Sie diese Funktionen nicht verwenden, erstellen Sie eine Kopie des RequestBuffers , bevor Sie mit der Übertragung beginnen.

Sie müssen die SCARD_IO_REQUEST-Struktur in den ReplyBuffer-Parameter kopieren, gefolgt von den Daten, die vom Karte empfangen werden. Auch wenn Sie die Funktionen SmartcardxxRequest und SmartcardxxReply verwenden, kopiert die Bibliothek die Struktur für Sie.

Anforderungen

Anforderung Wert
Header smclib.h (einschließen von Smclib.h)