SCardListReadersA-Funktion (winscard.h)

Artikel
08/27/2023

Die SCardListReaders-Funktion stellt die Liste der Leser innerhalb einer Gruppe von benannten Lesergruppen bereit, wodurch Duplikate beseitigt werden.

Der Aufrufer stellt eine Liste von Lesergruppen bereit und empfängt die Liste der Leser innerhalb der benannten Gruppen. Nicht erkannte Gruppennamen werden ignoriert. Diese Funktion gibt nur Leser innerhalb der benannten Gruppen zurück, die derzeit an das System angefügt sind und zur Verwendung zur Verfügung stehen.

Syntax

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

Parameter

[in] hContext

Handle, das den Ressourcen-Manager-Kontext für die Abfrage identifiziert. Der Ressourcen-Manager-Kontext kann durch einen vorherigen Aufruf von SCardEstablishContext festgelegt werden.

Wenn dieser Parameter auf NULL festgelegt ist, ist die Suche nach Lesern nicht auf einen kontext beschränkt.

[in, optional] mszGroups

Die Namen der Lesergruppen, die für das System definiert sind, sind mehrzeichenfolgenseitig. Verwenden Sie einen NULL-Wert , um alle Leser im System aufzulisten (d. a. die Gruppe SCard$AllReaders).

Wert	Bedeutung
SCARD_ALL_READERS TEXT("SCard$AllReaders\000")	Gruppe, die verwendet wird, wenn beim Auflisten von Lesern kein Gruppenname angegeben wird. Gibt eine Liste aller Leser zurück, unabhängig davon, in welcher Gruppe oder In welcher Gruppe sich die Leser befinden.
SCARD_DEFAULT_READERS TEXT("SCard$DefaultReaders\000")	Standardgruppe, der alle Leser hinzugefügt werden, wenn sie in das System eingeführt werden.
SCARD_LOCAL_READERS TEXT("SCard$LocalReaders\000")	Nicht verwendeter Legacywert. Dies ist eine intern verwaltete Gruppe, die nicht mithilfe von Lesergruppen-APIs geändert werden kann. Sie ist nur für die Enumeration vorgesehen.
SCARD_SYSTEM_READERS TEXT("SCard$SystemReaders\000")	Nicht verwendeter Legacywert. Dies ist eine intern verwaltete Gruppe, die nicht mithilfe von Lesergruppen-APIs geändert werden kann. Sie ist nur für die Enumeration vorgesehen.

[out] mszReaders

Mehrere Zeichenfolgen, die die Karte Leser innerhalb der angegebenen Lesergruppen auflistet. Wenn dieser Wert NULL ist, ignoriert SCardListReaders die in pcchReaders angegebene Pufferlänge, schreibt die Länge des Puffers, die zurückgegeben worden wäre, wenn dieser Parameter nicht NULL für pcchReaders gewesen wäre, und gibt einen Erfolgscode zurück.

[in, out] pcchReaders

Länge des mszReaders-Puffers in Zeichen. Dieser Parameter empfängt die tatsächliche Länge der Struktur mit mehreren Zeichenfolgen, einschließlich aller nachfolgenden 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 Mehrzeichenfolgenstruktur enthält. Dieser Speicherblock muss mit SCardFreeMemory verwaltet werden.

Rückgabewert

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

Rückgabecode/-wert	BESCHREIBUNG
Erfolgreich 0 (0x0)	SCARD_S_SUCCESS
Die Gruppe enthält keine Leser 2148532270 (0x8010002E)	SCARD_E_NO_READERS_AVAILABLE
Der angegebene Reader steht derzeit nicht zur Verwendung zur Verfügung. 2148532247 (0x80100017)	SCARD_E_READER_UNAVAILABLE
Andere	Ein Fehlercode. Weitere Informationen finden Sie unter Smartcard-Rückgabewerte.

Hinweise

Die SCardListReaders-Funktion ist eine Datenbankabfragefunktion. Weitere Informationen zu anderen Datenbankabfragefunktionen finden Sie unter Abfragefunktionen für SmartCard-Datenbanken.

Beispiele

Das folgende Beispiel zeigt die Auflistung der Reader.

LPTSTR          pmszReaders = NULL;
LPTSTR          pReader;
LONG            lReturn, lReturn2;
DWORD           cch = SCARD_AUTOALLOCATE;

// Retrieve the list the readers.
// hSC was set by a previous call to SCardEstablishContext.
lReturn = SCardListReaders(hSC,
                           NULL,
                           (LPTSTR)&pmszReaders,
                           &cch );
switch( lReturn )
{
    case SCARD_E_NO_READERS_AVAILABLE:
        printf("Reader is not in groups.\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( hSC,
                                   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 SCardListReaders 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]
Zielplattform	Windows
Kopfzeile	winscard.h
Bibliothek	Winscard.lib
DLL	Winscard.dll