(Page 5 of 12 in this chapter)

3.4 Establishing Outbound Calls

AG Access can be used to place calls with telephony protocols supporting outbound and bidirectional trunks. After the port's 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 or an ADIEVN_CALL_DISCONNECTED event.
The application chooses the criteria by which AG Access generates the connected and disconnected events. The ADI_PLACECALL_PARMS structure contains the connectmask and disconnectmask parameters that dictate when the connected 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 3.4.2 and Section 3.4.3. Note: If a condition is specified in both masks, connectmask takes precedence. The events controlled by these masks are discussed in Section 3.2.
The general procedure for establishing an outbound call is:

The application invokes adiPlaceCall.

AG Access 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).

The destination address is delivered to the telephone network switch.

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

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

If a telephone network connection is established, AG Access generates an ADIEVN_CALL_CONNECTED 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 5 is a sequence diagram depicting the command and event interchange for placing an outbound call. Informational events are shown with a dashed line. Figure 5. Outbound Call Sequence
Figure 6 is a state diagram for placing outbound calls. This diagram can be correlated with the sequence diagram in Figure 5 to gain a comprehensive understanding of outbound call states and events which are described in the next section. Figure 6. Outbound Call State

3.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 AG Access 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 AG Access when the call is placed with adiPlaceCall.

3.4.2 Connectmask

The ADI_PLACECALL_PARMS connectmask dictates which call progress analysis event causes AG Access to transition from the Placing Call state to the Call Connected state, as shown in Figure 6.
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 (see Section 3.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. (see Section 3.4.7.) ADI_CON_ON_VOICE_LONG Remote voice has lasted longer than the second time threshold. (see Section 3.4.7.) ADI_CON_ON_VOICE_EXTENDED Remote voice has lasted longer than the third time threshold. (see Section 3.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, AG Access generates an ADIEVN_CALL_CONNECTED event. The event's value field indicates the reason for the transition to the Connected state.

Connect Mask Bit	Condition for `ADIEVN_CALL_CONNECTED`
`ADI_CON_ON_RING_QUIT`	Ring tone stopped; no other events detected (see Section 3.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. (see Section 3.4.7.)
`ADI_CON_ON_VOICE_LONG`	Remote voice has lasted longer than the second time threshold. (see Section 3.4.7.)
`ADI_CON_ON_VOICE_EXTENDED`	Remote voice has lasted longer than the third time threshold. (see Section 3.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).

3.4.3 Disconnectmask

The disconnectmask parameter in ADI_PLACECALL_PARMS dictates which call progress analysis events cause AG Access 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 (see Section 3.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 (see Section 3.4.7). ADI_DIS_ON_VOICE_LONG Remote voice has lasted longer than the second threshold (see Section 3.4.7). ADI_DIS_ON_VOICE_EXTENDED Remote voice has lasted longer than the third threshold (see Section 3.4.7). ADI_DIS_ON_VOICE_END Remote party stopped speaking (see Section 3.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. Note that this default disconnect setting can be overridden by the ADI_CON_ON_SIT bit in the connectmask.
The call progress analysis parameters affecting these events are discussed in Section 3.4.4.

Disconnect Mask Bit	Condition for `ADIEVN_CALL_DISCONNECTED`
`ADI_DIS_ON_RING_QUIT`	Ring tone stopped; no other events detected (see Section 3.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 (see Section 3.4.7).
`ADI_DIS_ON_VOICE_LONG`	Remote voice has lasted longer than the second threshold (see Section 3.4.7).
`ADI_DIS_ON_VOICE_EXTENDED`	Remote voice has lasted longer than the third threshold (see Section 3.4.7).
`ADI_DIS_ON_VOICE_END`	Remote party stopped speaking (see Section 3.4.7).
`ADI_DIS_ON_TIMEOUT`	No events occur after the event `ADIEVN_CALL_PROCEEDING`.

3.4.4 Using Telephone Network Tone Detection

When establishing outbound calls, AG Access 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 7: Pulse width, which is the time during which a tone is active. Inter-pulse delay, which is the time between two active tone pulses. Tone cycle, which is the time during which a tone is active and then absent. Figure 7. Generic Tone Characteristics
AG Access uses two types of tone detectors to distinguish tones from voice data: a precise tone detector and a broadband tone detector. These are described in the next two sections.

3.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 tones Reorder tones 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, AG Access takes more time to discern the busy tone using broadband tone detection, as described in Section 3.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 above. Set it to the time required to detect the tone of shortest duration.

3.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 telephone 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 telephone 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 8 illustrates the effect these limits have on the tones. The waveforms depicted are in milliseconds and are representative of tones in the USA. Figure 8. Telephone Network Tone Pulse Width Limits
The time parameters depicted in Figure 8 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: AG Access presumes that maxreorder is less than maxbusy which is less than maxring: maxreorder < maxbusy < maxringThis 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 8 for the respective number of cycles before AG Access 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, AG Access concludes it is receiving a reorder (fast busy) signal.
Figure 9 depicts ring tone termination. After having established that the line is receiving ring tone, the call progress analysis operation concludes that the remote trunk has quit ringing if a ring tone is not received in the maxringperiod period. This parameter controls the ring quit event. Figure 9. Ring Tone Termination

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.

Tone	Parameter	Description
Busy	`busycount`	Busy signal received.
Reorder	`busycount`	Reorder received.
Ring	`ringcount`	Call not answered.

3.4.7 Using Voice Detection

If AG Access passes through the telephone network connected phase without resolution (i.e., did not generate an ADIEVN_CALL_CONNECTED or an ADIEVN_CALL_DISCONNECTED event), call analysis advances into its final stage-voice detection.
AG Access 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, AG Access 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.
AG Access 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 condition" (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 10. Figure 10. Call Progress Analysis Voice Detection

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.

3.4.8 Using Call Placement Timeout

To ensure that call placement is resolved within a certain time period, AG Access provides a timeout parameter. The callprog.timeout parameter in ADI_PLACECALL_PARMS specifies the maximum time after the last detected event before AG Access generates an ADIEVN_CALL_CONNECTED or an ADIEVN_CALL_DISCONNECTED event. By default, AG Access 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.

3.4.9 Outbound Call Parameters

Section 3.4.4 through Section 3.4.8 describe in detail how to use the parameters stored in the ADI_PLACECALL_PARMS and ADI_CALLPROG_PARMS structures to control outbound call placement. For more details about the parameters stored in these structures, see the AG Access Function Reference Manual.
Additional parameters that govern outbound call establishment may be specific to the telephony protocol running on the given port. Refer to the documentation for the telephony protocol that your application is using for more detailed information. The telephony protocols that are included with AG Access are documented in the AG Access Function Reference Manual.

3.4.10 Outbound Call Events

The following table summarizes the AG Access events which are generated when establishing outbound calls: AG Access Event Description ADIEVN_CALL_CONNECTED Changes the port into 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). - AG Access 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 AG Access 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, AG Access 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.

AG Access Event	Description
`ADIEVN_CALL_CONNECTED`	Changes the port into 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). - AG Access 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 AG Access 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, AG Access 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.

(Page 5 of 12 in this chapter)

tech_support@nmss.com