NdisRequest
VOID
NdisRequest(
OUT PNDIS_STATUS Status,
IN NDIS_HANDLE NdisBindingHandle,
IN PNDIS_REQUEST NdisRequest
);
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.
Parameters
-
Status
-
Points 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.
-
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.
-
NdisRequest
-
Points to a buffered structure specifying the operation requested with a given
OID_XXX code for either a query or a set.
Comments
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 Chapter
5.
Callers of NdisRequest can be running at IRQL <= DISPATCH_LEVEL.
See Also
MiniportQueryInformation, MiniportSetInformation,
NdisOpenAdapter, NDIS_REQUEST,
ProtocolRequestComplete, ProtocolStatus