(Page 1 of 1 in this chapter) Version

Chapter 4

DPNSS Call Control

4.1 Introduction
4.2 Call Control Operations Supported By DPNSS Service
4.3 Call Control API Summary
4.3.1 Call Control Functions and Solicited Events
4.3.2 Unsolicited Events
4.4 Establishing Inbound Calls
4.4.1 Retrieving Call Information
4.4.2 Answering the Call
4.4.3 Rejecting the Call
4.4.4 Accepting the Call without Answering
4.5 Establishing Outbound Calls
4.5.1 Initiating an Outbound Call
4.6 Releasing a Call
4.6.1 Network-Initiated Call Release
4.6.2 Application-Initiated Call Release
4.7 Blocking and Unblocking Calls
4.7.1 Blocking Calls
4.7.2 Unblocking Calls

4.1 Introduction

This chapter:

4.2 Call Control Operations Supported By DPNSS Service

The DPNSS service supports the following call control operations:
Operation

Supported?

For more information, see...

Receiving inbound calls

Yes

Section 4.4 of this manual.

Placing outbound calls

Yes

Section 4.5 of this manual.

Releasing calls

Yes

Section 4.6 of this manual.

Call blocking

Yes

Section 4.7 of this manual.

Call transfer

Yes (through DPNSS supplementary services)

 Chapter 6 of this manual.

4.3 Call Control API Summary

The following section summarizes the DPNSS functions needed to perform call control. For most of these function calls, one or more events are expected in response to the command. These events are also described in this section.

Note: For detailed documentation of the functions, see Chapter 5.

There are two types of CT Access events associated with call control operations:

4.3.1 Call Control Functions and Solicited Events

The following table lists call control-related functions and associated events. For detailed documentation of the functions, parameters, and events, refer to Chapter 5.
Function

Description/Associated Events

dpnAcceptCall

Directs the DPNSS server to accept an incoming call without answering it. The application can then perform other operations before answering or rejecting the call.

Associated Events:

· DPNEVN_ACCEPTING_CALL: The DPNSS server is accepting the call. The line is ringing.

· DPNEVN_CALL_DISCONNECTED: A DISCONNECT message was received from the network, indicating that the remote party has hung up. The event value field contains the reason.

dpnAnswerCall

Directs the DPNSS server to answer a call.

Associated Events:

· DPNEVN_ANSWERING_CALL: The DPNSS server is answering.

· DPNEVN_CALL_CONNECTED: An incoming CONNECT message was acknowledged by the network, and the connection is established.

· DPNEVN_CALL_DISCONNECTED: A DISCONNECT message was received from the network, indicating that the remote party has hung up. The event value field contains the reason.

dpnBlockCalls

Requests the DPNSS server to block all incoming calls. The line remains in the blocked state until dpnUnBlockCalls is called.

Associated Events:

· DPNEVN_CALLS_BLOCKED: The "block calls" request has been granted.

· DPNEVN_CALL_DISCONNECTED: A DISCONNECT message was received from the network, indicating that the remote party has hung up. The event value field contains the reason.

dpnGetCallStatus

Retrieves calling/called number, call state, and other call status information.

dpnPlaceCall

Directs the DPNSS server to place a call to a specified number, using call placement parameters from the DPN_PLACECALL_PARMS structure.

Associated Events:

· DPNEVN_PLACING_CALL: This informational event is generated after the DPNSS server has placed the outgoing call.

· DPNEVN_REMOTE_ALERTING: This event means that the remote party accepted the call and is alerting.

· DPNEVN_CALL_CONNECTED: This event indicates that a CONNECT message has been received by the network.

· DPNEVN_CALL_DISCONNECTED: A DISCONNECT message was received from the network, indicating that the remote party has hung up. The event value field contains the reason.

· DPNEVN_INCOMING_CALL: A call is arriving on the channel. Call placement is aborted.

dpnRejectCall

Directs the DPNSS server to reject an incoming call.

Associated Events:

· DPNEVN_REJECTING_CALL: The reject sequence has started.

· DPNEVN_CALL_DISCONNECTED: A DISCONNECT message was received from the network, indicating that the remote party has hung up. The event value field contains the reason.

dpnReleaseCall

Directs the DPNSS server to perform one of the following actions: Initiate connection teardown, abandon call placement, or acknowledge a network disconnect event.

Associated Events:

· DPNEVN_CALL_RELEASED: The call has been released. A DISCONNECT message was sent to the network, and was acknowledged.

· DPNEVN_CALL_DISCONNECTED: A DISCONNECT message was received from the network, indicating that the remote party hung up while the release was taking place. The event value field contains the reason.

dpnSetExtendedArgs

Sets new arguments or DPNSS supplementary service messages for the call control function that immediately follows it.

Associated events:

none

dpnStartProtocol

Starts the DPNSS protocol.

Associated Events:

· DPNEVN_STARTPROTOCOL_DONE: The function has finished. The event value field indicates if the protocol started successfully. CTA_REASON_FINISHED means a successful completion. Any other value implies an error.

dpnStopProtocol

Stops the DPNSS protocol.

Associated Events:

· DPNEVN_STOPPROTOCOL_DONE: Indicates that the DPNSS protocol has been halted. The value field is set to CTA_REASON_FINISHED.

dpnUnBlockCalls

Requests the DPNSS server to stop blocking calls.

Associated Events:

· DPNEVN_CALLS_UNBLOCKED: The request to unblock the line is granted.

dpnSendFeatureMessage

 Requests the DPNSS service to send a DPNSS end-to-end message containing the supplementary service codes and parameters previously set by using dpnSetExtendedArgs.

Associated Events:

none

4.3.2 Unsolicited Events

The following is a list of call control-related unsolicited events:

4.4 Establishing Inbound Calls

This section describes how a typical DPNSS call control application receives and processes calls, once it has been initialized as described in Chapter 3.

The following is a summary of the steps to establishing an inbound call:

  1. The network offers the call. 

    

  2. The application takes one of the following actions: 
    

    
 

    


    
 Action 
    

    		
 What Happens 
    


    
 It accepts and answers the call, by invoking dpnAnswerCall. 
    

    		
 The DPNSS server connects the call. 
    


    
 It rejects the call, by invoking dpnRejectCall. 
    

    		
 The call is cleared. 
    


    
 It accepts the call without answering, by invoking dpnAcceptCall. 
    

    		
 The DPNSS server accepts the call. The application can then exchange DPNSS supplementary service messages and invoke dpnAnswerCall or dpnRejectCall as needed. 
    



    


    

    

    





Figure 6 is a state diagram for inbound calls. The sequence diagrams on the following pages can be correlated with this diagram to gain a comprehensive understanding of inbound call states and events. 





Figure 6.	 Inbound Call State Diagram






4.4.1	 Retrieving Call Information





When the network first offers a call (i.e., sends a DPNSS Initial Service Request message), the DPNSS server handles the request of an incoming call, and collects incoming digits and other information. When all initial phases of the Initial Service Request are complete, and the digits and other setup information are available, a DPNEVN_INCOMING_CALL event is generated. 



The application can call dpnGetCallStatus to retrieve the calling number and other information, including the stream and timeslot of the channel (which infers whether it is real or virtual). The call status information is stored in the DPN_CALL_STATUS data structure, shown here: 


#define DPN_MAX_DIGITS 31
typedef struct
{                                  /* Used by dpnGetCallStatus           */
    DWORD    size;                 /* Size returned by dpnGetCallStatus  */
    DWORD    state;                /* Call states (DPN_CC_STATE_xxx)     */
    INT32    reason;               /* Reason for going back to IDLE state*/
                                   /* DPN_DIS_xxx                        */
    char     calledaddr [DPN_MAX_DIGITS+1]; /* called number             */
                                   /* (null-terminated string)           */
    char     callingaddr[DPN_MAX_DIGITS+1]; /* calling number            */
                                   /* (null-terminated string)           */
    DWORD    pendingcommand;       /* Current unacknowledged command     */
    BYTE     stream;               /* MVIP address of channel            */
    BYTE     timeslot;             /* MVIP address of channel            */
    WORD     reserved;             /* Reserved                           */
    DWORD    dpnconstate;          /* DPNSS connection state             */
} DPN_CALL_STATUS;                 /* DPN_CONSTATE_xxx                   */




The DPN_CALL_STATUS structure contains the following fields: 


 





 Field 



 Description 




 size 



 Number of bytes written at the address pointed to by the status argument in dpnGetCallStatus call. 




 state 



 Current call control state. Values applicable to DPNSS are: 


·	 DPN_CC_STATE_STOPPED 


·	 DPN_CC_STATE_IDLE 


·	 DPN_CC_STATE_INCOMING_CALL 


·	 DPN_CC_STATE_ANSWERING_CALL


·	 DPN_CC_STATE_PLACING_CALL 


·	 DPN_CC_STATE_ACCEPTING_CALL 


·	 DPN_CC_STATE_DISCONNECTED 


·	 DPN_CC_STATE_CONNECTED 


·	 DPN_CC_STATE_REJECTING_CALL 


·	 DPN_CC_STATE_BLOCKING


·	 DPN_CC_STATE_OUT_OF_SERVICE 




 reason 



 Reason for the last disconnect (return to Idle state). reason is 0 if the application initiated the disconnect. Otherwise, reason is the value received in the DPNEVN_CALL_DISCONNECTED event. The value is one of the generic or DPNSS specific DPN_DIS_xx values defined in dpndef.h.




 calledaddr 



 The address of the called party. This information is sent or received by the DPNSS CLI supplementary service.




 callingaddr 



 The address of the calling party. This information is sent or received by the DPNSS CLI supplementary service.




 pendingcommand 



 The last call control command issued that has not yet been acknowledged by the driver. This field is set when a call control command is sent to the BX-3000 board. The field is cleared on the next event that causes a transition to a new call state. 


 Values applicable to DPNSS are: 


 0 No command pending. 


 1 DPN_PENDCMD_PLACE_CALL 


 2 DPN_PENDCMD_ANSWER_CALL 


 3 DPN_PENDCMD_REJECT_CALL 


 4 DPN_PENDCMD_RELEASE_CALL


 8 DPN_PENDCMD_ACCEPT_CALL




 stream 



 This field and timeslot together indicate the MVIP address of the channel. For BX-3000 boards, this is an MVIP-95 local stream.




 timeslot 



 This field and stream together indicate the MVIP address of the channel. stream also indicates whether the channel is  real or virtual:


·	 A number less than or equal to 29 means a real channel.


·	 A number greater than or equal to 32 means a virtual channel.




 dpnconstate



 Current DPNSS connection state. This field is relevant only when the state field value is DPN_CC_STATE_CONNECTED. 


 If state is DPN_CC_STATE_CONNECTED, the possible values are: 


·	 DPN_CONSTATE_TRANSIT 


·	 DPN_CONSTATE_TRANSIT_ACTIVE


·	 DPN_CONSTATE_HELD 


·	 DPN_CONSTATE_HOLDING


·	 DPN_CONSTATE_CONFERENCE


·	 DPN_CONSTATE_INTRUDING


 If state is any other value, dpnconstate may be any DPN_CC_xxx value.


















4.4.2	 Answering the Call





To answer the call, the application calls the function dpnAnswerCall.



The following events are associated with this function: 




Figure 7 is a sequence diagram for answering an inbound call. This diagram depicts the normal exchange of commands and events between the DPNSS service and the application. 





Figure 7.	 Sequence Diagram for Answering Inbound Call






4.4.3	 Rejecting the Call





To reject the call, the application can call dpnRejectCall. The following events are associated with this function: 




Figure 8 illustrates rejection of an inbound call. 





Figure 8.	 Sequence Diagram for Rejecting Inbound Call






4.4.4	 Accepting the Call without Answering





An application can accept an inbound call without answering, by calling dpnAcceptCall. In response to this function call, the DPNSS server sends a Number Acknowledge Message (NAM) message on the trunk indicating that the call is ringing. No further action is taken until the application calls dpnAnswerCall or dpnRejectCall, or the remote party disconnects. 



The following events are associated with dpnAcceptCall: 




Figure 9 illustrates accepting an inbound call and then rejecting it. 





Figure 9.	 Sequence Diagram for Accepting and then Rejecting Inbound Call




Figure 10 illustrates accepting an inbound call and then answering it. 





Figure 10.	 Sequence Diagram for Accepting and then Answering Inbound Call






4.5	 Establishing Outbound Calls





This section describes how a typical DPNSS call control application places calls, once it has been initialized as described in Chapter 3. 



Once the DPNSS protocol is started on the CTA context with dpnStartProtocol, the application can place outgoing calls. Outbound calls are established as follows: 


    


  1. The application invokes dpnPlaceCall. 
    

    

  2. The DPNSS server causes an Initial Service Request message to be sent to the network. This message contains all of the information necessary to place the call. 
    

    

  3. The DPNSS server generates an DPNEVN_PLACING_CALL event. The DPNSS server then waits for the remote party to accept, answer, or reject the call. 
    

    

  4. If the call request is rejected by the network, the DPNSS server abandons call placement. 
    

    

  5. If a network connection is established, CT Access generates a "call connected" event.
    




Figure 11 is a state diagram for placing outbound calls. This diagram can be correlated with the sequence diagram in Figure 12 to gain an understanding of outbound call states and events. 





Figure 11.	 Outbound Call State Diagram




Figure 12 is a sequence diagram depicting the command and event interchange for placing an outbound call. 





Figure 12.	 Sequence Diagram for Outbound Call






4.5.1	 Initiating an Outbound Call





To initiate an outbound call, the application calls dpnPlaceCall. This function tells the DPNSS server to deliver a digit string to the network switch. 



The following events are generated while the call is being set up: 




  • DPNEVN_INCOMING_CALL: A call is coming in on the channel. The call 
placement is aborted. 

    

    • 

    

    4.6	 Releasing a Call
    

    


    In order for CT Access to release a call, both the application and the network must actively release it. The network can disconnect at any time, regardless of the call control state. 
    


    After the call is released by both the network and the application, CT Access generates a call released event (DPNEVN_CALL_RELEASED). Once the call is released, no more events will be generated on the CTA context, and the application is eligible to receive and place new calls. 
    


    The next two sections present procedures for both network- and application-initiated call releases. 
    

    

    

    4.6.1	 Network-Initiated Call Release
    

    


    To release a call in response to a network disconnect: 
    

      


    1. The DPNSS server causes CT Access to generate a call disconnected event, DPNEVN_CALL_DISCONNECTED. 
      

      

    2. In response to DPNEVN_CALL_DISCONNECTED, the application invokes dpnReleaseCall. 
      

      

    3. CT Access generates a call released event, DPNEVN_CALL_RELEASED. 
      

      

    4. When the application processes the event, its internal state is reset to Idle. 
      

    


    The application is now eligible to place and receive new calls. 
    


    Figure 13 is a sequence diagram depicting the command and event interchange for a network-initiated release: 
    

 


    Figure 13.	 Sequence Diagram for Network-Initiated Release
    

    

    

    4.6.2	 Application-Initiated Call Release
    

    


    To release a call from within an application: 
    

      


    1. The application invokes dpnReleaseCall. In response to dpnReleaseCall, the DPNSS server sends a disconnection message to the network. 
      

      

    2. When the network acknowledges the disconnection message, the DPNSS server causes CT Access to generate a call released event, DPNEVN_CALL_RELEASED. 
      

      

    3. When CT Access processes the event, its internal call state is reset to Idle. 
      

    


    The application is now eligible to place and receive new calls. 
    


    Figure 14 is a sequence diagram depicting the command and event interchange for an application-initiated release: 
    




    Figure 14.	 Sequence Diagram for Application-Initiated Release
    

    

    

    4.7	 Blocking and Unblocking Calls
    

    


    The DPNSS service allows the application to block incoming calls and prevent placement of outbound calls. While calls are being blocked, no call control events are generated. 
    

    

    

    4.7.1	 Blocking Calls
    

    


    The application blocks calls by invoking dpnBlockCalls. This call can be made regardless of the state of the call. However, blocking only takes effect when the call next reaches the Idle state. If the call control state is not Idle, blocking is deferred until the call is released. When the DPNSS service begins blocking calls, the application no longer receives any call control events, and cannot place any outbound calls. If the other party connected to the trunk tries to place a call on a blocked channel, the channel appears as busy. 
    


    When the DPNSS service begins blocking calls, the DPNEVN_CALLS_ BLOCKED event is generated. 
    

    

    

    4.7.2	 Unblocking Calls
    

    


    To unblock calls, invoke dpnUnBlockCalls. 
    


    When dpnUnBlockCalls is executed, the DPNEVN_CALLS_UNBLOCKED event is generated, the call control state returns to Idle, and new calls may be established.
    

    

    


    
 
    (Page 1 of 1 in this chapter)  Version
    


    
 



    
tech_support@nmss.com

    

Copyright © 1999, Natural MicroSystems, Inc.   All rights
reserved.