SCardStatusA 函数 (winscard.h)

  • 项目

SCardStatus 函数提供读取器中智能卡的当前状态。 在成功调用 SCardConnect 之后和成功调用 SCardDisconnect 之前，可以随时调用它。 它不会影响读取器或读取器驱动程序的状态。

语法

LONG SCardStatusA(
  [in]                SCARDHANDLE hCard,
  [out]               LPSTR       mszReaderNames,
  [in, out, optional] LPDWORD     pcchReaderLen,
  [out, optional]     LPDWORD     pdwState,
  [out, optional]     LPDWORD     pdwProtocol,
  [out]               LPBYTE      pbAtr,
  [in, out, optional] LPDWORD     pcbAtrLen
);

参数

[in] hCard

从 SCardConnect 返回的引用值。

[out] mszReaderNames

显示名称列表 (多个字符串) ，通过这些字符串可知道当前连接的读取器。

[in, out, optional] pcchReaderLen

输入时，提供 szReaderName 缓冲区的长度。

输出时，接收实际长度 (，以读取者名称列表) 字符（包括尾随 NULL 字符）为单位。 如果此缓冲区长度指定为 SCARD_AUTOALLOCATE，则 szReaderName 将转换为指向字节指针的指针，并接收包含多字符串结构的内存块的地址。

[out, optional] pdwState

读取器中智能卡的当前状态。 成功后，它会收到以下状态指示器之一。

值 含义
SCARD_ABSENT
 读取器中没有卡。
SCARD_PRESENT
 读取器中有一个卡，但尚未移动到位置以供使用。
SCARD_SWALLOWED
 读取器中有一个卡可供使用。 卡未供电。
SCARD_POWERED
 正在为卡提供电源，但读取器驱动程序不知道卡的模式。
SCARD_NEGOTIABLE
 卡已重置，正在等待 PTS 协商。
SCARD_SPECIFIC
 卡已重置，并已建立特定的通信协议。

[out, optional] pdwProtocol

当前协议（如果有）。 仅当 返回的 pdwState 值SCARD_SPECIFICMODE时，返回的值才有意义。

值 含义
SCARD_PROTOCOL_RAW
 正在使用原始传输协议。
SCARD_PROTOCOL_T0
 正在使用 ISO 7816/3 T=0 协议。
SCARD_PROTOCOL_T1
 正在使用 ISO 7816/3 T=1 协议。

[out] pbAtr

指向 32 字节缓冲区的指针，该缓冲区从当前插入的卡接收 ATR 字符串（如果可用）。

[in, out, optional] pcbAtrLen

输入时，提供 pbAtr 缓冲区的长度。 输出时，接收 ATR 字符串中的字节数 (最大 32 个字节) 。 如果此缓冲区长度指定为 SCARD_AUTOALLOCATE，则 pbAtr 将转换为指向字节指针的指针，并接收包含多字符串结构的内存块的地址。

返回值

如果函数在读取器中成功提供智能卡的当前状态，则返回值SCARD_S_SUCCESS。

如果函数失败，它将返回错误代码。 有关详细信息，请参阅 智能卡返回值。

注解

SCardStatus 函数是智能卡和读取器访问函数。 有关其他访问函数的信息，请参阅 智能卡和读取器访问函数。

示例

以下示例演示如何确定智能卡的状态。

WCHAR           szReader[200];
DWORD           cch = 200;
BYTE            bAttr[32];
DWORD           cByte = 32;
DWORD           dwState, dwProtocol;
LONG            lReturn;

// Determine the status.
// hCardHandle was set by an earlier call to SCardConnect.
lReturn = SCardStatus(hCardHandle,
                      szReader,
                      &cch,
                      &dwState,
                      &dwProtocol,
                      (LPBYTE)&bAttr,
                      &cByte); 

if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardStatus\n");
    exit(1);     // or other appropriate action
}

// Examine retrieved status elements.
// Look at the reader name and card state.
printf("%S\n", szReader );
switch ( dwState )
{
    case SCARD_ABSENT:
        printf("Card absent.\n");
        break;
    case SCARD_PRESENT:
        printf("Card present.\n");
        break;
    case SCARD_SWALLOWED:
        printf("Card swallowed.\n");
        break;
    case SCARD_POWERED:
        printf("Card has power.\n");
        break;
    case SCARD_NEGOTIABLE:
        printf("Card reset and waiting PTS negotiation.\n");
        break;
    case SCARD_SPECIFIC:
        printf("Card has specific communication protocols set.\n");
        break;
    default:
        printf("Unknown or unexpected card state.\n");
        break;
}

注意

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

要求

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

另请参阅

SCardConnect

SCardDisconnect