SCardListCardsW 函数 (winscard.h)

项目
08/27/2023

SCardListCards 函数搜索智能卡数据库，并提供之前由用户引入系统的命名卡列表。

调用方指定 ATR 字符串、一组接口标识符 (GUID) ，或同时指定这两者。如果同时提供 ATR 字符串和标识符数组，则返回的卡将与提供的 ATR 字符串匹配并支持指定的接口。

语法

LONG SCardListCardsW(
  [in]           SCARDCONTEXT hContext,
  [in, optional] LPCBYTE      pbAtr,
  [in]           LPCGUID      rgquidInterfaces,
  [in]           DWORD        cguidInterfaceCount,
  [out]          WCHAR        *mszCards,
  [in, out]      LPDWORD      pcchCards
);

参数

[in] hContext

标识查询的资源管理器上下文的句柄。资源管理器上下文可以通过之前调用 SCardEstablishContext 来设置。

如果此参数设置为 NULL，则搜索卡片不限于任何上下文。

[in, optional] pbAtr

要与已知卡进行比较的 ATR 字符串的地址;如果未执行 ATR 匹配，则为 NULL 。

[in] rgquidInterfaces

标识符数组 (GUID) ;如果不执行接口匹配，则为 NULL 。提供数组时，仅当卡支持所有指定的标识符时，才会返回卡名称。

[in] cguidInterfaceCount

rgguidInterfaces 数组中的条目数。如果 rgguidInterfaces 为 NULL，则忽略此值。

[out] mszCards

列出找到的智能卡的多字符串。如果此值为 NULL，SCardListCards 将忽略 pcchCards 中提供的缓冲区长度，返回如果此参数不是 pcchCards 的 NULL 以及成功代码，则返回的缓冲区长度。

[in, out] pcchCards

mszCards 缓冲区的长度（以字符为单位）。接收多字符串结构的实际长度，包括所有尾随 null 字符。如果将缓冲区长度指定为 SCARD_AUTOALLOCATE，则 mszCards 将转换为指向字节指针的指针，并接收包含多字符串结构的内存块的地址。此内存块必须与 SCardFreeMemory 一起解除分配。

返回值

此函数根据是成功还是失败返回不同的值。

返回代码	说明
Success	SCARD_S_SUCCESS。
失败	错误代码。有关详细信息，请参阅智能卡返回值。

注解

此函数不会重定向，但在远程桌面会话内调用函数不会导致错误。它仅表示结果来自远程计算机，而不是来自本地计算机。

若要返回引入子系统的所有智能卡，请将 pbAtr 和 rgguidInterfaces 设置为 NULL。

SCardListCards 函数是一个数据库查询函数。有关其他数据库查询函数的详细信息，请参阅智能卡数据库查询函数。

应在事务外部调用此函数。如果应用程序使用 SCardBeginTransaction 函数开始事务，然后调用此函数，它将重置 SCardBeginTransaction 函数) SCARDHANDLE 类型的 hCard 参数 (。

Windows Server 2008 R2 和 Windows 7： 在事务中调用此函数可能会导致计算机无响应。

Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP： 不适用。

示例

以下示例显示了智能卡的列表。

LPTSTR pmszCards = NULL;
LPTSTR pCard;
LONG lReturn;
DWORD cch = SCARD_AUTOALLOCATE;

// Retrieve the list of cards.
lReturn = SCardListCards(NULL,
                         NULL,
                         NULL,
                         NULL,
                         (LPTSTR)&pmszCards,
                         &cch );
if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardListCards\n");
    exit(1); // Or other appropriate error action
}
// Do something with the multi string of cards.
// Output the values.
// A double-null terminates the list of values.
pCard = pmszCards;
while ( '\0' != *pCard )
{
    // Display the value.
    printf("%S\n", pCard );
    // Advance to the next value.
    pCard = pCard + wcslen(pCard) + 1;
}

// Remember to free pmszCards (by calling SCardFreeMemory).
// ...

注意

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

要求


最低受支持的客户端	Windows XP [仅限桌面应用]
最低受支持的服务器	Windows Server 2003 [仅限桌面应用]
目标平台	Windows
标头	winscard.h
Library	Winscard.lib
DLL	Winscard.dll