NDIS_OID_REQUEST (Compact 2013)

  • [アーティクル]

3/26/2014

To query or set OID information, NDIS submits this 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.
  • 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 Comments 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 Comments section.

  • DATA
    A union that defines the request data. The information in the data varies according to the type of request (QUERY_INFORMATION, SET_INFORMATION, or METHOD_INFORMATION). The following data members are specified.

    • 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 queries or from which the underlying driver reads caller-supplied information for set operations.
    • 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. If this is a method OID, 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. If this is a method OID, 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 perform 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.

    • InputBufferLength
      The number of bytes in the buffer at InformationBuffer that the driver can read.
    • 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.
  • 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 6.0 structure that is supported by an NDIS 6.0 or later versions miniport driver. A revisioned structure is any NDIS 6.0 structure that has an NDIS_OBJECT_HEADER structure inside it. When the miniport driver succeeds in setting an OID, it has to set SupportedRevision to the revision number of the structure it supports for the set operation.
  • Reserved1
    Reserved.
  • Reserved2
    Reserved.

Remarks

A protocol driver or a filter driver should allocate nonpaged memory for the buffer at InformationBuffer and for the NDIS_OID_REQUEST structure. By using data that is allocated from paged memory can cause fatal page faults because the underlying drivers run at IRQL = DISPATCH_LEVEL to perform 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 whether 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

Header

ndis.h

See Also

Reference

NDIS OID Request Structures
NDIS_OBJECT_HEADER
NDIS_REQUEST_TYPE
NDIS_STATUS_INDICATION
NdisOidRequest
OID_GEN_SUPPORTED_GUIDS