SCardListReadersWithDeviceInstanceIdA-Funktion (winscard.h)

Artikel
08/27/2023

Die Funktion SCardListReadersWithDeviceInstanceId ruft die Liste der Leser ab, die ein Gerät instance Id bereitgestellt haben. Diese Funktion wirkt sich nicht auf den Zustand des Readers aus.

Syntax

LONG SCardListReadersWithDeviceInstanceIdA(
  [in]            SCARDCONTEXT hContext,
  [in]            LPCSTR       szDeviceInstanceId,
  [out, optional] LPSTR        mszReaders,
  [in, out]       LPDWORD      pcchReaders
);

Parameter

[in] hContext

Handle, das den Ressourcen-Manager-Kontext für die Abfrage identifiziert. Sie können den Ressourcen-Manager-Kontext durch einen vorherigen Aufruf der SCardEstablishContext-Funktion festlegen. Dieser Parameter darf nicht NULL sein.

[in] szDeviceInstanceId

Geräte-instance-ID des Lesers. Sie können diesen Wert abrufen, indem Sie die SCardGetReaderDeviceInstanceId-Funktion mit dem Namen des Lesers oder die SetupDiGetDeviceInstanceId-Funktion aus dem DDK aufrufen.

[out, optional] mszReaders

Eine mehrfache Zeichenfolge, die die Leser des intelligenten Karte innerhalb des angegebenen Geräte-instance-Bezeichners enthält. Wenn dieser Wert NULL ist, ignoriert die Funktion die im pcchReaders-Parameter angegebene Pufferlänge, schreibt die Länge des Puffers, der zurückgegeben worden wäre, wenn dieser Parameter nicht NULL gewesen wäre, in pcchReaders und gibt einen Erfolgscode zurück.

[in, out] pcchReaders

Die Länge des mszReaders-Puffers in Zeichen. Dieser Parameter empfängt die tatsächliche Länge der Struktur mit mehreren Zeichenfolgen, einschließlich aller endenden NULL-Zeichen. Wenn die Pufferlänge als SCARD_AUTOALLOCATE angegeben wird, wird mszReaders in einen Zeiger auf einen Bytezeiger konvertiert und empfängt die Adresse eines Speicherblocks, der die Struktur mit mehreren Zeichenfolgen enthält. Wenn Sie mit der Verwendung dieses Speichers fertig sind, haben Sie die Zuordnung mithilfe der SCardFreeMemory-Funktion aufgehoben.

Rückgabewert

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

Rückgabecode	BESCHREIBUNG
Erfolgreich	SCARD_S_SUCCESS.
Fehler	Ein Fehlercode. Weitere Informationen finden Sie unter Smartcard-Rückgabewerte.

Hinweise

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

Beispiele


szDeviceInstanceIdcchReaderNameLONG     lReturn, lReturn2;

LPTSTR   pmszReaders = NULL;
LPTSTR   pReader = NULL;WCHAR
DWORD    cchReaderName = SCARD_AUTOALLOCATE;

// Retrieve the reader’s name from it’s device instance ID
// hContext was set by a previous call to SCardEstablishContext. 

// szDeviceInstanceId was obtained by calling SetupDiGetDeviceInstanceId
lReturn = SCardListReadersWithDeviceInstanceId (hContext,
                         szDeviceInstanceId,
                         (LPTSTR)&pmszReaders,
                         &cchReaderName);

switch( lReturn )
{
    case SCARD_E_NO_READERS_AVAILABLE:
        printf("No readers have the provided device instance ID.\n");
        // Take appropriate action.
        // ...
        break;

    case SCARD_S_SUCCESS:
        // Do something with the multi string of readers.
        // Output the values.
        // A double-null terminates the list of values.
        pReader = pmszReaders;
        while ( '\0' != *pReader )
        {
            // Display the value.
            printf("Reader: %S\n", pReader );
            // Advance to the next value.
            pReader = pReader + wcslen((wchar_t *)pReader) + 1;
        }
        // Free the memory.
        lReturn2 = SCardFreeMemory( hContext,
                                   pmszReaders );
        if ( SCARD_S_SUCCESS != lReturn2 )
            printf("Failed SCardFreeMemory\n");
        break;

default:
        printf("Failed SCardListReaders\n");
        // Take appropriate action.
        // ...
        break;

Hinweis

Der winscard.h-Header definiert SCardListReadersWithDeviceInstanceId 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


Unterstützte Mindestversion (Client)	Windows 8 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winscard.h

Freigeben über