Fonction SCardLocateCardsA (winscard.h)

La fonction SCardLocateCards recherche dans les lecteurs répertoriés dans le paramètre rgReaderStates un carte avec une chaîne ATR qui correspond à l’un des noms carte spécifiés dans mszCards, et retourne 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 retournée

Cette fonction retourne des valeurs différentes selon qu’elle réussit ou échoue.

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 pour attendre carte modifications de disponibilité.

La fonction SCardLocateCards est une fonction de suivi intelligente carte. Pour plus d’informations sur d’autres fonctions de suivi, consultez Fonctions de suivi de carte à puce.

L’appel de cette fonction doit être effectué en dehors d’une transaction. Si une application commence une transaction avec la fonction SCardBeginTransaction , puis appelle cette fonction, elle réinitialise le paramètre hCard (de type SCARDHANDLE) de la fonction SCardBeginTransaction .

Windows Server 2008 R2 et Windows 7 : L’appel de cette fonction dans 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;
}

Configuration requise

Voir aussi

SCARD_READERSTATE

SCardCancel

SCardEstablishContext

SCardGetStatusChange