Indicating an Incoming Call (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 call manager or MCM driver is alerted to an incoming call by signaling messages from the network. From these signaling messages, the call manager or MCM driver extracts the call parameters for the call, including the SAP to which the incoming call is addressed.
The following figure shows a call manager indicating an incoming call.
.png)
The following figure shows an MCM driver indicating an incoming call.
.png)
If the incoming call parameters are unacceptable to the call manager or MCM driver, it can attempt to negotiate a change in these parameters with the remote party if such negotiation is allowed by the signaling protocol. Alternatively, the client to which the incoming call is directed could attempt to negotiate the call parameters after receiving the call indication from the call manager or MCM driver (see Client-Initiated Request to Change Call Parameters). If the call manager or MCM driver cannot negotiate acceptable call parameters for the call with the remote party, it might refuse the call. The signaling protocol determines what is possible in such cases.
Before indicating an incoming call to a client, the call manager or MCM driver must identify the SAP to which the call is directed. The SAP must have been previously registered by a client (see Registering a SAP) The call manager or MCM driver must also initiate the creation of a virtual connection (see Creating a VC) and initiate the activation of this VC (see Activating a VC).
The call manager or MCM driver then indicates the incoming call to the client that registered the SAP to which the incoming call is directed. A call manager indicates an incoming call with NdisCmDispatchIncomingCall. An MCM driver indicates an incoming call with NdisMCmDispatchIncomingCall.
In the call to NdisMCmDispatchIncomingCall, the call manager or MCM driver passes the following:
An NdisSapHandle that identifies the SAP to which the incoming call is addressed
An NdisVcHandle that identifies the virtual circuit for the incoming call
A pointer to a structure of type CO_CALL_PARAMETERS, which contains the call parameters for the call
The call to NdisMCmDispatchIncomingCall causes NDIS to call the client's ProtocolClIncomingCall function, within which the client either accepts or rejects the requested connection. ProtocolClIncomingCall should validate the SAP, VC, and call parameters.
ProtocolClIncomingCall can complete synchronously or it can return NDIS_STATUS_PENDING and complete asynchronously with NdisClIncomingCallComplete. A call to NdisClIncomingCallCompletecauses NDIS to call the call manager's or MCM driver's ProtocolCmIncomingCallCompletefunction.
The NDIS_STATUS code returned by a synchronous completion of ProtocolClIncomingCall or supplied to NdisClIncomingCallComplete indicates the client's acceptance or rejection of the incoming call. The client also returns the call parameters for the call in a buffered CO_CALL_PARAMETERS structure. If the client finds the call parameters unacceptable, it can, if allowed by the signaling protocol, request a change in the call parameters by setting the Flagsmember in the CO_CALL_PARAMETERS structure with CALL_PARAMETERS_CHANGED and by supplying the revised call parameters in a buffered CO_CALL_PARAMETERS structure.
If the client accepts the incoming call, the call manager or MCM driver should send signaling messages to indicate to the calling entity that the call has been accepted. Otherwise, the call manager or MCM driver should send signaling messages to indicate that the call has been rejected. If the client is requesting a change in call parameters, the call manager or MCM driver sends signaling messages to request a change in call parameters.
If the client accepted the call, or if the client's requested change in call parameters was accepted by the remote party, a call manager calls NdisCmDispatchCallConnected, and an MCM driver calls NdisMCmDispatchCallConnected. The call to NdisCmDispatchCallConnected causes NDIS to call the client's ProtocolClCallConnected function.
If the client rejected the call and the call manager or MCM driver has already activated a VC for the incoming call, the call manager or MCM driver calls Ndis(M)CmDeactivateVcto deactivate the VC if the VC is activated. The call manager or MCM driver can then initiate deletion of the VC by calling NdisCoDeleteVcin the case of the call manager or NdisMCmDeleteVcin the case of the MCM driver (see Deleting a VC).
If the client accepted the call but the end-to-end connection was not successfully established (because, for example, the remote party tore down the call), then the call manager or MCM driver will not call NdisCmDispatchCallConnected. Instead, it will call Ndis(M)CmDispatchIncomingCloseCall, which causes NDIS to call the client's ProtocolClIncomingCloseCallfunction. The client must then call NdisClCloseCallto complete the teardown of the call. The call manager or MCM driver then calls Ndis(M)CmDeactivateVcto deactivate the VC that it created for the incoming call (see Deactivating a VC). The call manager or MCM driver can then initiate deletion of the VC by calling NdisCoDeleteVcin the case of the call manager or NdisMCmDeleteVcin the case of the MCM driver (see Deleting a VC).