NDIS_OID_REQUEST structure (ndis/oidrequest.h)

To query or set OID information, NDIS submits NDIS_OID_REQUEST structures to filter drivers and miniport drivers.

Syntax

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;

Members

Header

The NDIS_OBJECT_HEADER structure for the NDIS_OID_REQUEST structure. Set the Type member to NDIS_OBJECT_TYPE_OID_REQUEST. To indicate the version of the NDIS_OID_REQUEST structure, set the Revision member to one of the following values:

NDIS_OID_REQUEST_REVISION_2

Added the SwitchId, VPortId, and Flags members for NDIS 6.50.

Set the Header Size member to NDIS_SIZEOF_OID_REQUEST_REVISION_2.

NDIS_OID_REQUEST_REVISION_1

Original version for NDIS 6.0.

Set the Header Size member to NDIS_SIZEOF_OID_REQUEST_REVISION_1.

RequestType

The request type as one of the NDIS_REQUEST_TYPE enumeration values.

PortNumber

The port to which the request is sent. If the port is unknown or default, this member is zero.

Timeout

A time-out, in seconds, for the request. NDIS can reset the driver or cancel the request if the time-out expires before the driver completes the request.

RequestId

An identifier for the request. If a miniport driver must complete a request immediately and it completes the request with a status of NDIS_STATUS_INDICATION_REQUIRED, the miniport driver uses this RequestId value to set the RequestId member of the associated NDIS_STATUS_INDICATION structure.

NDIS or overlying drivers can also use the RequestId to cancel a request. When a miniport driver receives a cancellation request, the miniport driver cancels any pending requests with a matching RequestId. If RequestId is zero, the miniport driver can ignore this member. For more information about status indications, see the following Remarks section.

RequestHandle

A handle that identifies the source that issued the OID request. If a miniport driver must complete the request immediately and completes the request with a status of NDIS_STATUS_INDICATION_REQUIRED, the miniport driver uses this RequestHandle value to set the DestinationHandle member of the associated NDIS_STATUS_INDICATION structure. In this case, NDIS will send only the subsequent status indication to the source that issued the OID request.

For more information about status indications, see the following Remarks section.

DATA

A union that defines the request data. The information in the data varies according to the type of request as specified by the RequestType member. The following member structures are specified:

DATA.Oid

DATA.QUERY_INFORMATION

This structure contains the parameters for an NdisRequestQueryInformation or NdisRequestQueryStatistics request type. This structure is specified as follows:


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

DATA.QUERY_INFORMATION.Oid

The object identifier of the requested operation. The value is an OID_ XXX code.

DATA.QUERY_INFORMATION.InformationBuffer

A pointer to a buffer into which the underlying driver or NDIS returns the requested information for query-information requests.

DATA.QUERY_INFORMATION.InformationBufferLength

The size, in bytes, of the buffer at InformationBuffer. The value at Oid determines the value appropriate to this member.

DATA.QUERY_INFORMATION.BytesWritten

The number of bytes that the underlying driver or NDIS transfers into the buffer at InformationBuffer for query-information requests. If the NdisOidRequest function returns NDIS_STATUS_INVALID_LENGTH, the value of this member is meaningless.

DATA.QUERY_INFORMATION.BytesNeeded

The number of bytes that are required to return query information requested by the given OID_ XXX code.

If NdisOidRequest returns NDIS_STATUS_SUCCESS, the value of this member is meaningless. If the InformationBufferLength is too small for the given OID_ XXX on a query request, this member indicates how large a buffer is required to satisfy the request.

DATA.SET_INFORMATION

This structure contains the parameters for an NdisRequestSetInformation request type. This structure is specified as follows:


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

DATA.SET_INFORMATION.Oid

The object identifier of the requested operation. The value is an OID_ XXX code.

DATA.SET_INFORMATION.InformationBuffer

A pointer to a buffer from which the underlying driver reads caller-supplied information for set-information requests.

DATA.SET_INFORMATION.InformationBufferLength

The size, in bytes, of the buffer at InformationBuffer. The value at Oid determines the value appropriate to this member.

DATA.SET_INFORMATION.BytesRead

The number of bytes that the underlying driver read from the buffer at InformationBuffer for set-information requests.

DATA.SET_INFORMATION.BytesNeeded

The number of bytes that are required to carry out the set operation requested by the given OID_ XXX code.

If NdisOidRequest returns NDIS_STATUS_SUCCESS, the value of this member is meaningless. If the buffer at InformationBuffer does not contain sufficient data for the given OID_ XXX on a set request, this member indicates how much data is required.

DATA.METHOD_INFORMATION

This structure contains the parameters for an NdisRequestMethod request type. This structure is specified as follows:


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

The object identifier of the requested operation. The value is an OID_ XXX code.

DATA.METHOD_INFORMATION.InformationBuffer

A pointer to a buffer into which the underlying driver or NDIS returns the requested information for query operations or from which the underlying driver reads caller-supplied information for set operations. These operations are specific to the type of NdisRequestMethod request type that is being made.

Note  This buffer is used for both set-information and query-information requests. As a result, data in the buffer for the set-information request would be overwritten by data that is returned for the query-information request. The exact usage depends on the requested operation as specified by the Oid member.
 

DATA.METHOD_INFORMATION.InputBufferLength

The size, in bytes, of the readable data in the buffer at InformationBuffer. The value at Oid determines the value appropriate to this member.

DATA.METHOD_INFORMATION.OutputBufferLength

The number of bytes in the buffer at InformationBuffer that the driver can write.

DATA.METHOD_INFORMATION.MethodId

The method to run for a method OID. A method OID request can support multiple operations as defined by MethodId. It can be any value that is greater or equal to zero. Zero indicates the default method. NDIS can define public method OIDs with some predefined methods. Miniport drivers can define custom method OIDs. For more information about custom OIDs, see OID_GEN_SUPPORTED_GUIDS.

DATA.METHOD_INFORMATION.BytesWritten

The number of bytes that the underlying driver or NDIS transfers into the buffer at InformationBuffer for query-information requests. If the NdisOidRequest function returns NDIS_STATUS_INVALID_LENGTH, the value of this member is meaningless.

For method OIDs, BytesWritten should be less than or equal to the value in the OutputBufferLength member.

DATA.METHOD_INFORMATION.BytesRead

The number of bytes that the underlying driver read from the buffer at InformationBuffer for set-information requests.

For method OIDs, BytesRead should be less than or equal to the value in the InputBufferLength member.

DATA.METHOD_INFORMATION.BytesNeeded

The number of bytes that are required to return query information or to carry out the set operation requested by the given OID_ XXX code.

If NdisOidRequest returns NDIS_STATUS_SUCCESS, the value of this member is meaningless. If the InformationBufferLength is too small for the given OID_ XXX on a query, this member indicates how large a buffer is required to satisfy the request. If the buffer at InformationBuffer does not contain sufficient data for the given OID_ XXX on a set, this member indicates how much data is required.

_REQUEST_DATA

NdisReserved[NDIS_OID_REQUEST_NDIS_RESERVED_SIZE * sizeof(PVOID)]

An area that is reserved for NDIS.

MiniportReserved[2 * sizeof(PVOID)]

An area that is reserved for the miniport driver.

SourceReserved[2 * sizeof(PVOID)]

An area that is reserved for the originating driver. Reserved for the allocator of the NDIS_OID_REQUEST structure. This is usually an NDIS protocol driver or an NDIS filter driver.

SupportedRevision

The revision of an NDIS structure that was supported by an NDIS 6.0 or later driver when it handled an OID request. A revisioned structure is any NDIS 6.0 structure that has an NDIS_OBJECT_HEADER structure inside it. When the driver succeeds in setting an OID, it must set SupportedRevision to the revision number of the structure that it supported. For more information about NDIS version information, see Specifying NDIS Version Information.

Reserved1

Reserved for future use.

Reserved2

Reserved for future use.

SwitchId

An NDIS_NIC_SWITCH_ID value that identifies the switch on which the target VPort, specified by VPortId, is running.

Note

This field is supported in NDIS 6.50 and later.

VPortId

An NDIS_NIC_SWITCH_VPORT_ID value that identifies the VPort that this OID request is targeting. This field is considered valid only if the NDIS_OID_REQUEST_FLAGS_VPORT_ID_VALID flag is set.

Note

This field is supported in NDIS 6.50 and later.

Flags

A ULONG value that contains a bitwise OR of flags for this OID request. Currently, these flags are supported:

Flag Value Description
NDIS_OID_REQUEST_FLAGS_VPORT_ID_VALID 0x0001 When this flag is set, the VportId member is considered valid and identifies the VPort to which the OID is targeted. If this flag is not set, then the OID is for the miniport adapter itself.

Note

This field is supported in NDIS 6.50 and later.

Remarks

A protocol driver or a filter driver should allocate nonpaged memory for the buffer at InformationBuffer and for the NDIS_OID_REQUEST structure. Using data that is allocated from paged memory can cause fatal page faults because the underlying drivers run at IRQL = DISPATCH_LEVEL to carry out the requested operation.

NDIS_OID_REQUEST contains a DATA substructure for each type of operation that a protocol driver can request of an underlying driver. Before calling NdisOidRequest, the protocol driver fills in the relevant members of the substructure that represents the query or set operation it specified in the Oid member. NDIS or the underlying driver fills in the remaining members before it returns control to the caller.

Some OID requests allow a miniport driver to provide an OID completion status with a status indication. In this case, the miniport driver returns NDIS_STATUS_INDICATION_REQUIRED for the completion status of the OID request. A miniport driver cannot return this status unless the particular OID allows it. To determine if this status is allowed, see the OID reference page.

If a status indication is associated with an OID request where the miniport driver returned NDIS_STATUS_INDICATION_REQUIRED, the driver making the status indication must set the DestinationHandle and RequestId members in the NDIS_STATUS_INDICATION structure.

In this case, the driver sets the DestinationHandle and RequestId members to the values from the RequestHandle and RequestId members in the NDIS_OID_REQUEST structure, respectively.

For example, in wireless networking, the processing of an OID request can take a very long time to complete. In this case, the miniport driver can complete the OID request immediately and provide a status indication later to provide the final result for the OID request.

The NdisRequestGenericn(1-4) types are available for miniport drivers that create their own internal requests. To implement such a request, a miniport driver assigns an internal variable to one of these generic types.

Requirements

Requirement Value
Minimum supported client Supported in NDIS 6.0 and later.
Header ndis/oidrequest.h (include ndis.h)

See also

NDIS_OBJECT_HEADER

NDIS_REQUEST_TYPE

NDIS_STATUS_INDICATION

NdisOidRequest

OID_GEN_SUPPORTED_GUIDS