SCardLocateCardsA, fonction (winscard.h)
La fonction SCardLocateCards recherche les lecteurs répertoriés dans le paramètre rgReaderStates pour une carte avec une chaîne ATR qui correspond à l’un des noms de carte spécifiés dans mszCards, en retournant immédiatement avec le résultat.
Syntaxe
LONG SCardLocateCardsA(
[in] SCARDCONTEXT hContext,
[in] LPCSTR mszCards,
[in, out] LPSCARD_READERSTATEA rgReaderStates,
[in] DWORD cReaders
);
Paramètres
[in] hContext
Handle qui identifie le contexte Resource Manager. Le contexte resource manager est défini par un appel précédent à SCardEstablishContext.
[in] mszCards
Chaîne multiple qui contient les noms des cartes à rechercher.
[in, out] rgReaderStates
Tableau de structures SCARD_READERSTATE qui, en entrée, spécifient les lecteurs à rechercher et qui, en sortie, reçoivent le résultat.
[in] cReaders
Nombre d’éléments dans le tableau rgReaderStates.
Valeur de retour
Cette fonction retourne des valeurs différentes selon qu’elle réussit ou échoue.
| Retourner le code | Description |
|---|---|
|
SCARD_S_SUCCESS. |
|
Code d’erreur. Pour plus d’informations, consultez valeurs de retour de carte à puce. |
Remarques
Ce service est particulièrement utile lorsqu’il est utilisé conjointement avec SCardGetStatusChange. Si aucune carte correspondante n’est trouvée au moyen de SCardLocateCards, l’application appelante peut utiliser SCardGetStatusChange attendre les modifications de disponibilité des cartes.
La fonction SCardLocateCards
L’appel de cette fonction doit être effectué en dehors d’une transaction. Si une application commence une transaction avec la fonction
Windows Server 2008 R2 et Windows 7 : Appeler cette fonction au sein d’une transaction peut entraîner la non-réponse de votre ordinateur.
Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : Non applicable.
Exemples
L’exemple suivant montre la localisation des cartes à puce.
// 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;
}
Note
L’en-tête winscard.h définit SCardLocateCards comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows XP [applications de bureau uniquement] |
| serveur minimum pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| plateforme cible | Windows |
| d’en-tête | winscard.h |
| bibliothèque | Winscard.lib |
| DLL | Winscard.dll |