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 |
|---|---|
|
Não há cartão no leitor. |
|
Há um cartão no leitor, mas ele não foi movido para a posição para uso. |
|
Há um cartão no leitor em posição para uso. O cartão não está ligado. |
|
A energia está sendo fornecida ao cartão, mas o driver do leitor não está ciente do modo do cartão. |
|
O cartão foi redefinido e aguarda negociação de PTS. |
|
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 |
|---|---|
|
O protocolo De transferência bruta está em uso. |
|
O protocolo ISO 7816/3 T=0 está em uso. |
|
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 |