(Page 1 of 1 in this chapter) Version

Chapter 2

Call Control

2.1 Introduction
2.1.1 Call Control and Protocol Independence
2.2 Telephone Network Events
2.2.1 Informational Events
2.2.2 Transitional Events
2.3 Responding to Inbound Calls
2.3.1 Inbound Call Parameters
2.3.2 Inbound Call Events
2.3.3 Accepting Calls
2.3.4 Performing Caller ID on Inbound Calls
2.4 Establishing Outbound Calls
2.4.1 Call Control Mask Parameters
2.4.2 Connectmask
2.4.3 Disconnectmask
2.4.4 Using Telephone Network Tone Detection
2.4.5 Using Precise Tone Detection
2.4.6 Using Broadband Tone Detection
2.4.7 Using Voice Detection
2.4.8 Using Call Placement Timeout
2.4.9 Outbound Call Parameters
2.4.10 Outbound Call Events
2.5 Releasing Calls
2.5.1 Telephone Network-Initiated Release
2.5.2 Application-Initiated Release
2.5.3 Cleardown Tone Detection
2.5.4 Call Release Parameters
2.5.5 Call Release Events
2.6 Blocking and Unblocking Calls
2.6.1 Call Blocking Parameters
2.6.2 Call Blocking Events
2.7 Managing Service Interruption
2.8 Transferring Calls
2.8.1 Using Supervised Transfer
2.8.2 Using Automatic Transfer
2.8.3 Call Transfer Parameters
2.8.4 Call Transfer Events
2.9 State Diagrams

2.1 Introduction

This chapter describes the ADI service call control functions. These functions manage telephone network signaling, and the procedures required for establishing and maintaining calls.

Note: The Natural Call Control (NCC) service API is the new standard call control API for NMS products. The NCC service provides an extended and enhanced version of the call control portion of the ADI service API. If your application currently uses the ADI service for call control, consider migrating to the NCC service for better performance, new features, and more control over your application's call control functionality.

There are two methods for establishing calls - answering inbound calls and placing outbound calls. In either case, the ADI service and the application exchange commands and events to advance to the call-connected state. Eventually, the ADI service and the application cooperatively release the call.

The ADI service call control functions manage:

The ADI service provides the following call control functions:
If you want to...

 Then use...

Accept an incoming call without answering or rejecting it

 adiAcceptCall

Answer an incoming call

 adiAnswerCall

Block subsequent calls

 adiBlockCalls

Retrieve the current call status

 adiGetCallStatus

Place an outbound call

 adiPlaceCall

Place the first call on hold and dial a second number or extension

 adiPlaceSecondCall

Reject an incoming call

 adiRejectCall

Release a call

 adiReleaseCall

Release second call and retrieve a first call

 adiReleaseSecondCall

Transfer a call

 adiTransferCall

Unblock previously blocked calls

 adiUnBlockCalls

With the release of CT Access 3.0, the call control functions within ADI will be considered to be deprecated functions. Eventually, the ADI call control API will be phased out entirely.

Refer to the Natural Call Control Service Developer's Reference Manual for further information.

2.1.1 Call Control and Protocol Independence

The ADI service call control functions are protocol-independent. Your application must be running a specific telephony protocol, but it uses the same ADI service call control functions regardless of which telephony protocol is running. In the ADI service, a protocol is embodied by a Trunk Control Program (TCP) or a Dynamic Link Library (DLL), which must be started using adiStartProtocol. For information about call control procedures and parameters for specific TCPs, refer to the AG CAS for the ADI Service Installation and Developer's Manual.

Telephone network events and protocol-specific events are mapped to the ADI service call control events, which are semantically identical across all protocols. This independence promotes application portability and accelerates application development.

Note: The Natural Call Control Service supercedes ADI call control.

2.2 Telephone Network Events

When performing call control functions, the ADI service processes the events that arrive from the telephone network, and in response to ADI service commands. The ADI service translates the telephone network events into generic call control events. These telephone network events fall into two classes: informational and transitional. Actual event names for use in C programming are defined in uppercase letters with an ADIEVN_ prefix. Refer to the events appendix in the ADI Service Function Reference Manual for a complete listing of events.

2.2.1 Informational Events

Informational events do not require any action by the application. For example, the protocol error event, ADIEVN_PROTOCOL_ERROR, provides information about abnormalities on the line including false seizure, too many incoming digits, or premature answer while dialing. Other informational events are generated only if you enable them by setting them in the eventmask in ADI_CALLCTL_PARMS.

The eventmask parameter dictates which optional informational events are generated.

The informational telephone network events are:
ADI Service Event

 Description

ADIEVN_SEIZURE_DETECTED

 The telephone network has seized the line (inbound only).

ADIEVN_INCOMING_DIGIT

 Each digit the TCP receives is sent to the application (inbound only).

ADIEVN_CALL_PROCEEDING

 The destination address has been delivered (outbound only).

ADIEVN_REMOTE_ALERTING

 Ring tone has been received from the telephone network (outbound only).

ADIEVN_REMOTE_ANSWERED

 The call is connected to the telephone network (outbound only).

ADIEVN_PROTOCOL_ERROR

 An abnormality on the line has occurred, such as false seizure, too many incoming digits, or premature answer while dialing.

ADIEVN_STATUSINFO_UPDATE

 The CALL_STATUS structure has been updated by the TCP (e.g., with UUI or billing information). The event value field contains the information.

2.2.2 Transitional Events

Transitional events are generated when the call state changes. They are generated because the ADI service needs the application to choose an action (e.g., incoming call response) or acknowledge that an application command is proceeding (e.g., placing call).

The transitional events are:
ADI Service Event

 Description

ADIEVN_INCOMING_CALL

 The network is offering a call.

ADIEVN_ACCEPTING_CALL

 The ADI service is accepting an incoming call without answering or rejecting it.

ADIEVN_ANSWERING_CALL

 The ADI service is answering the incoming call.

ADIEVN_REJECTING_CALL

 The ADI service is not answering the incoming call. This can occur for two reasons: either the application commanded it or the protocol forced it due to an application timeout once the remote side hangs up as a result, the reason in the disconnect event value field is set to rejected.

The application must still release the call via adiReleaseCall.

ADIEVN_PLACING_CALL

 The ADI service has seized an outbound line and is delivering the destination address.

For bidirectional lines, the placing call event guarantees that an incoming call event will not be generated until the call is released. This is called glare resolution.

ADIEVN_CALL_CONNECTED

 Inbound: The telephone network connection is established.

Outbound: The telephone network connection is established and any other connection criteria have been satisfied (e.g., voice detected, modem tones detected).

ADIEVN_CALL_DISCONNECTED

 The remote party has disconnected or the telephone network has rejected a placed call (e.g., busy tone detected). The application must still release the call by invoking adiReleaseCall.

ADIEVN_CALL_RELEASED

 The telephone network connection and all the ADI service resources allocated to this call have been released.

ADIEVN_CALLS_BLOCKED

 Call establishment is disabled. Inbound calls are rejected and outbound calls are prevented.

ADIEVN_CALLS_UNBLOCKED

 Call establishment is re-enabled. Inbound calls may be received and outbound calls may be placed.

ADIEVN_PLACING_CALL2

 The main call was placed on hold and a second call is being placed.

ADIEVN_CALL2_CONNECTED

 The third party has answered the call.

ADIEVN_CALL2_DISCONNECTED

 The third party is unavailable or has hung up.

ADIEVN_OUT_OF_SERVICE

 The line is not available for use. Either the telephone network is blocking calls, or the line and associated hardware are not configured properly.

ADIEVN_IN_SERVICE

 The line has returned to normal after being out of service.

2.3 Responding to Inbound Calls

The ADI service establishes network-initiated connections for protocols supporting inbound or bidirectional trunks. Once the telephony protocol is started with adiStartProtocol, it is eligible to receive incoming calls. After the incoming call event is offered to the application, the application is required to either accept the call by calling adiAcceptCall, to answer the call by calling adiAnswerCall, or to reject the call by calling adiRejectCall. If the application does not respond to the event, the call is rejected.

The demonstration program incta demonstrates responding to an incoming call. Refer to the CT Access Developer's Reference Manual for more information about incta.

To establish an inbound call:

  1. The telephone network offers the call.

    

  2. The ADI service generates an incoming call event.
    

    

  3. The application can accept, answer, or reject the call.
    

    
The ADI service performs network procedures to execute the application's decision.
    

  4. The ADI service generates a call connected event if the call is successfully established, or a call disconnected event if the remote party disconnects.
    




Figure 2 contains two protocol timing sequence diagrams: one for answering an inbound call, and one for rejecting an inbound call. The diagrams depict the normal exchange of commands and events between the ADI service and the application. Informational events are shown with a dashed line.





Figure 2.	 Inbound Call Sequence




Figure 3 is a state diagram for inbound trunks. The sequence diagrams in Figure 2 can be correlated with the state diagram in Figure 3 to gain a comprehensive understanding of the inbound call states and events, which are described in the next section.





Figure 3.	 Inbound Call States






2.3.1	 Inbound Call Parameters





Most of the parameters that govern inbound call establishment are specific to the telephony protocol that is running. Refer to the documentation for the telephony protocol that your application is using for more detailed information. The telephony protocols that are included with the ADI service are documented in the AG CAS for the ADI Service Installation and Developer's Manual.






2.3.2	 Inbound Call Events





The following table summarizes the ADI service events which are generated when responding to inbound calls: 





 Event



 Description



 




 ADIEVN_SEIZURE_DETECTED



 Informational event generated when a line is seized by the telephone network (only appears if enabled in eventmask).


 Examples of a line-seized event include:




 



 Line Type
Wink start
Loop start



 Condition
Off-hook detected.
The leading edge of the first ring.




 ADIEVN_INCOMING_DIGIT



 Informational event reporting each incoming digit. The application can analyze the digits as they arrive and, if necessary, force the presentation of the incoming call using the function adiAcceptIncomingAddress.This event is received after each digit is received only if the TCP is set up to report incoming digits individually as they arrive.




 ADIEVN_INCOMING_CALL



 Event that signifies the transition of the call from the Idle state to the Incoming Call state. It is generated after the telephone network delivers the call to the ADI service. The following examples illustrate conditions that generate an incoming call event:




 



 Line Type
Wink start


 


 


 


 Loop start



 Condition
All required destination address digits have been received by the ADI service. adiGetCallStatus may be invoked to get the called party and the calling party digits.
A specified number of rings have been received, along with optional caller ID information (refer to the loop-start parameters in the AG CAS for the ADI Service Installation and Developer's Manual).




 



 The application should respond to the incoming call event by invoking either adiAcceptCall, adiAnswerCall, or adiRejectCall.


 Wink-start protocols require the application to respond within a specified period of time. If the application fails to respond within the given period, the ADI service automatically rejects the call and generates an ADIEVN_REJECTING_CALL event.




 ADIEVN_ACCEPTING_CALL



 The event that is generated when the ADI service enters the Accepting Call state in response to adiAcceptCall.




 ADIEVN_ANSWERING_CALL



 After the application invokes adiAnswerCall, this event is generated to acknowledge that the ADI service has begun executing the answer call function. Once this event is received, the application transitions to the Answering Call state.




 ADIEVN_CALL_CONNECTED



 After the application invokes adiAnswerCall, and receives the ADIEVN_ANSWERING_CALL acknowledgment, the ADI service executes the telephone network procedures for accepting the call and establishing the connection. Once the connection is established, the call connected event is generated and the call state transitions to Connected.




 ADIEVN_REJECTING_CALL



 If the application invokes adiRejectCall, the rejecting event is generated once the ADI service begins executing the specified reject method. Rejection of incoming calls is protocol-dependent.


 Loop-start lines can only reject calls by not answering them. The board reports disconnected when the incoming ring has stopped. Wink-start lines may use one of four methods of call rejection:


·	 Playing reorder tones


·	 Playing busy tones


·	 Playing ring tones indefinitely


·	 Playing application-provided audio (e.g., SIT tone)


 The method of rejection is returned back in the value field of the event. The rejecting event is also generated if the application fails to respond to the incoming call event as described above. In this case, the value field will contain "host timeout."




 ADIEVN_CALL_DISCONNECTED



 This event is generated when the calling party disconnects. It can occur in any call state. The disconnect event contains the reason for disconnect in the value field.




 ADIEVN_CALL_RELEASED



 After the application invokes adiReleaseCall, the ADI service generates the call released event when its internal state is reset to Idle.




 ADIEVN_STATUSINFO_UPDATE



 The CALL_STATUS structure has been updated by the TCP (e.g., with UUI or billing information). The event value field contains the information type.



















2.3.3	 Accepting Calls





In this state, an incoming call has been accepted, but the call has been neither answered nor rejected. This state allows applications to perform media functions (such as playing a voice file) before connecting an inbound call. 



The ADIEVN_INCOMING_CALL event indicates that an incoming call has been detected. The application can then invoke adiAcceptCall to place the call in the Accepting Call state. Arguments passed to adiAcceptCall can also cause a ring tone or user audio to be played when the call enters the state.



The application receives an ADIEVN_ACCEPTING_CALL event which indicates that the call is in the Accepting Call state. The call will remain in this state until the application invokes adiAnswerCall or adiRejectCall. Receipt of ADIEVN_ANSWERING_CALL or ADIEVN_REJECTING_CALL indicates that the call has been answered or rejected, or that the telephone network has timed out. The call is no longer in the Accepting Call state.



The application may receive ADIEVN_CALL_DISCONNECTED while the call is in the Accepting Call state. This event indicates that the remote party has hung up. The event value field contains the reason. The application should then invoke adiReleaseCall to release the call and return to the Idle state.



adiAcceptCall causes the trunk protocol to accept the incoming call, entering the Accepting Call state. The trunk protocol accepts the call using one of the following actions, depending upon the value of method: 





 Method



 Action




 ADI_ACCEPT_PLAY_RING



 Plays ring tone.




 ADI_ACCEPT_QUIET



 Plays nothing.




 ADI_ACCEPT_USER_AUDIO



 Allows the application to generate any programmable tone and perform voice playback functions.
















The generated tone is played until the application invokes adiAnswerCall or adiRejectCall, or until the remote party disconnects.






2.3.4	 Performing Caller ID on Inbound Calls





The sections describe performing caller ID under different protocols.


 Caller ID with Loop Start



For AG hardware, to enable your application to use caller ID data, ensure that the ag.cfg file loads the DSP file adsir.dsp during board initialization (adsi.m54 for AG 2000 boards). For QX hardware, to enable your application to use caller ID data, set the caller ID flag in the structure for the active telephony protocol. For all boards, enable caller ID by modifying the protocol parameters as indicated in the protocol appendix in the AG CAS for the ADI Service Installation and Developer's Manual.



Ensure that the application responds to an ADIEVN_INCOMING_CALL event by invoking adiGetCallStatus. The application needs to analyze the call status for every incoming call in order to retrieve the caller ID data, since the data is written to the ADI_CALL_STATUS structure.



The Bellcore specifications define two types of CID message formats which NMS currently supports:




All other message formats and parameter types are ignored.


Note:  For specific information about the ADI_CALL_STATUS structure, refer to the ADI Service Function Reference Manual.


If the caller's ID or name is blocked, the callingname or callingaddr fields respectively, will contain a P. If either is unavailable, the letter O is placed in the field. No information is returned if there are any line errors (such as a bad stop bit or a drop in data).



Keep in mind that if caller ID is enabled, even if the ringcount is set to 0 or 1, the ADIEVN_INCOMING_CALL event is not generated until the caller information is received, which occurs sometime between the first and second rings.


 Caller ID with DID or Wink Start



Some incoming trunks deliver both calling ID (ANI) and called ID in a single burst of digits. There may be a special digit such as * separating the two number strings. You can use the wink-start or DID protocol with these trunks. 



To analyze caller ID data:


    


  1. Set the numdigits parameter in the protocol's parameter structure to the total number of digits expected, including the separator character. 
    

    

  2. After an incoming call arrives, retrieve the digits from the ADI_CALL_STATUS structure with adiGetCallStatus. The entire string will be in the calledaddr field of the status structure.
    







2.4	 Establishing Outbound Calls





The ADI service can be used to place calls with telephony protocols supporting outbound and bidirectional trunks. After the telephony protocol is started by calling adiStartProtocol, the application is eligible to place calls.



The application places a call by invoking adiPlaceCall, which initiates dialing and call progress analysis. Call progress analysis detects several events (e.g., signaling, tones, voice) received from the telephone network and the remote party. These events indicate the call's progression through the telephone network.



Once adiPlaceCall is acknowledged, dialing and call progress analysis are initiated and the application is guaranteed to receive either an ADIEVN_CALL_CONNECTED event or an ADIEVN_CALL_DISCONNECTED event.



The application chooses the criteria by which the ADI service generates the connected events and disconnected events. The ADI_PLACECALL_PARMS structure contains the connectmask and disconnectmask parameters that dictate when the connected events and disconnected events are generated, thus terminating call progress analysis. Each bit in these masks corresponds to a telephone network or remote party event. These masks are explained in detail in Section 2.4.2 and Section 2.4.3.


Note:  If a condition is specified in both masks, connectmask takes precedence. The events controlled by these masks are discussed in Section 2.2.


The demonstration program outcta demonstrates placing an outbound call. Refer to the CT Access Developer's Reference Manual for more information about outcta.



To establish an outbound call:


    


  1. The application invokes adiPlaceCall. 
    

    
The ADI service seizes the line and generates an ADIEVN_PLACING_CALL event when a positive "go-ahead" is received from the telephone network (e.g., dial tone).
    

  2. The destination address is delivered to the network switch. 
    

    
The ADI service then monitors inband energy and out-of-band signaling, if any, to detect a telephone network connection.
    

  3. If the call request is rejected by the telephone network (e.g., busy signal detected), the ADI service abandons call placement and delivers an ADIEVN_CALL_DISCONNECTED event.
    

    

  4. If a telephone network connection is established, the ADI service generates an ADIEVN_CALL_CONNECTED event or an ADIEVN_CALL_DISCONNECTED event depending upon the events received in conjunction with the application-specified criteria.
    

    
For example, if the application is only interested in reaching fax machines it would specify "connect on CED" and "disconnect on voice."



Figure 4 is a sequence diagram depicting the command and event interchange for placing an outbound call. Informational events are shown with a dashed line.





Figure 4.	 Outbound Call Sequence




Figure 5 is a state diagram for placing outbound calls. This diagram can be correlated with the timing diagram in Figure 4 to gain a comprehensive understanding of outbound call states and events (which are described in the next section).





Figure 5.	 Outbound Call States






2.4.1	 Call Control Mask Parameters





This section summarizes the call control mask parameters stored in the ADI_PLACECALL_PARMS structure. These parameters provide the criteria according to which the ADI service generates connected and disconnected events. Each bit in these masks corresponds to an event received from the telephone network or from the called party. The ADI_PLACECALL_PARMS structure is passed to the ADI service when the call is placed with adiPlaceCall.






2.4.2	 Connectmask





The ADI_PLACECALL_PARMS connectmask dictates which call progress analysis event causes the ADI service to transition from the Placing Call state to the call Connected state (as shown in Figure 5).



Each of the following bits occupies a position in the connectmask parameter. If the bit is enabled (set) and the condition described occurs, the ADIEVN_CALL_CONNECTED event is generated. 





 Connect Mask Bit



 Condition for ADIEVN_CALL_CONNECTED




 ADI_CON_ON_RING_QUIT



 Ring tone stopped; no other events detected (refer to Section 2.4.4).




 ADI_CON_ON_SIGNAL



 Out-of-band signaling indicates telephone network connection established.




 ADI_CON_ON_CED



 Modem tone detected from remote station.




 ADI_CON_ON_VOICE_BEGIN



 First detection of remote voice.




 ADI_CON_ON_VOICE_MEDIUM



 Remote voice has lasted longer than the first time threshold. (refer to Section 2.4.7.)




 ADI_CON_ON_VOICE_LONG



 Remote voice has lasted longer than the second time threshold. (refer to Section 2.4.7.)




 ADI_CON_ON_VOICE_EXTENDED



 Remote voice has lasted longer than the third time threshold. (refer to Section 2.4.7.)




 ADI_CON_ON_DIALTONE



 Dial tone was detected after placing the call.




 ADI_CON_ON_SIT



 Special Information Tone (SIT) was received.




 ADI_CON_ON_CALL_PROCEEDING



 Unconditional - connect immediately after dialing (no call analysis).
















The following two conditions, if satisfied, always generate an ADIEVN_CALL_CONNECTED event. These two conditions have no bit position in the connectmask. In effect, they are always turned "on." They are:




To override either of these conditions, set the corresponding bit within the disconnectmask, ADI_DIS_ON_VOICE_END or ADI_DIS_ON_TIMEOUT, respectively.



Once one of the enabling conditions is satisfied, the call is connected. When the call is connected, the ADI service generates an ADIEVN_CALL_CONNECTED event. The event's value field indicates the reason for the transition to the Connected state.






2.4.3	 Disconnectmask





The ADI_PLACECALL_PARMS disconnectmask parameter dictates which call progress analysis events cause the ADI service to transition from the Placing Call state to the Disconnected state.



Each of the following bits occupies a position in the disconnectmask parameter. If the bit is enabled (set) and the condition described occurs, the ADIEVN_CALL_DISCONNECTED event is generated.


Note:  The connectmask takes precedence. If a condition is selected in both the connectmask and disconnectmask, a call will be connected if that condition occurs. 





 Disconnect Mask Bit



 Condition for ADIEVN_CALL_DISCONNECTED




 ADI_DIS_ON_RING_QUIT



 Ring tone stopped; no other events detected (refer to Section 2.4.4).




 ADI_DIS_ON_CED



 Fax or modem tone detected from remote station.




 ADI_DIS_ON_VOICE_BEGIN



 First detection of remote voice.




 ADI_DIS_ON_VOICE_MEDIUM



 Remote voice has lasted longer than the first threshold. (refer to Section 2.4.7.)




 ADI_DIS_ON_VOICE_LONG



 Remote voice has lasted longer than the second threshold. (refer to Section 2.4.7.)




 ADI_DIS_ON_VOICE_EXTENDED



 Remote voice has lasted longer than the third threshold. (refer to Section 2.4.7.)




 ADI_DIS_ON_VOICE_END



 Remote party stopped speaking. (refer to Section 2.4.7.)




 ADI_DIS_ON_TIMEOUT



 No events occur after the event ADIEVN_CALL_PROCEEDING.















The following conditions, if satisfied, always generate a disconnected event. These conditions have no bit position in the disconnectmask. In effect, they are always turned "on." They are:




Refer to Section 2.4.4 for more information about the call progress analysis parameters affecting these events.






2.4.4	 Using Telephone Network Tone Detection





When establishing outbound calls, the ADI service analyzes inband audio to detect the following telephone network signals:




The ADI_PLACECALL_PARMS parameters set the criteria to determine if the energy received is a telephone network tone or voice. These parameters are sent to the AG board by adiPlaceCall.



The following terms are used to characterize telephone network tones, and are illustrated in Figure 6:




The ADI service uses two types of tone detectors to distinguish tones from voice data: a precise tone detector and a broadband tone detector.






2.4.5	 Using Precise Tone Detection





The precise tone detector quickly analyzes inband audio at specific frequencies to detect the following types of tones:




The application specifies which of these tones will be detected by configuring the precmask in the ADI_PLACECALL_PARMS structure. If the busy tone detection is not enabled, the ADI service takes more time to discern the busy tone using broadband tone detection, as described in Section 2.4.6. If SIT detection and CED detection are not enabled, these tones cannot be detected.



The precqualtime parameter determines the duration in which the tones are qualified. This parameter applies to all three tones defined in this section. Set it to the time required to detect the tone of shortest duration.






2.4.6	 Using Broadband Tone Detection





The broadband detection method uses simple high and low pass frequency discrimination together with broadband energy measurements over time to qualify network tones. For example, the DSP determines that a ring tone is present if all of the following conditions are met:




Two signal characteristics are used for broadband tone detection: pulse width and cadence.



When defining pulse width, the application specifies time limits for excluding each telephone network tone. Figure 7 illustrates the effect these limits have on the tones. The waveforms depicted are in milliseconds and are representative of tones in the USA.





Figure 7.	 Telephone Network Tone Pulse Width Limits




The time parameters depicted in Figure 7 are described in the following table and are stored in the ADI_CALLPROG_PARMS structure: 





 Parameter



 Description




 maxreorder



 The upper limit for a telephone network reorder tone cycle time (ms). The reorder tone will be excluded from consideration if the cycle time is greater than this value.




 maxbusy



 The upper limit for a telephone network busy tone cycle time (ms). The busy tone will be excluded from consideration if the cycle time is greater than this value.




 maxring



 The upper limit (ms) for a telephone network ring tone. If the telephone network tone is present for longer than maxring milliseconds, dial tone is being received.















Note:  The ADI service presumes that maxreorder is less than maxbusy which is less than maxring: 
  maxreorder  <  maxbusy  <  maxring

This relationship defines a time tolerance - minimum and maximum - for each of the three tones being detected.


The second characteristic used for broadband tone detection is the signal's cadence. The application specifies tone counts in the ADI_PLACECALL_PARMS structure. The signal must satisfy the single tone criteria described in Figure 7 for the respective number of cycles before the ADI service concludes the signal is present. The following table defines the cadence for each signal: 





 Tone



 Parameter



 Description




 Busy



 busycount



 Busy signal received.




 Reorder



 busycount



 Reorder received.




 Ring



 ringcount



 Call not answered.

















For example, when busycount reorder tones are counted, the ADI service concludes it is receiving a reorder (fast busy) signal.



Figure 8 depicts ring tone termination. After having established that the line is receiving ring tone, the ADI service concludes that the remote trunk has quit ringing if a ring tone is not received in the maxringperiod. This parameter controls the ring quit event.





Figure 8.	 Ring Tone Termination






2.4.7	 Using Voice Detection 





If the ADI service passes through the network connected phase without resolution (i.e., did not generate a ADIEVN_CALL_CONNECTED event or ADIEVN_CALL_DISCONNECTED event), call analysis advances into its final stage: voice detection.



The ADI service detects when the remote party starts and stops speaking. These are the Voice Begin and Voice End conditions, respectively. The Voice Begin condition indicates that the call is being answered by the remote party.



By default, the ADI service generates an ADIEVN_CALL_CONNECTED event on Voice Begin, which terminates the place call operation. The application can override this behavior by clearing the ADI_CON_ON_VOICE_BEGIN bit in the connectmask.



The ADI service supports three voice duration time thresholds - medium, long, and extended. The duration for these three thresholds is specified in the ADI_CALLPROG_PARMS structure (a substructure of ADI_PLACECALL_PARMS). The application can set the connectmask and disconnectmask to force call resolution on any of these voice thresholds, as well as on the Voice End condition.



For example, suppose the application should connect the call only if the call is answered with a short salutation (e.g., "Hello"). The "disconnect on voice medium event" (ADI_DIS_ON_VOICE_MEDIUM) bit in the disconnectmask should be set, and the Voice Medium time threshold should be set accordingly. This would generate an ADIEVN_CALL_DISCONNECTED event if an answering machine were reached.



The precise definition of each of these conditions is controlled by parameters in the callprog structure in ADI_PLACECALL_PARMS: 





 Voice Condition



 Description



 Controlling Parameter in callprog in ADI_PLACECALL_PARMS




 Voice Begin



 Remote party begins speaking.



 None.




 Voice Medium



 Remote party has spoken for a period longer than the first time threshold.



 voicemedium - (ms) first time threshold.




 Voice Long



 Remote party has spoken for a period longer than the second time threshold.



 voicelong - (ms) second time threshold.




 Voice Extended



 Remote party has spoken for a period longer than the third time threshold.



 voicextended - (ms) third and final time threshold.




 Voice End



 Remote party stopped speaking.



 silencetime - (ms) qualification time before concluding voice end.
















Voice Begin can be triggered when the remote party begins speaking. Voice End occurs after an absence of voice for silencetime milliseconds. This is illustrated in Figure 9.





Figure 9.	 Call Progress Analysis Voice Detection






2.4.8	 Using Call Placement Timeout





To ensure that call placement is resolved within a certain time period, the ADI service provides a timeout parameter. The callprog.timeout parameter in ADI_PLACECALL_PARMS specifies the maximum time after the last detected event before the ADI service generates an ADIEVN_CALL_CONNECTED or an ADIEVN_CALL_DISCONNECTED event. By default, the ADI service generates an ADIEVN_CALL_CONNECTED event if this time period elapses. The application can choose to disconnect on timeout by setting the disconnectmask accordingly. The timeout feature can be defeated by setting the callprog.timeout parameter in ADI_PLACECALL_PARMS to zero.






2.4.9	 Outbound Call Parameters





Section 2.4.4 through Section 2.4.8 describe how to use the parameters stored in the ADI_PLACECALL_PARMS and ADI_CALLPROG_PARMS structures to control outbound call placement. For more information about the parameters stored in these structures, refer to the ADI Service Function Reference Manual.



Additional parameters that govern outbound call establishment may be specific to the telephony protocol that is running. Refer to the documentation for the telephony protocol that your application is using for more detailed information. The telephony protocols that are included with the ADI service are documented in the AG CAS for the ADI Service Installation and Developer's Manual.






2.4.10	 Outbound Call Events





The following table summarizes the ADI service events which are generated when establishing outbound calls: 





 ADI Service Event



 Description




 ADIEVN_CALL_CONNECTED



 Changes to the call Connected state and terminates the place call operation. Multiple conditions as programmed by the application can generate the call connected event. By default, the call connected event is generated when any of the following occur:


·	 After the remote party has answered the call and delivered a salutation (e.g., "Hello?").


·	 After ring tone is detected, ringing stops.


·	 No call progress analysis events occur for a specified period of time.


 These defaults can be overridden by assigning the disconnectmask to disconnect upon occurrence of the event. Other events can also be added to the connectmask.




 ADIEVN_CALL_DISCONNECTED



 Generated if call placement fails at any time for any reason.


 The following conditions generate the call disconnected event after receiving ADIEVN_PLACING_CALL:


·	 The telephone network rejects the call (e.g., busy, SIT, reorder, no answer).


·	 The ADI service abandons the call upon occurrence of application-specified criteria (e.g., CED or "Long Voice").


·	 The remote party disconnects before the call connected event is delivered.


 The following conditions generate the call disconnected event before receiving ADIEVN_PLACING_CALL:


·	 The telephone network does not acknowledge a seizure on wink-start trunks.


·	 The telephone network does not provide dial tone on loop-start trunks.


 Other events may cause call disconnect if added to the disconnectmask.




 ADIEVN_PLACING_CALL



 Generated after the ADI service has seized an outgoing line in response to the application invoking adiPlaceCall. The placing call event confirms that the line is seized and glare (a race with an incoming call) is resolved.


 Note: For suspected glare conditions on loop-start trunks, the application can configure the protocol to abandon placing a call (ADIEVN_DISCONNECTED) or offer an inbound call (ADIEVN_INCOMING_CALL). For glare conditions on wink-start trunks, the ADIEVN_INCOMING_CALL event may arrive instead of the placing call event. In this case, the place call function is terminated.




 ADIEVN_CALL_PROCEEDING



 An informational event that is generated after the destination address is delivered to the telephone network switch (digits dialed).




 ADIEVN_CALL_RELEASED



 After the application invokes adiReleaseCall, the ADI service generates the call released event when its internal state is reset to Idle.




 ADIEVN_REMOTE_ALERTING



 An informational event that is generated when ring tone is received from the telephone network.




 ADIEVN_REMOTE_ANSWERED



 An informational event that is generated on the first positive indication that the call is being answered by the remote party. For positive indication, one of the following conditions must be met:


·	 Out-of-band signaling indicates connection.


·	 Voice is detected from the remote party.


·	 CED (fax/modem) tone is detected from the remote party.



















2.5	 Releasing Calls





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



After the call is released by both the telephone network and the application, the ADI service generates a call released event. Once the call is released, no more DSP-related events will be generated on the CTA context, and the application is eligible to receive and place new calls.



The demonstration program incta demonstrates releasing calls. Refer to the CT Access Developer's Reference Manual for more information about incta.



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






2.5.1	 Telephone Network-Initiated Release





Releasing a call in response to a telephone network disconnection follows these steps:


    


  1. The ADI service detects the telephone network disconnect signal and generates an ADIEVN_CALL_DISCONNECTED event.
    

    
All active operations that use DSP resources are terminated, and their DONE events are generated.
    
Note:  After the application retrieves the ADIEVN_CALL_DISCONNECTED event from the driver, the ADI service will not allow DSP-related operations to be started on the context until the context reenters the Connected state.


  2. In response to the ADIEVN_CALL_DISCONNECTED event, the application invokes adiReleaseCall.
    

    

  3. The ADI service generates an ADIEVN_CALL_RELEASED event.
    

    

  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.






2.5.2	 Application-Initiated Release





To release a call from within an application, the application invokes adiReleaseCall.




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






2.5.3	 Cleardown Tone Detection





Some protocols, for example, loop start, detect a specific tone as a disconnect signal. The tone is defined in the ADI.START.cleardown parameters. The default setting configures the tone detector for a U.S. dial tone.



These parameters can be configured to detect steady tone or cadenced tone. To detect steady tone, set ADI.START.cleardown.tonecount equal to 0, and set ADI.START.cleardown.qualtime to the minimum duration of continuous tone that qualifies as disconnect. 



For cadenced tones, set ADI.START.cleardown.tonecount to the minimum number of on-off cycles of the tone. In this case, ADI.START.cleardown.qualtime is ignored.



For example, you can use the ADISTART_CLEARDOWN_PARMS to configure a tone detector for a cleardown tone of 440 Hz (+ or - 20 Hz) with a 100 ms on, 600 ms off (+ or - 20 ms) cadence, with -20 dBm amplitude. This tone is a good candidate for a cadence detector because the short duration and single frequency require a detector which is susceptible to false hits from voice. Qualifying several tones with precise timing provides more reliable detection of the tone and eliminates false hits. 



For this example tone, set ADI.START.cleardown structure to the following: 





 Field



 Value



 Description




 freq1



 440



 Nominal frequency (Hz)




 bandw1



 60



 Twice the max error + margin (Hz)




 freq2



 0



 No second frequency




 bandw2



 0



 Ignored if freq2 == 0




 qualampl



 -25



 Minimum total signal level (dBm)




 tonecount



 3



 Qualify three tones




 minontime



 70



 Slightly shorter than shortest tone




 maxontime



 130



 Slightly longer than longest tone




 minofftime



 570



 Slightly shorter than shortest silence




 maxofftime



 630



 Slightly longer than longest silence



















2.5.4	  Call Release Parameters





Most of the parameters that govern call release are specific to the telephony protocol that is running. Refer to the documentation for the telephony protocol that your application is using for more detailed information. The telephony protocols that are included with the ADI service are documented in the AG CAS for the ADI Service Installation and Developer's Manual.






2.5.5	 Call Release Events





If the telephone network disconnects a call, the ADI service generates an ADIEVN_CALL_DISCONNECTED event. When the application calls adiReleaseCall in response to disconnect or to initiate hang up, the ADI service generates an ADIEVN_CALL_RELEASED event.






2.6	 Blocking and Unblocking Calls





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



The application blocks calls by invoking adiBlockCalls from any call control state. Blocking only takes effect in the call Idle state. If the call control state is not Idle, blocking will be deferred until the call is released. When the ADI service begins blocking calls, the application will no longer receive any call control events or be allowed to place any outbound calls.



The ADI service supports two blocking methods, which are:




To unblock calls, invoke adiUnBlockCalls.






2.6.1	 Call Blocking Parameters





The ADI_CALLCTL_PARMS structure contains the blockmode parameter which determines how adiBlockCalls will work. This parameter can be set to zero (0) to reject all incoming calls, or to one (1) to respond with a reverse-make-busy signal.






2.6.2	 Call Blocking Events





When the ADI service begins blocking calls, the ADIEVN_CALLS_BLOCKED event is generated. The application will not receive any subsequent call control events or be allowed to place any outbound calls.



After adiUnBlockCalls is executed, the ADIEVN_CALLS_UNBLOCKED event is generated, the call control state returns to Idle, and new calls may be established.






2.7	 Managing Service Interruption





The ADI service detects service interruption and informs the application by generating an ADIEVN_OUT_OF_SERVICE event. These events are rare and are protocol-dependent. The application cannot place or receive calls while the line is in the out-of-service state. When the line resumes normal operation, the ADI service generates an ADIEVN_IN_SERVICE event.


Note:  The out-of-service event can be generated in any call control state except connected and while blocking calls.





2.8	 Transferring Calls





The ADI service supports the ability to transfer calls from a first line to a second line through a Private Branch Exchange (PBX), Centrex, or Centrex-like exchange. Call transfer operations can only be initiated when the call (first line) is in the Connected state.



The two methods for transferring calls are:




Both methods deliver a flash hook or other configurable dialing sequence to the first line and obtain a second line. After the ADI service receives a recall dial tone from the line, the process for placing a second call is identical to that described in Section 2.4.


Note:  The transfer functions use the same call progress analysis algorithms described in previous sections about placing calls. adiPlaceSecondCall and adiTransferCall also use the ADI_PLACECALL parameters.





2.8.1	 Using Supervised Transfer





The supervised transfer method allows the application to control the transfer process. The procedure for a supervised transfer is as follows (refer to Figure 10):


    


  1. The application invokes adiPlaceSecondCall. 
    

    
The ADI service obtains a second line and generates the ADIEVN_PLACING_CALL2 event. The ADI service then delivers the second address to the line and monitors the call as described in Section 2.2.
    
If the ADI service fails to establish the second call, an ADIEVN_CALL2_DISCONNECTED event is generated. The call control state changes back to the Connected state for the first line.
    
If the second call is successfully placed, the ADI service generates an ADIEVN_CALL2_CONNECTED event. The application is now speaking to the third party (second line destination).
    
If the third party hangs up, the ADI service generates an ADIEVN_CALL2_DISCONNECTED event, the call control state transitions back to the Connected state for the first line, and the application resumes speaking with the first party.
    

  2. The application can invoke adiReleaseSecondCall, which causes the ADI service to deliver a flash hook or other configurable dialing sequence to the line and generate an ADIEVN_CALL2_DISCONNECTED event. 
    

    
The call control state changes back to the Connected state for the first line.
    
Note:  Depending on the PBX or switch, this may result in a three-way conversation.


  3. The application can invoke adiReleaseCall, which causes the ADI service to send an on-hook to the line interface. The ADIEVN_CALL_RELEASED event is generated and the call control state changes back to Idle. This completes the transfer.
    

    



    Figure 10.	 Call Transfer States
    







2.8.2	 Using Automatic Transfer





The automatic transfer method allows CT Access to control call transfer. The application specifies one of the following conditions, on which it disconnects from the switch, as an argument to adiTransferCall: 





 Condition



 Description




 ADI_XFER_PROCEEDING



 The second line's address is delivered to the switch and the transfer is completed as soon as the digit string is dialed.




 ADI_XFER_ALERTING



 The transfer is completed as soon as the ring tone is received on the second line.




 ADI_XFER_CONNECTED



 The transfer is completed as soon as the second line has been answered.
















To perform an automatic transfer, the application invokes adiTransferCall. Refer to Figure 10 for a diagram of call transfer states.



The ADI service obtains a second line and generates an ADIEVN_PLACING_CALL2 event. The ADI service then delivers the second address to the PBX or switch.



Depending on which transfer condition was passed to adiTransferCall, one of the following actions takes place:






2.8.3	 Call Transfer Parameters





For automatic transfer, the condition on which to transfer a call is specified as an argument to adiTransferCall. Otherwise, call transfer operations use the same parameters as outbound call placement operations. These parameters are stored in the ADI_PLACECALL_PARMS and ADI_CALLPROG_PARMS structures.



Section 2.4.1 through Section 2.4.8 describe how to use the parameters stored in the ADI_PLACECALL_PARMS and ADI_CALLPROG_PARMS structures. For more details about the parameters stored in these structures, refer to the ADI Service Function Reference Manual.



Additional parameters that govern call transfer may be specific to the telephony protocol that is running. Refer to the documentation for the telephony protocol that your application is using for more detailed information. The telephony protocols that are included with the ADI service are documented in the AG CAS for the ADI Service Installation and Developer's Manual.



With the loop-start and wink-start protocols, you can specify prefix dial strings for transfer and reconnect by modifying the connstring or xferstring parameters.



When in the Connected state, if an attempt is made to transfer a call, and transfer is enabled (xfersupport==1), the protocol dials the string specified by the xferstring parameter before dialing the called address that was passed to adiTransferCall or adiPlaceSecondCall.



If the dial fails, ADIEVN_CALL2_DISCONNECTED is generated. The ADI service then returns to the Connected state. When returning to the Connected state, the second string specified by the connstring parameter is dialed.






2.8.4	 Call Transfer Events





The call transfer events generated by the ADI service are:


 





 Call Transfer Event



 Description




 ADIEVN_PLACING_CALL2



 After delivering the flash hook or other configurable dialing sequence to the line and getting a recall dial tone, the ADI service generates the placing second call event. The destination address for the third party is then delivered to the switch.




 ADIEVN_CALL2_DISCONNECTED



 If placement of the second call fails or if the third-party hangs up, the ADIEVN_CALL2_DISCONNECTED event is generated. The call returns to the Connected state for the first call. This event is also generated when the application releases the second call via adiReleaseSecondCall.




 ADIEVN_CALL2_CONNECTED



 This event is generated if the second call is successfully established via adiPlaceSecondCall. The connection criteria and processing are identical to those when originating calls via adiPlaceCall.




 ADIEVN_CALL_DISCONNECTED



 The call disconnected event is generated when a blind transfer succeeds. It is also generated if the first line disconnects before the ADI service generates the placing second call event. The call disconnected event disconnects the channel from both calls and the application must invoke adiReleaseCall.


















2.9	 State Diagrams





This section presents two state diagrams of call control functions. Figure 11 is a state diagram encompassing inbound, outbound, and service interruption control functions. Figure 12 adds call transfer functionality to Figure 11.



The ADI service call state machine is event-driven. The state does not change when a call control function is invoked.



To detect if a function is called twice in a row, the library stores the identity of the last call control command issued to the board in the pendingcommand field of the ADI_CALL_STATUS structure.



The following table shows which functions are allowed in each state: 





 State



 Pending Command



 Functions Allowed




 IDLE



 (none)
Place call
Release



 adiPlaceCall
adiReleaseCall
(none)




 INCOMING_CALL



 (none)
Answer
Reject



 adiAcceptCall, adiAnswerCall, adiRejectCall
adiAnswerCall
(none)




 ACCEPTING_CALL



 (none)
Answer
Reject



 adiAnswerCall, adiRejectCall
adiAnswerCall
(none)




 ANSWERING_CALL



 (none)
Answer
Release



 adiAnswerCall, adiReleaseCall
adiAnswerCall, adiReleaseCall
(none)




 PLACING_CALL



 (none)
Release



 adiReleaseCall
(none)




 DISCONNECTED



 (none)
Release



 adiReleaseCall
(none)




 CONNECTED



 (none)

Release
Release 2nd
Transfer
Place 2nd call



 adiReleaseCall, adiTransferCall, adiPlaceSecondCall
(none)
adiReleaseCall
adiReleaseCall, adiReleaseSecondCall
adiReleaseCall, adiReleaseSecondCall




 REJECTING



 (none)



 (none)




 PLACING_CALL2



 (none)
Release
Release 2nd



 adiReleaseCall, adiReleaseSecondCall
(none)
adiReleaseCall




 CONNECTED2



 (none)
Release
Release 2nd



 adiReleaseCall, adiReleaseSecondCall
(none)
adiReleaseCall


















Figure 11.	 Inbound, Outbound, and Service Interruption States






Figure 12.	 Inbound, Outbound, Service Interruption, and Call Transfer








 
    (Page 1 of 1 in this chapter)  Version




 




tech_support@nmss.com



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