SCardListReaderGroupsA-Funktion (winscard.h)

Artikel
08/27/2023

Die SCardListReaderGroups-Funktion stellt die Liste der Lesergruppen bereit, die zuvor in das System eingeführt wurden.

Syntax

LONG SCardListReaderGroupsA(
  [in]      SCARDCONTEXT hContext,
  [out]     LPSTR        mszGroups,
  [in, out] LPDWORD      pcchGroups
);

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 Lesergruppen nicht auf einen beliebigen Kontext beschränkt.

[out] mszGroups

Mit mehreren Zeichenfolgen werden die Lesergruppen aufgelistet, die für das System definiert und für den aktuellen Benutzer im aktuellen Terminal verfügbar sind. Wenn dieser Wert NULL ist, ignoriert SCardListReaderGroups die in pcchGroups angegebene Pufferlänge, schreibt die Länge des Puffers, die zurückgegeben worden wäre, wenn dieser Parameter nicht NULL an pcchGroups gewesen wäre, und gibt einen Erfolgscode zurück.

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.

[in, out] pcchGroups

Länge des mszGroups-Puffers in Zeichen und 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 mszGroups in einen Zeiger auf einen Bytezeiger konvertiert und empfängt die Adresse eines Speicherblocks, der die Struktur mit mehreren Zeichenfolgen 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	BESCHREIBUNG
Erfolgreich	SCARD_S_SUCCESS.
Fehler	Ein Fehlercode. Weitere Informationen finden Sie unter Smartcard-Rückgabewerte.

Hinweise

Eine Gruppe wird nur zurückgegeben, wenn sie mindestens einen Leser enthält. Dies schließt die Gruppe SCard$DefaultReaders ein. Die Gruppe SCard$AllReaders kann nicht zurückgegeben werden, da sie nur implizit vorhanden ist.

Die SCardListReaderGroups-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 Lesergruppen.

LPTSTR          pmszReaderGroups = NULL;
LPTSTR          pReaderGroup;
LONG            lReturn;
DWORD           cch = SCARD_AUTOALLOCATE;
    
// Retrieve the list the reader groups.
// hSC was set by a previous call to SCardEstablishContext.
lReturn = SCardListReaderGroups(hSC,
                                (LPTSTR)&pmszReaderGroups,
                                &cch );
if ( SCARD_S_SUCCESS != lReturn )
    printf("Failed SCardListReaderGroups\n");
else
{
    // Do something with the multi string of reader groups.
    // Output the values.
    // A double-null terminates the list of values.
    pReaderGroup = pmszReaderGroups;
    while ( '\0' != *pReaderGroup )
    {
        // Display the value.
        printf("%S\n", pReaderGroup );
        // Advance to the next value.
        pReaderGroup = pReaderGroup + wcslen((wchar_t *) pReaderGroup) + 1;
    }

    // Remember to free pmszReaderGroups by a call to SCardFreeMemory.
    // ...
}

Hinweis

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