ProtocolClMakeCallComplete (NDIS 5.1) 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 ProtocolClMakeCallComplete function is used by connection-oriented NDIS clients that make outgoing calls. Such clients must have ProtocolClMakeCallComplete functions to complete the asynchronous operations that they initiate with NdisClMakeCall. Otherwise, such a protocol driver's registered ProtocolClMakeCallComplete function can simply return control.

Syntax

VOID ProtocolClMakeCallComplete(
  _In_     NDIS_STATUS         Status,
  _In_     NDIS_HANDLE         ProtocolVcContext,
  _In_opt_ NDIS_HANDLE         NdisPartyHandle,
  _In_     PCO_CALL_PARAMETERS CallParameters
);

Parameters

Status [in]
Specifies the final status of the client's original call to NdisClMakeCall, which can be one of the following:
- NDIS_STATUS_SUCCESS
  The client's attempt to set up a virtual connection succeded. Consequently, the client can proceed to make transfers on the active VC using the NdisVcHandle returned by NdisCoCreateVc, which the client has stored in its per-VC context area at ProtocolVcContext.
- NDIS_STATUS_RESOURCES
  NDIS, the call manager, or an underlying driver could not allocate sufficient resources to set up the connection.
- NDIS_STATUS_XXX
  The call manager or underlying miniport driver failed to establish an active connection and NDIS propagated this driver-determined failure status to the client.
ProtocolVcContext [in]
Specifies the handle to the client's per-VC context area, which the client originally supplied to NDIS when it called NdisCoCreateVc to set up the VC for its outgoing call.
NdisPartyHandle [in, optional]
If Status is NDIS_STATUS_SUCCESS and the client created a multipoint VC by passing an explicit ProtocolPartyContext handle to NdisClMakeCall, this is a valid NdisPartyHandle. Otherwise, this parameter is NULL.

ProtocolClMakeCallComplete must save any valid input NdisPartyHandle, usually in the client's per-party context area. The client must use this handle if (or when) it makes a subsequent call to NdisClDropParty or NdisClCloseCall that refers to this party.
CallParameters [in]
Pointer to a buffered CO_CALL_PARAMETERS structure. The client allocated this buffer and initialized this structure with client-determined data before passing this pointer to NdisClMakeCall. While processing the client's request, the call manager can modify this data to reflect the results of its negotiation with the network or with a signaling peer.

Return value

None

Remarks

A call to ProtocolClMakeCallComplete indicates that the call manager has completed processing the client's request to establish a virtual connection with NdisClMakeCall.

If the client's attempt to establish an outgoing call is unsuccessful (input Status is anything except NDIS_STATUS_SUCCESS), ProtocolClMakeCallComplete should do the following:

Release or prepare for reuse the ProtocolPartyContext area, if any, and the buffer at CallParameters that the client allocated.
Tear down the client-created VC with a call to NdisCoDeleteVc and release or prepare for reuse the client-allocated ProtocolVcContext area.

Otherwise, ProtocolClMakeCallComplete should do the following:

Check the Flags member of the structure at CallParameters to see whether CALL_PARAMETERS_CHANGED is set, which indicates that the call manager modified the client-supplied call parameters.
If so, examine the data at CallParameters to determine whether they are acceptable for this connection.

For example, the client might retain the buffered call parameters for the active VC, save the NdisPartyHandle if this is a multipoint VC, and generally make the client ready for subsequent transfers and other operations on the active VC if it finds the given call parameters satisfactory.
If not, the signaling protocol determines whether the client can attempt to renegotiate for acceptable call parameters with the call manager.

For example, a particular call manager might allow its clients to call NdisClModifyCallQoS one or more times in these circumstances.
If the CM-modified call parameters are unacceptable and further renegotiation is impossible, ProtocolClMakeCallComplete must tear down the call with NdisClCloseCall.

In this case, ProtocolClMakeCallComplete should not attempt to release any client-allocated resources on return from NdisClCloseCall but can simply return control. Instead, the client should release the resources it allocated (or prepare them for reuse) within its ProtocolClCloseCallComplete function.

Requirements

Target platform	Desktop
Version	See ProtocolClMakeCallComplete.
Header	Ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL

Share via