PROTOCOL_CO_OID_REQUEST_COMPLETE回调函数 (ndis.h)

项目
08/07/2023

ProtocolCoOidRequestComplete 函数完成异步 CoNDIS OID 请求的处理。

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

语法

PROTOCOL_CO_OID_REQUEST_COMPLETE ProtocolCoOidRequestComplete;

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

参数

[in] ProtocolAfContext

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

[in] ProtocolVcContext

一个句柄，用于标识驱动程序为其请求或设置信息的 VC (VC) 的活动虚拟连接（如果请求特定于 VC）。否则，此参数为 NULL。

[in] ProtocolPartyContext

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

[in, out] OidRequest

指向驱动程序提供的 NDIS_OID_REQUEST 结构的指针，该结构以前传递给 NdisCoOidRequest 或 NdisMCmOidRequest 函数。

[in] Status

请求的最终状态。目标驱动程序或 NDIS 确定此最终状态。此参数确定 ProtocolCoOidRequestComplete 对 OidRequest 中的信息执行的操作。

返回值

无

备注

NDIS 调用 ProtocolCoOidRequestComplete 函数以完成 NdisCoOidRequest 函数或 NdisMCmOidRequest 函数返回NDIS_STATUS_PENDING CoNDIS 客户端、调用管理器或 MCM OID 请求的处理。

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

目标驱动程序是为 OID 信息请求提供服务的驱动程序。目标驱动程序对 NdisMCoOidRequestComplete、 NdisCoOidRequestComplete 的调用，或 NdisMCmOidRequestComplete 函数导致 NDIS 调用 ProtocolCoOidRequestComplete 函数。 NDIS 将传递给这些函数的 Status 参数的值作为输入 Status 参数转发到 ProtocolCoOidRequestComplete。

ProtocolCoOidRequestComplete 使用 Status 的输入值，如下所示：

如果 Status 为 NDIS_STATUS_SUCCESS，则 OidRequest 参数指向的 NDIS_OID_REQUEST 结构的 BytesRead 或 BytesWritten 成员将指定从 NDIS_OID_REQUEST 的 InformationBuffer 成员中的缓冲区传输到目标驱动程序的信息量，或者分别在 InformationBuffer 处返回的信息量。
如果驱动程序发出查询请求，ProtocolCoOidRequestComplete 可以根据在 NDIS_OID_REQUEST 的 Oid 成员中指定的值使用 InformationBuffer 中返回的数据。
如果 Status 为NDIS_STATUS_INVALID_LENGTH或NDIS_STATUS_BUFFER_TOO_SHORT，则 OidRequest 指向的 NDIS_OID_REQUEST 结构的 BytesNeeded 成员指定执行请求的操作所需的 NDIS_OID_REQUEST informationBufferLength 成员的 informationBufferLength 成员的 OID 特定值。
在这些情况下，ProtocolCoOidRequestComplete 可以为请求分配足够的缓冲区空间，使用 InformationBufferLength 所需的值设置另一个NDIS_OID_REQUEST结构，然后重试 OID 请求。
如果 Status 是不可恢复错误的NDIS_STATUS_ XXX 值， 则 ProtocolCoOidRequestComplete 应释放NDIS_OID_REQUEST结构的内存。 ProtocolCoOidRequestComplete 还应确定驱动程序是应关闭绑定还是调整其特定于绑定的状态信息，以处理对绑定的持续网络 I/O 操作。

有关系统定义的 OID 的详细信息，请参阅 NDIS OID。

可以在驱动程序有时间检查 NdisCoOidRequest 或 NdisMCmOidRequest 返回的状态代码之前调用 ProtocolCoOidRequestComplete。

NDIS 在 IRQL <= DISPATCH_LEVEL 调用 ProtocolCoOidRequestComplete。

示例

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

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

PROTOCOL_CO_OID_REQUEST_COMPLETE MyCoOidRequestComplete;

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

_Use_decl_annotations_
VOID
 MyCoOidRequestComplete(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  ProtocolPartyContext,
    PNDIS_OID_REQUEST  OidRequest,
    NDIS_STATUS  Status
    )
  {...}

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

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

要求

要求	值
最低受支持的客户端	在 NDIS 6.0 及更高版本中受支持。
目标平台	Windows
标头	ndis.h (包括 Ndis.h)
IRQL	<= DISPATCH_LEVEL (请参阅备注部分)