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.

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;
}

Requisiti

Vedi anche

SCARD_READERSTATE

SCardCancel

SCardEstablishContext

SCardGetStatusChange