Funzione SCardLocateCardsW (winscard.h)

Articolo
11/20/2024

La funzione SCardLocateCards cerca nei lettori elencati nel parametro rgReaderStates una scheda con un stringa ATR corrispondente a uno dei nomi di scheda specificati in mszCards, restituendo immediatamente con il risultato.

Sintassi

LONG SCardLocateCardsW(
  [in]      SCARDCONTEXT         hContext,
  [in]      LPCWSTR              mszCards,
  [in, out] LPSCARD_READERSTATEW rgReaderStates,
  [in]      DWORD                cReaders
);

Parametri

[in] hContext

Handle che identifica il contesto di gestione risorse . 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 di rgReaderStates.

Valore restituito

Questa funzione restituisce valori diversi a seconda che abbia esito positivo o negativo.

Codice restituito	Descrizione
esito positivo	SCARD_S_SUCCESS.
errore	Codice di errore. Per altre informazioni, vedere valori restituiti della smart card.

Osservazioni

Questo servizio è particolarmente utile quando viene usato insieme a SCardGetStatusChange. Se non viene trovata alcuna scheda corrispondente tramite SCardLocateCards, l'applicazione chiamante può usare SCardGetStatusChange attendere le modifiche alla disponibilità delle schede.

La funzione di SCardLocateCards è una funzione di rilevamento smart card. Per altre informazioni su altre funzioni di rilevamento, vedere funzioni di rilevamento delle smart card.

La chiamata a questa funzione deve essere eseguita all'esterno di una transazione. Se un'applicazione avvia una transazione con la funzione di 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 di questa funzione all'interno di una transazione potrebbe causare la mancata risposta del computer.

Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Non applicabile.

Esempi

Nell'esempio seguente viene illustrata 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 non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [solo app desktop]
server minimo supportato	Windows Server 2003 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	winscard.h
libreria	Winscard.lib
dll	Winscard.dll

Vedere anche

SCARD_READERSTATE

SCardCancel

SCardEstablishContext

SCardGetStatusChange

Condividi tramite