MINIPORT_DIRECT_OID_REQUEST回调函数 (ndis.h)

项目
08/07/2023

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

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

语法

MINIPORT_DIRECT_OID_REQUEST MiniportDirectOidRequest;

NDIS_STATUS MiniportDirectOidRequest(
  [in] NDIS_HANDLE MiniportAdapterContext,
  [in] PNDIS_OID_REQUEST OidRequest
)
{...}

参数

[in] MiniportAdapterContext

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

[in] OidRequest

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

返回值

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

返回代码	说明
NDIS_STATUS_SUCCESS	微型端口驱动程序已按请求设置或获取数据。
NDIS_STATUS_PENDING	微型端口驱动程序将以异步方式完成请求。微型端口驱动程序完成所有处理后，它必须调用 NdisMDirectOidRequestComplete 函数，用于通知 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 上为请求指定的一个或多个参数无效。
NDIS_STATUS_NOT_ACCEPTED	调用后 MiniportDevicePnPEventNotify 函数指示意外删除，NDIS 调用驱动程序的 MiniportHaltEx 函数。如果驱动程序在 NDIS 调用 MiniportHaltEx 之前收到了任何 OID 请求，则应立即完成状态值为 NDIS_STATUS_NOT_ACCEPTED 的此类请求。
NDIS_STATUS_REQUEST_ABORTED	微型端口驱动程序停止处理请求。例如，NDIS 调用 MiniportResetEx 函数。
NDIS_STATUS_INDICATION_REQUIRED	微型端口驱动程序将提供 OID 完成状态以及后续状态指示。微型端口驱动程序无法返回NDIS_STATUS_INDICATION_REQUIRED，除非特定的 OID 允许。若要确定是否允许此状态，请参阅 OID 参考页。有关NDIS_STATUS_INDICATION_REQUIRED的详细信息，请参阅 NDIS_OID_REQUEST 和 NDIS_STATUS_INDICATION。

注解

MiniportDirectOidRequest 是一个可选函数。如果微型端口驱动程序处理直接 OID 请求，则会注册此函数。驱动程序在调用时指定 MiniportDirectOidRequest 入口点 NdisMRegisterMiniportDriver 函数。注册的微型端口驱动程序 MiniportCancelDirectOidRequest 函数还必须注册 MiniportDirectOidRequest。

NDIS 代表 MiniportDirectOidRequest 函数本身或调用 NdisDirectOidRequest 函数的绑定协议驱动程序调用 MiniportDirectOidRequest 函数。微型端口驱动程序应检查 在 OidRequest 参数中提供的请求，并执行请求的操作。

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

NDIS 不会与其他 OID 请求一起序列化发送到 MiniportDirectOidRequest 的请求。当发送到 MiniportOidRequest 或 MiniportDirectOidRequest 的其他请求未完成时，微型端口驱动程序必须能够处理对 MiniportDirectOidRequest 的多个调用。

注意如果微型端口驱动程序在 MiniportOidRequest 调用的上下文中等待，则 NDIS 检查 for-hang 逻辑不会重置未响应的微型端口驱动程序。因此，微型端口驱动程序不应等待 从 MiniportOidRequest 调用的上下文中完成硬件操作。相反，驱动程序可以返回NDIS_STATUS_PENDING并将工作项排队。

NDIS 在 IRQL <= DISPATCH_LEVEL 调用 MiniportDirectOidRequest 。

示例

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

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

MINIPORT_DIRECT_OID_REQUEST MyDirectOidRequest;

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

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

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

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