Функция SCardStatusA (winscard.h)

  • Статья

Функция SCardStatus предоставляет текущее состояние смарт-карта в средстве чтения. Его можно вызвать в любое время после успешного вызова SCardConnect и до успешного вызова SCardDisconnect. Это не влияет на состояние средства чтения или драйвера средства чтения.

Синтаксис

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

Параметры

[in] hCard

Значение ссылки, возвращаемое из SCardConnect.

[out] mszReaderNames

Список отображаемых имен (несколько строк), по которым известно текущее подключенное средство чтения.

[in, out, optional] pcchReaderLen

На входных данных предоставляет длину буфера szReaderName .

В выходных данных получает фактическую длину (в символах) списка имен читателя, включая конечный символ NULL . Если эта длина буфера указана как SCARD_AUTOALLOCATE, то szReaderName преобразуется в указатель на байтовый указатель и получает адрес блока памяти, содержащего структуру из нескольких строк.

[out, optional] pdwState

Текущее состояние смарт-карта в средстве чтения. При успешном выполнении он получает один из следующих индикаторов состояния.

Значение Значение
SCARD_ABSENT
 В читателе нет карта.
SCARD_PRESENT
 Существует карта в средстве чтения, но он не был перемещен в положение для использования.
SCARD_SWALLOWED
 Существует карта в считыватель в положении для использования. Карта не работает.
SCARD_POWERED
 Питание предоставляется карта, но драйвер чтения не знает о режиме карта.
SCARD_NEGOTIABLE
 Карта был сброшен и ожидает согласования PTS.
SCARD_SPECIFIC
 Карта был сброшен и установлены определенные протоколы связи.

[out, optional] pdwProtocol

Текущий протокол, если он есть. Возвращаемое значение имеет смысл, только если возвращаемое значение pdwState SCARD_SPECIFICMODE.

Значение Значение
SCARD_PROTOCOL_RAW
 Используется протокол необработанной передачи.
SCARD_PROTOCOL_T0
 Используется протокол ISO 7816/3 T=0 .
SCARD_PROTOCOL_T1
 Используется протокол ISO 7816/3 T=1 .

[out] pbAtr

Указатель на 32-байтовый буфер, который получает строку ATR из текущей вставленной карта, если она доступна.

[in, out, optional] pcbAtrLen

На входных данных предоставляет длину буфера pbAtr . В выходных данных получает количество байтов в строке ATR (максимум 32 байта). Если эта длина буфера указана как SCARD_AUTOALLOCATE, то pbAtr преобразуется в указатель на байтовый указатель и получает адрес блока памяти, содержащего структуру из нескольких строк.

Возвращаемое значение

Если функция успешно предоставляет текущее состояние смарт-карта в средстве чтения, возвращаемое значение будет SCARD_S_SUCCESS.

Если функция завершается сбоем, она возвращает код ошибки. Дополнительные сведения см. в разделе Возвращаемые значения смарт-карты.

Комментарии

Функция SCardStatus — это интеллектуальная карта и функция доступа для чтения. Дополнительные сведения о других функциях доступа см. в разделе Функции доступа к смарт-картам и читателю.

Примеры

В следующем примере показано, как определить состояние смарт-карта.

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

Примечание

Заголовок winscard.h определяет SCardStatus как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование Значение
Минимальная версия клиента Windows XP [только классические приложения]
Минимальная версия сервера Windows Server 2003 [только классические приложения]
Целевая платформа Windows
Header winscard.h
Библиотека Winscard.lib
DLL Winscard.dll

См. также раздел

SCardConnect

SCardDisconnect