Função SCardConnectA (winscard.h)

Artigo
11/20/2024

A função SCardConnect estabelece uma conexão (usando umade contexto específica do gerenciador de recursos ) entre o aplicativo de chamada e um cartão inteligente contido por um leitor específico. Se nenhum cartão existir no leitor especificado, um erro será retornado.

Sintaxe

LONG SCardConnectA(
  [in]  SCARDCONTEXT  hContext,
  [in]  LPCSTR        szReader,
  [in]  DWORD         dwShareMode,
  [in]  DWORD         dwPreferredProtocols,
  [out] LPSCARDHANDLE phCard,
  [out] LPDWORD       pdwActiveProtocol
);

Parâmetros

[in] hContext

Um identificador que identifica ode contexto do gerenciador de recursos . O contexto do gerenciador de recursos é definido por uma chamada anterior para SCardEstablishContext.

[in] szReader

O nome do leitor que contém o cartão de destino.

[in] dwShareMode

Um sinalizador que indica se outros aplicativos podem formar conexões com o cartão.

Valor	Significado
SCARD_SHARE_SHARED	Este aplicativo está disposto a compartilhar o cartão com outros aplicativos.
SCARD_SHARE_EXCLUSIVE	Este aplicativo não está disposto a compartilhar o cartão com outros aplicativos.
SCARD_SHARE_DIRECT	Esse aplicativo está alocando o leitor para seu uso privado e o controlará diretamente. Nenhum outro aplicativo tem permissão de acesso a ele.

[in] dwPreferredProtocols

Uma máscara de bits de protocolos aceitáveis para a conexão. Os valores possíveis podem ser combinados com a operação OR.

Valor	Significado
SCARD_PROTOCOL_T0	T=0 é um protocolo aceitável.
SCARD_PROTOCOL_T1	T=1 é um protocolo aceitável.
0	Esse parâmetro poderá ser zero somente se dwShareMode estiver definido como SCARD_SHARE_DIRECT. Nesse caso, nenhuma negociação de protocolo será executada pelos drivers até que uma diretiva de controle de IOCTL_SMARTCARD_SET_PROTOCOL seja enviada com SCardControl.

[out] phCard

Um identificador que identifica a conexão com o cartão inteligente no leitor designado.

[out] pdwActiveProtocol

Um sinalizador que indica o protocolo ativo estabelecido.

Valor	Significado
SCARD_PROTOCOL_T0	T=0 é o protocolo ativo.
SCARD_PROTOCOL_T1	T=1 é o protocolo ativo.
SCARD_PROTOCOL_UNDEFINED	SCARD_SHARE_DIRECT foi especificado, de modo que nenhuma negociação de protocolo tenha ocorrido. É possível que não haja cartão no leitor.

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.
SCARD_E_NOT_READY	O leitor não pôde se conectar ao cartão.

Observações

A função SCardConnect é uma função de acesso de de cartão inteligente e leitor de . Para obter mais informações sobre outras funções de acesso, consulte funções de acesso de cartão inteligente e leitor.

Exemplos

O exemplo a seguir cria uma conexão com um leitor. O exemplo pressupõe que hContext é um identificador válido do tipo SCARDCONTEXT recebido de uma chamada anterior para SCardEstablishContext.

SCARDHANDLE     hCardHandle;
LONG            lReturn;
DWORD           dwAP;

lReturn = SCardConnect( hContext, 
                        (LPCTSTR)"Rainbow Technologies SCR3531 0",
                        SCARD_SHARE_SHARED,
                        SCARD_PROTOCOL_T0 | SCARD_PROTOCOL_T1,
                        &hCardHandle,
                        &dwAP );
if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardConnect\n");
    exit(1);  // Or other appropriate action.
}

// Use the connection.
// Display the active protocol.
switch ( dwAP )
{
    case SCARD_PROTOCOL_T0:
        printf("Active protocol T0\n"); 
        break;

    case SCARD_PROTOCOL_T1:
        printf("Active protocol T1\n"); 
        break;

    case SCARD_PROTOCOL_UNDEFINED:
    default:
        printf("Active protocol unnegotiated or unknown\n"); 
        break;
}

// Remember to disconnect (by calling SCardDisconnect).
// ...

Nota

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

SCardControl

SCardDisconnect

SCardEstablishContext

SCardReconnect

Compartilhar via