MINIPORT_CO_OID_REQUEST回调函数 (ndis.h)

项目
03/05/2024

MiniportCoOidRequest 函数处理 OID 请求，以在 CoNDIS 微型端口驱动程序中查询或设置信息。

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

语法

MINIPORT_CO_OID_REQUEST MiniportCoOidRequest;

NDIS_STATUS MiniportCoOidRequest(
  [in] NDIS_HANDLE MiniportAdapterContext,
  [in] NDIS_HANDLE MiniportVcContext,
       PNDIS_OID_REQUEST NdisRequest
)
{...}

参数

[in] MiniportAdapterContext

微型端口驱动程序在其 MiniportInitializeEx 函数中分配的上下文区域的句柄。微型端口驱动程序使用此上下文区域来维护微型端口适配器的状态信息。

[in] MiniportVcContext

微型端口驱动程序分配的上下文区域的句柄，微型端口驱动程序在其中维护其每个虚拟的连接 (VC) 状态。微型端口驱动程序从其 MiniportCoCreateVc 函数向 NDIS 提供此句柄。如果请求不是特定于 VC 的，则此参数为 NULL。

NdisRequest

指向 NDIS_OID_REQUEST 结构的指针，该结构包含微型端口驱动程序要处理的缓冲区和请求数据包。根据请求，驱动程序在此参数指向的结构中返回请求的信息。

返回值

MiniportCoOidRequest 可以返回以下状态值之一：

返回代码	说明
NDIS_STATUS_SUCCESS	微型端口驱动程序已按请求设置或获取数据。
NDIS_STATUS_PENDING	微型端口驱动程序将以异步方式完成请求。微型端口驱动程序完成所有处理后，必须调用 NdisMCoOidRequestComplete 函数，用于通知 NDIS 请求已完成。
NDIS_STATUS_INVALID_OID	指定的 OidRequest 参数无效或无法识别的请求。
NDIS_STATUS_NOT_SUPPORTED	微型端口驱动程序已识别指定 OidRequest 参数的请求，但不受支持。
NDIS_STATUS_BUFFER_TOO_SHORT	OidRequest 参数提供的缓冲区太小，无法容纳请求的数据。
NDIS_STATUS_INVALID_LENGTH	在 OidRequest 处的 NDIS_OID_REQUEST 结构的 InformationBufferLength 成员中指定的值对于指定的 OID_XXX 代码不正确。
NDIS_STATUS_INVALID_DATA	在 OidRequest iwas 处为请求指定的一个或多个参数无效。
NDIS_STATUS_NOT_ACCEPTED	在 NDIS 调用 MiniportDevicePnPEventNotify 函数指示意外删除，NDIS 调用驱动程序的 MiniportHaltEx 函数。如果驱动程序在 NDIS 调用 MiniportHaltEx 之前收到任何 OID 请求，则应立即完成状态值为 NDIS_STATUS_NOT_ACCEPTED 的此类请求。
NDIS_STATUS_REQUEST_ABORTED	微型端口驱动程序已停止处理请求。例如，NDIS 调用 MiniportResetEx 或 MiniportCancelOidRequest 函数。

注解

NDIS 调用 MiniportCoOidRequest 函数来处理 OID 请求，以查询或设置 CoNDIS 微型端口驱动程序中的信息。

若要注册 MiniportCoOidRequest，微型端口驱动程序从 MiniportSetOptions 函数调用 NdisSetOptionalHandlers 函数。在 MiniportSetOptions 中，微型端口驱动程序初始化 NDIS_MINIPORT_CO_CHARACTERISTICS结构，并在 NdisSetOptionalHandlers 的 OptionalHandlers 参数中传递它。

NDIS 代表它自己或代表调用 NdisCoOidRequest 函数的绑定协议驱动程序调用 MiniportCoOidRequest 函数。微型端口驱动程序应检查 OidRequest 中提供的请求并执行请求的操作。有关微型端口驱动程序处理的 OID 的详细信息，请参阅 NDIS OID。

请注意，NDIS 不会在 OidRequest 中验证特定于 OID 的内容。因此，驱动程序本身必须验证这些内容。如果驱动程序确定要设置的值超出边界，则它应使请求失败并返回NDIS_STATUS_INVALID_DATA。

如果 MiniportCoOidRequest 返回NDIS_STATUS_PENDING，则在挂起的请求完成之前，NDIS 可以使用另一个请求为 MiniportAdapterContext 中指定的微型端口适配器调用 MiniportCoOidRequest。 NDIS 不序列化面向连接的 OID 请求。

示例

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

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

MINIPORT_CO_OID_REQUEST MyCoOidRequest;

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

_Use_decl_annotations_
NDIS_STATUS
 MyCoOidRequest(
    NDIS_HANDLE  MiniportAdapterContext,
    NDIS_HANDLE  MiniportVcContext,
    PNDIS_OID_REQUEST  OidRequest
    )
  {...}

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

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