Função SCardListReaderGroupsA (winscard.h)
A função SCardListReaderGroups fornece a lista de grupos de leitores que foram introduzidos anteriormente no sistema.
Sintaxe
LONG SCardListReaderGroupsA(
[in] SCARDCONTEXT hContext,
[out] LPSTR mszGroups,
[in, out] LPDWORD pcchGroups
);
Parâmetros
[in] hContext
Identificador que identifica o 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 por grupos de leitores não se limitará a nenhum contexto.
[out] mszGroups
Várias cadeias de caracteres que listam os grupos de leitores definidos para o sistema e disponíveis para o usuário atual no terminal atual. Se esse valor for NULL, SCardListReaderGroups ignorará o comprimento do buffer fornecido em pcchGroups, gravará o comprimento do buffer que teria sido retornado se esse parâmetro não tivesse sido NULL para pcchGroups e retornará um código de êxito.
[in, out] pcchGroups
Comprimento do buffer mszGroups em caracteres e 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, mszGroups 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.
Retornar valor
Essa função retorna valores diferentes dependendo se ela é bem-sucedida ou falha.
Código de retorno | Descrição |
---|---|
|
SCARD_S_SUCCESS. |
|
Um código de erro. Para obter mais informações, consulte Valores retornados de cartão inteligente. |
Comentários
Um grupo será retornado somente se contiver pelo menos um leitor. Isso inclui o grupo SCard$DefaultReaders. O grupo SCard$AllReaders não pode ser retornado, pois ele existe apenas implicitamente.
A função SCardListReaderGroups é 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 grupos de leitores.
LPTSTR pmszReaderGroups = NULL;
LPTSTR pReaderGroup;
LONG lReturn;
DWORD cch = SCARD_AUTOALLOCATE;
// Retrieve the list the reader groups.
// hSC was set by a previous call to SCardEstablishContext.
lReturn = SCardListReaderGroups(hSC,
(LPTSTR)&pmszReaderGroups,
&cch );
if ( SCARD_S_SUCCESS != lReturn )
printf("Failed SCardListReaderGroups\n");
else
{
// Do something with the multi string of reader groups.
// Output the values.
// A double-null terminates the list of values.
pReaderGroup = pmszReaderGroups;
while ( '\0' != *pReaderGroup )
{
// Display the value.
printf("%S\n", pReaderGroup );
// Advance to the next value.
pReaderGroup = pReaderGroup + wcslen((wchar_t *) pReaderGroup) + 1;
}
// Remember to free pmszReaderGroups by a call to SCardFreeMemory.
// ...
}
Observação
O cabeçalho winscard.h define SCardListReaderGroups 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
Requisito | Valor |
---|---|
Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
Plataforma de Destino | Windows |
Cabeçalho | winscard.h |
Biblioteca | Winscard.lib |
DLL | Winscard.dll |