Edit

NdisRequest function (ndis.h)

  • Article

Note   NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.

NdisRequest forwards a request to the underlying driver that it query the capabilities or status of its NIC or that it set the state of its NIC.

Syntax

void NdisRequest(
  [out] PNDIS_STATUS  Status,
  [in]  NDIS_HANDLE   NdisBindingHandle,
  [in]  PNDIS_REQUEST NdisRequest
);

Parameters

[out] Status

Pointer to a caller-supplied variable that is set on return from this function. The underlying driver determines which NDIS_STATUS_XXX is returned, but it is usually one of the following values:

  • NDIS_STATUS_SUCCESS
    The requested operation completed successfully.

  • NDIS_STATUS_PENDING
    The request is being handled asynchronously, and the caller's ProtocolRequestComplete function will be called when it is completed.

  • NDIS_STATUS_INVALID_OID
    The OID_XXX code specified in the Oid member of the NDIS_REQUEST-structured buffer at NdisRequest 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_REQUEST-structured buffer at NdisRequest 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 NdisRequest.

  • NDIS_STATUS_INVALID_DATA
    The data supplied at InformationBuffer in the given NDIS_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 due to a resource shortage. Usually, this return 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 its NIC but it was failed by the netcard. For example, an attempt to set too many multicast addresses might cause the return of this value.

  • NDIS_STATUS_CLOSING or NDIS_STATUS_CLOSING_INDICATING
    The underlying driver failed the requested operation because a close is in progress.

  • NDIS_STATUS_RESET_IN_PROGRESS
    The underlying NIC driver cannot satisfy the request at this time because it is currently resetting the netcard. The caller's ProtocolStatus function was or will be called with 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.

[in] NdisBindingHandle

Specifies the handle returned by NdisOpenAdapter that identifies the target NIC or the virtual adapter of the next-lower driver to which the caller is bound.

[in] NdisRequest

Pointer to a buffered structure specifying the operation requested with a given OID_ XXX code for either a query or a set.

Return value

None

Remarks

A protocol driver must allocate sufficient memory for the information buffer associated with the OID_XXX of the operation it will request. The driver also must allocate and set up the buffer at NdisRequest before it calls NdisRequest. Both buffers must be allocated from nonpaged pool because the underlying driver runs at raised IRQL while processing the request.

For callers layered above an intermediate NDIS driver, NdisRequest forwards a request to the next-lower driver that it return information about its own capabilities or directs that driver to handle specific functionality in a caller-determined manner. If the next-lower driver is an NDIS intermediate driver, it can call NdisRequest with an OID-specific request of its own before completing the request originally submitted by the higher-level protocol.

Some errors returned at Status 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 NdisRequest appropriately to correct the OID_XXX code and/or the size or contents of the buffer at InformationBuffer and resubmit the request packet to NdisRequest. The same packet might be satisfied on resubmission to NdisRequest 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 Object Identifiers.

  • Target platform: Universal
  • Version: Not supported for NDIS 6.0 drivers in Windows Vista. Use NdisOidRequestinstead. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP.

Requirements

Requirement Value
Header ndis.h (include Ndis.h)
Library Ndis.lib
IRQL IRQL <= DISPATCH_LEVEL

See also