SCardLocateCardsA-Funktion (winscard.h)
Die SCardLocateCards--Funktion durchsucht die im rgReaderStates Parameter aufgeführten Leser nach einer Karte mit einer ATR-Zeichenfolge, die einem der kartennamen entspricht, die in mszCardsangegeben sind und sofort mit dem Ergebnis zurückgegeben werden.
Syntax
LONG SCardLocateCardsA(
[in] SCARDCONTEXT hContext,
[in] LPCSTR mszCards,
[in, out] LPSCARD_READERSTATEA rgReaderStates,
[in] DWORD cReaders
);
Parameter
[in] hContext
Ein Handle, das den Kontext des Ressourcen-Managersidentifiziert. Der Ressourcen-Manager-Kontext wird durch einen vorherigen Aufruf von SCardEstablishContextfestgelegt.
[in] mszCards
Eine mehrfache Zeichenfolge, die die Namen der zu suchden Karten enthält.
[in, out] rgReaderStates
Ein Array von SCARD_READERSTATE Strukturen, die bei Eingaben die zu durchsuchenden Leser angeben und die das Ergebnis bei der Ausgabe erhalten.
[in] cReaders
Die Anzahl der Elemente in der rgReaderStates Arrays.
Rückgabewert
Diese Funktion gibt unterschiedliche Werte zurück, je nachdem, ob sie erfolgreich ist oder fehlschlägt.
| Rückgabecode | Beschreibung |
|---|---|
|
SCARD_S_SUCCESS. |
|
Fehlercode. Weitere Informationen finden Sie unter Smartcard-Rückgabewerte. |
Bemerkungen
Dieser Dienst ist besonders nützlich, wenn er in Verbindung mit SCardGetStatusChangeverwendet wird. Wenn keine übereinstimmenden Karten mithilfe von SCardLocateCardsgefunden werden, kann die aufrufende Anwendung SCardGetStatusChange verwenden, um auf Kartenverfügbarkeitsänderungen zu warten.
Die funktion SCardLocateCards ist eine Smartcard- Tracking-Funktion. Weitere Informationen zu anderen Tracking-Funktionen finden Sie unter SmartCard Tracking Functions.
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 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;
}
Anmerkung
Der winscard.h-Header definiert SCardLocateCards als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante 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 |