NdisCmActivateVc function (ndis.h)

Article
04/18/2022

NdisCmActivateVc passes CM-supplied call parameters, including media parameters, for a particular VC down to the underlying miniport driver.

Syntax

NDIS_STATUS NdisCmActivateVc(
  [in]      NDIS_HANDLE         NdisVcHandle,
  [in, out] PCO_CALL_PARAMETERS CallParameters
);

Parameters

[in] NdisVcHandle

Specifies the handle identifying the VC on which to set call parameters. The call manager either obtained this handle from NdisCoCreateVc for an incoming call or as an input parameter to its ProtocolCoCreateVc function for a client-initiated outgoing call.

[in, out] CallParameters

Pointer to a CM-allocated resident buffer, formatted as a structure of type CO_CALL_PARAMETERS, containing all the media-specific parameters that the underlying miniport driver uses for VC activation.

Return value

When NdisCmActivateVc returns anything other than NDIS_STATUS_PENDING, the call manager should make an internal call to its ProtocolCmActivateVcComplete function. Otherwise, NDIS calls the CM's ProtocolCmActivateVcComplete function when this operation is completed.

Remarks

NdisCmActivateVc notifies the underlying miniport driver to set up call and media parameters on a newly created VC or to change those of an established VC. NDIS forwards the given call parameters and VC handle to the underlying miniport driver's MiniportCoActivateVc function, which sets up all necessary resources to track the state of the VC and makes itself and a NIC ready for data transfers on the VC.

A stand-alone CM always calls NdisCmActivateVc after establishing a connection on a VC but before any data is sent or received on that VC. For the duration of the connection, a CM can call NdisCmActivateVc many times with the same NdisVcHandle as conditions on the network change and/or whenever the client calls NdisClModifyCallQoS. At each such call to NdisCmActivateVc, the underlying miniport driver's MiniportCoActivateVc function must do either of the following:

Update the state that the miniport driver maintains about call parameters to the new values supplied by the call manager if the miniport driver can continue to make transfers on the VC according to the newly modified call parameters.
Fail the call if the miniport driver cannot continue to make transfers under the constraints of the given call parameters.

When the underlying miniport driver fails a request to set or reset call parameters, the call manager might modify its original specification at CallParameters and call NdisCmActivateVc again. The limit on the number of times any call manager makes repeated attempts to activate a VC is implementation-dependent.

For a client-initiated outgoing call, a stand-alone CM usually calls NdisCmActivateVc immediately following the packet exchange confirming a negotiated agreement with the remote target of the call or successful call-setup at the switch, before it notifies NDIS (and the client) of outgoing call completion with NdisCmMakeCallComplete. For an incoming call, a call manager usually calls NdisCmActivateVc after it has called NdisCoCreateVc successfully and before it calls NdisCmDispatchIncomingCall.

In the process of setting up an outgoing call and while any VC remains activated, the client can request changes to the call parameters for that VC, for example, by calling NdisClModifyCallQos. After verifying the validity of the given call parameters for any such a request, the stand-alone call manager must call NdisCmActivateVc to pass the modified call parameters down to the underlying miniport driver.

Only stand-alone call managers, which register themselves with NDIS as protocol drivers, can call NdisCmActivateVc. Connection-oriented miniport drivers that provide integrated call-management support call NdisMCmActivateVc instead.

Requirements

Requirement	Value
Minimum supported client	Supported for NDIS 6.0 and NDIS 5.1 drivers (see NdisCmActivateVc (NDIS 5.1)) in Windows Vista. Supported for NDIS 5.1 drivers (see NdisCmActivateVc (NDIS 5.1)) in Windows XP.
Target Platform	Desktop
Header	ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	<= DISPATCH_LEVEL
DDI compliance rules	Irql_CallManager_Function(ndis)