SCardLocateCardsA-Funktion (winscard.h)
Die SCardLocateCards-Funktion durchsucht die im rgReaderStates-Parameter aufgeführten Leser nach einem Karte mit einer ATR-Zeichenfolge, die mit einem der in mszCards angegebenen Karte Namen übereinstimmt, und gibt sofort mit dem Ergebnis zurück.
Syntax
LONG SCardLocateCardsA(
[in] SCARDCONTEXT hContext,
[in] LPCSTR mszCards,
[in, out] LPSCARD_READERSTATEA rgReaderStates,
[in] DWORD cReaders
);
Parameter
[in] hContext
Ein Handle, das den Ressourcen-Manager-Kontext identifiziert. Der Ressourcen-Manager-Kontext wird durch einen vorherigen Aufruf von SCardEstablishContext festgelegt.
[in] mszCards
Eine mehrfache Zeichenfolge, die die Namen der zu durchsuchenden Karten enthält.
[in, out] rgReaderStates
Ein Array von SCARD_READERSTATE Strukturen, die bei der Eingabe die zu durchsuchenden Leser angeben und bei der Ausgabe das Ergebnis empfängt.
[in] cReaders
Die Anzahl der Elemente im rgReaderStates-Array .
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
Dieser Dienst ist besonders nützlich, wenn er in Verbindung mit SCardGetStatusChange verwendet wird. Wenn keine übereinstimmenden Karten mithilfe von SCardLocateCards gefunden werden, kann die aufrufende Anwendung SCardGetStatusChange verwenden, um auf Karte Verfügbarkeitsänderungen zu warten.
Die SCardLocateCards-Funktion ist eine intelligente Karte Tracking-Funktion. Weitere Informationen zu anderen Nachverfolgungsfunktionen finden Sie unter Smartcard-Nachverfolgungsfunktionen.
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 das Auffinden von Smartcards.
// Copyright (C) Microsoft. All rights reserved.
#include <stdio.h>
#include <winscard.h>
#include <tchar.h>
#pragma comment(lib, "winscard.lib")
HRESULT __cdecl main()
{
HRESULT hr = S_OK;
LPTSTR szReaders, szRdr;
DWORD cchReaders = SCARD_AUTOALLOCATE;
DWORD dwI, dwRdrCount;
SCARD_READERSTATE rgscState[MAXIMUM_SMARTCARD_READERS];
TCHAR szCard[MAX_PATH];
SCARDCONTEXT hSC;
LONG lReturn;
// Establish the card to watch for.
// Multiple cards can be looked for, but
// this sample looks for only one card.
_tcscat_s ( szCard, MAX_PATH * sizeof(TCHAR), TEXT("GemSAFE"));
szCard[lstrlen(szCard) + 1] = 0; // Double trailing zero.
// Establish a context.
lReturn = SCardEstablishContext(SCARD_SCOPE_USER,
NULL,
NULL,
&hSC );
if ( SCARD_S_SUCCESS != lReturn )
{
printf("Failed SCardEstablishContext\n");
exit(1);
}
// Determine which readers are available.
lReturn = SCardListReaders(hSC,
NULL,
(LPTSTR)&szReaders,
&cchReaders );
if ( SCARD_S_SUCCESS != lReturn )
{
printf("Failed SCardListReaders\n");
exit(1);
}
// Place the readers into the state array.
szRdr = szReaders;
for ( dwI = 0; dwI < MAXIMUM_SMARTCARD_READERS; dwI++ )
{
if ( 0 == *szRdr )
break;
rgscState[dwI].szReader = szRdr;
rgscState[dwI].dwCurrentState = SCARD_STATE_UNAWARE;
szRdr += lstrlen(szRdr) + 1;
}
dwRdrCount = dwI;
// If any readers are available, proceed.
if ( 0 != dwRdrCount )
{
for (;;)
{
// Look for the card.
lReturn = SCardLocateCards(hSC,
szCard,
rgscState,
dwRdrCount );
if ( SCARD_S_SUCCESS != lReturn )
{
printf("Failed SCardLocateCards\n");
exit(1);
}
// Look through the array of readers.
for ( dwI=0; dwI < dwRdrCount; dwI++)
{
if ( 0 != ( SCARD_STATE_ATRMATCH &
rgscState[dwI].dwEventState))
{
_tprintf( TEXT("Card '%s' found in reader '%s'.\n"),
szCard,
rgscState[dwI].szReader );
SCardFreeMemory( hSC,
szReaders );
return 0; // Context will be release automatically.
}
// Update the state.
rgscState[dwI].dwCurrentState = rgscState[dwI].dwEventState;
}
// Card not found yet; wait until there is a change.
lReturn = SCardGetStatusChange(hSC,
INFINITE, // infinite wait
rgscState,
dwRdrCount );
if ( SCARD_S_SUCCESS != lReturn )
{
printf("Failed SCardGetStatusChange\n");
exit(1);
}
} // for (;;)
}
else
printf("No readers available\n");
// Release the context.
lReturn = SCardReleaseContext(hSC);
if ( SCARD_S_SUCCESS != lReturn )
{
printf("Failed SCardReleaseContext\n");
exit(1);
}
SCardFreeMemory( hSC,
szReaders );
return hr;
}
Hinweis
Der winscard.h-Header definiert SCardLocateCards 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 |
|---|---|
| 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 |