Função SCardListCardsA (winscard.h)

Artigo
11/20/2024

A função SCardListCards pesquisa o banco de dados de cartão inteligente e fornece uma lista de cartões nomeados introduzidos anteriormente no sistema pelo usuário.

O chamador especifica um de cadeia de caracteres ATR, um conjunto de GUIDs (identificadores de interface) ou ambos. Se uma cadeia de caracteres ATR e uma matriz de identificador forem fornecidas, os cartões retornados corresponderão à cadeia de caracteres ATR fornecida e darão suporte às interfaces especificadas.

Sintaxe

LONG SCardListCardsA(
  [in]           SCARDCONTEXT hContext,
  [in, optional] LPCBYTE      pbAtr,
  [in]           LPCGUID      rgquidInterfaces,
  [in]           DWORD        cguidInterfaceCount,
  [out]          CHAR         *mszCards,
  [in, out]      LPDWORD      pcchCards
);

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 for definido como NULL, a pesquisa de cartões não se limitará a nenhum contexto.

[in, optional] pbAtr

Endereço de uma cadeia de caracteres ATR para comparar com cartões conhecidos ou NULL se nenhuma correspondência de ATR for executada.

[in] rgquidInterfaces

Matriz de identificadores (GUIDs) ou NULL se nenhuma correspondência de interface for executada. Quando uma matriz for fornecida, um nome de cartão será retornado somente se todos os identificadores especificados tiverem suporte no cartão.

[in] cguidInterfaceCount

Número de entradas na matriz de rgguidInterfaces . Se rgguidInterfaces for NULL, esse valor será ignorado.

[out] mszCards

Várias cadeias de caracteres que listam os cartões inteligentes encontrados. Se esse valor for NULL, SCardListCards ignorará o comprimento do buffer fornecido em pcchCards, retornando o comprimento do buffer que teria sido retornado se esse parâmetro não tivesse sido NULL para pcchCards e um código de êxito.

[in, out] pcchCards

Comprimento do buffer mszCards em caracteres. Recebe o comprimento real da estrutura de várias cadeias de caracteres, incluindo todos os caracteres nulos à direita. Se o comprimento do buffer for especificado como SCARD_AUTOALLOCATE, mszCards 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 de retorno	Descrição
de sucesso do	SCARD_S_SUCCESS.
de falha do	Um código de erro. Para obter mais informações, consulte valores de retorno de cartão inteligente.

Observações

Essa função não é redirecionada, mas chamar a função quando dentro de uma sessão de Área de Trabalho Remota não resultará em um erro. Isso significa apenas que o resultado será do computador remoto em vez do computador local.

Para retornar todos os cartões inteligentes introduzidos no subsistema, defina pbAtr e rgguidInterfaces para NULL.

A função SCardListCards é 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.

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 listagem dos cartões inteligentes.

LPTSTR pmszCards = NULL;
LPTSTR pCard;
LONG lReturn;
DWORD cch = SCARD_AUTOALLOCATE;

// Retrieve the list of cards.
lReturn = SCardListCards(NULL,
                         NULL,
                         NULL,
                         NULL,
                         (LPTSTR)&pmszCards,
                         &cch );
if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardListCards\n");
    exit(1); // Or other appropriate error action
}
// Do something with the multi string of cards.
// Output the values.
// A double-null terminates the list of values.
pCard = pmszCards;
while ( '\0' != *pCard )
{
    // Display the value.
    printf("%S\n", pCard );
    // Advance to the next value.
    pCard = pCard + wcslen(pCard) + 1;
}

// Remember to free pmszCards (by calling SCardFreeMemory).
// ...

Nota

O cabeçalho winscard.h define SCardListCards 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

SCardListInterfaces

SCardListReaderGroups

SCardListReaders

Compartilhar via