CO_REQUEST_COMPLETE_HANDLER callback function

Article
06/19/2017

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 ProtocolCoRequestComplete function is required. This function postprocesses the results of a connection-oriented client's or stand-alone call manager's call to NdisCoRequest or of an MCM driver's call to NdisMCmRequest.

Syntax

CO_REQUEST_COMPLETE_HANDLER ProtocolCoRequestComplete;

VOID ProtocolCoRequestComplete(
  _In_     NDIS_STATUS   Status,
  _In_opt_ NDIS_HANDLE   ProtocolAfContext,
  _In_opt_ NDIS_HANDLE   ProtocolVcContext,
  _In_opt_ NDIS_HANDLE   ProtocolPartyContext,
  _Inout_  PNDIS_REQUEST NdisRequest
)
{ ... }

Parameters

Status [in]
Specifies the final status of the driver-initiated request, either NDIS_STATUS_SUCCESS or a failure NDIS_STATUS_XXX that was set by the corresponding client or call manager that handled this request. This parameter is never NDIS_STATUS_PENDING.
ProtocolAfContext [in, optional]
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 to which this request was directed.
ProtocolVcContext [in, optional]
Specifies the handle identifying the active VC for which the client or call manager was requesting or setting information if the request was 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 was requesting or setting information if the request is party-specific. Otherwise, this parameter is NULL.
NdisRequest [in, out]
Pointer to the driver-allocated buffer, formatted as an NDIS_REQUEST structure that the driver passed in a preceding call to NdisCoRequest or NdisMCmRequest. 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 corresponding client or call manager returned the requested information for a query or from which it transferred the given information for a set if Status is NDIS_STATUS_SUCCESS.

Return value

None

Remarks

ProtocolCoRequestComplete can use the input Status as follows:

If this argument is NDIS_STATUS_SUCCESS, the BytesRead or BytesWritten member of the NDIS_REQUEST structure has been set to specify how much data was transferred into or from the buffer at InformationBuffer.

If the given OID_GEN_CO_XXX was a query, ProtocolCoRequestComplete can use the data returned at InformationBuffer in any driver-determined way, depending on the value of the Oid member.

ProtocolCoRequestComplete is responsible for releasing the driver-allocated buffers at NdisRequest and InformationBuffer when the driver completes its postprocessing of this request.
If this argument is NDIS_STATUS_INVALID_LENGTH or NDIS_STATUS_BUFFER_TOO_SHORT, the BytesNeeded member specifies the Oid-specific value of the InformationBufferLength required to carry out the requested operation.

In these circumstances, ProtocolCoRequestComplete can allocate sufficient buffer space for the request, set up another NDIS_REQUEST structure with the required InformationBufferLength and the same Oid value, and retry the driver's call to NdisCoRequest or NdisMCmRequest.
If this argument is an NDIS_STATUS_XXX that indicates an unrecoverable error, ProtocolCoRequestComplete should release the buffer at NdisRequest and carry out any driver-determined operations that are necessary. For example, ProtocolCoRequestComplete might tear down the driver-created VC if a returned error status indicates that the driver cannot continue to make transfers on the virtual connection.

Even if a driver's call to NdisCoRequest or NdisMCmRequest returns something other than NDIS_STATUS_PENDING, that driver should use its ProtocolCoRequestComplete function to postprocess completed requests. Making an internal call to the driver's own ProtocolCoRequestComplete function on return from NdisCoRequest or NdisMCmRequest has almost no adverse effect on the driver's performance, makes the driver's image smaller, and makes the driver easier to maintain from one operating system release to the next since such a driver has no duplicate code doing status-return checking on driver-initiated requests.

Requirements

Target platform	Desktop
Version	Not supported for NDIS 6.0 drivers in Windows Vista. Use ProtocolCoOidRequestCompleteinstead. Supported for NDIS 5.1 drivers in Windows Vista and Microsoft Windows XP
Header	Ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL

Share via