Funzione SCardLocateCardsA (winscard.h)
La funzione SCardLocateCards cerca nei lettori elencati nel parametro rgReaderStates una scheda con una stringa ATR che corrisponde a uno dei nomi di scheda specificati in mszCards, restituendo immediatamente con il risultato.
Sintassi
LONG SCardLocateCardsA(
[in] SCARDCONTEXT hContext,
[in] LPCSTR mszCards,
[in, out] LPSCARD_READERSTATEA rgReaderStates,
[in] DWORD cReaders
);
Parametri
[in] hContext
Handle che identifica il contesto di Resource Manager. Il contesto di Resource Manager viene impostato da una chiamata precedente a SCardEstablishContext.
[in] mszCards
Stringa multipla contenente i nomi delle schede da cercare.
[in, out] rgReaderStates
Matrice di strutture SCARD_READERSTATE che, all'input, specificare i lettori da cercare e che, nell'output, riceve il risultato.
[in] cReaders
Numero di elementi nella matrice rgReaderStates .
Valore restituito
Questa funzione restituisce valori diversi a seconda che abbia esito positivo o negativo.
| Codice restituito | Descrizione |
|---|---|
|
SCARD_S_SUCCESS. |
|
Codice di errore. Per altre informazioni, vedere Valori restituiti della smart card. |
Commenti
Questo servizio è particolarmente utile quando usato insieme a SCardGetStatusChange. Se non vengono trovate schede corrispondenti tramite SCardLocateCards, l'applicazione chiamante può usare SCardGetStatusChange per attendere le modifiche alla disponibilità delle schede.
La funzione SCardLocateCards è una funzione di rilevamento delle smart card . Per altre informazioni su altre funzioni di rilevamento, vedere Funzioni di rilevamento delle smart card.
Chiamare questa funzione deve essere eseguita all'esterno di una transazione. Se un'applicazione avvia una transazione con la funzione SCardBeginTransaction e quindi chiama questa funzione, reimposta il parametro hCard (di tipo SCARDHANDLE) della funzione SCardBeginTransaction .
Windows Server 2008 R2 e Windows 7: La chiamata a questa funzione all'interno di una transazione potrebbe comportare la mancata risposta del computer.
Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Non applicabile.
Esempio
L'esempio seguente mostra l'individuazione di smart card.
// 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;
}
Nota
L'intestazione winscard.h definisce SCardLocateCards come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows XP [solo app desktop] |
| Server minimo supportato | Windows Server 2003 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | winscard.h |
| Libreria | Winscard.lib |
| DLL | Winscard.dll |