NdisCoOidRequest function (ndis.h)
The NdisCoOidRequest function forwards a request to targeted CoNDIS drivers to query or set OID-specified information of the target driver.
Syntax
NDIS_STATUS NdisCoOidRequest(
[in] NDIS_HANDLE NdisBindingHandle,
[in, optional] NDIS_HANDLE NdisAfHandle,
[in, optional] NDIS_HANDLE NdisVcHandle,
[in, optional] NDIS_HANDLE NdisPartyHandle,
[in, out] PNDIS_OID_REQUEST OidRequest
);
Parameters
[in] NdisBindingHandle
A handle that the NdisOpenAdapterEx function returned that identifies the target adapter for the binding.
[in, optional] NdisAfHandle
A handle that identifies the address family (AF) that is shared among the client, call manager, and NDIS. This handle was obtained as follows:
- If the caller is a client that is making a request to the call manager, the client originally obtained this handle from a successful call to the NdisClOpenAddressFamilyEx function.
- If the caller is a stand-alone call manager or miniport call manager (MCM) that is making a request to a client, the call manager or MCM originally obtained this handle as an input parameter to its ProtocolCmOpenAf function.
[in, optional] NdisVcHandle
A handle that identifies the virtual connection (VC) the caller is requesting or setting information for, if the request is VC-specific. Otherwise, if this parameter is NULL, the request is not VC-specific. For any VC-specific request, the caller originally obtained this handle either when it created the VC with the NdisCoCreateVc function, or as an input parameter to its ProtocolCoCreateVc function. For a VC-specific request that is directed to the underlying miniport driver, this handle identifies the VC, while NdisAfHandle and NdisPartyHandle are NULL.
[in, optional] NdisPartyHandle
A handle that identifies the party on a multipoint VC the caller is requesting or setting information for, if the request is party-specific. Otherwise, if this parameter is NULL, the request is not party-specific. For any party-specific request, a client originally obtained this handle from a successful call to the NdisClAddParty function or the NdisClMakeCall function or the call manager obtained this handle as an input parameter to its ProtocolCmAddParty function. If NdisAfHandle is NULL, NdisPartyHandle also is NULL.
[in, out] OidRequest
A pointer to an NDIS_OID_REQUEST structure that specifies the operation that is requested with a given OID_XXX code to query or to set information.
Return value
The target driver determines which NDIS_STATUS_XXX code NdisCoOidRequest returns, usually one of the following values:
| Return code | Description |
|---|---|
|
The request operation completed successfully. |
|
The request is being handled asynchronously, and NDIS will call the caller's ProtocolCoOidRequestComplete function when the request is completed. |
|
The OID_XXX code that was specified in the Oid member of the NDIS_OID_REQUEST structure at the OidRequest parameter is invalid or unsupported by the underlying driver. |
|
The value that was 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 of NDIS_OID_REQUEST contains the correct value for InformationBufferLength, when NdisCoOidRequest returns. |
|
The data supplied at InformationBuffer in the given NDIS_OID_REQUEST structure is invalid for the given OID_XXX code. |
|
The underlying driver does not support the requested operation. |
|
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, if submitted later, will fail for the same reason. |
|
The underlying driver attempted the requested operation, usually a set request, but the operation failed. For example, an attempt to set too many multicast addresses might cause NdisCoOidRequest to return this value. |
|
The underlying driver failed the requested operation because a close operation is in progress. |
|
The underlying miniport driver cannot satisfy the request at this time because it is currently resetting the affected NIC. The caller's ProtocolStatusEx 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, if submitted later, will fail for the same reason. |
|
This value usually is a nonspecific default value that is returned when none of the more specific NDIS_STATUS_XXX caused the underlying driver to fail the request. |
|
The miniport driver stopped processing the request. For example, NDIS called an underlying miniport driver's MiniportResetEx or MiniportCancelOidRequest function. |
Remarks
CoNDIS clients and stand-alone call managers can call the NdisCoOidRequest function to send an OID request to query or set OID-specified information in a target driver. The target driver can be another CoNDIS protocol driver or an underlying driver.
The caller of NdisCoOidRequest must allocate sufficient memory to hold the information buffer that is associated with the specified OID. The caller must also allocate and set up the buffer at OidRequest before it calls NdisCoOidRequest. Both buffers must be allocated from nonpaged pool because the target driver can run at raised IRQL while it processes the request.
Some errors that NdisCoOidRequest returns 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
Depending on the value of the NdisAfHandle parameter, clients and stand-alone call managers call NdisCoOidRequest to communicate with each other or with the underlying connection-oriented miniport driver.
If a driver passes NULL for NdisVcHandle, the request is global in nature, whether the request is directed to the client, call manager, or miniport driver. For example, if the caller supplies a non-NULL value for NdisVcHandle, an OID_GEN_CO_RCV_CRC_ERROR OID request to an underlying connection-oriented miniport driver returns the number of cyclic redundancy check (CRC) errors that were encountered for a particular VC. For the same request with NULL for NdisVcHandle, the underlying miniport driver returns the total number of CRC errors that were encountered for all of the VCs.
Clients and stand-alone call managers should call the NdisOidRequest function for all of the OIDs that are not connection-oriented, such as those that are returned in an OID_GEN_SUPPORTED_LIST query, which is commonly issued during initialization after the protocol driver has bound itself to the underlying NIC driver.
If NdisCoOidRequest returns NDIS_STATUS_PENDING, the request is being handled asynchronously and NDIS will call the driver's ProtocolCoOidRequestComplete function when the request is completed. If NdisCoOidRequest returns any other status, the request is complete when NdisCoOidRequest returns, and NDIS does not call ProtocolCoOidRequestComplete.
For more information about the sets of OIDs that are defined to use with NdisCoOidRequest and NdisOidRequest, see NDIS OIDs.
Only clients and stand-alone call managers, which are protocol drivers, can call NdisCoOidRequest. MCMs call the NdisMCmOidRequest function to communicate with their clients.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Supported in NDIS 6.0 and later. |
| Target Platform | Desktop |
| Header | ndis.h (include Ndis.h) |
| Library | Ndis.lib |
| IRQL | <= DISPATCH_LEVEL |
| DDI compliance rules | Irql_Connection_Function(ndis) |