PROTOCOL_CO_OID_REQUEST回调函数 (ndis.h)

项目
02/26/2024

ProtocolCoOidRequest 函数处理 CoNDIS 客户端或独立调用管理器通过调用 NdisCoOidRequest 函数启动的 OID 请求，或者 MCM) 驱动程序通过调用 NdisMCmOidRequest 函数启动的微型端口调用管理器 (。

注意必须使用 PROTOCOL_CO_OID_REQUEST 类型声明函数。有关详细信息，请参阅以下示例部分。

语法

PROTOCOL_CO_OID_REQUEST ProtocolCoOidRequest;

NDIS_STATUS ProtocolCoOidRequest(
  [in]      NDIS_HANDLE ProtocolAfContext,
  [in]      NDIS_HANDLE ProtocolVcContext,
  [in]      NDIS_HANDLE ProtocolPartyContext,
  [in, out] PNDIS_OID_REQUEST OidRequest
)
{...}

参数

[in] ProtocolAfContext

标识地址系列 (AF) 上下文区域的句柄。如果驱动程序是客户端，则它在调用时提供此句柄 NdisClOpenAddressFamilyEx 函数，用于将自身连接到调用管理器。如果驱动程序是调用管理器，则它从其 ProtocolCmOpenAf 函数提供此句柄。

[in] ProtocolVcContext

标识虚拟连接的句柄， (VC) 查询或设置信息（如果请求特定于 VC）。否则，此参数为 NULL。

[in] ProtocolPartyContext

一个句柄，用于标识多点 VC 上要查询或设置其信息的参与方（如果请求特定于参与方）。否则，此参数为 NULL。

[in, out] OidRequest

指向 NDIS_OID_REQUEST 结构的指针，该结构包含目标驱动程序要处理的缓冲区和请求数据包。根据请求，驱动程序在 OidRequest 指向的结构中返回请求的信息。

返回值

ProtocolCoOidRequest 可以返回下列值之一：

返回代码	说明
NDIS_STATUS_SUCCESS	客户端或调用管理器执行请求的操作。
NDIS_STATUS_PENDING	客户端或调用管理器以异步方式处理此请求，并将调用 NdisCoOidRequestComplete 函数或请求的操作完成时，NdisMCmOidRequestComplete 函数。
NDIS_STATUS_INVALID_LENGTH或NDIS_STATUS_BUFFER_TOO_SHORT	驱动程序使请求失败，因为 NdisCoOidRequest 或 NdisMCmOidRequest 函数的调用方没有为给定请求的 NDIS_OID_REQUEST 结构的 InformationBuffer 成员提供足够的值。驱动程序将 OidRequest 参数缓冲区中 NDIS_OID_REQUEST 的 BytesNeeded 成员设置为执行所请求操作所需的 InformationBufferLength 成员的特定于 OID 的值。
NDIS_STATUS_XXX	客户端或调用管理器因某些驱动程序确定的原因（例如为集指定的输入数据无效）使请求失败。
NDIS_STATUS_NOT_SUPPORTED	客户端或调用管理器使此请求失败，因为它无法识别 NdisRequest 缓冲区中 Oid 成员中的 OID_GEN_CO_XXX 代码。

注解

CoNDIS 客户端、调用管理器和 MMC 需要 ProtocolCoOidRequest 函数。 ProtocolCoOidRequest 类似于微型端口驱动程序的 MiniportCoOidRequest 函数。

CoNDIS 客户端和调用管理器在调用 NdisCoOidRequest 函数时，通过在 NdisAfHandle 参数中指定非 NULL 值来相互发送信息。同样，MCM 使用 NdisAfHandle 的显式值调用 NdisMCmOidRequest，以便将信息传达给客户端。对 NdisCoOidRequest 或 NdisMCmOidRequest 的此类调用会导致 NDIS 调用与指定 AF 句柄关联的目标客户端、调用管理器或 MCM 的 ProtocolCoOidRequest 函数。

若要将 ProtocolCoOidRequest 注册为客户端，驱动程序会初始化 NDIS_CO_CLIENT_OPTIONAL_HANDLERS 结构，并将其传递到 NdisSetOptionalHandlers 函数的 OptionalHandlers 参数。若要将 ProtocolCoOidRequest 注册为调用管理器，驱动程序会初始化 NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS 结构并将其传递到 OptionalHandlers 参数。

如果 NdisCoOidRequest 或 NdisMCmOidRequest 的 NdisVcHandle 和 NdisPartyHandle 参数为 NULL，则请求本质上是全局请求。也就是说， NdisVcHandle 或 NdisPartyHandle 的显式值指示 ProtocolCoOidRequest 应分别满足每个 VC 或每方给定的请求。

OidRequest 参数处的缓冲区是从非分页池分配的，因此可通过引发的 IRQL 进行访问。 NdisCoOidRequest (或 NdisMCmOidRequest) 的调用方必须释放 OidRequest 指向的 NDIS_OID_REQUEST 结构的 InformationBuffer 成员处的此缓冲区和内部缓冲区。

如果 ProtocolCoOidRequest 返回NDIS_STATUS_PENDING，则驱动程序随后必须调用 NdisCoOidRequestComplete 函数或当驱动程序完成请求时，MCM 驱动程序的 NdisMCmOidRequestComplete 函数。

示例

若要定义 ProtocolCoOidRequest 函数，必须首先提供一个函数声明，用于标识要定义的函数类型。 Windows 为驱动程序提供一组函数类型。使用函数类型声明函数可帮助驱动程序的代码分析、静态驱动程序验证程序 (SDV) 和其他验证工具查找错误，并且这是编写 Windows 操作系统驱动程序的要求。

例如，若要定义名为“ MyCoOidRequest”的 ProtocolCoOidRequest 函数，请使用 PROTOCOL_CO_OID_REQUEST 类型，如以下代码示例所示：

PROTOCOL_CO_OID_REQUEST MyCoOidRequest;

然后，按如下所示实现函数：

_Use_decl_annotations_
NDIS_STATUS
 MyCoOidRequest(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  ProtocolPartyContext,
    PNDIS_OID_REQUEST  OidRequest
    )
  {...}

PROTOCOL_CO_OID_REQUEST函数类型在 Ndis.h 头文件中定义。若要在运行代码分析工具时更准确地识别错误，请务必将 Use_decl_annotations 注释添加到函数定义。 Use_decl_annotations批注可确保使用应用于头文件中PROTOCOL_CO_OID_REQUEST函数类型的注释。有关函数声明要求的详细信息，请参阅使用 NDIS 驱动程序的函数角色类型声明函数。

有关 Use_decl_annotations的信息，请参阅批注函数行为。