OPENCARD_SEARCH_CRITERIAA-Struktur (winscard.h)

Artikel
03/06/2024

Die OPENCARD_SEARCH_CRITERIA-Struktur wird von der Funktion SCardUIDlgSelectCard verwendet, um Karten zu erkennen, die die vom Aufrufer festgelegten Anforderungen erfüllen. Sie können jedoch SCardUIDlgSelectCard aufrufen, ohne diese Struktur zu verwenden.

Syntax

typedef struct {
  DWORD          dwStructSize;
  LPSTR          lpstrGroupNames;
  DWORD          nMaxGroupNames;
  LPCGUID        rgguidInterfaces;
  DWORD          cguidInterfaces;
  LPSTR          lpstrCardNames;
  DWORD          nMaxCardNames;
  LPOCNCHKPROC   lpfnCheck;
  LPOCNCONNPROCA lpfnConnect;
  LPOCNDSCPROC   lpfnDisconnect;
  LPVOID         pvUserData;
  DWORD          dwShareMode;
  DWORD          dwPreferredProtocols;
} OPENCARD_SEARCH_CRITERIAA, *POPENCARD_SEARCH_CRITERIAA, *LPOPENCARD_SEARCH_CRITERIAA;

Member

dwStructSize

Die Länge der Struktur in Bytes. Darf nicht NULL sein.

lpstrGroupNames

Ein Zeiger auf einen Puffer, der NULL-beendete Gruppennamenzeichenfolgen enthält. Die letzte Zeichenfolge im Puffer muss mit zwei NULL-Zeichen beendet werden. Jede Zeichenfolge ist der Name einer Gruppe von Karten, die in die Suche einbezogen werden soll. Wenn lpstrGroupNamesNULL ist, wird die Standardgruppe (Scard$DefaultReaders) durchsucht.

nMaxGroupNames

Die maximale Anzahl von Bytes (ANSI-Version) oder Zeichen (Unicode-Version ) in der lpstrGroupNames-Zeichenfolge .

rgguidInterfaces

Für die zukünftige Verwendung reserviert. Ein Array von GUIDs, das die erforderlichen Schnittstellen identifiziert. Legen Sie dieses Element auf NULL fest.

cguidInterfaces

Für die zukünftige Verwendung reserviert. Die Anzahl der Schnittstellen im rgguidInterfaces-Array . Legen Sie dieses Element auf NULL fest.

lpstrCardNames

Ein Zeiger auf einen Puffer, der NULL-beendete Karte Namenszeichenfolgen enthält. Die letzte Zeichenfolge im Puffer muss mit zwei NULL-Zeichen beendet werden. Jede Zeichenfolge ist der Name einer Karte, die sich befinden soll.

nMaxCardNames

Die maximale Anzahl von Bytes (ANSI-Version) oder Zeichen (Unicode-Version) in der lpstrGroupNames-Zeichenfolge .

lpfnCheck

Ein Zeiger auf die Karte Überprüfungsroutine des Aufrufers. Wenn keine besondere Karte Überprüfung erforderlich ist, ist dieser Zeiger NULL. Wenn die Karte von der Überprüfungsroutine abgelehnt wird, wird FALSE zurückgegeben, und die Karte wird getrennt. Wenn die Karte von der Überprüfungsroutine akzeptiert wird, wird TRUE zurückgegeben.

Der Prototyp für die Überprüfungsroutine lautet wie folgt.

Boolean Check(
  hSCardContext, // the card context passed in the parameter block
  hCard,         // card handle
  pvUserData     // pointer to user data passed in the parameter block
);

lpfnConnect

Ein Zeiger auf die Karte Verbindungsroutine des Aufrufers. Wenn der Aufrufer zusätzliche Verarbeitung ausführen muss, um eine Verbindung mit dem Karte herzustellen, wird dieser Funktionszeiger auf die Verbindungsfunktion des Benutzers festgelegt. Wenn die Verbindungsfunktion erfolgreich ist, bleibt die Karte verbunden und initialisiert, und das Karte Handle wird zurückgegeben.

Der Prototyp für die Connect-Routine sieht wie folgt aus.

Connect(
  hSCardContext, // the card context passed in the parameter block
  szReader,      // the name of the reader
  mszCards,      // multiple string that contains
                 //    the possible card names in the reader
  pvUserData     // pointer to user data passed in parameter block
);

lpfnDisconnect

Ein Zeiger auf die Karte Verbindungsroutine des Aufrufers.

Der Prototyp für die Trennungsroutine sieht wie folgt aus.

Disconnect(
  hSCardContext, // the card context passed in the parameter block
  hCard,         // card handle
  pvUserData     // pointer to user data passed in the parameter block
);

Hinweis Wenn Sie lpfnConnect, lpfnCheck und lpfnDisconnect verwenden, sollten alle drei Rückrufprozeduren vorhanden sein. Die Verwendung dieser Rückrufe ermöglicht eine weitere Überprüfung, ob die aufrufende Anwendung die entsprechende Karte gefunden hat. Dies ist der beste Weg, um sicherzustellen, dass die geeignete Karte ausgewählt wird. Wenn Sie jedoch einen Wert verwenden, der für lpfnCheck nicht NULL ist, müssen sowohl lpfnConnect als auch lpfnDisconnect nicht NULL sein (und pvUserData sollte ebenfalls angegeben werden), oder dwShareMode und dwPreferredProtocols müssen beide festgelegt werden.

pvUserData

Void-Zeiger auf Benutzerdaten. Dieser Zeiger wird an den Aufrufer in den Routinen Verbinden, Überprüfen und Trennen zurückgegeben.

dwShareMode

Wenn lpfnConnect nicht NULL ist, werden die Elemente dwShareMode und dwPreferredProtocols ignoriert. Wenn lpfnConnectNULL und dwShareMode nonzero ist, wird ein interner Aufruf von SCardConnect ausgeführt, der dwShareMode und dwPreferredProtocols als Parameter verwendet.

dwPreferredProtocols

Wird für die interne Verbindung verwendet, wie in dwShareMode beschrieben.

Hinweise

Hinweis

Der winscard.h-Header definiert OPENCARD_SEARCH_CRITERIA als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Kopfzeile	winscard.h

Weitere Informationen

OPENCARDNAME_EX

SCardUIDlgSelectCard

Share via