OPENCARDNAME_EXA 结构 (winscard.h)

项目
03/04/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

用于与智能卡资源管理器通信的上下文。调用 SCardEstablishContext 以设置资源管理器上下文，并调用 SCardReleaseContext 以释放它。此成员的值不得为 NULL。

hwndOwner

拥有对话框的窗口。此成员可以是任何有效的窗口句柄，也可以是桌面默认值的 NULL 。

dwFlags

可用于初始化对话框的一组位标志。当对话框返回时，它会设置这些标志以指示用户的输入。此成员可以是以下标志之一。

值	含义
SC_DLG_MINIMAL_UI	仅当调用应用程序搜索的卡未找到且可用于读取器时，才显示对话框。这样就可以找到卡，通过内部对话框机制或用户回调函数) (连接，并返回到调用应用程序。
SC_DLG_NO_UI	无论搜索结果如何，都不强制显示 “选择卡”用户界面 (UI) 。
SC_DLG_FORCE_UI	无论搜索结果如何，强制显示 “选择卡片 ”UI。

lpstrTitle

指向要放置在对话框标题栏中的字符串的指针。如果此成员为 NULL，则系统使用默认标题“选择卡片：”。

lpstrSearchDesc

指向要作为插入智能卡的提示向用户显示的字符串的指针。如果此成员为 NULL，则系统会使用默认文本“请插入智能卡”。

hIcon

图标的句柄 (32 x 32 像素) 。可以指定要在对话框中显示的特定于供应商的图标。如果此值为 NULL，则显示一个通用的智能卡读取器加载图标。

pOpenCardSearchCriteria

指向要使用的 OPENCARD_SEARCH_CRITERIA 结构的指针;如果未使用，则为 NULL。

lpfnConnect

指向调用方卡连接例程的指针。如果调用方需要执行其他处理以连接到卡，则此函数指针将设置为用户的 connect 函数。如果连接函数成功，则卡保持连接状态并初始化，并返回卡句柄。

连接例程的原型如下所示。

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 成员。如果 lpfnConnect 为 NULL 且 dwShareMode 为非零值，则会对 SCardConnect 进行内部调用，该调用使用 dwShareMode 和 dwPreferredProtocols 作为 dwShareMode 和 dwPreferredProtocols 参数。如果连接成功， hCardHandle 设置为 SCardConnect 返回的句柄。如果 lpfnConnect 为 NULL 且 dwShareMode 为零， 则 hCardHandle 设置为 NULL。

dwPreferredProtocols

用于内部连接，如 dwShareMode 中所述。

lpstrRdr

如果找到卡，则 lpstrRdr 缓冲区包含读取器的名称，该读取器包含定位卡。缓冲区的长度应至少为 256 个字符。

nMaxRdr

lpstrRdr 指向的缓冲区 (ANSI 版本) 或字符 (Unicode 版本) 的字符。如果缓冲区太小，无法包含读取器信息， SCardUIDlgSelectCard 将返回SCARD_E_NO_MEMORY以及 lpstrRdr 指向的缓冲区的所需大小。

lpstrCard

如果找到卡，则 lpstrCard 缓冲区包含所卡的名称。缓冲区的长度应至少为 256 个字符。

nMaxCard

lpstrCard 指向的缓冲区 (ANSI 版本) 或字符 (Unicode 版本) 字符。如果缓冲区太小，无法包含卡信息，则 SCardUIDlgSelectCard 将返回SCARD_E_NO_MEMORY以及 nMaxCard 中所需的缓冲区大小。

dwActiveProtocol

对话框连接到卡时使用的实际协议。

hCardHandle

通过内部对话框连接或 lpfnConnect 回调) 连接卡 (句柄。

注解

注意

winscard.h 标头将 OPENCARDNAME_EX 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。