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
Success	SCARD_S_SUCCESS.
Operazioni non riuscite	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

Vedi anche

SCARD_READERSTATE

SCardCancel

SCardEstablishContext

SCardGetStatusChange