Função SCardConnectA (winscard.h)

  • Artigo

A função SCardConnect estabelece uma conexão (usando um contexto específico do gerenciador de recursos) entre o aplicativo de chamada e um cartão inteligente contido por um leitor específico. Se não houver cartão 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 o 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
 Esse 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 para acessá-lo.

[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 só poderá ser zero 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, para que nenhuma negociação de protocolo tenha ocorrido. É possível que não haja cartão no leitor.

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

Comentários

A função SCardConnect é uma função de acesso inteligente cartão e leitor. 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).
// ...

Observação

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

Confira também

SCardControl

SCardDisconnect

Scardestablishcontext

SCardReconnect