Client-Initiated Request to Change Call Parameters (NDIS 5.1)
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.
A client requests a change in quality of service (QoS) on an active virtual connection (VC) with NdisClModifyCallQoS.
The following figure shows the client of a call manager requesting a change in quality of service.
.png)
The following figure shows the client of an MCM driver requesting a change in quality of service.
.png)
In the call to NdisClModifyCallQoS, the client supplies the following:
An NdisVcHandle that identifies the VC
A pointer to a CO_CALL_PARAMETERS structure that contains the call parameters the client is requesting
The circumstances under which a client can request a change in QoS are determined by the signaling protocol.
The call to NdisClModifyCallQoScauses NDIS to call the call manager's or MCM driver's ProtocolCmModifyCallQoS function, which inputs the NdisVcHandle and buffered CO_CALL_PARAMETERS structure passed by the client to NdisClModifyCallQoS. ProtocolCmModifyCallQoS communicates with network control devices or other media-specific agents, as necessitated by its media, to modify the media-specific call parameters for an established virtual connection.
After communicating with the network and determining that the changes were successful, a call manager must call NdisCmActivateVc (and an MCM driver must call NdisMCmActivateVC) to activate the specified VC with the new call parameters.
If the network does not accept the new call parameters or if the underlying miniport driver cannot accept the parameters, the call manager or MCM driver must restore the VC to the state that existed before any modifications were attempted, and return NDIS_STATUS_FAILURE.
To indicate the status of the client's request to change QoS, a call manager calls NdisCmModifyCallQoSComplete, and an MCM driver calls NdisMCmModifyCallQoSComplete. In this call, the call manager or MCM driver passes the following:
An NDIS_STATUS that indicates the status of the request
An NdisVcHandle that identifies the VC
A pointer to a CO_CALL_PARAMETERS structure that contains the call parameters for the VC
If allowed by the signaling protocol, the call manager or MCM driver can pass modified call parameters back to the client. These modifications can be the product of negotiation with the network or they can be supplied by the call manager or MCM driver itself. A call manager or MCM driver should indicate that the call parameters have been modified by setting the CALL_PARAMETERS_CHANGE flag in the CO_CALL_PARAMETERS structure.
The call to NdisCmModifyCallQoSComplete causes NDIS to call the client's ProtocolClModifyCallQoSComplete function. NDIS passes the following to ProtocolClModifyCallQoSComplete:
An NDIS_STATUS that indicates the status of the client's request to change the QoS
A ProtocolVcContext handle that identifies the VC
A pointer to a CO_CALL_PARAMETERS structure that contains the call parameters passed by the call manager or MCM driver to NdisCmModifyCallQoSComplete
If the CALL_PARAMETERS_CHANGED flag is set in the CO_CALL_PARAMETERS structure, the client must examine the returned call parameters and determine whether the modifications are acceptable. If the client's call to NdisClModifyCallQoSsucceeds, ProtocolClModifyCallQoSComplete can accept the QoS change by simply returning control. Otherwise, ProtocolClModifyCallQoSComplete can engage in further negotiation with the call manager if allowed by the signaling protocol and as long as the client's developer places some reasonable limit on the number of possible renegotiations. Alternatively, ProtocolClModifyCallQoSComplete can simply tear down the call with NdisClCloseCall (see Client-Initiated Request to Close a Call) whenever the call manager rejects a request to change the QoS and the previously established QoS has become unacceptable to the client.