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

Статья
07/16/2024

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

Синтаксис

typedef struct {
  DWORD                      dwStructSize;
  SCARDCONTEXT               hSCardContext;
  HWND                       hwndOwner;
  DWORD                      dwFlags;
  LPCSTR                     lpstrTitle;
  LPCSTR                     lpstrSearchDesc;
  HICON                      hIcon;
  POPENCARD_SEARCH_CRITERIAA pOpenCardSearchCriteria;
  LPOCNCONNPROCA             lpfnConnect;
  LPVOID                     pvUserData;
  DWORD                      dwShareMode;
  DWORD                      dwPreferredProtocols;
  LPSTR                      lpstrRdr;
  DWORD                      nMaxRdr;
  LPSTR                      lpstrCard;
  DWORD                      nMaxCard;
  DWORD                      dwActiveProtocol;
  SCARDHANDLE                hCardHandle;
} OPENCARDNAME_EXA, *POPENCARDNAME_EXA, *LPOPENCARDNAME_EXA;

Члены

dwStructSize

Длина структуры в байтах. Значение этого элемента не должно быть NULL.

hSCardContext

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

hwndOwner

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

dwFlags

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

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

lpstrTitle

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

lpstrSearchDesc

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

hIcon

Дескриптор значка (32 x 32 пикселя). Вы можете указать значок для конкретного поставщика для отображения в диалоговом окне. Если это значение равно NULL, отображается универсальный значок чтения смарт-карт.

pOpenCardSearchCriteria

Указатель на используемую структуру OPENCARD_SEARCH_CRITERIA или NULL, если он не используется.

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

pvUserData

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

dwShareMode

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

dwPreferredProtocols

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

lpstrRdr

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

nMaxRdr

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

lpstrCard

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

nMaxCard

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

dwActiveProtocol

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

hCardHandle

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

Замечания

Заметка

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

Требования

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

См. также

SCardConnect

SCardEstablishContext

SCardReleaseContext

SCardUIDlgSelectCard

возвращаемых значений смарт-карт

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