Структура OPENCARDNAMEA (winscard.h)

Статья
07/16/2024

Структура OPENCARDNAME содержит сведения, которые использует функция GetOpenCardName для инициализации смарт-карты выбора карточки. Вызов SCardUIDlgSelectCard с OPENCARDNAME_EX рекомендуется использовать для вызова GetOpenCardName с OPENCARDNAME. OPENCARDNAME предоставляется для обеспечения обратной совместимости.

Синтаксис

typedef struct {
  DWORD          dwStructSize;
  HWND           hwndOwner;
  SCARDCONTEXT   hSCardContext;
  LPSTR          lpstrGroupNames;
  DWORD          nMaxGroupNames;
  LPSTR          lpstrCardNames;
  DWORD          nMaxCardNames;
  LPCGUID        rgguidInterfaces;
  DWORD          cguidInterfaces;
  LPSTR          lpstrRdr;
  DWORD          nMaxRdr;
  LPSTR          lpstrCard;
  DWORD          nMaxCard;
  LPCSTR         lpstrTitle;
  DWORD          dwFlags;
  LPVOID         pvUserData;
  DWORD          dwShareMode;
  DWORD          dwPreferredProtocols;
  DWORD          dwActiveProtocol;
  LPOCNCONNPROCA lpfnConnect;
  LPOCNCHKPROC   lpfnCheck;
  LPOCNDSCPROC   lpfnDisconnect;
  SCARDHANDLE    hCardHandle;
} OPENCARDNAMEA, *POPENCARDNAMEA, *LPOPENCARDNAMEA;

Члены

dwStructSize

Указывает длину структуры в байтах. Этот элемент не должен быть NULL.

hwndOwner

Окно, владеющее диалоговым окном. Этот член может быть любым допустимым дескриптором окна или может быть null для классического компьютера по умолчанию.

hSCardContext

Контекст, используемый для связи с смарт-картой resource manager. Вызовите SCardEstablishContext, чтобы задать контекст диспетчера ресурсов и SCardReleaseContext. Этот элемент не должен быть NULL.

lpstrGroupNames

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

nMaxGroupNames

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

lpstrCardNames

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

nMaxCardNames

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

rgguidInterfaces

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

cguidInterfaces

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

lpstrRdr

Если карта расположена, буфер lpstrRdr содержит имя средства чтения, содержащего расположенную карточку. Буфер должен содержать не менее 256 символов.

nMaxRdr

Размер буфера в байтах (версия ANSI) или символах ( версии Юникода), на который указывает lpstrRdr. Если буфер слишком мал, чтобы содержать сведения о средстве чтения, GetOpenCardName возвращает SCARD_E_NO_MEMORY и требуемый размер буфера, на который указывает lpstrRdr.

lpstrCard

Если карта расположена, буфер lpstrCard содержит имя расположенной карточки. Буфер должен содержать не менее 256 символов.

nMaxCard

Размер буфера в байтах (версия ANSI) или символы (версия Юникода), на который указывает lpstrCard. Если буфер слишком мал, чтобы содержать сведения о карточке, GetOpenCardName возвращает SCARD_E_NO_MEMORY и требуемый размер буфера в nMaxCard.

lpstrTitle

Указатель на строку, которая будет помещена в заголовок диалогового окна. Если этот элемент NULL, система использует название по умолчанию "Выбрать карточку:".

dwFlags

Набор битовых флагов, которые можно использовать для инициализации диалогового окна. Когда диалоговое окно возвращается, он задает эти флаги, чтобы указать входные данные пользователя. Этот элемент может быть сочетанием следующих флагов.

Ценность	Значение
SC_DLG_MINIMAL_UI	Отображает диалоговое окно только в том случае, если карточка, которую ищет вызывающее приложение, не находится и доступно для использования в средстве чтения. Это позволяет найти карточку, подключиться (через внутренний механизм диалогового окна или функции обратного вызова пользователя) и вернуться в вызывающее приложение.
SC_DLG_NO_UI	Принудительное отсутствие отображения выбор карточкипользовательского интерфейса (пользовательский интерфейс), независимо от результата поиска.
SC_DLG_FORCE_UI	Принудительное отображение пользовательского интерфейса select Card независимо от результата поиска.

pvUserData

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

dwShareMode

Если lpfnConnect не null, dwShareMode и dwPreferredProtocols члены игнорируются.

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

Если lpfnConnectnull и dwShareMode равно нулю, диалоговое окно возвращает hCardHandle как NULL.

dwPreferredProtocols

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

dwActiveProtocol

Возвращает фактический протокол, используемый при подключении диалогового окна к карточке.

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

lpfnCheck

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

Если карточка отклонена подпрограммой проверки, возвращается FALSE и карточка отключена, как указано lpfnDisconnect.

Если карточка принимается подпрограммой проверки, возвращается TRUE. Когда пользователь принимает карту, все остальные карты, подключенные в данный момент, будут отключены, как указано в lpfnDisconnect, и эта карта будет возвращена как расположенная карта. Расположенная карточка останется подключенной.

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

Check(
  hSCardContext, // the card context passed in the parameter block
  hCard,         // card handle
  pvUserData     // pointer to user data passed in the 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, все три процедуры обратного вызова должны присутствовать. Использование этих обратных вызовов позволяет дополнительно проверить, что вызывающее приложение обнаружило соответствующую карточку. Это лучший способ убедиться, что выбрана соответствующая карточка.

hCardHandle

Дескриптор подключенной карточки (через внутреннее диалоговое окно или lpfnConnect обратного вызова).

Замечания

Заметка

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

Требования

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

См. также

GetOpenCardName

SCardConnect

SCardEstablishContext

SCardReleaseContext

SCardUIDlgSelectCard

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