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
保留供期货使用。 设置为 NULL。 rgguidInterfaces 数组中的接口数。
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
可用于初始化对话框的一组位标志。 当对话框返回时,它将设置这些标志来指示用户的输入。 此成员可以是以下标志的组合。
价值 | 意义 |
---|---|
|
仅当调用应用程序搜索的卡片未找到且可用于读取器时,才会显示对话框。 这允许找到卡、连接(通过内部对话框机制或用户回调函数),并返回到调用应用程序。 |
|
强制不显示 选择卡用户界面(UI),而不考虑搜索结果。 |
|
无论搜索结果如何,强制显示 选择卡片 UI。 |
pvUserData
指向用户数据的 void 指针。 此指针将传回 Connect、Check 和 Disconnect 例程上的调用方。
dwShareMode
如果 lpfnConnect 未 NULL,则忽略 dwShareMode 和 dwPreferredProtocols 成员。
如果
如果 lpfnConnectNULL,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
);
hCardHandle
已连接卡的句柄(通过内部对话框连接或 lpfnConnect 回调)。
言论
注意
winscard.h 标头将 OPENCARDNAME 定义为别名,该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非中性编码别名与非非编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息,请参阅函数原型的
要求
要求 | 价值 |
---|---|
最低支持的客户端 | Windows XP [仅限桌面应用] |
支持的最低服务器 | Windows Server 2003 [仅限桌面应用] |
标头 | winscard.h |