Função SCardStatusA (winscard.h)

A função SCardStatus fornece o status atual de um cartão inteligente em um leitor. Você pode chamá-lo a qualquer momento após uma chamada bem-sucedida para SCardConnect e antes de uma chamada bem-sucedida para SCardDisconnect. Ele não afeta o estado do leitor ou do driver de leitor.

Sintaxe

LONG SCardStatusA(
  [in]                SCARDHANDLE hCard,
  [out]               LPSTR       mszReaderNames,
  [in, out, optional] LPDWORD     pcchReaderLen,
  [out, optional]     LPDWORD     pdwState,
  [out, optional]     LPDWORD     pdwProtocol,
  [out]               LPBYTE      pbAtr,
  [in, out, optional] LPDWORD     pcbAtrLen
);

Parâmetros

[in] hCard

Valor de referência retornado de SCardConnect.

[out] mszReaderNames

Lista de nomes de exibição (várias cadeias de caracteres) pelos quais o leitor conectado no momento é conhecido.

[in, out, optional] pcchReaderLen

Na entrada, fornece o comprimento do buffer szReaderName .

Na saída, recebe o comprimento real (em caracteres) da lista de nomes do leitor, incluindo o caractere NULL à direita. Se esse comprimento de buffer for especificado como SCARD_AUTOALLOCATE, szReaderName 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.

[out, optional] pdwState

Estado atual do cartão inteligente no leitor. Após o êxito, ele recebe um dos seguintes indicadores de estado.

Valor	Significado
SCARD_ABSENT	Não há cartão no leitor.
SCARD_PRESENT	Há um cartão no leitor, mas ele não foi movido para a posição para uso.
SCARD_SWALLOWED	Há um cartão no leitor em posição para uso. O cartão não está ligado.
SCARD_POWERED	A energia está sendo fornecida ao cartão, mas o driver do leitor não está ciente do modo do cartão.
SCARD_NEGOTIABLE	O cartão foi redefinido e aguarda negociação de PTS.
SCARD_SPECIFIC	O cartão foi redefinido e protocolos de comunicação específicos foram estabelecidos.

[out, optional] pdwProtocol

Protocolo atual, se houver. O valor retornado será significativo somente se o valor retornado de pdwState for SCARD_SPECIFICMODE.

Valor	Significado
SCARD_PROTOCOL_RAW	O protocolo De transferência bruta está em uso.
SCARD_PROTOCOL_T0	O protocolo ISO 7816/3 T=0 está em uso.
SCARD_PROTOCOL_T1	O protocolo ISO 7816/3 T=1 está em uso.

[out] pbAtr

Ponteiro para um buffer de 32 bytes que recebe a cadeia de caracteres ATR da cartão inserida no momento, se disponível.

[in, out, optional] pcbAtrLen

Na entrada, fornece o comprimento do buffer pbAtr . Na saída, recebe o número de bytes na cadeia de caracteres ATR (máximo de 32 bytes). Se esse comprimento de buffer for especificado como SCARD_AUTOALLOCATE, pbAtr 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.

Retornar valor

Se a função fornecer com êxito o status atual de um cartão inteligente em um leitor, o valor retornado será SCARD_S_SUCCESS.

Se a função falhar, será exibido um código de erro. Para obter mais informações, consulte Valores retornados de cartão inteligente.

Comentários

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

Exemplos

O exemplo a seguir mostra como determinar o estado do cartão inteligente.

WCHAR           szReader[200];
DWORD           cch = 200;
BYTE            bAttr[32];
DWORD           cByte = 32;
DWORD           dwState, dwProtocol;
LONG            lReturn;

// Determine the status.
// hCardHandle was set by an earlier call to SCardConnect.
lReturn = SCardStatus(hCardHandle,
                      szReader,
                      &cch,
                      &dwState,
                      &dwProtocol,
                      (LPBYTE)&bAttr,
                      &cByte); 

if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardStatus\n");
    exit(1);     // or other appropriate action
}

// Examine retrieved status elements.
// Look at the reader name and card state.
printf("%S\n", szReader );
switch ( dwState )
{
    case SCARD_ABSENT:
        printf("Card absent.\n");
        break;
    case SCARD_PRESENT:
        printf("Card present.\n");
        break;
    case SCARD_SWALLOWED:
        printf("Card swallowed.\n");
        break;
    case SCARD_POWERED:
        printf("Card has power.\n");
        break;
    case SCARD_NEGOTIABLE:
        printf("Card reset and waiting PTS negotiation.\n");
        break;
    case SCARD_SPECIFIC:
        printf("Card has specific communication protocols set.\n");
        break;
    default:
        printf("Unknown or unexpected card state.\n");
        break;
}

Observação

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

Scardconnect

SCardDisconnect