NDIS_OID_REQUEST结构(ndis/oidrequest.h)

若要查询或设置 OID 信息,NDIS 将提交NDIS_OID_REQUEST结构来筛选驱动程序和微型端口驱动程序。

语法

typedef struct _NDIS_OID_REQUEST {
  NDIS_OBJECT_HEADER       Header;
  NDIS_REQUEST_TYPE        RequestType;
  NDIS_PORT_NUMBER         PortNumber;
  UINT                     Timeout;
  PVOID                    RequestId;
  NDIS_HANDLE              RequestHandle;
  union {
    NDIS_OID Oid;
    struct {
      NDIS_OID Oid;
      PVOID    InformationBuffer;
      UINT     InformationBufferLength;
      UINT     BytesWritten;
      UINT     BytesNeeded;
    } QUERY_INFORMATION;
    struct {
      NDIS_OID Oid;
      PVOID    InformationBuffer;
      UINT     InformationBufferLength;
      UINT     BytesRead;
      UINT     BytesNeeded;
    } SET_INFORMATION;
    struct {
      NDIS_OID Oid;
      PVOID    InformationBuffer;
      ULONG    InputBufferLength;
      ULONG    OutputBufferLength;
      ULONG    MethodId;
      UINT     BytesWritten;
      UINT     BytesRead;
      UINT     BytesNeeded;
    } METHOD_INFORMATION;
  } DATA;
  _REQUEST_DATA            _REQUEST_DATA;
  UCHAR                    *NdisReserved[NDIS_OID_REQUEST_NDIS_RESERVED_SIZE  sizeof(PVOID)];
  UCHAR                    *MiniportReserved[2  sizeof(PVOID)];
  UCHAR                    *SourceReserved[2  sizeof(PVOID)];
  UCHAR                    SupportedRevision;
  UCHAR                    Reserved1;
  USHORT                   Reserved2;
  NDIS_NIC_SWITCH_ID       SwitchId;
  NDIS_NIC_SWITCH_VPORT_ID VPortId;
  ULONG                    Flags;
} NDIS_OID_REQUEST, *PNDIS_OID_REQUEST;

成员

Header

NDIS_OID_REQUEST结构的 NDIS_OBJECT_HEADER 结构。 将 类型 成员设置为NDIS_OBJECT_TYPE_OID_REQUEST。 若要指示NDIS_OID_REQUEST结构的版本,请将 Revision 成员设置为以下值之一:

NDIS_OID_REQUEST_REVISION_2

添加了 SwitchIdVPortId,以及 NDIS 6.50 的 标志 成员。

标头大小 成员设置为NDIS_SIZEOF_OID_REQUEST_REVISION_2。

NDIS_OID_REQUEST_REVISION_1

NDIS 6.0 的原始版本。

标头大小 成员设置为NDIS_SIZEOF_OID_REQUEST_REVISION_1。

RequestType

请求类型作为 NDIS_REQUEST_TYPE 枚举值之一。

PortNumber

请求发送到的端口。 如果端口未知或默认值,则此成员为零。

Timeout

请求的超时(以秒为单位)。 如果超时在驱动程序完成请求之前过期,NDIS 可以重置驱动程序或取消请求。

RequestId

请求的标识符。 如果微型端口驱动程序必须立即完成请求,并且该请求的状态为NDIS_STATUS_INDICATION_REQUIRED,则微型端口驱动程序使用此 RequestId 值来设置关联的 NDIS_STATUS_INDICATION 结构的 RequestId 成员。

NDIS 或过度分配驱动程序也可以使用 RequestId 来取消请求。 当微型端口驱动程序收到取消请求时,微型端口驱动程序会取消任何具有匹配 RequestId的挂起请求。 如果 RequestId 为零,则微型端口驱动程序可以忽略此成员。 有关状态指示的详细信息,请参阅以下“备注”部分。

RequestHandle

标识发出 OID 请求的源的句柄。 如果微型端口驱动程序必须立即完成请求并完成状态为NDIS_STATUS_INDICATION_REQUIRED的请求,微型端口驱动程序使用此 RequestHandle 值来设置关联的NDIS_STATUS_INDICATION结构的 DestinationHandle 成员。 在这种情况下,NDIS 将仅向发出 OID 请求的源发送后续状态指示。

有关状态指示的详细信息,请参阅以下“备注”部分。

DATA

定义请求数据的联合。 数据中的信息因 RequestType 成员指定的请求类型而异。 指定了以下成员结构:

DATA.Oid

DATA.QUERY_INFORMATION

此结构包含 NdisRequestQueryInformationNdisRequestQueryStatistics 请求类型的参数。 此结构按如下所示指定:


struct _QUERY
  {
    NDIS_OID    Oid;
    PVOID       InformationBuffer;
    UINT        InformationBufferLength;
    UINT        BytesWritten;
    UINT        BytesNeeded;
  } QUERY_INFORMATION;

DATA.QUERY_INFORMATION.Oid

请求的操作的对象标识符。 该值是OID_ XXX 代码。

DATA.QUERY_INFORMATION.InformationBuffer

指向基础驱动程序或 NDIS 将请求的信息返回查询信息请求的缓冲区的指针。

DATA.QUERY_INFORMATION.InformationBufferLength

InformationBuffer的缓冲区的大小(以字节为单位)。 Oid 处的值确定适合此成员的值。

DATA.QUERY_INFORMATION.BytesWritten

基础驱动程序或 NDIS 传输到缓冲区的字节数,InformationBuffer 查询信息请求。 如果 NdisOidRequest 函数返回NDIS_STATUS_INVALID_LENGTH,则此成员的值毫无意义。

DATA.QUERY_INFORMATION.BytesNeeded

返回给定OID_ XXX 代码请求的查询信息所需的字节数。

如果 NdisOidRequest 返回NDIS_STATUS_SUCCESS,则此成员的值毫无意义。 如果 InformationBufferLength 对于查询请求上的给定OID_ XXX 来说太小,则此成员指示满足请求所需的缓冲区大小。

DATA.SET_INFORMATION

此结构包含 NdisRequestSetInformation 请求类型的参数。 此结构按如下所示指定:


struct _SET
  {
    NDIS_OID    Oid;
    PVOID       InformationBuffer;
    UINT        InformationBufferLength;
    UINT        BytesRead;
    UINT        BytesNeeded;
  } SET_INFORMATION;

DATA.SET_INFORMATION.Oid

请求的操作的对象标识符。 该值是OID_ XXX 代码。

DATA.SET_INFORMATION.InformationBuffer

指向基础驱动程序从中读取设置信息请求的调用方提供的信息的缓冲区的指针。

DATA.SET_INFORMATION.InformationBufferLength

InformationBuffer的缓冲区的大小(以字节为单位)。 Oid 处的值确定适合此成员的值。

DATA.SET_INFORMATION.BytesRead

基础驱动程序从缓冲区读取的字节数,InformationBuffer 用于设置信息请求。

DATA.SET_INFORMATION.BytesNeeded

执行给定OID_ XXX 代码请求的设置操作所需的字节数。

如果 NdisOidRequest 返回NDIS_STATUS_SUCCESS,则此成员的值毫无意义。 如果 InformationBuffer 上的缓冲区在设置请求上不包含给定的 OID_ XXX 足够的数据,则此成员表示需要多少数据。

DATA.METHOD_INFORMATION

此结构包含 NdisRequestMethod 请求类型的参数。 此结构按如下所示指定:


struct _METHOD
  {
    NDIS_OID            Oid;
    PVOID               InformationBuffer;
    ULONG               InputBufferLength;
    ULONG               OutputBufferLength;
    ULONG               MethodId;
    UINT                BytesWritten;
    UINT                BytesRead;
    UINT                BytesNeeded;
  } METHOD_INFORMATION;

DATA.METHOD_INFORMATION.Oid

请求的操作的对象标识符。 该值是OID_ XXX 代码。

DATA.METHOD_INFORMATION.InformationBuffer

指向基础驱动程序或 NDIS 返回查询操作的请求信息或基础驱动程序从中读取设置操作的调用方提供的信息的缓冲区的指针。 这些操作特定于正在发出的 NdisRequestMethod 请求类型。

注释 此缓冲区用于设置信息和查询信息请求。 因此,设置信息请求缓冲区中的数据将被为查询信息请求返回的数据覆盖。 确切的用法取决于由 Oid 成员指定的请求的操作。
 

DATA.METHOD_INFORMATION.InputBufferLength

InformationBuffer缓冲区中可读数据的大小(以字节为单位)。 Oid 处的值确定适合此成员的值。

DATA.METHOD_INFORMATION.OutputBufferLength

InformationBuffer 缓冲区中可以写入的字节数。

DATA.METHOD_INFORMATION.MethodId

要为方法 OID 运行的方法。 方法 OID 请求可以支持由 MethodId定义的多个操作。 它可以是大于或等于零的任何值。 零表示默认方法。 NDIS 可以使用一些预定义的方法定义公共方法 OID。 微型端口驱动程序可以定义自定义方法 OID。 有关自定义 OID 的详细信息,请参阅 OID_GEN_SUPPORTED_GUIDS

DATA.METHOD_INFORMATION.BytesWritten

基础驱动程序或 NDIS 传输到缓冲区的字节数,InformationBuffer 查询信息请求。 如果 NdisOidRequest 函数返回NDIS_STATUS_INVALID_LENGTH,则此成员的值毫无意义。

对于方法 OID,BytesWritten 应小于或等于 OutputBufferLength 成员中的值。

DATA.METHOD_INFORMATION.BytesRead

基础驱动程序从缓冲区读取的字节数,InformationBuffer 用于设置信息请求。

对于方法 OID,BytesRead 应小于或等于 InputBufferLength 成员中的值。

DATA.METHOD_INFORMATION.BytesNeeded

返回查询信息或执行给定OID_ XXX 代码请求的设置操作所需的字节数。

如果 NdisOidRequest 返回NDIS_STATUS_SUCCESS,则此成员的值毫无意义。 如果 InformationBufferLength 对于查询上的给定OID_ XXX 来说太小,则此成员表示满足请求所需的缓冲区大小。 如果 InformationBuffer 上的缓冲区不包含集上给定的 OID_ XXX 的足够数据,则此成员指示需要多少数据。

_REQUEST_DATA

NdisReserved[NDIS_OID_REQUEST_NDIS_RESERVED_SIZE * sizeof(PVOID)]

为 NDIS 保留的区域。

MiniportReserved[2 * sizeof(PVOID)]

为微型端口驱动程序保留的区域。

SourceReserved[2 * sizeof(PVOID)]

为原始驱动程序保留的区域。 保留为NDIS_OID_REQUEST结构的分配器。 这通常是 NDIS 协议驱动程序或 NDIS 筛选器驱动程序。

SupportedRevision

NDIS 6.0 或更高版本驱动程序在处理 OID 请求时支持的 NDIS 结构的修订。 修订的结构是任何具有 NDIS_OBJECT_HEADER 结构的 NDIS 6.0 结构。 当驱动程序成功设置 OID 时,它必须将 SupportedRevision 设置为支持的结构的修订号。 有关 NDIS 版本信息的详细信息,请参阅 指定 NDIS 版本信息

Reserved1

保留以供将来使用。

Reserved2

保留以供将来使用。

SwitchId

一个NDIS_NIC_SWITCH_ID值,该值标识运行由 VPortId指定的目标 VPort 的开关。

注意

NDIS 6.50 及更高版本中支持此字段。

VPortId

一个NDIS_NIC_SWITCH_VPORT_ID值,该值标识此 OID 请求所面向的 VPort。 仅当设置了 NDIS_OID_REQUEST_FLAGS_VPORT_ID_VALID 标志时,此字段才被视为有效。

注意

NDIS 6.50 及更高版本中支持此字段。

Flags

包含此 OID 请求的按位 OR 标志的 ULONG 值。 目前支持以下标志:

价值 描述
NDIS_OID_REQUEST_FLAGS_VPORT_ID_VALID 0x0001 设置此标志后,VportId 成员被视为有效,并标识 OID 的目标 VPort。 如果未设置此标志,则 OID 适用于微型端口适配器本身。

注意

NDIS 6.50 及更高版本中支持此字段。

言论

协议驱动程序或筛选器驱动程序应为 InformationBuffer 和NDIS_OID_REQUEST结构上的缓冲区分配非分页内存。 使用从分页内存分配的数据可能会导致严重的页面错误,因为基础驱动程序在 IRQL = DISPATCH_LEVEL 运行以执行请求的操作。

NDIS_OID_REQUEST包含协议驱动程序可以请求基础驱动程序的每种操作的 DATA 子结构。 在调用 NdisOidRequest之前,协议驱动程序将填充表示 Oid 成员中指定的查询或设置操作的子结构的相关成员。 NDIS 或基础驱动程序在将控制权返回到调用方之前填充剩余成员。

某些 OID 请求允许微型端口驱动程序提供状态指示的 OID 完成状态。 在这种情况下,微型端口驱动程序返回NDIS_STATUS_INDICATION_REQUIRED OID 请求的完成状态。 微型端口驱动程序无法返回此状态,除非特定的 OID 允许它。 若要确定是否允许此状态,请参阅 OID 参考页。

如果状态指示与微型端口驱动程序返回NDIS_STATUS_INDICATION_REQUIRED的 OID 请求相关联,则发出状态指示的驱动程序必须在 NDIS_STATUS_INDICATION 结构中设置 DestinationHandleRequestId 成员。

在这种情况下,驱动程序将 DestinationHandleRequestId 成员分别设置为 NDIS_OID_REQUEST RequestHandleRequestId 成员的值。

例如,在无线网络中,OID 请求的处理可能需要很长时间才能完成。 在这种情况下,微型端口驱动程序可以立即完成 OID 请求,并在以后提供状态指示,以提供 OID 请求的最终结果。

NdisRequestGenericn(1-4) 类型可用于创建自己的内部请求的微型端口驱动程序。 若要实现此类请求,微型端口驱动程序会将内部变量分配给这些泛型类型之一。

要求

要求 价值
最低支持的客户端 NDIS 6.0 及更高版本中受支持。
标头 ndis/oidrequest.h (include ndis.h)

另请参阅

NDIS_OBJECT_HEADER

NDIS_REQUEST_TYPE

NDIS_STATUS_INDICATION

NdisOidRequest

OID_GEN_SUPPORTED_GUIDS