SCardListCardsW-Funktion (winscard.h)

Artikel
08/27/2023

Die SCardListCards-Funktion durchsucht die Smart Karte-Datenbank und stellt eine Liste der benannten Karten bereit, die zuvor vom Benutzer in das System eingeführt wurden.

Der Aufrufer gibt eine ATR-Zeichenfolge, einen Satz von GuiDs (Interface Identifiers) oder beides an. Wenn sowohl eine ATR-Zeichenfolge als auch ein Bezeichnerarray angegeben werden, entsprechen die zurückgegebenen Karten der bereitgestellten ATR-Zeichenfolge und unterstützen die angegebenen Schnittstellen.

Syntax

LONG SCardListCardsW(
  [in]           SCARDCONTEXT hContext,
  [in, optional] LPCBYTE      pbAtr,
  [in]           LPCGUID      rgquidInterfaces,
  [in]           DWORD        cguidInterfaceCount,
  [out]          WCHAR        *mszCards,
  [in, out]      LPDWORD      pcchCards
);

Parameter

[in] hContext

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

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

[in, optional] pbAtr

Adresse einer ATR-Zeichenfolge, die mit bekannten Karten verglichen werden soll, oder NULL , wenn kein ATR-Abgleich durchgeführt werden soll.

[in] rgquidInterfaces

Array von Bezeichnern (GUIDs) oder NULL , wenn kein Schnittstellenabgleich durchgeführt werden soll. Wenn ein Array bereitgestellt wird, wird nur dann ein Karte Name zurückgegeben, wenn alle angegebenen Bezeichner vom Karte unterstützt werden.

[in] cguidInterfaceCount

Anzahl der Einträge im rgguidInterfaces-Array . Wenn rgguidInterfacesNULL ist, wird dieser Wert ignoriert.

[out] mszCards

Mehrere Zeichenfolgen, die die gefundenen Smartcards auflistet. Wenn dieser Wert NULL ist, ignoriert SCardListCards die in pcchCards angegebene Pufferlänge und gibt die Länge des Puffers zurück, die zurückgegeben worden wäre, wenn dieser Parameter nicht NULL für pcchCards gewesen wäre, und einen Erfolgscode.

[in, out] pcchCards

Länge des mszCards-Puffers in Zeichen. 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 mszCards 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 aufgehoben 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

Diese Funktion wird nicht umgeleitet, aber das Aufrufen der Funktion innerhalb einer Remotedesktopsitzung führt nicht zu einem Fehler. Dies bedeutet nur, dass das Ergebnis nicht vom lokalen Computer, sondern vom Remotecomputer stammt.

Um alle Smartcards zurückzugeben, die in das Subsystem eingeführt wurden, legen Sie pbAtr und rgguidInterfaces auf NULL fest.

Die SCardListCards-Funktion ist eine Datenbankabfragefunktion. Weitere Informationen zu anderen Datenbankabfragefunktionen finden Sie unter Smartcard-Datenbankabfragefunktionen.

Der Aufruf dieser Funktion sollte außerhalb einer Transaktion erfolgen. Wenn eine Anwendung eine Transaktion mit der SCardBeginTransaction-Funktion beginnt und dann diese Funktion aufruft, wird der hCard-Parameter (vom Typ SCARDHANDLE) der SCardBeginTransaction-Funktion zurückgesetzt.

Windows Server 2008 R2 und Windows 7: Das Aufrufen dieser Funktion innerhalb einer Transaktion kann dazu führen, dass Ihr Computer nicht mehr reagiert.

Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Nicht zutreffend.

Beispiele

Das folgende Beispiel zeigt die Auflistung der Smartcards.

LPTSTR pmszCards = NULL;
LPTSTR pCard;
LONG lReturn;
DWORD cch = SCARD_AUTOALLOCATE;

// Retrieve the list of cards.
lReturn = SCardListCards(NULL,
                         NULL,
                         NULL,
                         NULL,
                         (LPTSTR)&pmszCards,
                         &cch );
if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardListCards\n");
    exit(1); // Or other appropriate error action
}
// Do something with the multi string of cards.
// Output the values.
// A double-null terminates the list of values.
pCard = pmszCards;
while ( '\0' != *pCard )
{
    // Display the value.
    printf("%S\n", pCard );
    // Advance to the next value.
    pCard = pCard + wcslen(pCard) + 1;
}

// Remember to free pmszCards (by calling SCardFreeMemory).
// ...

Hinweis

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