Função SCardStatusA (winscard.h)

Artigo
11/20/2024

A função SCardStatus fornece o status atual de um de cartão inteligente em umde leitor de . 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 a de estado do leitor oudo driver de leitor de .

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) pela qual o leitor conectado atualmente é conhecido.

[in, out, optional] pcchReaderLen

Na entrada, fornece o comprimento do buffer de 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

O estado atual do cartão inteligente no leitor. Após o sucesso, 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 posição para uso.
SCARD_SWALLOWED	Há um cartão no leitor em posição para uso. O cartão não é alimentado.
SCARD_POWERED	A energia está sendo fornecida ao cartão, mas o driver de 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 Raw Transfer 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 do cartão inserido no momento, se disponível.

[in, out, optional] pcbAtrLen

Na entrada, fornece o comprimento do buffer de 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.

Valor de retorno

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

Se a função falhar, ela retornará um código de erro. Para obter mais informações, consulte valores de retorno de cartão inteligente.

Observações

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

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

Nota

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

SCardConnect

SCardDisconnect

Compartilhar via