NdisCoAssignInstanceName 函数 (ndis.h)

项目
02/26/2024

NdisCoAssignInstanceName 将实例名称分配给 VC，并使 NDIS 使用 Windows Management Instrumentation (WMI) 为分配的名称注册 GUID (全局唯一标识符) 。

语法

NDIS_STATUS NdisCoAssignInstanceName(
  [in]            NDIS_HANDLE  NdisVcHandle,
  [in]            PNDIS_STRING BaseInstanceName,
  [out, optional] PNDIS_STRING VcInstanceName
);

参数

[in] NdisVcHandle

指定要命名的 VC 的句柄。此句柄由 NDIS 在最初使用 NdisCoCreateVc 创建时由 NDIS 提供，无论是由准备发出传出呼叫的客户端还是由准备将传入呼叫调度到客户端的呼叫管理器提供。

[in] BaseInstanceName

指向NDIS_STRING类型的指针，该类型描述调用方提供的 Unicode 字符串，该字符串指定 VC 的基名称。基名称可以是任何可本地化的 Unicode 字符串，用于唯一标识微型端口驱动程序范围内其他已命名 VC 的 VC。对于 Windows Vista 及更高版本，NDIS 将NDIS_STRING类型定义为 UNICODE_STRING 类型。

[out, optional] VcInstanceName

指向调用方分配NDIS_STRING类型的指针，在该类型中，此例程返回 Unicode 字符串，该字符串指定为 VC 分配的 NDIS 分配实例名称。

返回值

NdisCoAssignInstanceName 可以返回以下任一项：

返回代码	说明
NDIS_STATUS_SUCCESS	NDIS 向指定的 VC 分配了实例名称，并使用 WMI 为实例名称注册了 GUID。
NDIS_STATUS_FAILURE	尝试将实例名称分配给 VC 失败。
NDIS_STATUS_RESOURCES	NDIS 无法为实例名称分配缓冲区。

注解

使用 NdisCoCreateVc 启动 VC 设置后，调用管理器或面向连接的客户端可以使用 NdisCoAssignInstanceName 为 VC 命名。调用 NdisCoAssignInstanceName 会导致 NDIS 为 VC 分配实例名称，并将实例名称注册到 WMI。然后，WMI 客户端可以枚举 VC，并查询或设置相对于 VC 的 OID。

(MCM) 驱动程序的集成微型端口调用管理器无法使用 NdisCoAssignInstanceName 为其 VC 命名。相反，MCM 驱动程序应为 VC 创建自定义 GUID 和 OID，并使用 NDIS 注册 GUID 到 OID 的映射。

NDIS 通过将索引追加到调用方指向的基名称，为指定的 VC 创建实例名称。 NDIS 将基名称 (索引) 返回给调用方的完整实例名称，然后使用 WMI 注册实例名称的 GUID。 WMI 客户端只能枚举和查询命名的 VC。未命名的 VC 对 WMI 客户端不可见。

如果指定的 VC 已在上一次调用 NdisCoAssignInstanceName) 中分配了实例名称 (，则 NDIS 将返回NDIS_STATUS_SUCCESS以及分配给 VC 的原始 实例名称。实例名称将保留分配给 VC，直到删除该 VC。

调用方可以将返回的实例名称与 NDIS 之前从 NdisCoCreateVc 返回给调用方命名的 VC 的句柄相关联。但是，NDIS 将继续使用 VC 句柄（而不是实例名称）在后续调用中引用 VC。 NdisCoAssignInstanceName 的调用方可能会发现需要将实例名称返回到其他某个管理实体。

调用方负责释放包含返回的实例名称的缓冲区。使用 NdisCoDeleteVc 删除命名的 VC 后，调用方必须使用 NdisFreeString 释放缓冲区。

要求

要求	值
最低受支持的客户端	NDIS 6.0 和 NDIS 5.1 驱动程序支持 (请参阅 Windows Vista 中的 NdisCoAssignInstanceName (NDIS 5.1) ) 。 NDIS 5.1 驱动程序支持 (请参阅 Windows XP 中的 NdisCoAssignInstanceName (NDIS 5.1) ) 。
目标平台	桌面
标头	ndis.h (包括 Ndis.h)
Library	Ndis.lib
IRQL	DISPATCH_LEVEL
DDI 符合性规则	Irql_Connection_Function (ndis)