OPENCARDNAMEA-Struktur (winscard.h)
Die OPENCARDNAME--Struktur enthält die Informationen, die die GetOpenCardName-funktion verwendet, um eine Smartcard zu initialisieren, Dialogfeld auswählen. Das Aufrufen SCardUIDlgSelectCard- mit OPENCARDNAME_EX wird empfohlen, GetOpenCardName- mit OPENCARDNAME-aufzurufen. OPENCARDNAME- wird aus Gründen der Abwärtskompatibilität bereitgestellt.
Syntax
typedef struct {
DWORD dwStructSize;
HWND hwndOwner;
SCARDCONTEXT hSCardContext;
LPSTR lpstrGroupNames;
DWORD nMaxGroupNames;
LPSTR lpstrCardNames;
DWORD nMaxCardNames;
LPCGUID rgguidInterfaces;
DWORD cguidInterfaces;
LPSTR lpstrRdr;
DWORD nMaxRdr;
LPSTR lpstrCard;
DWORD nMaxCard;
LPCSTR lpstrTitle;
DWORD dwFlags;
LPVOID pvUserData;
DWORD dwShareMode;
DWORD dwPreferredProtocols;
DWORD dwActiveProtocol;
LPOCNCONNPROCA lpfnConnect;
LPOCNCHKPROC lpfnCheck;
LPOCNDSCPROC lpfnDisconnect;
SCARDHANDLE hCardHandle;
} OPENCARDNAMEA, *POPENCARDNAMEA, *LPOPENCARDNAMEA;
Angehörige
dwStructSize
Gibt die Länge der Struktur in Bytes an. Dieses Element darf nicht NULL-sein.
hwndOwner
Das Fenster, das das Dialogfeld besitzt. Dieses Element kann ein beliebiges gültiges Fensterhandle sein, oder es kann NULL- für den Desktopstandard sein.
hSCardContext
Der Kontext für die Kommunikation mit der SmartcardRessourcen-Manager. Rufen Sie SCardEstablishContext- auf, um den Kontext des Ressourcen-Managers festzulegen, und SCardReleaseContext-, um ihn freizugeben. Dieses Element darf nicht NULL-sein.
lpstrGroupNames
Ein Zeiger auf einen Puffer, der Null-beendete Gruppennamenzeichenfolgen enthält. Die letzte Zeichenfolge im Puffer muss durch 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.
lpstrCardNames
Ein Zeiger auf einen Puffer, der Null-beendete Kartennamenzeichenfolgen enthält. Die letzte Zeichenfolge im Puffer muss durch zwei NULL-Zeichen beendet werden. Jede Zeichenfolge ist der Name einer Karte, die sich befindet.
nMaxCardNames
Die maximale Anzahl von Bytes (ANSI-Version) oder Zeichen (Unicode Version) in der lpstrCardNames Zeichenfolge.
rgguidInterfaces
Reserviert für die zukünftige Verwendung. Wird auf NULL-festgelegt. Ein Array von GUIDs, die die erforderlichen Schnittstellen identifizieren.
cguidInterfaces
Reserviert für die Verwendung von Futures. Wird auf NULL-festgelegt. Die Anzahl der Schnittstellen in der rgguidInterfaces Arrays.
lpstrRdr
Wenn sich die Karte befindet, enthält der lpstrRdr- Puffer den Namen des Lesers, der die gefundene Karte enthält. Der Puffer sollte mindestens 256 Zeichen lang sein.
nMaxRdr
Die Größe des Puffers in Byte (ANSI-Version) oder Zeichen (Unicode--Version) des Puffers, auf den lpstrRdrverweist. Wenn der Puffer zu klein ist, um die Leseinformationen zu enthalten, gibt GetOpenCardName SCARD_E_NO_MEMORY und die erforderliche Größe des Puffers zurück, auf den lpstrRdrverweist.
lpstrCard
Wenn sich die Karte befindet, enthält der lpstrCard- Puffer den Namen der gefundenen Karte. Der Puffer sollte mindestens 256 Zeichen lang sein.
nMaxCard
Die Größe des Puffers in Bytes (ANSI-Version) oder Zeichen (Unicode- Version) des Puffers, auf den lpstrCard-verweist. Wenn der Puffer zu klein ist, um die Karteninformationen zu enthalten, gibt GetOpenCardName SCARD_E_NO_MEMORY und die erforderliche Größe des Puffers in nMaxCard-zurück.
lpstrTitle
Ein Zeiger auf eine Zeichenfolge, die in der Titelleiste des Dialogfelds platziert werden soll. Wenn dieses Element NULL-ist, verwendet das System den Standardtitel "Select Card:".
dwFlags
Eine Reihe von Bitkennzeichnungen, die Sie zum Initialisieren des Dialogfelds verwenden können. Wenn das Dialogfeld zurückgegeben wird, legt es diese Flags fest, um die Eingabe des Benutzers anzugeben. Dieses Element kann eine Kombination aus den folgenden Flags sein.
| Wert | Bedeutung |
|---|---|
|
Zeigt das Dialogfeld nur an, wenn sich die karte, nach der die aufrufende Anwendung durchsucht wird, nicht befindet und für die Verwendung in einem Reader verfügbar ist. Auf diese Weise kann die Karte gefunden, verbunden (entweder über den internen Dialogfeldmechanismus oder die Benutzerrückruffunktionen) und an die aufrufende Anwendung zurückgegeben werden. |
|
Erzwingen Sie unabhängig vom Suchergebnis keine Anzeige der AuswahlkarteBenutzeroberfläche (UI). |
|
Erzwingen der Anzeige der Auswahlkarte Ui, unabhängig vom Suchergebnis. |
pvUserData
Ein ungültiger Zeiger auf Benutzerdaten. Dieser Zeiger wird an den Anrufer in den Routinen "Verbinden", "Überprüfen" und "Trennen" übergeben.
dwShareMode
Wenn lpfnConnect- nicht NULL-ist, werden die dwShareMode- und dwPreferredProtocols-Member ignoriert.
Wenn lpfnConnect-NULL- ist und dwShareMode- ungleich Null ist, anschließend wird ein interner Aufruf an SCardConnect- ausgeführt, der dwShareMode- und dwPreferredProtocols als dwShareMode- und dwPreferredProtocols Parameter verwendet. Wenn die Verbindung erfolgreich ist, wird hCardHandle- auf den von hSCardConnectzurückgegebenen Handle festgelegt.
Wenn lpfnConnect-NULL- ist und dwShareMode- null ist, gibt das Dialogfeld hCardHandle als NULL-zurück.
dwPreferredProtocols
Wird für die interne Verbindung verwendet, wie in dwShareModebeschrieben.
dwActiveProtocol
Gibt das tatsächliche Protokoll zurück, das verwendet wird, wenn das Dialogfeld eine Verbindung mit einer Karte erstellt.
lpfnConnect
Ein Zeiger auf die Kartenverbindungsroutine des Anrufers. Wenn der Aufrufer eine zusätzliche Verarbeitung durchführen muss, um eine Verbindung mit der Karte herzustellen, wird dieser Funktionszeiger auf die Verbindungsfunktion für den Benutzer festgelegt. Wenn die Verbindungsfunktion erfolgreich ist, bleibt die Karte verbunden und initialisiert, und der Kartenziehpunkt wird zurückgegeben.
Der Prototyp für die Verbindungsroutine lautet wie folgt.
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
);
lpfnCheck
Ein Zeiger auf die Kartenüberprüfungsroutine des Anrufers. Wenn keine spezielle Kartenü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, wie durch lpfnDisconnectangegeben.
Wenn die Karte von der Überprüfungsroutine akzeptiert wird, wird TRUE zurückgegeben. Wenn der Benutzer die Karte akzeptiert, werden alle anderen aktuell verbundenen Karten getrennt, wie durch lpfnDisconnectangegeben, und diese Karte wird als die gefundene Karte zurückgegeben. Die gespeicherte Karte bleibt verbunden.
Der Prototyp für die Prüfroutine lautet wie folgt.
Check(
hSCardContext, // the card context passed in the parameter block
hCard, // card handle
pvUserData // pointer to user data passed in the parameter block
);
lpfnDisconnect
Ein Zeiger auf die Kartentrennroutine des Anrufers.
Der Prototyp für die Disconnect-Routine lautet wie folgt.
Disconnect(
hSCardContext, // the card context passed in the parameter block
hCard, // card handle
pvUserData // pointer to user data passed in the parameter block
);
hCardHandle
Ein Handle der verbundenen Karte (entweder über ein internes Dialogfeld verbinden oder ein lpfnConnect Rückruf).
Bemerkungen
Anmerkung
Der winscard.h-Header definiert OPENCARDNAME 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 Code, der nicht codierungsneutral ist, 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 |
|---|---|
| mindestens unterstützte Client- | Windows XP [nur Desktop-Apps] |
| mindestens unterstützte Server- | Windows Server 2003 [Nur Desktop-Apps] |
| Header- | winscard.h |