SMARTCARD_EXTENSION Struktur (smclib.h)

Die SMARTCARD_EXTENSION Struktur wird sowohl vom Smartcardlesertreiber als auch von der Smartcardtreiberbibliothek verwendet, um auf alle anderen Smartcarddatenstrukturen 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;

Angehörige

Version

Gibt die Version dieser Struktur an.

VendorAttr

Enthält Informationen, die den Lesertreiber identifizieren, z. B. den Herstellernamen, die Einheitennummer und die Seriennummer.

ReaderFunction[16]

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

Ein Zeiger auf ein Array von Rückruffunktionen für Leser. Die Rückruffunktionen, die ein vom Anbieter bereitgestellter Lesetreiber implementieren kann. Ein Lesertreiber stellt diese Rückruffunktionen für die Smartcardbibliotheksroutine, SmartcardDeviceControl-, zur Verfügung, um sie aufzurufen, indem Zeiger in der Smartcard-Geräteerweiterung 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 der eingefügten Smartcard.

LastError

Wird nicht verwendet.

IoRequest

Eine Struktur mit den folgenden Elementen:

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 die 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 Bytes der Daten an, die von der E/A-Anforderung zurückgegeben werden.

MajorIoControlCode

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

MinorIoControlCode

Enthält den Hilfs-E/A-Steuerelementcode.

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 Smartcardleser spezifisch sind.

SmartcardReply

Enthält Daten, die vom Leser stammen.

SmartcardRequest

Enthält den aktuellen Befehl und die Daten, die an die Smartcard 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)]

Reserviert für die Systemverwendung.

Bemerkungen

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	Wahlfrei. Die RDF_ATR_PARSE Analysefunktion analysiert eine Antwort-zu-Zurücksetzung (ATR) für die Smartcardtreiberbibliothek, wenn die Treiberbibliothek die Smartcardtreiberbibliothek nicht erkennen oder analysieren kann.
RDF_CARD_EJECT	Wahlfrei. RDF_CARD_EJECT Rückruffunktion Mit der RDF_CARD_EJECT Rückruffunktion wird eine eingefügte Smartcard vom Leser ausgeworfen.
RDF_CARD_POWER	Die RDF_CARD_POWER Rückruffunktion setzt eine eingefügte Smartcard zurück oder deaktiviert sie. Es ist obligatorisch, wenn Smartcardlesertreiber diese Rückruffunktion implementieren. Bei eingaben sollte die Struktur, auf die SmartcardExtens ion verweist, die folgenden Memberwerte aufweisen: MajorIoControlCode- Sollte den Wert IOCTL_SMARTCARD_POWERhaben. IoRequest.ReplyBufferLength Sollte die Länge des Puffers enthalten. MinorIoControlCode- Sollte über einen der folgenden Nebencodes verfügen: SCARD_COLD_RESET Führt eine kalte Zurücksetzung der Smartcard durch. SCARD_WARM_RESET Führt eine warme Zurücksetzung der Smartcard durch. SCARD_POWER_DOWN Deaktiviert die Smartcard-Stromversorgung. Bei der Ausgabe sollte die Struktur, auf die SmartcardExtension verweist, die folgenden Werte aufweisen: IoRequest.ReplyBuffer Empfängt den ATR, der von der Smartcard zurückgegeben wird. Darüber hinaus müssen Sie den ATR auf SmartcardExtension->CardCapabilities.ATR.Buffer-übertragen, damit die Bibliothek den ATR analysieren kann. IoRequest.Information Empfängt die Länge des ATR. CardCapabilities.ATR.Length Enthält die Länge des ATR.
RDF_CARD_TRACKING	Die RDF_CARD_TRACKING Rückruffunktion installiert einen Ereignishandler, um jedes Mal nachzuverfolgen, wenn eine Karte in einen Kartenleser eingefügt oder daraus entfernt wird. Es ist obligatorisch, wenn Smartcardlesertreiber diese Rückruffunktion implementieren. Nach Erhalt einer IOCTL_SMARTCARD_IS_PRESENT Anforderung bestimmt die Treiberbibliothek, ob die Smartcard bereits vorhanden ist. Wenn die Smartcard vorhanden ist, schließt die Treiberbibliothek die Anforderung mit dem Status STATUS_SUCCESS ab. Wenn keine Smartcard vorhanden ist, ruft die Treiberbibliothek die Smartcard-Tracking-Rückruffunktion des Lesertreibers auf, und der Lesertreiber sucht nach der Smartcard. Nach dem Initiieren der Smartcardverfolgung kennzeichnet die Treiberbibliothek die Anforderung als status von STATUS_PENDING. Die Treiberbibliothek schließt die Anforderung ab. WDM-Gerätetreiber Die entsprechende WDM-Treiberbibliothek fügt der Anforderung in SmartcardExtension->OsData->NotificationIrpeinen Zeiger hinzu. Der Lesertreiber muss die Anforderung abschließen, sobald erkannt wird, dass eine Smartcard eingefügt oder entfernt wurde. Der Lesertreiber schließt die Anforderung ab, indem er IoCompleteRequestaufruft. Danach muss der Lesertreiber das NotificationIrp Mitglied von SmartcardExtension festlegen –> OsData zurück zu NULL-, um die Treiberbibliothek darüber zu informieren, dass der Lesertreiber weitere Smartcard-Nachverfolgungsanforderungen annehmen kann. Da dieser Aufruf eine unbestimmte Dauer haben kann und der Aufrufer die Anforderung beenden kann, bevor sie abgeschlossen ist, ist es wichtig, diesen IRP als abbruchfähig zu kennzeichnen. 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 anbieterspezifische IOCTL-Vorgänge aus. Sie ist optional für Smartcardlesertreiber, um diese Rückruffunktion zu 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 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 bereitgestellte Wert. Muss auf die Anzahl der zurückgegebenen Bytes festgelegt werden. Wie bei allen anderen IOCTLs verteilt eine Benutzermodusanwendung ein vom Anbieter definiertes IOCTL an ein Smartcardlesergerät, indem die DeviceIoControl--Funktion aufgerufen wird. Wenn die IOCTL vom Hersteller definiert ist, muss die Anwendung jedoch zuerst das Lesegerät für den "überlappenden" (d. h. asynchronen) Zugriff öffnen. Die Anwendung muss auch eine ÜBERLAPPENDE 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-Kontrollroutine des Treibers aufruft, übergibt es eine DIOCPARAMETERS-Struktur an den Treiber. Das lpoOverlapped- Element der DIOCPARAMETERS-Struktur enthält einen Zeiger auf die ÜBERLAPPENDE Struktur.
RDF_READER_SWALLOW	Die RDF_READER_SWALLOW Rückruffunktion führt eine mechanische Schwalbenfunktion durch, was geschieht, wenn die Smartcard vollständig in den Smartcardleser eingefügt wird. Sie ist optional für Smartcardlesertreiber, um diese Rückruffunktion zu implementieren.
RDF_SET_PROTOCOL	Die RDF_SET_PROTOCOL Rückruffunktion wählt ein Übertragungsprotokoll für die eingefügte Smartcard aus. Smartcardlesertreiber 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 ODER eines oder mehrerer Protokolle, als der Aufrufer akzeptiert. Der Treiber muss ein Protokoll auswählen, das von der eingefügten Smartcard 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 Wird auf Größe von(ULONG) festgelegt. Der Aufrufer kann eine Maske akzeptabler Protokolle bereitstellen. Die Set-Protokollrückrufroutine des Treibers wählt eines der Protokolle in der Maske aus und gibt das ausgewählte Protokoll in SmartcardExtension->IoRequest.ReplyBufferzurück.
RDF_TRANSMIT	Die RDF_TRANSMIT Rückruffunktion führt Datenübertragungen durch. Smartcardlesertreiber 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 die 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 Byte, die von der Smartcard 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; Das 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 Byte. Die Größe dieser Struktur beträgt in der Regel 8 Byte. Auf die SCARD_IO_REQUEST Struktur folgen (Protokolldaten), die an die Karte übertragen werden sollen. Je nach Protokoll, das für die Übertragung verwendet werden soll, bietet die Bibliothek mehrere Supportfunktionen. Weitere Informationen zu diesen Unterstützungsfunktionen finden Sie unter SmartcardT0Request (WDM) und SmartcardT1Request (WDM). RequestBuffer und ReplyBuffer auf denselben Systempuffer zeigen. Wenn Sie die Bibliotheksfunktion SmartcardxxRequest und SmartcardxxReplyverwenden, überschreiben Sie den Eingabepuffer nicht. Wenn Sie diese Funktionen nicht verwenden, erstellen Sie eine Kopie der RequestBuffer-, bevor Sie mit übertragungen beginnen. Sie müssen die SCARD_IO_REQUEST Struktur in den ReplyBuffer Parameter kopieren, gefolgt von den von der Karte empfangenen Daten. Wenn Sie die SmartcardxxRequest- und SmartcardxxReply--Funktionen verwenden, kopiert die Bibliothek die Struktur für Sie.

Anforderungen

Anforderung	Wert
Header-	smclib.h (include Smclib.h)