Call analysis consists of both pre-connect and post-connect information about the progress of the call. Pre-connect call progress determines the status of the call connection, that is, busy, no dial tone, no ringback, etc. Post-connect call analysis, which is also known as media type detection, determines the destination party's media type, that is, answering machine, fax, voice, etc.
The following sections discuss:
3.2.1. Call Analysis with DM3 BoardsThere are two methods available for call analysis when using DM3 boards: the Global Call method and the dx_dial( ) method.
The Global Call media detection method is especially useful for performing post-connect call analysis. When activated by setting the GCPR_MEDIADETECT parameter to GCPV_ENABLE for a particular channel, post-connect call analysis is performed as part of the gc_MakeCall( ) function's operation. The gc_MakeCall( ) function is used to place a call; the signal detector analyzes the incoming signals to perform call progress analysis.
After the normal gc_MakeCall( ) processing finishes and GCEV_CONNECTED event is sent, call analysis runs and generates a GCEV_MEDIADETECTED event that tells the application the result of the analysis (for example, FAX, PVD, or PAMD is detected).
The outcome of the analysis determines the events generated and the action that can be taken as follows:
GCPR_MEDIADETECT and GCPR_CALLPROGRESS parameter settings for gc_SetParm( ) actually allow the application to specify whether pre- or post-connect call analysis or both should be activated. This method for achieving this is shown in Table 2.
Table 2. Global Call Call Progress Settings
GCPR_CALLPROGRESS=GCPV_DISABLE |
GCPR_CALLPROGRESS=GCPV_ENABLE (default) | |
GCPR_MEDIADETECT=GCPV_DISABLE (default) |
No call progress |
Pre-connect call progress only |
GCPR_MEDIADETECT=GCPV_ENABLE |
No call progress |
Full call progress |
As can be seen in this table, the default behavior (GCPR_MEDIADETECT = GCPV_DISABLE) disables media detection but actually activates pre-connect call progress for CAS protocols. To enable full call progress analysis, set the GCPR_MEDIADETECT parameter to GCPV_ENABLE for the respective channel.
The GCPR_CALLPROGRESS parameter can be used to enable or disable pre-connect call progress. When combined with GCPR_MEDIADETECT, this allows the application to specify whether to use pre-connect call progress only or full call progress. If GCPR_CALLPROGRESS = GCPV_DISABLE, there will be no call progress at all, regardless of the setting of GCPR_MEDIADETECT.
Table 3 explains call analysis support via the Global Call interface. The table applies to DM3 CAS protocols with flexible routing clusters, provided that a voice device is attached to the network device. The table also applies to any fixed routing configuration regardless of the protocol. Check on a protocol-by-protocol basis, as some might not support call analysis at all.
Table 3. Call Analysis Support on DM3 Boards with CAS
Note that the call analysis time-out parameters values apply, and they are configurable by the user. (They cannot be changed at runtime.) The parameters are CaSignalTimeout, CaAnswerTimeout, and CaPvdTimeout; their values are found in the CHP section of the configuration (.config) file. However, they apply only to post-connect call analysis and are not used until the call moves from an initiated to a Proceeding, Alerting, or Connected state.
Another option for call analysis is provided by the voice API, which provides post-connect call analysis on DM3 boards through the dx_dial( ) function. Note that the Global Call method and the dx_dial( ) method are mutually exclusive, so you must choose one or the other.
3.2.2. Call Analysis with Springware BoardsThe gc_GetCallInfo( ) function is used immediately following the receipt of a GCEV_CONNECTED event to retrieve this post-connect information notifying of the media type of the answering party. See the Global Call API Library Reference for more information.
Call analysis tones such as dial tone, ringback, busy, and fax are defined either in the firmware (Global Tone Detection and Global Tone Generation), or in the country dependent parameters (.cdp) file, or a combination of both. Tones defined in the firmware can be enabled or disabled by configuring parameters in the DX_CAP (call analysis parameter) data structure. Similarly, the DX_CAP data structure can be used to configure the voice detection algorithm that distinguishes answering machine or human speech. The default parameter values defined in the DX_CAP data structure can be changed by the gc_LoadDxParm( ) function to fit the needs of your application. For a detailed description of enhanced call analysis (PerfectCall) and how to use call analysis, see the Voice API Programming Guide for your operating system. For a detailed description of the gc_LoadDxParm( ) function, see the Global Call API Library Reference.
Some example uses of call progress tones are as follows:
3.2.3. Call Analysis Functionality for PDK ProtocolsPDK protocols configure default call analysis operation through the use of two Protocol Service Layer (PSL) parameters in the protocol .cdp file (the parameter names are different for DM3 and Springware boards):
When call progress or media detection support PSL parameters are specified as pass-through values in the .cdp file, the application is permitted to define call analysis settings, for example via gc_MakeCall( ) when using Global Call. More specifically:
On Springware boards, PDK protocols support call analysis via the gc_MakeCall( ) function, which uses the flags parameter in the PDK_MAKECALL_BLK structure to determine if call progress and/or media type detection are enabled on a per call basis. The two flags are NO_CALL_PROGRESS and MEDIA_TYPE. The default values are such that call progress is enabled and media type detection is disabled, but the bits in the flags parameter can be changed to enable/disable call progress and/or media type detection as required. If this method is used for media detection, the application must receive a GCEV_CONNECTED event before the gc_GetCallInfo( ) function can be used to get information about the type of connection. Even after the GCEV_CONNECTED event is received, the call information may not be available. Consequently, the application may need to poll for the information.
On DM3 and Springware boards, PDK protocols also support a more preferred method of call progress configuration using the gc_SetParm( ) function. The parameters used to specify call progress in this case are GCPR_MEDIADETECT (DM3 only) and GCPR_CALLPROGRESS (see Table 2. Global Call Call Progress Settings). When this method is used to enable media type detection, a GCEV_MEDIADETECTED event is returned to the application on media type detection so that the gc_GetCallInfo( ) function can be used immediately to get information about the type of connection, that is, the application does not have to wait for a GCEV_CONNECTED event.
When the gc_GetCallInfo( ) function is used to retrieve information about the detected media type, the info_id parameter to the gc_GetCallInfo( ) function must be CONNECT_TYPE. See the gc_GetCallInfo( ) function description for a list of the values that may be returned when the info_id parameter is CONNECT_TYPE.
Whether a positive media detection result is sufficient to signal a call state change to the CONNECTED state is dependent upon the specific PDK protocol. For example, in PDK protocols where CAS signaling is required for identifying a connection, a signaling bit change must be received before signaling a CONNECTED call state change. For increased flexibility, a separate .cdp file parameter, CDP_Connect_Upon_Media, may be defined in the associated parameter file and used inside the protocol to enable the protocol to perform a call state change to the Connected state immediately upon positive media detection. This parameter is mostly of interest to T-1 protocols.
On Springware boards, call analysis and progress tones are mapped to US specified tones by default. PDK protocols also permit call analysis and progress tones to be customized for non-US defaults via PSL_TONE_CP_xxx (where xxx is the call analysis tone type, that is BUSY, RINGBACK, etc.) parameters as specified in the protocol .cdp file.
The format of a tone definition in the .cdp file is as follows:
ALL TONE_t TONE_<NAME> = Frequency_1, Frequency_1_Deviation, Frequency_2, Frequency_2_Deviation, Amplitude_1, Amplitude_2, OnTime, OnTime_Deviation, OffTime, OffTime_Deviation, Mode, Repeat Count
There are two basic types of tone detection for both single and dual tones: edge detection and cadence detection.
Tone detection using the edge detection algorithm provides notification either when the energy in the specified frequency band(s) exceeds the threshold (leading-edge detection) or no longer exceeds the threshold (trailing-edge detection). Edge detection is identified by assigning a value of zero (0) to the On Time parameter. See Table 4 below.
Tone detection using the cadence detection algorithm provides notification when the energy in the specified frequency band(s) exceeds threshold and meets the timing requirements of the specified ring cadence. Cadence detection, like edge detection, can provide notification either when the cadence completes the specified number of cycles (Repeat Count parameter) or when the cadence ceases after ringing the specified number of cycles. Cadence detection is identified by assigning a non-zero value to the On Time parameter.
Another tone detection feature is the ability to debounce the leading edge of the tone. Rather than notifying the protocol immediately when the leading edge of the tone is detected, the protocol can specify to wait for a period of time (debounce time) before the tone signal is delivered to the protocol, that is, debouncing. This type of tone detection can be specified in the tone template as:
The meaning of each argument of a tone definition is explained in Table 4.
Table 4. TONE_t Signal Definition Parameters
Parameter Number |
Name |
Description |
Detect/ |
Edge/ |
1 |
Frequency 1 |
Frequency of first tone (in Hz) |
Detect, Generate |
Edge, Cadence |
2 |
Frequency 1 Deviation |
Frequency deviation for first tone (in Hz) Note: The minimum recommended value for this parameter is 50. |
Detect |
Edge, Cadence |
3 |
Frequency 2 |
Frequency of second tone (in Hz) |
Detect, Generate |
Edge, Cadence |
4 |
Frequency 2 Deviation |
Frequency deviation for second tone (in Hz) Note: The minimum recommended value for this parameter is 50. |
Detect |
Edge, Cadence |
5 |
Amplitude 1 |
Amplitude of first tone (in dB) |
Generate |
Neither |
6 |
Amplitude 2 |
Amplitude of second tone (in dB) |
Generate |
Neither |
7 |
On Time |
On duration (in milliseconds) Note: The minimum recommended value is 50. |
Detect, Generate |
Cadence |
8 |
On Time Deviation |
On time deviation (in milliseconds) Note: The minimum recommended value is 50. |
Detect |
Cadence |
9 |
Off Time |
Off duration (in milliseconds) Note: The minimum recommended value is 50. |
Detect, Generate |
Cadence |
10 |
Off Time Deviation |
Off time deviation (in milliseconds) Note: The minimum recommended value is 50. |
Detect |
Cadence |
11 |
Mode |
Detection notification:
|
Detect |
Edge, Cadence |
12 |
Repeat Count |
Repetition count (the number of repetitions on cycles) |
Detect, Generate |
Cadence |
If TONE_x is previously defined, TONE_y may be set equal to TONE_x in the following manner:
ALL TONE_t TONE_y = TONE_x
The following are examples of tone declarations in a .cdp file:
1 for the onset of the tone. This specifies leading edge in edge detection mode and onset of cadence detection in cadence detection mode.
/*
This defines the ringback tone. The currently defined tone is a
tone (440Hz+480Hz) on for 0.25 secs and off for 0.25 secs and a
ring count of 1
*/
R4 TONE_t TONE_RINGBACK = 440,0,480,0,0,0,250,0,250,0,0,1
/*
This identifies the KP tone for ANI.
*/
R4 TONE_t TONE_ANI_KP = 1100,0,1700,0,0,0,100,0,0,0,0,1
3.2.4. Call Analysis Functionality for ICAPI ProtocolsGlobal Call call analysis uses GTD and timers. Some of the country dependent parameters (.cdp) files define tone templates for recognition of call progress tones. The tone IDs defined match the protocol parameter numbers (for example, parameter $103 creates tone ID # 103). See the Voice API Programming Guide for your operating system for information about working with and building tone templates.
Parameter $1, $6, or $13 in the .cdp file defines the maximum time (in seconds) for a call to be answered. Within that interval, a busy tone and ringback tone can be detected. If the timer expires, the GCEV_DISCONNECTED event is reported to the application.
Two separate busy tones can be defined to accommodate two different call progress failure tones (that is, busy and out-of-order). Busy tones are defined in parameters $103 and $104 using the following format:
$103: - <frequency 1> <deviation> <frequency 2> <deviation>
%01: - <on time> <on deviation> <off time> <off deviation>
%02: - <number of cycles before detect>
Frequency is expressed in Hz; time duration is expressed in 10 ms units; unspecified values are set to 0. The deviation value for frequency 1 or 2 specifies the allowable variation in Hz. The %01 parameter relates to cadence detection. Cadence detection analyzes the audio signal on the line to detect a repeating pattern of sound (on time) and silence (off time). The deviation value for cadence detection is the allowable variation in 10 ms units. The %02 parameter specifies the number of times that the cadence on/off pattern must be detected before classifying the tone detected.
To comment out a tone template, insert a ";" (semicolon) as the first character in all three lines of the definition. If either of the busy tones is detected, the GCEV_DISCONNECTED event is reported to the application.
A ringback tone is defined in parameter $105 using the format defined above. The maximum allowable time between successive rings is defined in parameter $3 in 10 ms units. ICAPI starts a timer after receiving a ringback TONEOFF event. Typically, Connect is indicated by line signaling. However, if the network cannot indicate a Connect via line signaling, then Connect can be indicated if the next TONEON event does not arrive before the ICAPI timer expires.
To disable Connect detection, set parameter $3 to 0. Global Call will still be able to count the rings and report the GCEV_DISCONNECTED event if the maximum number of rings is reached. The maximum number of rings is set in parameter $1.
The ringback tone heard on any specific call depends on the specific CO that is serving the called party, not the local CO. If the ringback tone is not known, the recommendation is to remove this tone from the country dependent parameters (.cdp) file.
Only the call progress tone definitions in the .cdp file are used by the Global Call API. The R1 and R2 tone definitions are used only if you disable R2 MF support in the icapi.cfg file by setting the $17 parameter to 1.
The following are examples of the definitions of busy tones $103 and $104 and ringback tone $105 in the .cdp file:
****************************** * TID # 103 BUSY * ****************************** $103 BUSY : 450 35 %01 cadence : 50 10 50 10 %02 cycle : 2 ****************************** * TID # 104 SBUSY * ****************************** $104 SBUSY :450 35 %01 cadence : 25 5 25 5 %02 cycle : 3 ****************************** * TND # 105 RINGBACK * ****************************** $105 RINGBACK : 450 35 %01 cadence : 80
See the Voice API Programming Guide for your operating system for information about using cadence, cadence detection, and tone definitions for determining the progress of outbound calls.
In addition, the following outbound parameters in the .cdp file may need to be modified when using these call progress tones:
After the .cdp file is modified as described above, whenever one of the defined conditions is detected on a channel, the gc_MakeCall( ) function is terminated with a busy, no answer, or time-out result/error value.
For some ICAPI protocols, certain parameters must be set in the .cdp file to ensure proper operation of the protocol. Refer to the Global Call Country Dependent Parameters (CDP) Reference for country dependent parameters that are most likely to be modified and for any required settings.
Click here to contact Telecom Support Resources
Copyright 2002, Intel Corporation