CO_REQUEST_HANDLER callback function
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.
The ProtocolCoRequest function is required. This function handles OID_CO_XXX requests initiated by calls to NdisCoRequest from the corresponding client(s) or stand-alone call manager or initiated by an MCM driver's calls to NdisMCmRequest.
Syntax
CO_REQUEST_HANDLER ProtocolCoRequest;
NDIS_STATUS ProtocolCoRequest(
_In_ NDIS_HANDLE ProtocolAfContext,
_In_opt_ NDIS_HANDLE ProtocolVcContext,
_In_opt_ NDIS_HANDLE ProtocolPartyContext,
_Inout_ PNDIS_REQUEST NdisRequest
)
{ ... }
Parameters
ProtocolAfContext [in]
Specifies the handle to the driver's per-AF context area. The client supplied this handle when it called NdisClOpenAddressFamily to connect itself to the call manager. The call manager supplied this handle from its ProtocolCmOpenAf function, so this handle effectively identifies the particular client that issued this request.ProtocolVcContext [in, optional]
Specifies the handle identifying the active VC for which the client or call manager is requesting or setting information if the request is VC-specific. Otherwise, this parameter is NULL.ProtocolPartyContext [in, optional]
Specifies the handle identifying the party on a multipoint VC for which the client or call manager is requesting or setting information if the request is party-specific. Otherwise, this parameter is NULL.NdisRequest [in, out]
Pointer to a buffer, formatted as an NDIS_REQUEST structure specifying the operation to be carried out by ProtocolCoRequest. The Oid member of the NDIS_REQUEST structure contains the system-defined OID_GEN_CO_XXX code specifying the requested query or set operation, together with a buffer in which the protocol returns the requested information for a query or from which it transfers the given information for a set.
Return value
ProtocolCoRequest can return one of the following:
| Return code | Description |
|---|---|
| NDIS_STATUS_SUCCESS | The client or call manager carried out the requested operation. |
| NDIS_STATUS_PENDING | The client or call manager is handling this request asynchronously, and it will call NdisCoRequestComplete(or, from a miniport driver with integrated call-management support, NdisMCmRequestComplete) when the requested operation is done. |
| NDIS_STATUS_INVALID_LENGTH or NDIS_STATUS_BUFFER_TOO_SHORT | The driver is failing this request because the caller of NdisCoRequest or NdisMCmRequest did not supply an adequate InformationBuffer for the given request. The driver set the BytesNeeded member in the buffer at NdisRequest to the Oid-specific value of the InformationBufferLength required to carry out the requested operation. |
| NDIS_STATUS_XXX | The client or call manager failed the request for some driver-determined reason, such as invalid input data specified for a set. |
| NDIS_STATUS_NOT_SUPPORTED | The client or call manager failed this request because it did not recognize the OID_GEN_CO_XXX code in the Oid member in the buffer at NdisRequest. |
Remarks
Connection-oriented clients and stand-alone call managers communicate information to each other by specifying an explicit NdisAfHandle when they call NdisCoRequest. Similarly, a connection-oriented miniport driver with integrated call-management support calls NdisMCmRequest with explicit NdisAfHandle s to communicate information to its individual clients. Such a call to NdisCoRequest or NdisMCmRequest with an explicit NdisAfHandle causes NDIS to call the ProtocolCoRequest function of the client, stand-alone call manager, or MCM driver that shares the given NdisAfHandle.
If the input NdisVcHandle and NdisPartyHandle are NULL, ProtocolCoRequest can consider the request global in nature. For example, ProtocolCoRequest satisfies any OID_GEN_CO_XXX query for which it is passed only an explicit NdisAfHandle by returning information about all currently active VCs, including any active multipoint VCs, on the given address family.
An explicit NdisVcHandle or NdisPartyHandle indicates that ProtocolCoRequest should satisfy the given request on a per-VC or per-party basis, respectively.
ProtocolCoRequest can assume that the buffer at NdisRequest was allocated from nonpaged pool and is, therefore, accessible at raised IRQL. The caller of NdisCoRequest(or NdisMCmRequest) is responsible for releasing this buffer and the internal buffer at InformationBuffer that it allocated when its request has been completed.
If ProtocolCoRequest returns NDIS_STATUS_PENDING, the driver must make a subsequent call to NdisCoRequestComplete or, for an MCM driver, to NdisMCmRequestComplete when the driver completes its operations to satisfy the given request.
For more information about the sets of OIDs defined for use with NdisCoRequest, NdisMCmRequest, and NdisRequest, see NDIS Object Identifiers.
Requirements
Target platform |
Desktop |
Version |
Not supported for NDIS 6.0 drivers in Windows Vista. Use ProtocolCoOidRequestinstead. Supported for NDIS 5.1 drivers in Windows Vista and Microsoft Windows XP |
Header |
Ndis.h (include Ndis.h) |
IRQL |
<= DISPATCH_LEVEL |
See also