структура SMARTCARD_EXTENSION (smclib.h)

Структура SMARTCARD_EXTENSION используется драйвером средства чтения смарт-карта и библиотекой драйверов интеллектуального карта для доступа ко всем другим структурам данных интеллектуального карта.

Синтаксис

typedef struct _SMARTCARD_EXTENSION {
  ULONG                     Version;
  VENDOR_ATTR               VendorAttr;
  NTSTATUS(                 *ReaderFunction[16];
  SCARD_CARD_CAPABILITIES   CardCapabilities;
  ULONG                     LastError;
  struct {
    PULONG Information;
    PUCHAR RequestBuffer;
    ULONG  RequestBufferLength;
    PUCHAR ReplyBuffer;
    ULONG  ReplyBufferLength;
  } IoRequest;
  ULONG                     MajorIoControlCode;
  ULONG                     MinorIoControlCode;
  POS_DEP_DATA              OsData;
  SCARD_READER_CAPABILITIES ReaderCapabilities;
  PREADER_EXTENSION         ReaderExtension;
  SMARTCARD_REPLY           SmartcardReply;
  SMARTCARD_REQUEST         SmartcardRequest;
  T0_DATA                   T0;
  T1_DATA                   T1;
  PPERF_INFO                PerfInfo;
  ULONG                     Reserved[25 - sizeof(PPERF_INFO)];
} *PSMARTCARD_EXTENSION, SMARTCARD_EXTENSION;

Члены

Version

Указывает версию этой структуры.

VendorAttr

Содержит сведения, идентифицирующий драйвер средства чтения, например имя поставщика, номер единицы и серийный номер.

ReaderFunction[16]

Строка в блоке синтаксиса должна выглядеть следующим образом: NTSTATUS (*ReaderFunction[16])(PSMARTCARD_EXTENSION);

Указатель на массив функций обратного вызова для читателей. Функции обратного вызова, которые может реализовать драйвер чтения, предоставленный поставщиком. Драйвер средства чтения делает эти функции обратного вызова доступными для подпрограммы библиотеки смарт-карта, SmartcardDeviceControl, для вызова, сохраняя указатели на них в расширении смарт-карта устройства.

RDF_ATR_PARSE

RDF_CARD_EJECT

RDF_CARD_POWER

RDF_CARD_TRACKING

RDF_IOCTL_VENDOR

RDF_READER_SWALLOW

RDF_SET_PROTOCOL

RDF_TRANSMIT

Дополнительные сведения см. в подразделе "Примечания".

CardCapabilities

Содержит возможности вставленного смарт-карта.

LastError

Не используется.

IoRequest

Структура со следующими элементами:

IoRequest.Information

Содержит количество возвращаемых байтов.

IoRequest.RequestBuffer

Указатель на данные в пользовательском запросе ввода-вывода для отправки на карта.

IoRequest.RequestBufferLength

Указывает количество байтов, отправляемых в карта.

IoRequest.ReplyBuffer

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

IoRequest.ReplyBufferLength

Указывает количество байтов данных, возвращаемых запросом ввода-вывода.

MajorIoControlCode

Содержит основной код элемента управления вводом-выводом.

MinorIoControlCode

Содержит дополнительный код элемента управления вводом-выводом.

OsData

Содержит сведения, относящиеся к операционной системе и типу драйвера.

ReaderCapabilities

Содержит возможности средства чтения с клавиатуры.

ReaderExtension

Содержит данные, относящиеся к средству чтения смарт-карта.

SmartcardReply

Содержит данные, поступающие от средства чтения.

SmartcardRequest

Содержит текущую команду и данные, отправляемые в смарт-карта.

T0

Содержит данные для использования с протоколом T=0.

T1

Содержит данные, используемые с протоколом T=1.

PerfInfo

Reserved[25 - sizeof(PPERF_INFO)]

Зарезервировано для системного использования.

Комментарии

Эта структура передается всем функциям обратного вызова.

Отдельные функции обратного вызова определяются рядом значений констант, которые должны использоваться в качестве индексов в массиве ReaderFunction .

Индекс	Описание
RDF_ATR_PARSE	Необязательный элемент. Функция синтаксического анализа RDF_ATR_PARSE анализирует ответ на сброс (ATR) для библиотеки драйверов смарт-карта, если библиотеке драйверов не удается распознать или проанализировать библиотеку драйверов смарт-карта.
RDF_CARD_EJECT	Необязательный элемент. функция обратного вызова RDF_CARD_EJECT Функция обратного вызова RDF_CARD_EJECT извлекает из средства чтения вставленный смарт-карта.
RDF_CARD_POWER	Функция обратного вызова RDF_CARD_POWER сбрасывает или отключает вставленную смарт-карта. Эта функция обратного вызова является обязательной для драйверов средства чтения смарт-карта. Во входных данных структура, на которую указывает SmartcardExtension , должна иметь следующие значения элементов: MajorIoControlCode Должно иметь значение IOCTL_SMARTCARD_POWER. IoRequest.ReplyBufferLength Должен содержать длину буфера. MinorIoControlCode Должен иметь один из следующих дополнительных кодов: SCARD_COLD_RESET Выполняет холодный сброс смарт-карта. SCARD_WARM_RESET Выполняет горячий сброс смарт-карта. SCARD_POWER_DOWN Отключает интеллектуальное карта питание. В выходных данных структура, на которую указывает SmartcardExtension , должна иметь следующие значения: IoRequest.ReplyBuffer Получает ATR, возвращенный смарт-карта. Кроме того, необходимо передать ATR в SmartcardExtension->CardCapabilities.ATR.Buffer , чтобы библиотека ела анализ ATR. IoRequest.Information Получает длину ATR. CardCapabilities.ATR.Length Содержит длину ATR.
RDF_CARD_TRACKING	Функция обратного вызова RDF_CARD_TRACKING устанавливает обработчик событий для отслеживания каждый раз, когда карта вставляется в карта средство чтения или удаляется из него. Эта функция обратного вызова является обязательной для драйверов средства чтения смарт-карта. После получения запроса IOCTL_SMARTCARD_IS_PRESENT библиотека драйверов определяет, присутствует ли смарт-карта. Если смарт-карта присутствует, библиотека драйверов завершает запрос с состоянием STATUS_SUCCESS. Если смарт-карта отсутствует, библиотека драйверов вызывает функцию обратного вызова интеллектуального карта отслеживания драйвера средства чтения, и драйвер чтения начинает искать смарт-карта. После инициации отслеживания интеллектуального карта библиотека драйверов помечает запрос как имеющий состояние STATUS_PENDING. Библиотека драйверов завершает запрос. Драйверы устройств WDM Соответствующая библиотека драйверов WDM добавляет указатель на запрос в SmartcardExtension-OsData-NotificationIrp>>. Драйвер средства чтения должен выполнить запрос, как только обнаруживает, что смарт-карта был вставлен или удален. Драйвер средства чтения завершает запрос, вызывая IoCompleteRequest, после чего драйвер средства чтения должен установить для элемента NotificationIrpSmartcardExtension -> OsData значение NULL, чтобы сообщить библиотеке драйверов, что драйвер средства чтения может принимать дополнительные запросы отслеживания смарт-карта. Так как этот вызов может иметь неопределенный срок, а вызывающий объект может завершить запрос до его завершения, важно пометить этот IRP как отменяемый. MyDriverCardSupervision( SmartcardExtension, OtherParameters) // // This function is called whenever the card status changes // For example, the card has been inserted or the card has been removed // { if (SmartcardExtension->OsData->NotificationOverlappedData != NULL){ SmartcardCompleteCardTracking(SmartcardExtension); } // // Do additional tasks // }
RDF_IOCTL_VENDOR	Функция обратного вызова RDF_IOCTL_VENDOR выполняет операции IOCTL, относящиеся к поставщику. Для интеллектуальных драйверов средства чтения карта необязательно реализовать эту функцию обратного вызова. При входе вызывающий объект должен передать в функцию следующие значения: SmartcardExtension->MajorIoControlCode Содержит код IOCTL для конкретного поставщика. Сведения о том, как определить код IOCTL для конкретного поставщика, см. в SCARD_CTL_CODE макросов в Winsmcrd.h . Обратите внимание, что код должен находиться в диапазоне от 2048 до 4095. SmartcardExtension->IoRequest.RequestBuffer Указатель на входной буфер пользователя. SmartcardExtension->IoRequest.RequestBufferLength Размер входного буфера пользователя в байтах. SmartcardExtension->IoRequest.ReplyBuffer Указатель на выходной буфер пользователя. SmartcardExtension->IoRequest.ReplyBufferLength Размер выходного буфера пользователя (в байтах). SmartcardExtension->IoRequest.Information Значение, предоставленное запросом. Должно быть задано число возвращаемых байтов. Как и все другие ioCTL, приложение пользовательского режима отправляет определяемый поставщиком IOCTL на устройство чтения смарт-карта путем вызова функции DeviceIoControl. Однако если IOCTL определен поставщиком, приложение должно сначала открыть устройство чтения для "перекрывающегося" (то есть асинхронного) доступа. Приложение также должно определить структуру OVERLAPPED и передать ее в систему в последнем аргументе DeviceIoControl (структура OVERLAPPED также описана в документации по Windows SDK. Когда операционная система вызывает подпрограмму диспетчеризации управления вводом-выводом драйвера, она передает драйверу структуру DIOCPARAMETERS. Элемент lpoOverlapped структуры DIOCPARAMETERS содержит указатель на структуру OVERLAPPED.
RDF_READER_SWALLOW	Функция обратного вызова RDF_READER_SWALLOW выполняет механическое проглатывание, что происходит, когда смарт-карта полностью вставляется в средство чтения смарт-карта. Эта функция обратного вызова является необязательной для интеллектуальных драйверов чтения карта.
RDF_SET_PROTOCOL	Функция обратного вызова RDF_SET_PROTOCOL выбирает протокол передачи для вставленного смарт-карта. Эта функция обратного вызова должна быть реализована в драйверах интеллектуального средства чтения карта. При входе вызывающий объект должен передать в функцию следующие значения: SmartcardExtension->MajorIoControlCode Содержит IOCTL_SMARTCARD_SET_PROTOCOL. SmartcardExtension->MinorIoControlCode Содержит побитовое ИЛИ одного или нескольких протоколов, чем принимает вызывающий объект. Драйвер должен выбрать протокол, поддерживаемый вставленным смарт-карта. Рекомендуется, чтобы протокол T = 1 был иметь приоритет над протоколом T = 0. Значение Значение SCARD_PROTOCOL_RAW Выбирает необработанный протокол. SCARD_PROTOCOL_T0 Выбирает протокол ISO T = 0. SCARD_PROTOCOL_T1 Выбирает протокол ISO T = 1.   SmartcardExtension->IoRequest.ReplyBufferLength Содержит длину буфера ответов. SmartcardExtension->CardCapabilities.PtsData Содержит параметры, необходимые для выполнения запроса PTS. Дополнительные сведения см. в разделе PTS_DATA. Запрос возвращает следующие значения: SmartcardExtension->IoRequest.ReplyBuffer Содержит выбранный протокол. SmartcardExtension->IoRequest.Information Задайте для параметра sizeof(ULONG). Вызывающий объект может предоставить маску допустимых протоколов. Подпрограмма обратного вызова заданного протокола драйвера выбирает один из протоколов в маске и возвращает выбранный протокол в разделе SmartcardExtension->IoRequest.ReplyBuffer.
RDF_TRANSMIT	Функция обратного вызова RDF_TRANSMIT выполняет передачу данных. Эта функция обратного вызова должна быть реализована в драйверах интеллектуального средства чтения карта. При входе вызывающий объект должен передать в функцию следующие значения: SmartcardExtension->MajorIoControlCode Содержит IOCTL_SMARTCARD_TRANSMIT. SmartcardExtension->IoRequest.RequestBuffer Указатель на структуру SCARD_IO_REQUEST, за которой следуют данные для передачи в карта. SmartcardExtension->IoRequest.RequestBufferLength Число байтов, передаваемых в карта. SmartcardExtension->IoRequest.ReplyBufferLength Размер буфера ответов (в байтах). Запрос возвращает следующие значения: SmartcardExtension->IoRequest.ReplyBuffer Указатель на буфер, получающий структуру SCARD_IO_REQUEST, а также результат карта. SmartcardExtension->IoRequest.Information Получает фактическое количество байтов, возвращаемых смарт-карта, а также размер структуры SCARD_IO_REQUEST. Определение структуры SCARD_IO_REQUEST см. в разделе IOCTL_SMARTCARD_TRANSMIT. При вызове этой функции SmartcardExtension->IoRequest.RequestBuffer указывает на структуру SCARD_IO_REQUEST, за которой следует передаваемые данные. typedef struct _SCARD_IO_REQUEST{ DWORD dwProtocol; // Protocol identifier DWORD cbPciLength; // Protocol Control Information Length } SCARD_IO_REQUEST, *PSCARD_IO_REQUEST, *LPSCARD_IO_REQUEST; Член dwProtocol должен содержать идентификатор протокола, возвращаемый вызовом IOCTL_SMARTCARD_SET_PROTOCOL. Член cbPciLength содержит размер структуры SCARD_IO_REQUEST в байтах. Размер этой структуры обычно составляет 8 байт. За структурой SCARD_IO_REQUEST следуют данные (протокол) для передачи в карта. В зависимости от протокола, используемого для передачи, библиотека предлагает несколько функций поддержки. Дополнительные сведения об этих функциях поддержки см. в разделах SmartcardT0Request (WDM) и SmartcardT1Request (WDM). RequestBuffer и ReplyBuffer указывают на один и тот же системный буфер. Если вы используете функцию библиотеки SmartcardxxRequest и SmartcardxxReply, входной буфер перезаписывать не будет. Если вы не используете эти функции, создайте копию RequestBuffer перед началом передачи. Необходимо скопировать структуру SCARD_IO_REQUEST в параметр ReplyBuffer, а затем данные, полученные от карта. Опять же, если вы используете функции SmartcardxxRequest и SmartcardxxReply , библиотека скопирует структуру за вас.

Требования

Требование	Значение
Заголовок	smclib.h (включая Smclib.h)