OPENCARDNAMEA 结构 (winscard.h)

OPENCARDNAME 结构包含 GetOpenCardName 函数用来初始化智能卡 选择卡 对话框的信息。 建议使用 OPENCARDNAME_EX 调用 SCardUIDlgSelectCard,以 OPENCARDNAME调用 GetOpenCardName。 提供了 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

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

lpstrGroupNames

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

nMaxGroupNames

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

lpstrCardNames

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

nMaxCardNames

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

rgguidInterfaces

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

cguidInterfaces

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

lpstrRdr

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

nMaxRdr

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

lpstrCard

如果卡位于,则 lpstrCard 缓冲区包含该卡的名称。 缓冲区长度应至少为 256 个字符。

nMaxCard

lpstrCard指向的缓冲区的大小(以字节为单位)或字符(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

如果 lpfnConnectNULL,则忽略 dwShareModedwPreferredProtocols 成员。

如果 lpfnConnect NULLdwShareMode 为非零, 然后,对 SCardConnect 进行内部调用,该 使用 dwShareModedwPreferredProtocols 作为 dwShareModedwPreferredProtocols 参数。 如果连接成功,hCardHandle 设置为 hSCardConnect返回的句柄。

如果 lpfnConnectNULLdwShareMode 为零,则对话框将返回 hCardHandleNULL

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

注意 使用 lpfnConnectlpfnChecklpfnDisconnect时,应存在所有三个回调过程。 使用这些回调可以进一步验证调用应用程序是否找到了相应的卡片。 这是确保选择适当的卡片的最佳方式。
 

hCardHandle

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

言论

注意

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

要求

要求 价值
最低支持的客户端 Windows XP [仅限桌面应用]
支持的最低服务器 Windows Server 2003 [仅限桌面应用]
标头 winscard.h

另请参阅

GetOpenCardName

SCardConnect

SCardEstablishContext

SCardReleaseContext

SCardUIDlgSelectCard