Função SCardLocateCardsA (winscard.h)

A função SCardLocateCards pesquisa os leitores listados no parâmetro rgReaderStates para um cartão com uma cadeia de caracteres ATR que corresponde a um dos nomes de cartão especificados em mszCards, retornando imediatamente com o resultado.

Sintaxe

LONG SCardLocateCardsA(
  [in]      SCARDCONTEXT         hContext,
  [in]      LPCSTR               mszCards,
  [in, out] LPSCARD_READERSTATEA rgReaderStates,
  [in]      DWORD                cReaders
);

Parâmetros

[in] hContext

Um identificador que identifica ode contexto do gerenciador de recursos . O contexto do gerenciador de recursos é definido por uma chamada anterior para SCardEstablishContext.

[in] mszCards

Uma cadeia de caracteres múltipla que contém os nomes dos cartões a serem pesquisados.

[in, out] rgReaderStates

Uma matriz de estruturas SCARD_READERSTATE que, na entrada, especificam os leitores a serem pesquisados e que, na saída, recebem o resultado.

[in] cReaders

O número de elementos na matriz de rgReaderStates.

Valor de retorno

Essa função retorna valores diferentes dependendo se ela é bem-sucedida ou falha.

Observações

Esse serviço é especialmente útil quando usado em conjunto com SCardGetStatusChange. Se nenhum cartão correspondente for encontrado por meio de SCardLocateCards, o aplicativo de chamada poderá usar SCardGetStatusChange para aguardar as alterações de disponibilidade do cartão.

A função SCardLocateCards é uma função de acompanhamento de de cartão inteligente . Para obter mais informações sobre outras funções de acompanhamento, consulte funções de acompanhamento de cartão inteligente.

Chamar essa função deve ser feito fora de uma transação. Se um aplicativo iniciar uma transação com a função SCardBeginTransaction e chamar essa função, ele redefinirá o parâmetro hCard (do tipo SCARDHANDLE) da função SCardBeginTransaction.

Windows Server 2008 R2 e Windows 7: Chamar essa função em uma transação pode fazer com que o computador não responda.

Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Não aplicável.

Exemplos

O exemplo a seguir mostra a localização de cartões inteligentes.

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

Requisitos

Consulte também

SCARD_READERSTATE

SCardCancel

SCardEstablishContext

SCardGetStatusChange