SCardListReadersA 函数 (winscard.h)
SCardListReaders 函数提供一组命名读取器组中的读取器列表,消除了重复项。
调用方提供读取器组的列表,并接收命名组中的读取器列表。 忽略无法识别的组名称。 此函数仅返回当前附加到系统的命名组中可供使用的读取器。
语法
LONG SCardListReadersA(
[in] SCARDCONTEXT hContext,
[in, optional] LPCSTR mszGroups,
[out] LPSTR mszReaders,
[in, out] LPDWORD pcchReaders
);
参数
[in] hContext
标识查询的 资源管理器上下文 的句柄。 资源管理器上下文可以通过之前调用 SCardEstablishContext 来设置。
如果此参数设置为 NULL,则搜索读取器不限于任何上下文。
[in, optional] mszGroups
以多字符串形式定义的系统读取器组的名称。 使用 NULL 值列出系统 (中的所有读取器,即 SCard$AllReaders 组) 。
[out] mszReaders
列出提供的读取器组中卡读取器的多字符串。 如果此值为 NULL,SCardListReaders 将忽略 pcchReaders 中提供的缓冲区长度,写入如果此参数不是 pcchReaders的 NULL,将返回的缓冲区长度,并返回成功代码。
[in, out] pcchReaders
mszReaders 缓冲区的长度(以字符为单位)。 此参数接收多字符串结构的实际长度,包括所有尾随 null 字符。 如果将缓冲区长度指定为 SCARD_AUTOALLOCATE,则 mszReaders 将转换为指向字节指针的指针,并接收包含多字符串结构的内存块的地址。 此内存块必须与 SCardFreeMemory 一起解除分配。
返回值
此函数根据是成功还是失败返回不同的值。
返回代码/值 | 说明 |
---|---|
|
SCARD_S_SUCCESS |
|
SCARD_E_NO_READERS_AVAILABLE |
|
SCARD_E_READER_UNAVAILABLE |
|
错误代码。 有关详细信息,请参阅 智能卡返回值。 |
注解
SCardListReaders 函数是数据库查询函数。 有关其他数据库查询函数的详细信息,请参阅 智能卡数据库查询函数。
示例
以下示例显示列出读取器。
LPTSTR pmszReaders = NULL;
LPTSTR pReader;
LONG lReturn, lReturn2;
DWORD cch = SCARD_AUTOALLOCATE;
// Retrieve the list the readers.
// hSC was set by a previous call to SCardEstablishContext.
lReturn = SCardListReaders(hSC,
NULL,
(LPTSTR)&pmszReaders,
&cch );
switch( lReturn )
{
case SCARD_E_NO_READERS_AVAILABLE:
printf("Reader is not in groups.\n");
// Take appropriate action.
// ...
break;
case SCARD_S_SUCCESS:
// Do something with the multi string of readers.
// Output the values.
// A double-null terminates the list of values.
pReader = pmszReaders;
while ( '\0' != *pReader )
{
// Display the value.
printf("Reader: %S\n", pReader );
// Advance to the next value.
pReader = pReader + wcslen((wchar_t *)pReader) + 1;
}
// Free the memory.
lReturn2 = SCardFreeMemory( hSC,
pmszReaders );
if ( SCARD_S_SUCCESS != lReturn2 )
printf("Failed SCardFreeMemory\n");
break;
default:
printf("Failed SCardListReaders\n");
// Take appropriate action.
// ...
break;
}
注意
winscard.h 标头将 SCardListReaders 定义为别名,该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配,从而导致编译或运行时错误。 有关详细信息,请参阅 函数原型的约定。
要求
要求 | 值 |
---|---|
最低受支持的客户端 | Windows XP [仅限桌面应用] |
最低受支持的服务器 | Windows Server 2003 [仅限桌面应用] |
目标平台 | Windows |
标头 | winscard.h |
Library | Winscard.lib |
DLL | Winscard.dll |