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

Caller ID with Loop Start

Caller ID with DID or Wink Start

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 Supervised Transfer

2.8.2 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.

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:

• Answering inbound calls

• Placing outbound calls

• Releasing calls

• Blocking calls

• Transferring calls

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 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 (for example, 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 (for example, incoming call response) or acknowledge that an application command is proceeding (for example, 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 (for example, voice detected, modem tones detected).
ADIEVN_CALL_DISCONNECTED	The remote party has disconnected or the telephone network has rejected a placed call (for example, 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 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 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 (for example, 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 (for example, 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 board configuration 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 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:

• Single Message Data Format (SMDF)
  ADI_CALL_STATUS.callingaddr contains the caller's number.

• Multiple Message Data Format (MMDF)
  ADI_CALL_STATUS.callingaddr contains the caller's number, and ADI_CALL_STATUS.callingname contains the caller's name.

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 (for example, 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 (for example, 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 (for example, 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:

• Connect on voice end, which indicates that the remote party stopped speaking.

• Connect on timeout, which indicates that the call progress analysis exceeded the ADI_PLACECALL_PARMS callprog.timeout threshold without generating an event.

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:

• Disconnect on busy, which indicates that a busy signal has been detected.

• Disconnect on reorder, which indicates that a reorder signal has been detected.

• Disconnect on no answer, which indicates that the remote party did not answer.

• Disconnect on SIT, which indicates that a Special Information Tone (SIT) has been detected.

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:

• SIT (Special Information Tone)

• Reorder (fast busy)

• Busy

• Ringing (referred to as "ring tone")

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:

• Pulse width: the time during which a tone is active.

• Inter-pulse delay: the time between two active tone pulses.

• Tone cycle: the time during which a tone is active and then absent.
  
  
  Figure 6. Generic Tone Characteristics

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:

• Busy

• Reorder

• SIT (Special Information Tone)

• CED (generated by fax terminals or modems)

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:

• There is energy below the telephone network tone frequency threshold
  (1 kHz).

• There is little or no energy above the network tone frequency threshold.

• The amplitude and frequency are reasonably steady over the period of time defining the ring tone.

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 (for example, "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 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 (for example, "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 (for example, busy, SIT, reorder, no answer). · The ADI service abandons the call upon occurrence of application-specified criteria (for eample, 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.

• All active operations that use DSP resources are terminated, and their DONE events are generated.

• The ADI service executes the network teardown procedure.

• The ADI service generates an ADIEVN_CALL_RELEASED event.

• When the application processes the event, its internal state is reset to Idle.
  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.

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 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:

• Reject all incoming calls, which behaves as though the application has
  pre-responded to each call with an adiRejectCall (for example, on loop start lines the call is not answered; on wink-start lines reorder tone is played).

• Reverse-make-busy, which takes an active role (if the protocol supports it) and notifies the telephone network by signaling that the line is not receiving any calls.

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:

• Supervised transfer using adiPlaceSecondCall

• Blind transfer using adiTransferCall

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 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 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:

• If the adiTransferCall option is to disconnect on proceeding, the ADI service generates the ADIEVN_CALL_DISCONNECTED event as soon as the second call is dialed. The application must release the call (as described in Section 2.5) before new calls can be established.

• If the adiTransferCall option is to disconnect on alerting and the ADI service receives ring tone from the PBX or switch, the ADIEVN_CALL_DISCONNECTED event is generated and the application must release the call (as described in Section 2.5).

• If the adiTransferCall option is to disconnect when the second call is connected, the ADIEVN_CALL_DISCONNECTED event is generated if ADI service detects that the called party answers (as described in Section 2.4). The application must release the call (as described in Section 2.5).

• If the condition specified in adiTransferCall does not occur, the ADI service generates an ADIEVN_CALL2_DISCONNECTED event. The call control state is returned to Connected for the first line. This might occur, for example, if the second line is busy.

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 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