SCardGetReaderDeviceInstanceIdA-Funktion (winscard.h)

Artikel
11/20/2024

Die SCardGetReaderDeviceInstanceId Funktion ruft den Geräteinstanzbezeichner des Kartenlesers für den angegebenen Lesernamen ab. Diese Funktion wirkt sich nicht auf den Status des Readers aus.

Syntax

LONG SCardGetReaderDeviceInstanceIdA(
  [in]            SCARDCONTEXT hContext,
  [in]            LPCSTR       szReaderName,
  [out, optional] LPSTR        szDeviceInstanceId,
  [in, out]       LPDWORD      pcchDeviceInstanceId
);

Parameter

[in] hContext

Behandeln Sie dies, um den Ressourcen-Manager-Kontext für die Abfrage zu identifizieren. Sie können den Ressourcen-Manager-Kontext durch einen vorherigen Aufruf der SCardEstablishContext-Funktion festlegen. Dieser Parameter kann nicht NULL-werden.

[in] szReaderName

Lesename. Sie können diesen Wert abrufen, indem Sie die funktion SCardListReaders aufrufen.

[out, optional] szDeviceInstanceId

Puffer, der die Geräteinstanz-ID des Readers empfängt. Wenn dieser Wert NULL-ist, ignoriert die Funktion die pufferlänge, die in cchDeviceInstanceId Parameter angegeben wird, schreibt die Länge des Puffers, der zurückgegeben wurde, wenn dieser Parameter nicht NULLcchDeviceInstanceIdwurde und einen Erfolgscode zurückgibt.

[in, out] pcchDeviceInstanceId

Länge des szDeviceInstanceId- Puffers in Zeichen, einschließlich des NULL Terminator. Wenn die Pufferlänge als SCARD_AUTOALLOCATE angegeben wird, wird der szDeviceInstanceId Parameter in einen Zeiger auf einen Bytezeiger konvertiert und empfängt die Adresse eines Speicherblocks, der die Instanz-ID enthält. Dieser Speicherblock muss mit der SCardFreeMemory-funktion behandelt werden.

Rückgabewert

Diese Funktion gibt unterschiedliche Werte zurück, je nachdem, ob sie erfolgreich ist oder fehlschlägt.

Rückgabecode	Beschreibung
Erfolg	SCARD_S_SUCCESS.
Fehler	Fehlercode. Weitere Informationen finden Sie unter Smartcard-Rückgabewerte.

Bemerkungen

Diese Funktion wird nicht umgeleitet. Beim Aufrufen der SCardGetReaderDeviceInstanceId- Funktion in einer Remotedesktopsitzung tritt ein Fehler mit dem SCARD_E_READER_UNAVAILABLE Fehlercode auf.

Beispiele


LONG     lReturn;
LPTSTR   szReaderName = "USB Smart Card Reader 0";
WCHAR    szDeviceInstanceId[256];
DWORD    cchDeviceInstanceId = 256;

// Retrieve the reader's device instance ID.
// hContext was set by a previous call to SCardEstablishContext.
lReturn = SCardGetReaderDeviceInstanceId (hContext,
                         szReaderName,
                         szDeviceInstanceId,
                         &cchDeviceInstanceId);

if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardGetReaderDeviceInstanceId - %x\n", lReturn);
    // Take appropriate action.
}

Anmerkung

Der winscard.h-Header definiert SCardGetReaderDeviceInstanceId 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 8 [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2012 [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winscard.h

Freigeben über