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

Статья
11/20/2024

Функция 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 или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2003 [только классические приложения]
целевая платформа	Виндоус
заголовка	winscard.h
библиотеки	Winscard.lib
DLL	Winscard.dll

См. также

SCardConnect

SCardDisconnect

Поделиться через