Share via

NdisOidRequest (Compact 7)

  • Article

3/12/2014

This function forwards a request to the underlying drivers to query the capabilities or status of an adapter or set the state of an adapter.

Syntax

NDIS_STATUS
  NdisOidRequest(
    IN NDIS_HANDLE  NdisBindingHandle,
    IN PNDIS_OID_REQUEST  OidRequest
    );

Parameters

  • NdisBindingHandle
    The handle returned by the NdisOpenAdapterEx function that identifies the target adapter on the binding.
  • OidRequest
    A pointer to a NDIS_OID_REQUEST structure that specifies the operation requested with a given OID_XXX code to either query the status of an adapter or to set the state of an adapter.

Return Value

The underlying driver determines which NDIS_STATUS*_XXX* code NdisOidRequest returns, but it is usually one of the following values:

Value Description

NDIS_STATUS_SUCCESS

The request operation completed successfully.

NDIS_STATUS_PENDING

The request is being handled asynchronously, and NDIS will call the caller's ProtocolOidRequestComplete function when the request is completed.

NDIS_STATUS_INVALID_OID

The OID_XXX code specified in the Oid member of the NDIS_OID_REQUEST-structured buffer at OidRequest is invalid or unsupported by the underlying driver.

NDIS_STATUS_INVALID_LENGTH or NDIS_STATUS_BUFFER_TOO_SHORT

The value specified in the InformationBufferLength member of the NDIS_OID_REQUEST-structured buffer at OidRequest does not match the requirements for the given OID_XXX code. If the information buffer is too small, the BytesNeeded member contains the correct value for InformationBufferLength on return from NdisOidRequest.

NDIS_STATUS_INVALID_DATA

The data supplied at InformationBuffer in the given NDIS_OID_REQUEST structure is invalid for the given OID_XXX code.

NDIS_STATUS_NOT_SUPPORTED or NDIS_STATUS_NOT_RECOGNIZED

The underlying driver does not support the requested operation.

NDIS_STATUS_RESOURCES

The request could not be satisfied because of a resource shortage. Usually, this return value indicates that an attempt to allocate memory was unsuccessful, but it does not necessarily indicate that the same request, submitted later, will be failed for the same reason.

NDIS_STATUS_NOT_ACCEPTED

The underlying driver attempted the requested operation, usually a set on a network adapter, but it failed. For example, an attempt to set too many multicast addresses could cause the return of this value.

NDIS_STATUS_CLOSING or NDIS_STATUS_CLOSING_INDICATING

The underlying driver failed the requested operation because a close operation is in progress.

NDIS_STATUS_RESET_IN_PROGRESS

The underlying miniport driver cannot satisfy the request currently because it is currently resetting the affected network adapter. The caller's ProtocolStatusEx function was or will be called by using NDIS_STATUS_RESET_START to indicate that a reset is in progress. This return value does not necessarily indicate that the same request, submitted later, will be failed for the same reason.

NDIS_STATUS_FAILURE

This value usually is a nonspecific default, returned when none of the more specific NDIS_STATUS_XXX caused the underlying driver to fail the request.

Remarks

A protocol driver must allocate sufficient memory to hold the information buffer that is associated with the specified OID. The driver must also allocate and set up the buffer at OidRequest before it calls NdisOidRequest. Both buffers must be allocated from nonpaged pool because the underlying driver runs at raised IRQL while processing the request.

NdisOidRequest forwards a request to underlying drivers or handles the request itself.. If the next-lower driver is an NDIS intermediate driver, it can call NdisOidRequest with an OID-specific request of its own before completing the request originally submitted by the higher-level driver.

Some errors returned are recoverable, including the following:

NDIS_STATUS_INVALID_OID

NDIS_STATUS_INVALID_LENGTH

NDIS_STATUS_BUFFER_TOO_SHORT

NDIS_STATUS_INVALID_DATA

NDIS_STATUS_RESOURCES

NDIS_STATUS_RESET_IN_PROGRESS

That is, a driver can modify the packet at OidRequest appropriately to correct the OID_XXX code or the size or contents of the buffer at InformationBuffer and resubmit the request packet to NdisOidRequest. The same packet might be satisfied on resubmission to NdisOidRequest if the original call indicated a reset in progress or that a resource shortage, which might be temporary, prevented that request from being carried out.

The NDIS library maintains bindings for underlying miniport drivers. NDIS can return information for binding-specific queries if a given OID is associated with a system-defined medium type for which the system provides a filter library.

For more information about the general and media-specific OIDs and their respective associated information buffers, see NDIS OIDs.

Requirements

Header

ndis.h

See Also

Reference

NDIS OID Request Interface for Protocol Drivers
NDIS_OID_REQUEST
NdisOpenAdapterEx
ProtocolOidRequestComplete
ProtocolStatusEx
NDIS OID Request Interface