структура OPENCARD_SEARCH_CRITERIAA (winscard.h)

Статья
11/20/2024

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

Синтаксис

typedef struct {
  DWORD          dwStructSize;
  LPSTR          lpstrGroupNames;
  DWORD          nMaxGroupNames;
  LPCGUID        rgguidInterfaces;
  DWORD          cguidInterfaces;
  LPSTR          lpstrCardNames;
  DWORD          nMaxCardNames;
  LPOCNCHKPROC   lpfnCheck;
  LPOCNCONNPROCA lpfnConnect;
  LPOCNDSCPROC   lpfnDisconnect;
  LPVOID         pvUserData;
  DWORD          dwShareMode;
  DWORD          dwPreferredProtocols;
} OPENCARD_SEARCH_CRITERIAA, *POPENCARD_SEARCH_CRITERIAA, *LPOPENCARD_SEARCH_CRITERIAA;

Члены

dwStructSize

Длина структуры в байтах. Не должно быть значение NULL.

lpstrGroupNames

Указатель на буфер, содержащий строки имени группы, завершающиеся значением NULL. Последняя строка в буфере должна быть завершена двумя пустыми символами. Каждая строка — это имя группы карточек, которая должна быть включена в поиск. Если lpstrGroupNamesNULL, выполняется поиск группы по умолчанию (Scard$DefaultReaders).

nMaxGroupNames

Максимальное количество байтов (версия ANSI) или символов (версия Юникода) в строке lpstrGroupNames.

rgguidInterfaces

Зарезервировано для дальнейшего использования. Массив идентификаторов GUID, определяющих необходимые интерфейсы. Установите для этого элемента значение NULL.

cguidInterfaces

Зарезервировано для дальнейшего использования. Количество интерфейсов в массиве rgguidInterfaces. Установите для этого элемента значение NULL.

lpstrCardNames

Указатель на буфер, содержащий строки имени карточки, завершаемой значением NULL. Последняя строка в буфере должна быть завершена двумя пустыми символами. Каждая строка — это имя карточки, которая должна находиться.

nMaxCardNames

Максимальное количество байтов (версия ANSI) или символов (версия Юникода) в строке lpstrGroupNames.

lpfnCheck

Указатель на процедуру проверки карточки вызывающего абонента. Если специальная проверка карты не требуется, этот указатель null. Если карточка отклоняется подпрограммой проверки, возвращается false, а карточка будет отключена. Если карточка принимается подпрограммой проверки, возвращается TRUE.

Прототип подпрограммы проверки выглядит следующим образом.

Boolean Check(
  hSCardContext, // the card context passed in the parameter block
  hCard,         // card handle
  pvUserData     // pointer to user data passed in the parameter block
);

lpfnConnect

Указатель на подпрограмму подключения карточки вызывающего абонента. Если вызывающему объекту требуется выполнить дополнительную обработку для подключения к карточке, этот указатель функции устанавливается в функцию подключения пользователя. Если функция подключения выполнена успешно, карточка остается подключенной и инициализируется, а дескриптор карточки возвращается.

Прототип подпрограммы подключения выглядит следующим образом.

Connect(
  hSCardContext, // the card context passed in the parameter block
  szReader,      // the name of the reader
  mszCards,      // multiple string that contains
                 //    the possible card names in the reader
  pvUserData     // pointer to user data passed in parameter block
);

lpfnDisconnect

Указатель на подпрограмму отключения карточки вызывающего абонента.

Прототип подпрограммы отключения выглядит следующим образом.

Disconnect(
  hSCardContext, // the card context passed in the parameter block
  hCard,         // card handle
  pvUserData     // pointer to user data passed in the parameter block
);

Примечание при использовании lpfnConnect, lpfnCheckи lpfnDisconnect, все три процедуры обратного вызова должны присутствовать. Использование этих обратных вызовов позволяет дополнительно проверить, что вызывающее приложение обнаружило соответствующую карточку. Это лучший способ убедиться, что выбрана соответствующая карточка. Однако при использовании значения, не NULL для lpfnCheck, не должно быть lpfnConnect и lpfnDisconnect NULL (и pvUserData также следует указать), или dwShareMode и dwPreferredProtocols должны быть заданы.

pvUserData

Указатель void на пользовательские данные. Этот указатель передается вызывающей стороне в подпрограммах подключения, проверки и отключения.

dwShareMode

Если lpfnConnect не null, dwShareMode и dwPreferredProtocols члены игнорируются. Если lpfnConnectNULL и dwShareMode ненулевое, внутренний вызов выполняется для SCardConnect, использующего dwShareMode и dwPreferredProtocols в качестве параметра.

dwPreferredProtocols

Используется для внутреннего подключения, как описано в dwShareMode.

Замечания

Заметка

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

Требования

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

См. также

OPENCARDNAME_EX

SCardUIDlgSelectCard

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