# Managing call progress

Call progress functions monitor in-band energy to detect network tones, voice, and modem or fax terminal tones. Call progress functions enable you to manage low-level call control directly. Call progress is affected by the parameters stored in the ADI_CALLPROG_PARMS structure.

This topic presents:

- Tone detection

- Call progress tone events

- Call progress voice events

- Call progress termination events

- System restrictions

## Tone detection

Call progress functions are automatically invoked when nccPlaceCall is specified and turned off when the call reaches a connected state. Once the call is in a connected state, an application can invoke call progress functions and analyze in-band energy as described in the following topics.

### Telephone network tone detection

The call progress functions analyze in-band audio to detect the following telephone network signals:

- SIT (special information tone)

- Reorder (fast busy)

- Busy

- Ringing (referred to as ring tone)

- Number unassigned tone

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

The following terms are used to characterize telephone network tones:

Term | Description
Pulse width | Time during which a tone is active.
Inter-pulse delay | Time between two active tone pulses.
Tone cycle | Time during which a tone is active and then absent.

The following illustration shows generic tone characteristics:

The ADI service uses a precise tone detector and a broadband tone detector to distinguish tones from voice data.

### Precise tone detection

The precise tone detector analyzes in-band audio at specific frequencies to detect the following types of tones:

- Busy

- Reorder

- SIT (special information tone)

- CED (generated by fax terminals or modems)

- TDD/TTY (generated by devices for the hearing impaired)

- Number unassigned

The application specifies which of these tones to detect by configuring the precmask in ADI_CALLPROG_PARMS. If the busy tone detection is not enabled, the ADI service takes more time to discern the busy tone using broadband tone detection. 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 topic. Set it to the time required to detect the tone of shortest duration.

### 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: time period and cadence.

When defining time period, the application specifies time limits for excluding each telephone network tone. The following illustration shows the effect these limits have on the tones. The waveforms depicted are in milliseconds and are representative of tones in the USA.

The time parameters shown in the previous illustration are stored in ADI_CALLPROG_PARMS.

Note: The ADI service presumes that maxreorder is less than maxbusy, and maxbusy is less than maxring. This relationship defines a time tolerance (minimum and maximum) for each of the three tones detected.

The second characteristic used for broadband tone detection is the signal's cadence. The application specifies tone counts in ADI_CALLPROG_PARMS. The signal must satisfy the single tone criteria described in the following illustration 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.

The following illustration depicts ring tone termination. After having established that the line is receiving a 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.

### Voice detection

If the ADI service does not detect a network tone, call analysis advances into the final stage of 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.

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. 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, the application expects a voice to begin speaking with a short salutation (for example, Hello). The voice medium time threshold should be set accordingly.

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

Voice condition | Description | Controlling parameter in callprog in ADI_CALLPROG_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. The following illustration shows call progress analysis voice detection:

### Using call placement timeout

To ensure that call placement is resolved within a certain time period, the ADI service provides a timeout parameter. The timeout parameter in ADI_CALLPROG_PARMS specifies the maximum time after the last detected event before the ADI service generates ADIEVN_CP_DONE with a value of CTA_REASON_TIMEOUT. Setting the timeout parameter in ADI_CALLPROG_PARMS to zero overrides the timeout feature.

## Call progress tone events

The call progress tone events are mapped from tone events described in:

- Telephone network tone detection

- Precise tone detection

- Broadband tone detection

Call progress tone events are controlled by the ADI_CALLPROG_PARMS structure. The following tones are detected by call progress:

If the detected tone is... | The ADI event is...
--- | ---
Dial tone | ADIEVN_CP_DIALTONE
Reorder tone | ADIEVN_CP_REORDERTONE
Ring tone | ADIEVN_CP_RINGTONE
Ring quit | ADIEVN_CP_RINGQUIT
SIT | ADIEVN_CP_SIT
Fax/modem answer tone | ADIEVN_CP_CED
TDD/TTY tone | ADIEVN_CP_TDD

## Call progress voice events

The call progress voice events are mapped from the voice events described in Voice detection and are controlled by the ADI_CALLPROG_PARMS structure.

Whenever a voice event occurs during call progress, ADIEVN_CP_VOICE is generated. The event value field contains the voice event:

If the remote party... | The ADI event reason is...
--- | ---
Begins speaking (voice begin) | ADI_CP_VOICE_BEGIN
Has spoken for a period longer than the first time threshold (voice medium) | ADI_CP_VOICE_MEDIUM
Has spoken for a period longer than the second time threshold (voice long) | ADI_CP_VOICE_LONG
Has spoken for a period longer than the third time threshold (voice extended) | ADI_CP_VOICE_EXTENDED
Stopped speaking (voice end) | ADI_CP_VOICE_END

## Call progress termination events

Call progress terminates when any of the following events occur:

If... | The ADI event is...
--- | ---
A dial tone is detected | ADIEVN_CP_DIALTONE
A busy tone is detected | ADIEVN_CP_BUSYTONE
A reorder tone is detected | ADIEVN_CP_REORDERTONE
A SIT tone is detected | ADIEVN_CP_SIT
There is no answer | ADIEVN_CP_NOANSWER
A fax or modem answer tone is detected | ADIEVN_CP_CED
A TDD/TTY device tone is detected | ADIEVN_CP_TDD

Additionally, you can configure the stopmask parameter in the ADI_CALLPROG_PARMS structure to selectively terminate on the occurrence of any of the following telephone network events:

Telephone network event | ADI event
A ring tone is detected. | ADIEVN_CP_RINGTONE
There is a loss of ring tone with no subsequent events. | ADIEVN_CP_RINGQUIT
Remote party begins speaking (voice begin). Check the value field of the event for the voice event. | ADIEVN_CP_VOICE, with ADIEVN_CP_VOICE_BEGIN in the value field
Remote party has spoken for a period longer than the first time threshold (voice medium). Check the value field of the event for the voice event. | ADIEVN_CP_VOICE, with ADIEVN_CP_VOICE_MEDIUM in the value field
Remote party has spoken for a period longer than the second time threshold (voice long). Check the value field of the event for the voice event. | ADIEVN_CP_VOICE, with ADIEVN_CP_VOICE_LONG in the value field
Remote party has spoken for a period longer than the third time threshold (voice extended). Check the value field of the event for the voice event. | ADIEVN_CP_VOICE, with ADIEVN_CP_VOICE_EXTENDED in the value field
Remote party stopped speaking (voice end). Check the value field of the event for the voice event. | ADIEVN_CP_VOICE, with ADIEVN_CP_VOICE_END in the value field

When call progress terminates, ADIEVN_CP_DONE is generated.

## System restrictions

When using the NOCC protocol, call progress functions can be run at any time. With all other protocols, call progress is under the control of the protocol until the call enters the connected state. Once the call is in the connected state, the application can run call progress functions.