SCardListCardsA-Funktion (winscard.h)
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, stimmen die zurückgegebenen Karten mit der angegebenen ATR-Zeichenfolge überein und unterstützen die angegebenen Schnittstellen.
Syntax
LONG SCardListCardsA(
[in] SCARDCONTEXT hContext,
[in, optional] LPCBYTE pbAtr,
[in] LPCGUID rgquidInterfaces,
[in] DWORD cguidInterfaceCount,
[out] CHAR *mszCards,
[in, out] LPDWORD pcchCards
);
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 Karten nicht auf einen beliebigen Kontext beschränkt.
[in, optional] pbAtr
Adresse einer ATR-Zeichenfolge zum Vergleich mit bekannten Karten oder NULL , wenn kein ATR-Abgleich durchgeführt werden soll.
[in] rgquidInterfaces
Array of Identifiers (GUIDs) oder NULL , wenn kein Schnittstellenabgleich durchgeführt werden soll. Wenn ein Array angegeben wird, wird ein Karte Name nur zurückgegeben, wenn alle angegebenen Bezeichner vom Karte unterstützt werden.
[in] cguidInterfaceCount
Anzahl der Einträge im Array rgguidInterfaces . 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 und einen Erfolgscode gewesen wäre.
[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 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 | BESCHREIBUNG |
|---|---|
|
SCARD_S_SUCCESS. |
|
Ein Fehlercode. Weitere Informationen finden Sie unter Smartcard-Rückgabewerte. |
Hinweise
Diese Funktion wird nicht umgeleitet, aber das Aufrufen der Funktion in einer Remotedesktopsitzung führt nicht zu einem Fehler. Dies bedeutet nur, dass das Ergebnis vom Remotecomputer statt vom lokalen Computer 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 Abfragefunktionen für SmartCard-Datenbanken.
Das Aufrufen dieser Funktion sollte außerhalb einer Transaktion erfolgen. Wenn eine Anwendung eine Transaktion mit der SCardBeginTransaction-Funktion beginnt und dann diese Funktion aufruft, setzt sie den hCard-Parameter (vom Typ SCARDHANDLE) der SCardBeginTransaction-Funktion zurück.
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 eine 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 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 |