Função SCardGetCardTypeProviderNameA (winscard.h)

Artigo
07/16/2024

A função SCardGetCardTypeProviderName retorna o nome do módulo (biblioteca de links dinâmicos) que contém o provedor para um determinado nome de cartão e tipo de provedor.

Sintaxe

LONG SCardGetCardTypeProviderNameA(
  [in]      SCARDCONTEXT hContext,
  [in]      LPCSTR       szCardName,
  [in]      DWORD        dwProviderId,
  [out]     CHAR         *szProvider,
  [in, out] LPDWORD      pcchProvider
);

Parâmetros

[in] hContext

Identificador que identifica ode contexto do gerenciador de recursos . O contexto do gerenciador de recursos pode ser definido por uma chamada anterior para SCardEstablishContext. Esse valor poderá ser NULL se a chamada para SCardGetCardTypeProviderName não for direcionada para um contexto específico.

[in] szCardName

Nome do tipo de cartão ao qual esse nome de provedor está associado.

[in] dwProviderId

Identificador do provedor associado a esse tipo de cartão.

Valor	Significado
SCARD_PROVIDER_PRIMARY 1	A função recupera o nome do provedor de serviços primário do cartão inteligente como uma cadeia de caracteres GUID.
SCARD_PROVIDER_CSP 2	A função recupera o nome do provedor de serviços criptográficos .
SCARD_PROVIDER_KSP 3	A função recupera o nome do cartão inteligente KSP ( provedor de armazenamento de chaves).
SCARD_PROVIDER_CARD_MODULE 0x80000001	A função recupera o nome do módulo de cartão.

[out] szProvider

Variável de cadeia de caracteres para receber o nome do provedor após a conclusão bem-sucedida dessa função.

[in, out] pcchProvider

Ponteiro para valor de DWORD. Na entrada, pcchProvider fornece o comprimento do buffer de szProvider de em caracteres. Se esse valor for SCARD_AUTOALLOCATE, szProvider 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 cadeia de caracteres. Esse bloco de memória deve ser desalocado chamando SCardFreeMemory.

Na saída, esse valor representa o número real de caracteres, incluindo o terminador de nulo, na variável szProvider .

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.

Após a conclusão bem-sucedida dessa função, o valor em szProvider pode ser usado como o terceiro parâmetro em uma chamada para CryptAcquireContext.

Exemplos

O exemplo a seguir mostra como recuperar o nome do provedor para o contexto de leitor especificado. O exemplo pressupõe que hContext é um identificador válido obtido de uma chamada anterior para a função SCardEstablishContext.

LPTSTR szProvider = NULL;
LPTSTR szCardName = _T("WindowsCard");
DWORD  chProvider = SCARD_AUTOALLOCATE;
LONG   lReturn = SCARD_S_SUCCESS;

// Retrieve the provider name.
// hContext was set by SCardEstablishContext.
lReturn = SCardGetCardTypeProviderName(hContext,
                                       szCardName,
                                       SCARD_PROVIDER_CSP,
                                       (LPTSTR)&szProvider,
                                       &chProvider);
if (SCARD_S_SUCCESS == lReturn)
{
    BOOL fSts = TRUE;
    HCRYPTPROV hProv = NULL;
  
  // Acquire a Cryptographic operation context.
    fSts = CryptAcquireContext(&hProv,
                               NULL,
                               szProvider,
                               PROV_RSA_FULL,
                               0);
    // Perform Cryptographic operations with smart card
    // ...

    // Free memory allocated by SCardGetCardTypeProviderName.
    lReturn = SCardFreeMemory(hContext, szProvider);
}

Nota

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

SCardSetCardTypeProviderName

Compartilhar via