Função SCardListReadersA (winscard.h)

Artigo
11/20/2024

A função SCardListReaders fornece a lista de leitores dentro de um conjunto de grupos de leitores nomeados, eliminando duplicatas.

O chamador fornece uma lista de grupos de leitores e recebe a lista de leitores dentro dos grupos nomeados. Nomes de grupo não reconhecidos são ignorados. Essa função retorna somente leitores dentro dos grupos nomeados que estão atualmente anexados ao sistema e disponíveis para uso.

Sintaxe

LONG SCardListReadersA(
  [in]           SCARDCONTEXT hContext,
  [in, optional] LPCSTR       mszGroups,
  [out]          LPSTR        mszReaders,
  [in, out]      LPDWORD      pcchReaders
);

Parâmetros

[in] hContext

Identificador que identifica o de contexto do gerenciador de recursos para a consulta. O contexto do gerenciador de recursos pode ser definido por uma chamada anterior para SCardEstablishContext.

Se esse parâmetro estiver definido como NULL, a pesquisa por leitores não se limitará a nenhum contexto.

[in, optional] mszGroups

Nomes dos grupos de leitores definidos para o sistema, como uma cadeia de caracteres múltipla. Use um valor NULL para listar todos os leitores no sistema (ou seja, o grupo SCard$AllReaders).

Valor	Significado
SCARD_ALL_READERS TEXT("SCard$AllReaders\000")	Grupo usado quando nenhum nome de grupo é fornecido ao listar leitores. Retorna uma lista de todos os leitores, independentemente do grupo ou grupo em que os leitores estão.
SCARD_DEFAULT_READERS TEXT("SCard$DefaultReaders\000")	Grupo padrão ao qual todos os leitores são adicionados quando introduzidos no sistema.
SCARD_LOCAL_READERS TEXT("SCard$LocalReaders\000")	Valor herdado não utilizado. Esse é um grupo gerenciado internamente que não pode ser modificado usando APIs de grupo de leitores. Destina-se a ser usado somente para enumeração.
SCARD_SYSTEM_READERS TEXT("SCard$SystemReaders\000")	Valor herdado não utilizado. Esse é um grupo gerenciado internamente que não pode ser modificado usando APIs de grupo de leitores. Destina-se a ser usado somente para enumeração.

[out] mszReaders

Várias cadeias de caracteres que listam os leitores de cartão dentro dos grupos de leitores fornecidos. Se esse valor for NULL, SCardListReaders ignorará o comprimento do buffer fornecido em pcchReaders, gravará o comprimento do buffer que teria sido retornado se esse parâmetro não tivesse sido NULL para pcchReaderse retornará um código de êxito.

[in, out] pcchReaders

Comprimento do buffer de mszReaders em caracteres. Esse parâmetro recebe o comprimento real da estrutura de várias cadeias de caracteres, incluindo todos os caracteres de nulos à direita. Se o comprimento do buffer for especificado como SCARD_AUTOALLOCATE, mszReaders será convertido em um ponteiro para um ponteiro de bytes e receberá o endereço de um bloco de memória que contém a estrutura de várias cadeias de caracteres. Esse bloco de memória deve ser desalocado com SCardFreeMemory.

Valor de retorno

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

Código/valor de retorno	Descrição
de sucesso do 0 (0x0)	SCARD_S_SUCCESS
Group não contém leitores 2148532270 (0x8010002E)	SCARD_E_NO_READERS_AVAILABLE
leitor especificado não está disponível no momento para uso 2148532247 (0x80100017)	SCARD_E_READER_UNAVAILABLE
Outros	Um código de erro. Para obter mais informações, consulte valores de retorno de cartão inteligente.

Observações

A função SCardListReaders é uma função de consulta de banco de dados. Para obter mais informações sobre outras funções de consulta de banco de dados, consulte funções de consulta de banco de dados de cartão inteligente.

Exemplos

O exemplo a seguir mostra a listagem dos leitores.

LPTSTR          pmszReaders = NULL;
LPTSTR          pReader;
LONG            lReturn, lReturn2;
DWORD           cch = SCARD_AUTOALLOCATE;

// Retrieve the list the readers.
// hSC was set by a previous call to SCardEstablishContext.
lReturn = SCardListReaders(hSC,
                           NULL,
                           (LPTSTR)&pmszReaders,
                           &cch );
switch( lReturn )
{
    case SCARD_E_NO_READERS_AVAILABLE:
        printf("Reader is not in groups.\n");
        // Take appropriate action.
        // ...
        break;

    case SCARD_S_SUCCESS:
        // Do something with the multi string of readers.
        // Output the values.
        // A double-null terminates the list of values.
        pReader = pmszReaders;
        while ( '\0' != *pReader )
        {
            // Display the value.
            printf("Reader: %S\n", pReader );
            // Advance to the next value.
            pReader = pReader + wcslen((wchar_t *)pReader) + 1;
        }
        // Free the memory.
        lReturn2 = SCardFreeMemory( hSC,
                                   pmszReaders );
        if ( SCARD_S_SUCCESS != lReturn2 )
            printf("Failed SCardFreeMemory\n");
        break;

default:
        printf("Failed SCardListReaders\n");
        // Take appropriate action.
        // ...
        break;
}

Nota

O cabeçalho winscard.h define SCardListReaders como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2003 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	winscard.h
biblioteca	Winscard.lib
de DLL	Winscard.dll

Consulte também

SCardEstablishContext

SCardFreeMemory

SCardGetProviderId

SCardListCards

SCardListInterfaces

SCardListReaderGroups

Compartilhar via