MINIPORT_OID_REQUEST 回调函数 (ndis.h)

项目
08/07/2023

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

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

语法

MINIPORT_OID_REQUEST MiniportOidRequest;

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

参数

[in] MiniportAdapterContext

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

[in] OidRequest

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

返回值

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

返回代码	说明
NDIS_STATUS_SUCCESS	微型端口驱动程序已按请求设置或获取数据。
NDIS_STATUS_PENDING	微型端口驱动程序将以异步方式完成请求。微型端口驱动程序完成所有处理后，必须调用 NdisMOidRequestComplete 函数，用于通知 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-structure 的 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。

注解

驱动程序在调用时指定 MiniportOidRequest 入口点 NdisMRegisterMiniportDriver 函数。

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

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

如果 MiniportOidRequest 返回NDIS_STATUS_PENDING，则在挂起的请求完成之前，NDIS 不会为 MiniportAdapterContext 中指定的微型端口适配器使用另一个请求调用 MiniportOidRequest 。

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

NDIS 在 IRQL == PASSIVE_LEVEL 调用 MiniportOidRequest 。

示例

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

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

MINIPORT_OID_REQUEST MyOidRequest;

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

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

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

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

要求

要求	值
最低受支持的客户端	在 NDIS 6.0 及更高版本中受支持。
目标平台	Windows
标头	ndis.h (包括 Ndis.h)
IRQL	PASSIVE_LEVEL
DDI 符合性规则	NdisOidComplete、NdisOidDoubleComplete、NdisOidDoubleRequest、NdisTimedOidComplete、WlanAssociation、WlanDisassociation、WlanTimedAssociation、WlanTimedConnectionRoaming、WlanTimedConnectRequest、WlanTimedLinkQuality、WlanTimedScan