SCardIntroduceCardTypeW 函数（winscard.h）

项目
11/20/2024

SCardIntroduceCardType 函数通过将智能卡添加到智能卡数据库，向智能卡子系统（对于活动用户）引入了智能卡。

语法

LONG SCardIntroduceCardTypeW(
  [in]           SCARDCONTEXT hContext,
  [in]           LPCWSTR      szCardName,
  [in, optional] LPCGUID      pguidPrimaryProvider,
  [in, optional] LPCGUID      rgguidInterfaces,
  [in]           DWORD        dwInterfaceCount,
  [in]           LPCBYTE      pbAtr,
  [in]           LPCBYTE      pbAtrMask,
  [in]           DWORD        cbAtrLen
);

参数

[in] hContext

标识资源管理器上下文的句柄。资源管理器上下文由上一次调用 SCardEstablishContext设置。此参数不能 NULL。

[in] szCardName

用户可以识别卡片的名称。

[in, optional] pguidPrimaryProvider

指向智能卡主要服务提供商的标识符（GUID）的指针。

[in, optional] rgguidInterfaces

标识智能卡支持的接口的标识符（GUID）数组。

[in] dwInterfaceCount

rgguidInterfaces 数组中的标识符数。

[in] pbAtr

ATR 字符串，可用于查询智能卡数据库时用于匹配目的（有关详细信息，请参阅 SCardListCards）。此字符串的长度由普通 ATR 分析确定。

[in] pbAtrMask

将智能卡的 ATR 与 pbAtr中提供的 ATR 进行比较时要使用的可选位掩码。如果此值为非NULL，则必须指向与 pbAtr中提供的 ATR 字符串相同的长度的字符串。当给定的 ATR 字符串 A 与 pbAtr中提供的 ATR 进行比较时，它与 A & M = pbAtr匹配，其中 M 是提供的掩码，& 表示位 AND。

[in] cbAtrLen

ATR 和可选 ATR 掩码的长度。如果此值为零，则 ATR 的长度由正常 ATR 分析确定。如果提供了 pbAtr 值，则此值不能为零。

返回值

此函数返回不同的值，具体取决于它是成功还是失败。

返回代码	描述
成功	SCARD_S_SUCCESS。
故障	错误代码。有关详细信息，请参阅智能卡返回值。

言论

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

SCardIntroduceCardType 函数是数据库管理功能。有关其他数据库管理功能的详细信息，请参阅智能卡数据库管理功能。

若要删除智能卡，请使用 SCardForgetCardType。

例子

以下示例演示如何引入卡片类型。该示例假定 hContext 是从上一次调用 SCardEstablishContext 函数获取的有效句柄。

GUID  MyGuid = { 0xABCDEF00,
                 0xABCD,
                 0xABCD,
                 0xAA, 0xBB, 0xCC, 0xDD,
                 0xAA, 0xBB, 0xCC, 0xDD };

static const BYTE MyATR[] =     { 0xaa, 0xbb, 0xcc, 0x00, 0xdd };
static const BYTE MyATRMask[] = { 0xff, 0xff, 0xff, 0x00, 0xff};

LONG            lReturn;

lReturn = SCardIntroduceCardType(hContext, 
                                 L"MyCardName",
                                 &MyGuid,
                                 NULL,    // No interface array
                                 0,       // Interface count = 0
                                 MyATR,
                                 MyATRMask,
                                 sizeof(MyATR));
if ( SCARD_S_SUCCESS != lReturn )
    printf("Failed SCardIntroduceCardType\n");

注意

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

要求

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