Função SCardListReadersWithDeviceInstanceIdA (winscard.h)

A função SCardListReadersWithDeviceInstanceId obtém a lista de leitores que forneceram um identificador de instância de dispositivo. Essa função não afeta o estado do leitor.

Sintaxe

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

Parâmetros

[in] hContext

Identificador que identifica o contexto do gerenciador de recursos para a consulta. Você pode definir o contexto do gerenciador de recursos por uma chamada anterior para a função SCardEstablishContext . Esse parâmetro não pode ser NULL.

[in] szDeviceInstanceId

ID da instância do dispositivo do leitor. Você pode obter esse valor chamando a função SCardGetReaderDeviceInstanceId com o nome do leitor ou chamando a função SetupDiGetDeviceInstanceId do DDK.

[out, optional] mszReaders

Uma cadeia de caracteres múltipla que contém os leitores de cartão inteligentes dentro do identificador de instância do dispositivo fornecido. Se esse valor for NULL, a função ignorará o comprimento do buffer fornecido no parâmetro pcchReaders , gravará o comprimento do buffer que teria sido retornado se esse parâmetro não tivesse sido NULL para pcchReaders e retornará um código de êxito.

[in, out] pcchReaders

O comprimento, em caracteres, do buffer mszReaders . Esse parâmetro recebe o comprimento real da estrutura de várias cadeias de caracteres, incluindo todos os caracteres nulos de terminação. 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. Quando terminar de usar essa memória, desaloque-a usando a função SCardFreeMemory .

Valor retornado

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

Código de retorno	Descrição
Êxito	SCARD_S_SUCCESS.
Falha	Um código de erro. Para obter mais informações, consulte Valores retornados de cartão inteligente.

Comentários

Essa função não é redirecionada. Chamar a função SCardListReadersWithDeviceInstanceId quando dentro de uma sessão de Área de Trabalho Remota falha com o código de erro SCARD_E_READER_UNAVAILABLE.

Exemplos

szDeviceInstanceIdcchReaderNameLONG     lReturn, lReturn2;

LPTSTR   pmszReaders = NULL;
LPTSTR   pReader = NULL;WCHAR
DWORD    cchReaderName = SCARD_AUTOALLOCATE;

// Retrieve the reader’s name from it’s device instance ID
// hContext was set by a previous call to SCardEstablishContext. 

// szDeviceInstanceId was obtained by calling SetupDiGetDeviceInstanceId
lReturn = SCardListReadersWithDeviceInstanceId (hContext,
                         szDeviceInstanceId,
                         (LPTSTR)&pmszReaders,
                         &cchReaderName);

switch( lReturn )
{
    case SCARD_E_NO_READERS_AVAILABLE:
        printf("No readers have the provided device instance ID.\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( hContext,
                                   pmszReaders );
        if ( SCARD_S_SUCCESS != lReturn2 )
            printf("Failed SCardFreeMemory\n");
        break;

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

Observação

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

Requisitos

Cliente mínimo com suporte	Windows 8 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2012 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winscard.h