SCardListCardsA-Funktion (winscard.h)

Die SCardListCards--Funktion durchsucht die Smartcarddatenbank 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 Schnittstellenbezeichnern (GUIDs) 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 SCardListCardsA(
  [in]           SCARDCONTEXT hContext,
  [in, optional] LPCBYTE      pbAtr,
  [in]           LPCGUID      rgquidInterfaces,
  [in]           DWORD        cguidInterfaceCount,
  [out]          CHAR         *mszCards,
  [in, out]      LPDWORD      pcchCards
);

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 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 ausgeführt werden soll.

[in] rgquidInterfaces

Array von Bezeichnern (GUIDs) oder NULL-, wenn kein Schnittstellenabgleich ausgeführt werden soll. Wenn ein Array angegeben wird, wird ein Kartenname nur zurückgegeben, wenn alle angegebenen Bezeichner von der Karte unterstützt werden.

[in] cguidInterfaceCount

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

[out] mszCards

Mehrere Zeichenfolgen, die die gefundenen Smart cards auflisten. Wenn dieser Wert NULL-ist, ignoriert SCardCards die pufferlänge, die in pcchCardsangegeben wird, und gibt die Länge des Puffers zurück, der zurückgegeben wurde, wenn dieser Parameter nicht NULL- pcchCards und einen Erfolgscode .

[in, out] pcchCards

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

Bemerkungen

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 im 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.

Das Aufrufen dieser Funktion sollte außerhalb einer Transaktion erfolgen. Wenn eine Anwendung eine Transaktion mit der SCardBeginTransaction--Funktion beginnt und diese Funktion aufruft, setzt sie den hCard Parameter (vom Typ SCARDHANDLE) der SCardBeginTransaction--Funktion zurück.

Windows Server 2008 R2 und Windows 7: 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 anwendbar.

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).
// ...

Anforderungen

Siehe auch

SCardEstablishContext-

SCardFreeMemory-

SCardGetProviderId-

SCardListInterfaces

SCardListReaderGroups

SCardListReaders-