SCardListReadersWithDeviceInstanceIdA 函数 (winscard.h)

  • 项目

SCardListReadersWithDeviceInstanceId 函数获取已提供设备实例标识符的读取器列表。 此函数不会影响读取器的状态。

语法

LONG SCardListReadersWithDeviceInstanceIdA(
  [in]            SCARDCONTEXT hContext,
  [in]            LPCSTR       szDeviceInstanceId,
  [out, optional] LPSTR        mszReaders,
  [in, out]       LPDWORD      pcchReaders
);

参数

[in] hContext

标识查询的资源管理器上下文的句柄。 可以通过之前调用 SCardEstablishContext 函数来设置资源管理器上下文。 此参数不能为 NULL。

[in] szDeviceInstanceId

读取器的设备实例 ID。 可以通过使用读取器名称调用 SCardGetReaderDeviceInstanceId 函数或从 DDK 调用 SetupDiGetDeviceInstanceId 函数来获取此值。

[out, optional] mszReaders

在提供的设备实例标识符中包含智能卡读取器的多字符串。 如果此值为 NULL，则该函数将忽略 pcchReaders 参数中提供的缓冲区长度，写入如果此参数不是 PCchReaders的 NULL，将返回的缓冲区长度，并返回成功代码。

[in, out] pcchReaders

mszReaders 缓冲区的长度（以字符为单位）。 此参数接收多字符串结构的实际长度，包括所有终止 null 字符。 如果将缓冲区长度指定为 SCARD_AUTOALLOCATE，则 mszReaders 将转换为指向字节指针的指针，并接收包含多字符串结构的内存块的地址。 使用此内存后，使用 SCardFreeMemory 函数将其解除分配。

返回值

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

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

注解

不会重定向此函数。 在远程桌面会话内调用 SCardListReadersWithDeviceInstanceId 函数失败并显示SCARD_E_READER_UNAVAILABLE错误代码。

示例


szDeviceInstanceIdcchReaderNameLONG     lReturn, lReturn2;

LPTSTR   pmszReaders = NULL;
LPTSTR   pReader = NULL;WCHAR
DWORD    cchReaderName = SCARD_AUTOALLOCATE;

// Retrieve the reader’s name from it’s device instance ID
// hContext was set by a previous call to SCardEstablishContext. 

// szDeviceInstanceId was obtained by calling SetupDiGetDeviceInstanceId
lReturn = SCardListReadersWithDeviceInstanceId (hContext,
                         szDeviceInstanceId,
                         (LPTSTR)&pmszReaders,
                         &cchReaderName);

switch( lReturn )
{
    case SCARD_E_NO_READERS_AVAILABLE:
        printf("No readers have the provided device instance ID.\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( hContext,
                                   pmszReaders );
        if ( SCARD_S_SUCCESS != lReturn2 )
            printf("Failed SCardFreeMemory\n");
        break;

default:
        printf("Failed SCardListReaders\n");
        // Take appropriate action.
        // ...
        break;

注意

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

要求

   
最低受支持的客户端 Windows 8 [仅限桌面应用]
最低受支持的服务器 Windows Server 2012 [仅限桌面应用]
目标平台 Windows
标头 winscard.h