NDIS_OID_REQUEST structure

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 _REQUEST_DATA {
    struct _QUERY {
      NDIS_OID Oid;
      PVOID    InformationBuffer;
      UINT     InformationBufferLength;
      UINT     BytesWritten;
      UINT     BytesNeeded;
    } QUERY_INFORMATION;
    struct _SET {
      NDIS_OID Oid;
      PVOID    InformationBuffer;
      UINT     InformationBufferLength;
      UINT     BytesRead;
      UINT     BytesNeeded;
    } SET_INFORMATION;
    struct _METHOD {
      NDIS_OID Oid;
      PVOID    InformationBuffer;
      ULONG    InputBufferLength;
      ULONG    OutputBufferLength;
      ULONG    MethodId;
      UINT     BytesWritten;
      UINT     BytesRead;
      UINT     BytesNeeded;
    } METHOD_INFORMATION;
  } 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_OID_REQUEST, *PNDIS_OID_REQUEST;

Members

Header

The NDIS_OBJECT_HEADER structure for the NDIS_OID_REQUEST structure. Set the Type member of the structure that Header specifies to NDIS_OBJECT_TYPE_OID_REQUEST, the Revision member to NDIS_OID_REQUEST_REVISION_1, and the 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:

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;


Oid

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

InformationBuffer

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

InformationBufferLength

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

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.

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.

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;


Oid

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

InformationBuffer

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

InformationBufferLength

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

BytesRead

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

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.

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;


Oid

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

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.

InputBufferLength

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

OutputBufferLength

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

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.

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.

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.

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.

NdisReserved

An area that is reserved for NDIS.

MiniportReserved

An area that is reserved for the miniport driver.

SourceReserved

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.

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

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)

See also

NDIS_OBJECT_HEADER
NDIS_REQUEST_TYPE
NDIS_STATUS_INDICATION
NdisOidRequest
OID_GEN_SUPPORTED_GUIDS

 

 

Send comments about this topic to Microsoft

表示:
© 2014 Microsoft