Função SCardIntroduceCardTypeA (winscard.h)

Artigo
08/27/2023

A função SCardIntroduceCardType apresenta um cartão inteligente ao subsistema de cartão inteligente (para o usuário ativo) adicionando-o ao banco de dados de cartão inteligente.

Sintaxe

LONG SCardIntroduceCardTypeA(
  [in]           SCARDCONTEXT hContext,
  [in]           LPCSTR       szCardName,
  [in, optional] LPCGUID      pguidPrimaryProvider,
  [in, optional] LPCGUID      rgguidInterfaces,
  [in]           DWORD        dwInterfaceCount,
  [in]           LPCBYTE      pbAtr,
  [in]           LPCBYTE      pbAtrMask,
  [in]           DWORD        cbAtrLen
);

Parâmetros

[in] hContext

Identificador que identifica o contexto do gerenciador de recursos. O contexto do gerenciador de recursos é definido por uma chamada anterior para SCardEstablishContext. Esse parâmetro não pode ser NULL.

[in] szCardName

Nome pelo qual o usuário pode reconhecer o cartão.

[in, optional] pguidPrimaryProvider

Ponteiro para o IDENTIFICADOR (GUID) do provedor de serviços primário do cartão inteligente.

[in, optional] rgguidInterfaces

Matriz de identificadores (GUIDs) que identificam as interfaces compatíveis com o cartão inteligente.

[in] dwInterfaceCount

Número de identificadores na matriz rgguidInterfaces .

[in] pbAtr

Cadeia de caracteres ATR que pode ser usada para fins de correspondência ao consultar o banco de dados cartão inteligente (para obter mais informações, consulte SCardListCards). O comprimento dessa cadeia de caracteres é determinado pela análise normal do ATR.

[in] pbAtrMask

Máscara de bits opcional a ser usada ao comparar os ATRs de cartões inteligentes com o ATR fornecido no pbAtr. Se esse valor não for NULL, ele deverá apontar para uma cadeia de caracteres de bytes do mesmo comprimento que a cadeia de caracteres ATR fornecida em pbAtr. Quando uma determinada cadeia de caracteres ATR A é comparada com a ATR fornecida no pbAtr, ela corresponde a se e somente se A & M = pbAtr, em que M é a máscara fornecida e & representa AND bit a bit.

[in] cbAtrLen

Comprimento do ATR e da máscara de ATR opcional. Se esse valor for zero, o comprimento do ATR será determinado pela análise normal do ATR. Esse valor não poderá ser zero se um valor pbAtr for fornecido.

Retornar valor

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, 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.

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

Para remover um cartão inteligente, use SCardForgetCardType.

Exemplos

O exemplo a seguir mostra como introduzir um tipo de cartão. O exemplo pressupõe que hContext é um identificador válido obtido de uma chamada anterior para a função SCardEstablishContext .

GUID  MyGuid = { 0xABCDEF00,
                 0xABCD,
                 0xABCD,
                 0xAA, 0xBB, 0xCC, 0xDD,
                 0xAA, 0xBB, 0xCC, 0xDD };

static const BYTE MyATR[] =     { 0xaa, 0xbb, 0xcc, 0x00, 0xdd };
static const BYTE MyATRMask[] = { 0xff, 0xff, 0xff, 0x00, 0xff};

LONG            lReturn;

lReturn = SCardIntroduceCardType(hContext, 
                                 L"MyCardName",
                                 &MyGuid,
                                 NULL,    // No interface array
                                 0,       // Interface count = 0
                                 MyATR,
                                 MyATRMask,
                                 sizeof(MyATR));
if ( SCARD_S_SUCCESS != lReturn )
    printf("Failed SCardIntroduceCardType\n");

Observação

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