SCardListReaderGroupsA-Funktion (winscard.h)

Artikel
11/20/2024

Die funktion SCardListReaderGroups stellt die Liste der Lesergruppen bereit, die zuvor im System eingeführt wurden.

Syntax

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

Parameter

[in] hContext

Behandeln Sie die Ressourcen-Manager-Kontext für die Abfrage. Der Ressourcen-Manager-Kontext kann durch einen vorherigen Aufruf von SCardEstablishContextfestgelegt werden.

Wenn dieser Parameter auf NULL-festgelegt ist, ist die Suche nach Lesegruppen nicht auf einen Kontext beschränkt.

[out] mszGroups

Mehrere Zeichenfolgen, die die Lesergruppen auflisten, die für das System definiert sind und für den aktuellen Benutzer auf dem aktuellen Terminalverfügbar sind. Wenn dieser Wert NULL-ist, ignoriert SCardListReaderGroups die in pcchGroupsangegebene Pufferlänge ignoriert, schreibt die Länge des Puffers, der zurückgegeben würde, wenn dieser Parameter nicht NULL-pcchGroupswurde, und gibt einen Erfolgscode zurück.

Wert	Bedeutung
SCARD_ALL_READERS TEXT("SCard$AllReaders\000")	Die Gruppe wird verwendet, wenn beim Auflisten von Lesern kein Gruppenname angegeben wird. Gibt eine Liste aller Leser zurück, unabhängig davon, in welcher Gruppe oder 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 Lesegruppen-APIs geändert werden kann. Es ist nur für Enumerationen vorgesehen.
SCARD_SYSTEM_READERS TEXT("SCard$SystemReaders\000")	Nicht verwendeter Legacywert. Dies ist eine intern verwaltete Gruppe, die nicht mithilfe von Lesegruppen-APIs geändert werden kann. Es ist nur für Enumerationen vorgesehen.

[in, out] pcchGroups

Die Länge des mszGroups Puffers in Zeichen und empfängt die tatsächliche Länge der Mehrzeichenfolgenstruktur, einschließlich aller nachfolgenden NULL- Zeichen. Wenn die Pufferlänge als SCARD_AUTOALLOCATE angegeben wird, wird mszGroups in einen Zeiger in einen Bytezeiger konvertiert und empfängt die Adresse eines Speicherblocks, der die Mehrzeichenfolgenstruktur enthält. Dieser Speicherblock muss mit SCardFreeMemory-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

Eine Gruppe wird nur zurückgegeben, wenn sie mindestens einen Readerenthält. Dies schließt die Gruppe SCard$DefaultReadersein. 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 SmartCard-Datenbankabfragefunktionen.

Beispiele

Das folgende Beispiel zeigt das Auflisten 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.
    // ...
}

Anmerkung

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 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]
Zielplattform-	Fenster
Header-	winscard.h
Library	Winscard.lib
DLL-	Winscard.dll