OPENCARDNAMEW 结构 (winscard.h)

项目
03/04/2024

OPENCARDNAME 结构包含 GetOpenCardName 函数用于初始化智能卡选择卡片对话框的信息。建议使用 OPENCARDNAME_EX 调用 SCardUIDlgSelectCard，而不能使用 OPENCARDNAME 调用 GetOpenCardName。提供 OPENCARDNAME 是为了向后兼容。

语法

typedef struct {
  DWORD          dwStructSize;
  HWND           hwndOwner;
  SCARDCONTEXT   hSCardContext;
  LPWSTR         lpstrGroupNames;
  DWORD          nMaxGroupNames;
  LPWSTR         lpstrCardNames;
  DWORD          nMaxCardNames;
  LPCGUID        rgguidInterfaces;
  DWORD          cguidInterfaces;
  LPWSTR         lpstrRdr;
  DWORD          nMaxRdr;
  LPWSTR         lpstrCard;
  DWORD          nMaxCard;
  LPCWSTR        lpstrTitle;
  DWORD          dwFlags;
  LPVOID         pvUserData;
  DWORD          dwShareMode;
  DWORD          dwPreferredProtocols;
  DWORD          dwActiveProtocol;
  LPOCNCONNPROCW lpfnConnect;
  LPOCNCHKPROC   lpfnCheck;
  LPOCNDSCPROC   lpfnDisconnect;
  SCARDHANDLE    hCardHandle;
} OPENCARDNAMEW, *POPENCARDNAMEW, *LPOPENCARDNAMEW;

成员

dwStructSize

指定结构的长度（以字节为单位）。此成员不得为 NULL。

hwndOwner

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

hSCardContext

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

lpstrGroupNames

指向包含以 null 结尾的组名字符串的缓冲区的指针。缓冲区中的最后一个字符串必须以两个 null 字符结尾。每个字符串都是要包含在搜索中的一组卡片的名称。如果 lpstrGroupNames 为 NULL，则搜索 (Scard$DefaultReaders) 的默认组。

nMaxGroupNames

lpstrGroupNames 字符串 (中 unicode 版本) (ANSI 版本) 或字符的最大字节数。

lpstrCardNames

指向包含以 null 结尾卡名称字符串的缓冲区的指针。缓冲区中的最后一个字符串必须以两个 null 字符结尾。每个字符串都是要定位的卡的名称。

nMaxCardNames

lpstrCardNames 字符串中 unicode 版本) ) 或字符 ( (ANSI 版本的最大字节数。

rgguidInterfaces

保留供将来使用。设置为 NULL。标识所需接口的 GUID 数组。

cguidInterfaces

保留供期货使用。设置为 NULL。 rgguidInterfaces 数组中的接口数。

lpstrRdr

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

nMaxRdr

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

lpstrCard

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

nMaxCard

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

lpstrTitle

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

dwFlags

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

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

pvUserData

指向用户数据的 void 指针。此指针将传递回 Connect、Check 和 Disconnect 例程上的调用方。

dwShareMode

如果 lpfnConnect 不为 NULL，则忽略 dwShareMode 和 dwPreferredProtocols 成员。

如果 lpfnConnect 为 NULL 且 dwShareMode 为非零值，则对使用 dwShareMode 和 dwPreferredProtocols 作为 dwShareMode 和 dwPreferredProtocols 参数的 SCardConnect 进行内部调用。如果连接成功， hCardHandle 将设置为 hSCardConnect 返回的句柄。

如果 lpfnConnect 为 NULL 且 dwShareMode 为零，则对话框返回 hCardHandle 为 NULL。

dwPreferredProtocols

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

dwActiveProtocol

返回对话框与卡建立连接时使用的实际协议。

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

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 回调) 连接卡 (句柄。