通过

OPENCARD_SEARCH_CRITERIAW结构 （winscard.h）

  • 项目

SCardUIDlgSelectCard 函数使用 OPENCARD_SEARCH_CRITERIA 结构，以便识别满足调用方设置要求的卡。 但是，可以在不使用此结构的情况下调用 SCardUIDlgSelectCard。

语法

typedef struct {
  DWORD          dwStructSize;
  LPWSTR         lpstrGroupNames;
  DWORD          nMaxGroupNames;
  LPCGUID        rgguidInterfaces;
  DWORD          cguidInterfaces;
  LPWSTR         lpstrCardNames;
  DWORD          nMaxCardNames;
  LPOCNCHKPROC   lpfnCheck;
  LPOCNCONNPROCW lpfnConnect;
  LPOCNDSCPROC   lpfnDisconnect;
  LPVOID         pvUserData;
  DWORD          dwShareMode;
  DWORD          dwPreferredProtocols;
} OPENCARD_SEARCH_CRITERIAW, *POPENCARD_SEARCH_CRITERIAW, *LPOPENCARD_SEARCH_CRITERIAW;

成员

dwStructSize

结构的长度（以字节为单位）。 不得 NULL。

lpstrGroupNames

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

nMaxGroupNames

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

rgguidInterfaces

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

cguidInterfaces

保留以供将来使用。 rgguidInterfaces 数组中的接口数。 将此成员设置为 NULL。

lpstrCardNames

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

nMaxCardNames

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

lpfnCheck

指向调用方卡片验证例程的指针。 如果不需要特殊卡验证，此指针 NULL。 如果验证例程拒绝该卡，则返回 FALSE，并且该卡将断开连接。 如果验证例程接受卡片，则返回 true 。

检查例程的原型如下所示。

Boolean Check(
  hSCardContext, // the card context passed in the parameter block
  hCard,         // card handle
  pvUserData     // pointer to user data passed in the parameter block
);

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

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时，应存在所有三个回调过程。 使用这些回调可以进一步验证调用应用程序是否找到了相应的卡片。 这是确保选择适当的卡片的最佳方式。 但是，当对 lpfnCheck使用不 NULL 的值时，lpfnConnect 和 lpfnDisconnect 不应 NULL（还应提供 pvUserData），或者必须同时设置 dwShareMode 和 dwPreferredProtocols。
 

pvUserData

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

dwShareMode

如果 lpfnConnect 未 NULL，则忽略 dwShareMode 和 dwPreferredProtocols 成员。 如果 lpfnConnect NULL，dwShareMode 为非零，则对使用 dwShareMode 和 dwPreferredProtocols 作为参数的 SCardConnect 进行内部调用。

dwPreferredProtocols

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

言论

注意

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

要求

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

另请参阅

OPENCARDNAME_EX

SCardUIDlgSelectCard