TBwiki - User contributions [en]

AudioMixers

2012-08-23T15:30:05Z

Alexandre Lussier: /* TMedia conference capacity */

== Toolpack audio mixers ==
A mixer is used to mix the audio of multiple sources (call legs, playing audio file, tone generator...)

=== Typical usage of audio mixers ===
Audio mixers can be used, among other things, to:
* Build conferences
* Insert background music to a conversation
* Record both sides of the conversation into a single recorded file.

=== Joining audio source to a mixer ===
There are 2 ways to join a mixer:
* Join as a listener only
* Join as a speaker. Speakers can be active / or inactive (inactive speakers are not mixed, but monitored for voice activity)

[[File:mixer_internal.png|504px]]

=== Maximum call legs per mixer ===
The mixer has the following capabilities:
* The mixer can have any number of listeners (up to maximum number of call legs supported by the TMedia system)
* The mixer can have any number of speakers (up to maximum number of call legs supported by the TMedia system)
** Among these speakers, up to 10 will be considered as "active" (the 10 from which voice was received the most recently)
** Among these 10 active speakers, the audio from dominant N speakers will be mixed (N can be configured per mixer)

=== Resource usage of mixers ===
* An active speaker uses one mixer slot (up to 10 per conference)
* All non-active speakers use one mixer slot (although there is no per-conference limit)
* All listeners ''share'' the same mixer slot
* IVR on the mixer (playing file, recording file) use one mixer slot. It is possible to record and play at the same time, but the recording does not contain what is played on the mixer
:* It is possible to have a recording that contains what is played on the mixer, but it uses one more mixer slot (total of 2 slots)

=== TMedia conference capacity ===
In order to use conferences, TMedia must be equipped with DSPs.
Each TMG3200 or TMG7800 unit can be equipped with DSPs for 1,824 conference "slots" (thus a total of 29,184 for TMG7800 system).
If mixers need to be joined with call legs from different adapters, a TMS switch is needed.

 Here are capacity results, depending of conference type: 

- 3 call legs in a conference and no play/record:
:608 conferences and 1,824 "slots" 

- 2 call legs in a conference and play/record activated:
:680 conferences and 2,040 "slots" 
- 1 call leg in a conference and play and record activated (can record what is played):
:680 conferences and 2,040 "slots" 
- 11 call legs in a conference and play/record activated:
:168 conferences and 2,016 "slots" 
- 12 call legs in a conference and no play/record:
:160 conferences and 1,920 "slots"

AudioMixers

2012-08-23T15:29:04Z

Alexandre Lussier: /* TMedia conference capacity */

== Toolpack audio mixers ==
A mixer is used to mix the audio of multiple sources (call legs, playing audio file, tone generator...)

=== Typical usage of audio mixers ===
Audio mixers can be used, among other things, to:
* Build conferences
* Insert background music to a conversation
* Record both sides of the conversation into a single recorded file.

=== Joining audio source to a mixer ===
There are 2 ways to join a mixer:
* Join as a listener only
* Join as a speaker. Speakers can be active / or inactive (inactive speakers are not mixed, but monitored for voice activity)

[[File:mixer_internal.png|504px]]

=== Maximum call legs per mixer ===
The mixer has the following capabilities:
* The mixer can have any number of listeners (up to maximum number of call legs supported by the TMedia system)
* The mixer can have any number of speakers (up to maximum number of call legs supported by the TMedia system)
** Among these speakers, up to 10 will be considered as "active" (the 10 from which voice was received the most recently)
** Among these 10 active speakers, the audio from dominant N speakers will be mixed (N can be configured per mixer)

=== Resource usage of mixers ===
* An active speaker uses one mixer slot (up to 10 per conference)
* All non-active speakers use one mixer slot (although there is no per-conference limit)
* All listeners ''share'' the same mixer slot
* IVR on the mixer (playing file, recording file) use one mixer slot. It is possible to record and play at the same time, but the recording does not contain what is played on the mixer
:* It is possible to have a recording that contains what is played on the mixer, but it uses one more mixer slot (total of 2 slots)

=== TMedia conference capacity ===
In order to use conferences, TMedia must be equipped with DSPs.
Each TMG3200 or TMG7800 unit can be equipped with DSPs for 1,824 conference "slots" (thus a total of 29,184 for TMG7800 system).
If mixers need to be joined with call legs from different adapters, a TMS switch is needed.

 Here are capacity results, depending of conference type: 

- 3 call legs in a conference and no play/record:
:608 conferences and 1,824 "slots" 

- 2 call legs in a conference and play/record activated:
:680 conferences and 2,040 "slots" 
- 1 call leg in a conference and play and record activated (can record what is played):
:680 conferences and 2,040 "slots" 
- 11 call legs in a conference and play/record activated:
:168 conferences and 2,016 "slots" 
- 12 call legs in a conference and no play/record:
:160 conferences and 1,920 "slots" 


 Here is an example on how to calculate number of conferences and "slots" with the Dsp Wizard. This example also show you the options that are set on each type of "slots" (Stream: IVR, TDM: Call leg). 
[[File:DspWizard.JPG|504px]]

AudioMixers

2012-08-20T16:00:32Z

Alexandre Lussier: /* TMedia conference capacity */

== Toolpack audio mixers ==
A mixer is used to mix the audio of multiple sources (call legs, playing audio file, tone generator...)

=== Typical usage of audio mixers ===
Audio mixers can be used, among other things, to:
* Build conferences
* Insert background music to a conversation
* Record both sides of the conversation into a single recorded file.

=== Joining audio source to a mixer ===
There are 2 ways to join a mixer:
* Join as a listener only
* Join as a speaker. Speakers can be active / or inactive (inactive speakers are not mixed, but monitored for voice activity)

[[File:mixer_internal.png|504px]]

=== Maximum call legs per mixer ===
The mixer has the following capabilities:
* The mixer can have any number of listeners (up to maximum number of call legs supported by the TMedia system)
* The mixer can have any number of speakers (up to maximum number of call legs supported by the TMedia system)
** Among these speakers, up to 10 will be considered as "active" (the 10 from which voice was received the most recently)
** Among these 10 active speakers, the audio from dominant N speakers will be mixed (N can be configured per mixer)

=== Resource usage of mixers ===
* An active speaker uses one mixer slot (up to 10 per conference)
* All non-active speakers use one mixer slot (although there is no per-conference limit)
* All listeners ''share'' the same mixer slot
* IVR on the mixer (playing file, recording file) use one mixer slot. It is possible to record and play at the same time, but the recording does not contain what is played on the mixer
:* It is possible to have a recording that contains what is played on the mixer, but it uses one more mixer slot (total of 2 slots)

=== TMedia conference capacity ===
In order to use conferences, TMedia must be equipped with DSPs.
Each TMG3200 or TMG7800 unit can be equipped with DSPs for 1,824 conference "slots" (thus a total of 29,184 for TMG7800 system).
If mixers need to be joined with call legs from different adapters, a TMS switch is needed.

 Here are capacity results, depending of conference type: 

- 3 call legs in a conference and no play/record:
:608 conferences and 1,824 "slots" 

- 2 call legs in a conference and play/record activated:
:680 conferences and 2,040 "slots" 
- 1 call leg in a conference and play and record activated (can record what is played):
:680 conferences and 2,040 "slots" 
- 11 call legs in a conference and play/record activated:
:168 conferences and 2,016 "slots" 
- 12 call legs in a conference and no play/record:
:160 conferences and 1,920 "slots" 

 Here is an example on how to calculate number of conferences and "slots" with the Dsp Wizard. This example also show you the options that are set on each type of "slots" (Stream: IVR, TDM: Call leg). 
[[File:DspWizard.JPG|504px]]

AudioMixers

2012-08-20T16:00:19Z

Alexandre Lussier:

== Toolpack audio mixers ==
A mixer is used to mix the audio of multiple sources (call legs, playing audio file, tone generator...)

=== Typical usage of audio mixers ===
Audio mixers can be used, among other things, to:
* Build conferences
* Insert background music to a conversation
* Record both sides of the conversation into a single recorded file.

=== Joining audio source to a mixer ===
There are 2 ways to join a mixer:
* Join as a listener only
* Join as a speaker. Speakers can be active / or inactive (inactive speakers are not mixed, but monitored for voice activity)

[[File:mixer_internal.png|504px]]

=== Maximum call legs per mixer ===
The mixer has the following capabilities:
* The mixer can have any number of listeners (up to maximum number of call legs supported by the TMedia system)
* The mixer can have any number of speakers (up to maximum number of call legs supported by the TMedia system)
** Among these speakers, up to 10 will be considered as "active" (the 10 from which voice was received the most recently)
** Among these 10 active speakers, the audio from dominant N speakers will be mixed (N can be configured per mixer)

=== Resource usage of mixers ===
* An active speaker uses one mixer slot (up to 10 per conference)
* All non-active speakers use one mixer slot (although there is no per-conference limit)
* All listeners ''share'' the same mixer slot
* IVR on the mixer (playing file, recording file) use one mixer slot. It is possible to record and play at the same time, but the recording does not contain what is played on the mixer
:* It is possible to have a recording that contains what is played on the mixer, but it uses one more mixer slot (total of 2 slots)

=== TMedia conference capacity ===
In order to use conferences, TMedia must be equipped with DSPs.
Each TMG3200 or TMG7800 unit can be equipped with DSPs for 1,824 conference "slots" (thus a total of 29,184 for TMG7800 system).
If mixers need to be joined with call legs from different adapters, a TMS switch is needed.

 Here are capacity results, depending of conference type: 

- 3 call legs in a conference and no play/record:
:608 conferences and 1,824 "slots" 

- 2 call legs in a conference and play/record activated:
:680 conferences and 2,040 "slots" 
- 1 call leg in a conference and play and record activated (can record what is played):
:680 conferences and 2,040 "slots" 
- 11 call legs in a conference and play/record activated:
:168 conferences and 2,016 "slots" 
- 12 call legs in a conference and no play/record:
:160 conferences and 1,920 "slots" 

 Here is an example on how to calculate number of conferences and "slots" with the Dsp Wizard. This example also show you the options that are set on each type of "slots" (Stream: IVR, TDM: Call leg).
[[File:DspWizard.JPG|504px]]

File:DspWizard.JPG

2012-08-20T15:59:14Z

Alexandre Lussier: An example of use of the Dsp Wizard

An example of use of the Dsp Wizard

AudioMixers

2012-08-20T15:57:55Z

Alexandre Lussier: /* TMedia conference capacity */

== Toolpack audio mixers ==
A mixer is used to mix the audio of multiple sources (call legs, playing audio file, tone generator...)

=== Typical usage of audio mixers ===
Audio mixers can be used, among other things, to:
* Build conferences
* Insert background music to a conversation
* Record both sides of the conversation into a single recorded file.

=== Joining audio source to a mixer ===
There are 2 ways to join a mixer:
* Join as a listener only
* Join as a speaker. Speakers can be active / or inactive (inactive speakers are not mixed, but monitored for voice activity)

[[File:mixer_internal.png|504px]]

=== Maximum call legs per mixer ===
The mixer has the following capabilities:
* The mixer can have any number of listeners (up to maximum number of call legs supported by the TMedia system)
* The mixer can have any number of speakers (up to maximum number of call legs supported by the TMedia system)
** Among these speakers, up to 10 will be considered as "active" (the 10 from which voice was received the most recently)
** Among these 10 active speakers, the audio from dominant N speakers will be mixed (N can be configured per mixer)

=== Resource usage of mixers ===
* An active speaker uses one mixer slot (up to 10 per conference)
* All non-active speakers use one mixer slot (although there is no per-conference limit)
* All listeners ''share'' the same mixer slot
* IVR on the mixer (playing file, recording file) use one mixer slot. It is possible to record and play at the same time, but the recording does not contain what is played on the mixer
:* It is possible to have a recording that contains what is played on the mixer, but it uses one more mixer slot (total of 2 slots)

=== TMedia conference capacity ===
In order to use conferences, TMedia must be equipped with DSPs.
Each TMG3200 or TMG7800 unit can be equipped with DSPs for 1,824 conference "slots" (thus a total of 29,184 for TMG7800 system).
If mixers need to be joined with call legs from different adapters, a TMS switch is needed.

 Here are capacity results, depending of conference type: 

- 3 call legs in a conference and no play/record:
:608 conferences and 1,824 "slots" 

- 2 call legs in a conference and play/record activated:
:680 conferences and 2,040 "slots" 
- 1 call leg in a conference and play and record activated (can record what is played):
:680 conferences and 2,040 "slots" 
- 11 call legs in a conference and play/record activated:
:168 conferences and 2,016 "slots" 
- 12 call legs in a conference and no play/record:
:160 conferences and 1,920 "slots" 

 Here is an example on how to calculate number of conferences and "slots" with the Dsp Wizard. This example also show you the options that are set on each type of "slots" (Stream: IVR, TDM: Call leg).

AudioMixers

2012-08-20T15:23:58Z

Alexandre Lussier: /* TMedia conference capacity */

AudioMixers

2012-08-20T15:22:55Z

Alexandre Lussier: /* TMedia conference capacity */

== Toolpack audio mixers ==
A mixer is used to mix the audio of multiple sources (call legs, playing audio file, tone generator...)

=== Typical usage of audio mixers ===
Audio mixers can be used, among other things, to:
* Build conferences
* Insert background music to a conversation
* Record both sides of the conversation into a single recorded file.

=== Joining audio source to a mixer ===
There are 2 ways to join a mixer:
* Join as a listener only
* Join as a speaker. Speakers can be active / or inactive (inactive speakers are not mixed, but monitored for voice activity)

[[File:mixer_internal.png|504px]]

=== Maximum call legs per mixer ===
The mixer has the following capabilities:
* The mixer can have any number of listeners (up to maximum number of call legs supported by the TMedia system)
* The mixer can have any number of speakers (up to maximum number of call legs supported by the TMedia system)
** Among these speakers, up to 10 will be considered as "active" (the 10 from which voice was received the most recently)
** Among these 10 active speakers, the audio from dominant N speakers will be mixed (N can be configured per mixer)

=== Resource usage of mixers ===
* An active speaker uses one mixer slot (up to 10 per conference)
* All non-active speakers use one mixer slot (although there is no per-conference limit)
* All listeners ''share'' the same mixer slot
* IVR on the mixer (playing file, recording file) use one mixer slot. It is possible to record and play at the same time, but the recording does not contain what is played on the mixer
:* It is possible to have a recording that contains what is played on the mixer, but it uses one more mixer slot (total of 2 slots)

=== TMedia conference capacity ===
In order to use conferences, TMedia must be equipped with DSPs.
Each TMG3200 or TMG7800 unit can be equipped with DSPs for 1,824 conference "slots" (thus a total of 29,184 for TMG7800 system).
If mixers need to be joined with call legs from different adapters, a TMS switch is needed.

 Here are capacity results, depending of conference type: 

- 3 call legs in a conference and no play/record: 608 conferences and 1,824 "slots" 
- 2 call legs in a conference and play/record activated: 680 conferences and 2,040 "slots" 
- 1 call leg in a conference and play and record activated (can record what is played): 680 conferences and 2,040 "slots" 
- 11 call legs in a conference and play/record activated: 168 conferences and 2,016 "slots" 
- 12 call legs in a conference and no play/record: 160 conferences and 1,920 "slots"

AudioMixers

2012-08-20T15:22:41Z

Alexandre Lussier: /* TMedia conference capacity */

== Toolpack audio mixers ==
A mixer is used to mix the audio of multiple sources (call legs, playing audio file, tone generator...)

=== Typical usage of audio mixers ===
Audio mixers can be used, among other things, to:
* Build conferences
* Insert background music to a conversation
* Record both sides of the conversation into a single recorded file.

=== Joining audio source to a mixer ===
There are 2 ways to join a mixer:
* Join as a listener only
* Join as a speaker. Speakers can be active / or inactive (inactive speakers are not mixed, but monitored for voice activity)

[[File:mixer_internal.png|504px]]

=== Maximum call legs per mixer ===
The mixer has the following capabilities:
* The mixer can have any number of listeners (up to maximum number of call legs supported by the TMedia system)
* The mixer can have any number of speakers (up to maximum number of call legs supported by the TMedia system)
** Among these speakers, up to 10 will be considered as "active" (the 10 from which voice was received the most recently)
** Among these 10 active speakers, the audio from dominant N speakers will be mixed (N can be configured per mixer)

=== Resource usage of mixers ===
* An active speaker uses one mixer slot (up to 10 per conference)
* All non-active speakers use one mixer slot (although there is no per-conference limit)
* All listeners ''share'' the same mixer slot
* IVR on the mixer (playing file, recording file) use one mixer slot. It is possible to record and play at the same time, but the recording does not contain what is played on the mixer
:* It is possible to have a recording that contains what is played on the mixer, but it uses one more mixer slot (total of 2 slots)

=== TMedia conference capacity ===
In order to use conferences, TMedia must be equipped with DSPs.
Each TMG3200 or TMG7800 unit can be equipped with DSPs for 1,824 conference "slots" (thus a total of 29,184 for TMG7800 system).
If mixers need to be joined with call legs from different adapters, a TMS switch is needed.

Here are capacity results, depending of conference type: 

- 3 call legs in a conference and no play/record: 608 conferences and 1,824 "slots" 
- 2 call legs in a conference and play/record activated: 680 conferences and 2,040 "slots" 
- 1 call leg in a conference and play and record activated (can record what is played): 680 conferences and 2,040 "slots" 
- 11 call legs in a conference and play/record activated: 168 conferences and 2,016 "slots" 
- 12 call legs in a conference and no play/record: 160 conferences and 1,920 "slots"

AudioMixers

2012-08-20T15:22:19Z

Alexandre Lussier: /* TMedia conference capacity */

== Toolpack audio mixers ==
A mixer is used to mix the audio of multiple sources (call legs, playing audio file, tone generator...)

=== Typical usage of audio mixers ===
Audio mixers can be used, among other things, to:
* Build conferences
* Insert background music to a conversation
* Record both sides of the conversation into a single recorded file.

=== Joining audio source to a mixer ===
There are 2 ways to join a mixer:
* Join as a listener only
* Join as a speaker. Speakers can be active / or inactive (inactive speakers are not mixed, but monitored for voice activity)

[[File:mixer_internal.png|504px]]

=== Maximum call legs per mixer ===
The mixer has the following capabilities:
* The mixer can have any number of listeners (up to maximum number of call legs supported by the TMedia system)
* The mixer can have any number of speakers (up to maximum number of call legs supported by the TMedia system)
** Among these speakers, up to 10 will be considered as "active" (the 10 from which voice was received the most recently)
** Among these 10 active speakers, the audio from dominant N speakers will be mixed (N can be configured per mixer)

=== Resource usage of mixers ===
* An active speaker uses one mixer slot (up to 10 per conference)
* All non-active speakers use one mixer slot (although there is no per-conference limit)
* All listeners ''share'' the same mixer slot
* IVR on the mixer (playing file, recording file) use one mixer slot. It is possible to record and play at the same time, but the recording does not contain what is played on the mixer
:* It is possible to have a recording that contains what is played on the mixer, but it uses one more mixer slot (total of 2 slots)

=== TMedia conference capacity ===
In order to use conferences, TMedia must be equipped with DSPs.
Each TMG3200 or TMG7800 unit can be equipped with DSPs for 1,824 conference "slots" (thus a total of 29,184 for TMG7800 system).
If mixers need to be joined with call legs from different adapters, a TMS switch is needed.

Here are capacity results, depending of conference type:

- 3 call legs in a conference and no play/record: 608 conferences and 1,824 "slots"
- 2 call legs in a conference and play/record activated: 680 conferences and 2,040 "slots"
- 1 call leg in a conference and play and record activated (can record what is played): 680 conferences and 2,040 "slots"
- 11 call legs in a conference and play/record activated: 168 conferences and 2,016 "slots"
- 12 call legs in a conference and no play/record: 160 conferences and 1,920 "slots"

CAF: Caf Mixer Events

2012-08-13T16:00:19Z

Alexandre Lussier: /* Inserting / removing call legs (or other mixers) from the mixer: */ update new call back

== Events received from mixers by the CTBCAFCallFlow object ==

The call flow object (as well as all it's behaviors) receive the following events from it's mixers (please refer to the header file ITBCAFCallFlowMixer.hpp for more information on each of these functions):

=== Initialization and termination of mixer objects: ===
- OnMixerInit()
- OnMixerCreated()
- OnMixerTerminated()
- OnMixerFreed()
- OnMixerAttributeChanged()

=== Inserting / removing call legs (or other mixers) from the mixer: ===
- OnMixerLegJoinDone()
- OnMixerMixerJoinDone()
- OnMixerLegUnjoinDone()
- OnMixerMixerUnjoinDone()

=== Re-synchronization with [[Toolpack_Application:toolpack_engine|toolpack_engine]]: ===
- OnMixerSyncDone()
- OnMixerSyncLost()

=== Timers or custom events: ===
- OnMixerEvent()

=== Errors detected by [[Toolpack_Application:toolpack_engine|toolpack_engine]]: ===
- OnMixerError()

==== Playing/recording audio ====
- OnMixerStreamPlayingStarted()
- OnMixerStreamRecordingStarted()
- OnMixerStreamPlayingDone()
- OnMixerStreamRecordingDone()

AudioMixers

2012-08-13T15:47:10Z

Alexandre Lussier: /* TMedia conference capacity */ add TMS needs if mixed on multiple adapters

== Toolpack audio mixers ==
A mixer is used to mix the audio of multiple sources (call legs, playing audio file, tone generator...)

=== Typical usage of audio mixers ===
Audio mixers can be used, among other things, to:
* Build conferences
* Insert background music to a conversation
* Record both sides of the conversation into a single recorded file.

=== Joining audio source to a mixer ===
There are 2 ways to join a mixer:
* Join as a listener only
* Join as a speaker. Speakers can be active / or inactive (inactive speakers are not mixed, but monitored for voice activity)

[[File:mixer_internal.png|504px]]

=== Maximum call legs per mixer ===
The mixer has the following capabilities:
* The mixer can have any number of listeners (up to maximum number of call legs supported by the TMedia system)
* The mixer can have any number of speakers (up to maximum number of call legs supported by the TMedia system)
** Among these speakers, up to 10 will be considered as "active" (the 10 from which voice was received the most recently)
** Among these 10 active speakers, the audio from dominant N speakers will be mixed (N can be configured per mixer)

=== Resource usage of mixers ===
* An active speaker uses one mixer slot (up to 10 per conference)
* All non-active speakers use one mixer slot (although there is no per-conference limit)
* All listeners ''share'' the same mixer slot
* IVR on the mixer (playing file, recording file) use one mixer slot. It is possible to record and play at the same time, but the recording does not contain what is played on the mixer
:* It is possible to have a recording that contains what is played on the mixer, but it uses one more mixer slot (total of 2 slots)

=== TMedia conference capacity ===
In order to use conferences, TMedia must be equipped with DSPs.
Each TMG3200 or TMG7800 unit can be equipped with DSPs for 2,000 conference "slots" (thus a total of 32,000 for TMG7800 system).
If mixers need to be joined with call legs from different adapters, a TMS switch is needed.

AudioMixers

2012-08-13T15:44:47Z

Alexandre Lussier: /* Resource usage of mixers */

File:Mixer internal.png

2012-08-13T15:25:28Z

Alexandre Lussier: uploaded a new version of "File:Mixer internal.png": change active and inactive speaker for dominant and silent speaker to be coherent in our doc

Diagram of how a mixer works internally with:
- Active talkers
- Inactive talkers
- Listeners
- Stream Server Play/Record

AudioMixers

2012-08-13T15:09:13Z

Alexandre Lussier: /* Resource usage of mixers */

AudioMixers

2012-08-13T15:08:17Z

Alexandre Lussier: /* Resource usage of mixers */ talk about the possibility to record and play at the same time on a mixer

CAF: Working With Cmc Mixers

2012-08-13T14:50:22Z

Alexandre Lussier: /* Mixer Synchronization on Failover */ change order of mixer sync

== Audio Mixers Definition ==
Audio mixers are used to mix audio from multiple call legs and provide mixed output to each call leg.
At any time during a call flow the application can join call legs to one (or multiple) audio mixer.

== TMedia concepts and density ==
Please read the following page for general information about TMedia Mixers:
[[AudioMixers|Audio Mixers]]

== CTBCMCMixer class ==
An audio mixer is represented by an instance of the CTBCMCMixer class.
Call legs ([[CAF:_Working_With_Cmc_Call_Legs|CTBCMCLeg]]) can be joined to this audio mixer as speakers, listeners, or both.

In addition to call legs joining/unjoining, the CTBCMCMixer class allows some media functions such as playing audio files to all listeners of the mixer, or recording all active speakers of the mixer.

Other member functions are available to retrieve (and change in some cases) the mixer attributes, and the way different call legs are joined to the mixer (speaker/listener)

It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse the base class CTBCMCMixer with the class CTBCAFMixer. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs and mixers.

== Command Flow for Mixer Actions in CAF ==
All actions requested on a mixer are executed asynchronously. For each action '''DoSomething()''' on a mixer, a corresponding '''OnSomethingResponse()''' event will be received on the mixer once Toolpack starts processing the command. If the '''OnSomethingResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnMixerError()''' will be called. In some cases, when the action is completed, an event will be received on the mixer ('''OnSomethingDone()''' for example).

For example, to play an audio file on the mixer (heard by all legs listening to this mixer), one would call '''MixerPlayStream()'''. It would then almost immediately receive the '''OnMixerPlayStreamResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start configuring the resources to play on the mixer. Once the play has started, the user will receive an event '''OnMixerStreamPlayingStarted()''', and when it finished playing (or failed to start), the user will receive an '''OnMixerStreamPlayingDone()''' event.

== Mixer Creation ==
Creating a mixer is always done through the definition of a ''mixer attribute''. The values entered in the ''mixer attribute'' will define how the mixer behaves, and will influence resource reservation.

=== Preparing Mixer Attributes ===

The class CTBCMC_MIXER_ATTRIBUTE defines available attributes to configure an audio mixer. Default parameters are provided for standard usage, though parameters may be changed to control the behavior more precisely.
Example mixer attributes are:
* Reserve IVR resource (else add it dynamically when needed)
* Reserve 'listener-only' slot (else added dynamically upon joining of first 'listener-only' leg)
* Reserve speaker slots (else add speaker slots dynamically when needed)
* Maximum number of active "dominant" speakers (maximum number of audio sources mixed together at a given time, based on loudest speakers)
* Noise floor (for considering inactive speaker as now talking)
* Noise suppression limit (for removal of background noise from active speakers)
* Target power for conference output
* Loss limit / Gain limit (limiting the audio level adjustments allowed from speaker legs to reach the target power)
Note: Please refer to header file '''tbcmc_mixer.hpp''' for a more complete documentation on all available mixer attributes.

Once a mixer is created, Toolpack will manage reservation of DSP resources on a TMedia, and will manage connecting legs to the mixer (listeners, or speakers). When call legs are joined or unjoined from the mixer, Toolpack will automatically re-size the DSP resource if appropriate (with a minimum size determined by the 'reserve' mixer attributes).
And thus, the application does not have to deal with resource management distribution among TMedia units.
For more information about capacity of TMedia units (in number of conference "slots"), please refer to this page: [[AudioMixers#Resource_usage_of_mixers|Audio Mixers -> Resource usage]]

The following code snippet shows how to build the attributes.
PTRCTBCMC_MIXER_ATTRIBUTE ptrMixerAttribute;

ptrMixerAttribute = tbnew CTBCMC_MIXER_ATTRIBUTE();

ptrMixerAttribute->SetReserveIvrSlot( TBX_TRUE );
ptrMixerAttribute->->SetReserveListenerSlot( TBX_FALSE );
ptrMixerAttribute->SetNbReservedActiveSpeakerSlots( 3 );
ptrMixerAttribute->SetNbDominantSpeakers( 3 );
ptrMixerAttribute->SetNoiseFloor( TBCMC_VAD_NOISE_FLOOR_LEVEL_MINUS_30_DBM );
...

=== Creating the Mixer ===
Once the mixer attributes have been filled, creating the mixer in Toolpack is only a matter of creating a CTBCMCMixer object and calling '''MixerCreate()''' on it. At that moment a message is sent to Toolpack system to allocate the mixer on the hardware.

pCallMixer = new CTBCMCMixer( 0 /* or MixerId from OnMixerSync() */, ptrMixerAttribute, this, &mLegMutex );
pCallMixer ->MixerCreate();

Once the mixer has finished being allocated on hardware, the function '''OnMixerCreated()''' will be called.

== Mixer Termination ==

Terminating a mixer is a 2 steps process:
# Call '''MixerTerminate()'''
# Ask for mixer object free upon '''OnMixerTerminated()''' callback function

When '''MixerTerminate()''' is called, the Toolpack framework will start destroying the mixer (including unjoining any call leg that was joined to it). Once the mixer hardware resources have been deallocated, Toolpack will call '''OnMixerTerminated()'''. Receiving that event means that the mixer no more exists in Toolpack, and the object can thus be freed. Any time after '''OnMixerTerminated()''' (or within that function), the application is responsible to call method '''FreeMixer()''', which will eventually cause the mixer's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface function '''Free''' to be called. The ITBCMCFreeListener to use can be specified either in the CTBCMCMixer constructor and by calling '''SetFreeListener()'''. The mixer can be it's own ''FreeListener'', in which it just 'delete' itself. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the mixer is deleted. An example could be the case where the mixer object was allocated from a pool and it should be returned to that pool instead of being deleted.

In some situation, it is possible that mixer termination be initiated by Toolpack. This can happen in the event of sudden media resource unavailability on hardware, or if the application gets disconnected from Toolpack engine. In that cases, the callback '''OnMixerTerminated()''' is called. On reception of this event, the application should also acknowledge termination by calling '''FreeMixer()'''.

== Mixer Synchronization on Failover ==
When a Toolpack application is restarted, or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs, links and mixers:
* Callback '''OnCallLegSync()''' lists all legs that were retrieved from Toolpack
* Callback '''OnMixerSync()''' lists all mixers that were retrieved from Toolpack, along with list of legs joined to each mixer.
* Callback '''OnLinkSync()''' lists all joined leg pairs that were retrieved from Toolpack
* Callback '''OnMixerLinkSync()''' lists all legs joined to mixers, and mixers joined to mixers.

The course of action to take when receiving a leg or mixer synchronization event depends on the ability of the application to resynchronize or rebuild its own states.

A typical re-synchronization scenario would be similar to:
* Application receives all '''OnCallLegSync()''' callbacks, for each a new object of type CTBCMCLeg is created
* Application receives all '''OnMixerSync()''' callbacks, and for each a new object of type CTBCMCMixer is created.
* Application receives all '''OnLinkSync()''' callbacks, and for each re-builds the association between the CTBCMCLeg by calling function '''SetJoined()''' of one of the legs.
* Application receives all '''OnMixerLinkSync()''' callbacks, and for each re-builds the association between legs and mixers by calling function '''MixerSetJoined()'''.
* Any leg, link or mixer that the application does not wish to keep is destroyed ('''RefuseLeg''', '''RefuseLink''', '''RefuseMixer''', or '''RefuseMixerLink''')

When all legs, links and mixers have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. Event '''OnSyncDone()''' is also called on each re-synchronized leg, and '''OnMixerSyncDone()''' on each re-synchronized mixer.

Web Portal Tutorial Guide v2.5

2011-10-28T14:51:05Z

Alexandre Lussier: change link order

=Introduction=
This guide is designed to provide users with a scenario-based approach to installing [[Tmedia]] and [[Tdev]] systems, using the Web Portal configuration tool. This means that users must first go through the steps that are general to all installations, and subsequently follow the instructions that are specific to their particular application scenario (this corresponds to the type of service, and hardware system being set up).

==Prerequisites==
This document assumes that the [[Tmedia]] or [[Tdev]] devices are installed as described in their Quick Reference Guides, and in the case of the Tmedia system communication has been established with the control network.

(Note: Tmedia devices are shipped with the Tmedia Web Portal pre-installed, while Tdev devices require that Toolpack be installed as described in the [http://download.distribution.telcobridges.com/documentation/TMP6400_Installation_Guide.pdf TMP6400 Installation Guide].)

Furthermore, in the case of a Tdev device and the initial configuration of the [[Toolpack]] application server, the following will have been provided:
*The Tdev device to which the Web Portal will first connect.
*The Tdev device will have been pre-configured with its physical TDM interface.
*The serial number of the Tdev device will have been entered into the configuration file.
*The application software for the Tdev device will have been pre-installed on the Toolpack application server, as described in the [http://download.distribution.telcobridges.com/documentation/TMP6400_Installation_Guide.pdf TMP6400 Installation Guide].

This document also assumes familiarity with topics, such as [[ISDN]] signaling, [[SIP]] signaling, [[SS7]], [[CAS|CAS R2]] signaling, and [[SIGTRAN]] signaling.

==Key Concepts==
*'''System:''' A system is defined as the complete solution that is designed for a network. If a system solution is comprised of 4 TMP6400’s and a TMS1600, then the combination of these TelcoBridges devices is termed a system.
*'''Hardware:''' Each TelcoBridges devices, whether it is a TMP6400, TMG3200, or TMS1600 is referred to as a hardware device or hardware adapter.
*'''Line Interface:''' The physical TDM module installed on the TelcoBridges device is referred to as a line interface.

== General Web Portal Applications ==

'''''IMPORTANT!''''' The Topics covered in the following table are common to all TMedia installations. Therefore, this section should be consulted before moving on to any other.

 '''Topics covered here:'''

*The basic knowledge needed to properly navigate through the Web Portal '''(A)'''.
*The fundamentals of user account management and permission masks '''(B)'''.
*The initial steps required for first starting the Web Portal, and verifying that it is functioning properly '''(C)'''.
*The process involved in backing up your database for the first time '''(D)'''.
*The process involved in first configuring your IP interfaces '''(E)'''.

 

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: none repeat scroll 0% 0% rgb(239, 239, 239); -moz-background-inline-policy: continuous;" | (Topic A) Web Portal Basics
! width="200" style="background: none repeat scroll 0% 0% rgb(239, 239, 239); -moz-background-inline-policy: continuous;" | (Topic B) Log-on and User Access Levels
! width="200" style="background: none repeat scroll 0% 0% rgb(239, 239, 239); -moz-background-inline-policy: continuous;" | (Topic C) Application Start-up and Verification
! width="200" style="background: none repeat scroll 0% 0% rgb(239, 239, 239); -moz-background-inline-policy: continuous;" | (Topic D) Database Backup
|-
| valign="top" |
*[[Toolpack v2.5:Navigating the Web Portal|Navigating the Web Portal]]
*[[Typographic conventions|Typographic Conventions]]

 

| valign="top" |
*[[Toolpack v2.5:Connecting to the Web Server and logging on to the web portal|Connect to the web server and log on to the Web Portal]]
*[[Toolpack:User access|User Access]]
**[[Toolpack v2.5:Viewing the User List|Viewing the User List]]
**[[Toolpack v2.5:Creating a New User|Creating a New User]]
**[[Toolpack v2.5:Deleting a User|Deleting a User]]
**[[Toolpack v2.5:Logging Off Toolpack|Logging Off]]
*[https://forums.telcobridges.com/viewtopic.php?f=12&t=248&p=1101&hilit=privilege#p1101 User privilege level]

| valign="top" |
*[[Toolpack v2.5:Viewing the List of Installed Applications|Viewing the List of Installed Applications]]
*[[Toolpack v2.5:Starting an Application|Starting an Application]]
*[[Toolpack:Verifying that an Application is Operating|Verifying that an Application is Operating]]
**[[Toolpack v2.5:Verifying the Application Path|Verifying the Application Path]]
*[[Toolpack v2.5:Activating the Configuration|Activating the Configuration]]
**[[Toolpack v2.5:Status Menus:Applications|Verifying status]]

| valign="top" |
*[[Toolpack v2.5:Database Backup|Carrying out a First Database Backup]]
*[[Toolpack v2.5:Downloading a Database Backup|Downloading a Database Backup]]
*[[Toolpack v2.5:Uploading a Database Backup|Uploading a Database Backup]]
*[[Toolpack v2.5:Restoring a Database Backup|Restoring a Database Backup]]

|-
! width="200" style="background: none repeat scroll 0% 0% rgb(239, 239, 239); -moz-background-inline-policy: continuous;" | (Topic E) Configure IP Interfaces
|-
| valign="top" |
*[[Toolpack v2.5:Configuring IP Interfaces|Configure IP Interfaces]]

|}

=ISDN-SIP Gateway Configuration=

The following tables contain a typical configuration scenario for an [[ISDN]] to [[SIP]] gateway. This type of installation allows for the transfer of information from traditional [[ISDN]] signaling to [[SIP]] protocol for [[VoIP]] applications. Please follow each step one after another as these are listed in logical order.

'''The steps are as follows:'''

*1) Log On and Create a New Configuration
*2) Allocate Physical Interfaces
*3) Configure ISDN-PRI Signaling
*4) Configure Clocking Source
*5) Configure SIP Signaling
*6) Configure Codecs and Tone Detection
*7) Configure Network Access Points (NAPs)
*8) Create Call Routing Rules

'''IMPORTANT!''' After completing the setup process, remember to '''activate the configuration''', as outlined in the [[Web_Portal_Tutorial_Guide_v2.5#General_Web_Portal_Applications|General Web Portal Applications section]].

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 1) Log On and Create a New Configuration

! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 2) Allocate Physical Interfaces

! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 3) Configure ISDN-PRI Signaling

! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 4) Configure Clocking Source

|-
| valign="top" |
*[[Toolpack_v2.5:Connecting_to_the_Web_Server_and logging on to the web portal|Connect to the web server and log on to the Web Portal]]
*[[Toolpack_v2.5:Copying_the_Default_Configuration|Copy the default configuration]]

| valign="top" |
*[[Toolpack_v2.5:Creating_a_Line_Interface|Create a new line interface]]
*[[Toolpack_v2.5:Creating_a_Line_Service|Create a new line service]]

| valign="top" |
*[[Toolpack_v2.5:Configuring_an_ISDN_Stack|Configure an ISDN stack]]
OR 
*[[Configure NFAS]]

| valign="top" |
*[[Toolpack_v2.5:Defining_a_Clocking_Source|Define a clocking source]]

|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 5) Configure SIP Signaling

! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 6) Configure Codecs and Tone Detection

! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 7) Configure Network Access Points (NAPs)

! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 8) Create Call Routing Rules

|-
| valign="top" |
*[[Toolpack_v2.5:Creating_an_IP_Port_Range|Create an IP port range]]
*[[Toolpack_v2.5:Creating_a_SIP_Stack|Create a SIP stack]]
*[[Toolpack_v2.5:Creating_a_SIP_Transport_Server|Create a SIP transport server]]
*[[Toolpack_v2.5:Creating_a_Service_Access_Point_(SAP)|Create a service access point (SAP)]]

| valign="top" |
*[[Toolpack_v2.5:Accessing_Codec_and_Tone_Detection_Profiles_and_Validating_Settings|Access profiles and validate settings]]

| valign="top" |
*[[Toolpack_v2.5:Allocating_an_ISDN_Network_Access_Point_(NAP)|Allocate an ISDN NAP]]
*[[Toolpack_v2.5:Allocating_a_SIP_Network_Access_Point_(NAP)|Allocate a SIP NAP]]

| valign="top" |
*[[Toolpack_v2.5:Creating_a_First_Call_Route|Create a first call route]]
|}

=Configuring SS7=

The following table contains information on configuring the [[SS7]] signaling protocol.
The various control layers of the [[SS7]] protocol are listed individually in each column. These layers are:

* [[MTP2_Layer|MTP2]] layer '''(Step 1)'''
* [[MTP3_Layer|MTP3]] layer '''(Step 2)'''
* [[ISUP]] layer '''(Step 3)'''
* [[SCCP]] layer '''(Step 4)'''
* [[TCAP]] layer '''(Step 5)'''

'''Follow the topics listed in each column from left to right in order to configure an SS7 protocol stack.'''

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 1) Configuring the MTP2 Layer
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 2) Configuring the MTP3 Layer
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 3) Configuring the ISUP Layer
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 4) Configuring the SCCP Layer
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 5) Configuring the TCAP Layer

|-
| valign="top" |
*[[Toolpack_v2.5:Creating_an_MTP2_Configuration|Create an MTP2 Configuration]]
*[[Toolpack_v2.5:Creating_MTP2_Links|Create an MTP2 Link]]

| valign="top" |
*[[Toolpack_v2.5:Creating_an_MTP3_Configuration|Create an MTP3 Configuration]]
*[[Toolpack_v2.5:Creating_an_MTP3_Network|Create an MTP3 Network]]
**[[Toolpack_v2.5:Creating_SS7_Point_Codes|Create an MTP3 Point Code]]
**[[Toolpack_v2.5:Creating_an_MTP3_Linkset|Create an MTP3 Linkset]]
***[[Toolpack_v2.5:Creating_MTP3_Links|Create MTP3 Links]]
**[[Toolpack_v2.5:Creating_an_MTP3_Route|Create an MTP3 Route]]

| valign="top" |
*[[Toolpack_v2.5:Creating_an_ISUP_Stack|Create an ISUP Stack]]
*[[Toolpack_v2.5:Creating_an_ISUP_Network|Create an ISUP Network]]
*[[Toolpack_v2.5:Creating_an_ISUP_User_Part|Create an ISUP User Part]]
*[[Toolpack_v2.5:Creating_an_ISUP_Interface|Create an ISUP Interface]]

| valign="top" |
*[[Toolpack_v2.5:Creating_an_SCCP_Stack| Create an SCCP Stack]]
*[[Toolpack_v2.5:Creating_an_SCCP_Network|Create an SCCP Network]]
**[[Toolpack_v2.5:Creating_an_SCCP_Userpart|Create an SCCP Userpart]]
**[[Toolpack_v2.5:Creating_an_SCCP_LSAP|Create an SCCP LSAP]]
***[[Toolpack_v2.5:Creating_an_SCCP_Route|Create an SCCP Route]]
****[[Toolpack_v2.5:Creating_an_SCCP_SSN|Create an SCCP SSN]]
*[[Toolpack_v2.5:Creating_an_SCCP_GTT_Association|Create an SCCP GTT Association]]
**[[Toolpack_v2.5:Creating_an_SCCP_GTT_Address_Map|Create an SCCP GTT Address Map]]

| valign="top" |
*[[Toolpack_v2.5:Creating_a_TCAP_Stack|Create a TCAP Stack]]
**[[Toolpack_v2.5:Creating_a_TCAP_Userpart| Create a TCAP Userpart]]
*[[Toolpack_v2.5:Activating_the_Configuration|Activating the Configuration]]

|}

=SIGTRAN Application Scenarios=

Toolpack version 2.5 enables you to configure SIGTRAN and thereby extend SS7 signalling functionality to the IP network. Toolpack enables you to configure a number of SIGTRAN applications based upon your requirements. These applications are listed below as follows: 

*[[M2PA]] system. See column '''(A)''' below. In this configuration the SS7 MTP2 layer is replaced by the SIGTRAN M2PA layer which extends MTP2 signalling functionality into the IP network. This application is typically used between a Signalling Gateway and an IP Signalling Point, or between two IP Signalling Points.

*[[M2UA]] system. See columns '''(B)''' and '''(C)''' below. An M2UA system on a Signalling Gateway Controller interfaces with an M2UA system on a Media Gateway Controller. In this configuration, M2UA bridges the SS7 MTP2 layer of a Signalling Gateway, across an IP network, with the SS7 MTP3 layer of a Media Gateway Controller.

*[[IUA]] system. See column '''(D)''' below. An IUA system on a Signalling Gateway Controller interfaces with an IUA system on a Media Gateway Controller. In this configuration, IUA bridges the SS7 MTP2 layer of a Signalling Gateway, across an IP network, with the SS7 MTP3 layer of a Media Gateway Controller.

*[[M3UA]] system on two IP signalling points. See column '''(E''') below. In this configuration the SS7 MTP2 and MTP3 layers are replaced entirely by the SIGTRAN M3UA layer. This application is typically used between two IP Signalling Points.

*[[M3UA]] system. See columns '''(F)''' and '''(G)''' below. An M3UA system on a Signalling Gateway Process interfaces with an M3UA system on an Application Server Process. In this configuration, the MTP3 links are extended across the IP network.

 '''A SIGTRAN scenario walkthrough is provided in the table columns below, to illustrate the order that must be followed when configuring SIGTRAN.''' 

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Scenario A) Configuring an M2PA System
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Scenario B) Configuring an M2UA System on a Signalling Gateway
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Scenario C) Configuring an M2UA System on a Media Gateway Controller
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Scenario D) Configuring an IUA System on a Signalling Gateway
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Scenario E) Configuring an M3UA System on IP Signalling Points
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Scenario F) Configuring an M3UA System on a Signalling Gateway
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Scenario G) Configuring an M3UA System on an Application Server
|-
|
*[[Toolpack v2.5:Adding an Adapter|Adding an Adapter]]
*[[Toolpack v2.5:Creating a Line Interface|Create Line Interfaces]]
*[[Toolpack v2.5:Creating a Line Service|Create Line services]]
*[[Toolpack v2.5:Editing the SCTP Configuration|Edit the SCTP Configuration]]
*[[Toolpack v2.5:Creating the M2PA Configuration|Create an M2PA Configuration]]
**[[Toolpack v2.5:Creating an M2PA SAP|Create an M2PA SAP]]
**[[Toolpack v2.5:Adding M2PA Links|Add M2PA Links]]
*[[Toolpack v2.5:Creating SS7 Point Codes|Create SS7 Point Codes]]
*[[Toolpack v2.5:Creating an MTP3 Configuration|Create an MTP3 Configuration]]
**[[Toolpack v2.5:Creating an MTP3 Network|Create an MTP3 Network]]
**[[Toolpack v2.5:Creating an MTP3 Linkset|Create an MTP3 Linkset]]
***[[Toolpack v2.5:Creating MTP3 Links (M2PA)|Create MTP3 Links]]
**[[Toolpack v2.5:Creating an MTP3 Route|Create an MTP3 Route]]
*[[Toolpack v2.5:Creating an ISUP Stack|Create an ISUP Stack]]
**[[Toolpack v2.5:Creating an ISUP Network|Create an ISUP Network]]
**[[Toolpack v2.5:Creating an ISUP User Part|Create an ISUP User Part]]
**[[Toolpack v2.5:Creating an ISUP Interface|Create an ISUP Interface]]
***[[Toolpack v2.5:Creating ISUP CIC Groups|Create ISUP CIC Groups]]
**[[Toolpack v2.5:Creating a NAP (SIGTRAN)|Create a NAP]]

| valign="top" |
*[[Toolpack v2.5:Adding an Adapter|Adding an Adapter]]
*[[Toolpack v2.5:Creating a Line Interface|Create Line Interfaces]]
*[[Toolpack v2.5:Creating a Line Service|Create Line services]]
*[[Toolpack v2.5:Creating an MTP2 Configuration|Create an MTP2 Configuration]]
**[[Toolpack v2.5:Creating MTP2 Links|Create MTP2 Links]]
*[[Toolpack v2.5:Creating the SCTP Configuration|Edit the SCTP Configuration]]
*[[Toolpack v2.5:Creating the M2UA Configuration|Create an M2UA Configuration]]
**[[Toolpack v2.5:Creating an M2UA SAP|Create an M2UA SAP]]
**[[Toolpack v2.5:Creating an M2UA Cluster|Create an M2UA Cluster]]
**[[Toolpack v2.5:Creating M2UA Links|Create M2UA Links]]
**[[Toolpack v2.5:Creating M2UA Peers|Create M2UA Peers]]

 

| valign="top" |
*[[Toolpack v2.5:Adding an Adapter|Adding an Adapter]]
*[[Toolpack v2.5:Editing the SCTP Configuration|Edit the SCTP Configuration]]
*[[Toolpack v2.5:Creating the M2UA Configuration|Create an M2UA Configuration]]
**[[Toolpack v2.5:Creating an M2UA SAP|Create an M2UA SAP]]
**[[Toolpack v2.5:Creating an M2UA Cluster|Create an M2UA Cluster]]
**[[Toolpack v2.5:Creating M2UA Links|Create M2UA Links]]
**[[Toolpack v2.5:Creating M2UA Peers|Create M2UA Peers]]
*[[Toolpack v2.5:Creating SS7 Point Codes|Create SS7 Point Codes]]
*[[Toolpack v2.5:Creating an MTP3 Configuration|Create an MTP3 Configuration]]
**[[Toolpack v2.5:Creating an MTP3 Network|Create an MTP3 Network]]
**[[Toolpack v2.5:Creating an MTP3 Linkset|Create an MTP3 Linkset]]
**[[Toolpack v2.5:Creating MTP3 Links (M2UA)|Create MTP3 Links]]
**[[Toolpack v2.5:Creating an MTP3 Route|Create an MTP3 Route]]
*[[Toolpack v2.5:Creating an ISUP Stack|Create an ISUP Stack]]
**[[Toolpack v2.5:Creating an ISUP Network|Create an ISUP Network]]
**[[Toolpack v2.5:Creating an ISUP User Part|Create an ISUP User Part]]
**[[Toolpack v2.5:Creating an ISUP Interface|Create an ISUP Interface]]
***[[Toolpack v2.5:Creating ISUP CIC Groups|Create ISUP CIC Groups]]
**[[Toolpack v2.5:Creating a NAP (SIGTRAN)|Create a NAP]]

| valign="top" |
*[[Toolpack v2.5:Adding an Adapter|Adding an Adapter]]
*[[Toolpack v2.5:Creating a Line Interface|Create Line Interfaces]]
*[[Toolpack v2.5:Creating a Line Service|Create Line services]]
*[[Toolpack v2.5:Creating the SCTP Configuration|Edit the SCTP Configuration]]
*[[Toolpack v2.5:Creating the IUA Configuration|Create an IUA Configuration]]
**[[Toolpack v2.5:Creating an IUA SAP|Create an IUA SAP]]
**[[Toolpack v2.5:Creating an IUA Cluster|Create an IUA Cluster]]
**[[Toolpack v2.5:Creating IUA Links|Create IUA Links]]
**[[Toolpack v2.5:Creating IUA Peers|Create IUA Peers]]

 

| valign="top" |
*[[Toolpack v2.5:Adding an Adapter|Adding an Adapter]]
*[[Toolpack v2.5:Editing the SCTP Configuration|Edit the SCTP Configuration]]
*[[Toolpack v2.5:Creating SS7 Point Codes|Create SS7 Point Codes]]
*[[Toolpack v2.5:Creating an M3UA Configuration (IPSP)|Create an M3UA Configuration]]
**[[Toolpack v2.5:Creating an M3UA SAP|Create an M3UA SAP]]
**[[Toolpack v2.5:Creating an M3UA Network|Create an M3UA Network]]
**[[Toolpack v2.5:Creating an M3UA User Part|Create an M3UA User Part]]
**[[Toolpack v2.5:Creating an M3UA Peer Signalling Process (IPSP)|Create an M3UA Peer Signalling Process]]
**[[Toolpack v2.5:Creating an M3UA Peer Server|Create an M3UA Peer Server]]
**[[Toolpack v2.5:Creating an M3UA Route|Create an M3UA Route]]
*[[Toolpack v2.5:Creating an ISUP Stack|Create an ISUP Stack]]
**[[Toolpack v2.5:Creating an ISUP Network|Create an ISUP Network]]
**[[Toolpack v2.5:Creating an ISUP User Part|Create an ISUP User Part]]
**[[Toolpack v2.5:Creating an ISUP Interface|Create an ISUP Interface]]
***[[Toolpack v2.5:Creating ISUP CIC Groups|Create ISUP CIC Groups]]
**[[Toolpack v2.5:Creating a NAP (SIGTRAN)|Create a NAP]]

| valign="top" |
*[[Toolpack v2.5:Adding an Adapter|Adding an Adapter]]
*[[Toolpack v2.5:Creating a Line Interface|Create Line Interfaces]]
*[[Toolpack v2.5:Creating an MTP2 Configuration|Create an MTP2 Configuration]]
*[[Toolpack v2.5:Creating MTP2 Links|Create MTP2 Links]]
*[[Toolpack v2.5:Editing the SCTP Configuration|Edit the SCTP Configuration]]
*[[Toolpack v2.5:Creating SS7 Point Codes|Create SS7 Point Codes]]
*[[Toolpack v2.5:Creating an MTP3 Configuration|Create an MTP3 Configuration]]
**[[Toolpack v2.5:Creating an MTP3 Network|Create an MTP3 Network]]
**[[Toolpack v2.5:Creating an MTP3 Linkset|Create an MTP3 Linkset]]
**[[Toolpack v2.5:Creating MTP3 Links (M3UA)|Create MTP3 Links]]
**[[Toolpack v2.5:Creating an MTP3 Route|Create an MTP3 Route]]
*[[Toolpack v2.5:Creating an M3UA Configuration (SGP)|Create an M3UA Configuration]]
**[[Toolpack v2.5:Creating an M3UA SAP|Create an M3UA SAP]]
**[[Toolpack v2.5:Creating an M3UA Network|Create an M3UA Network]]
**[[Toolpack v2.5:Creating an M3UA User Part|Create an M3UA User Part]]
**[[Toolpack v2.5:Creating an M3UA Peer Signalling Process (SGP)|Create an M3UA Peer Signalling Process]]
**[[Toolpack v2.5:Creating an M3UA Peer Server|Create an M3UA Peer Server]]
**[[Toolpack v2.5:Creating an M3UA Route (SGP)|Create an M3UA Route]] 

| valign="top" |
*[[Toolpack v2.5:Adding an Adapter|Adding an Adapter]]
*[[Toolpack v2.5:Editing the SCTP Configuration|Edit the SCTP Configuration]]
*[[Toolpack v2.5:Creating SS7 Point Codes|Create SS7 Point Codes]]
*[[Toolpack v2.5:Creating an M3UA Configuration (ASP)|Create an M3UA Configuration]]
**[[Toolpack v2.5:Creating an M3UA SAP|Create an M3UA SAP]]
**[[Toolpack v2.5:Creating an M3UA Network|Create an M3UA Network]]
**[[Toolpack v2.5:Creating an M3UA User Part|Create an M3UA User Part]]
**[[Toolpack v2.5:Creating an M3UA Peer Signalling Process (ASP)|Create an M3UA Peer Signalling Process]]
**[[Toolpack v2.5:Creating an M3UA Peer Server|Create an M3UA Peer Server]]
**[[Toolpack v2.5:Creating an M3UA Route|Create an M3UA Route]]
*[[Toolpack v2.5:Creating an ISUP Stack|Create an ISUP Stack]]
**[[Toolpack v2.5:Creating an M3UA ISUP Network|Create an M3UA ISUP Network]]
**[[Toolpack v2.5:Creating an ISUP User Part|Create an ISUP User Part]]
**[[Toolpack v2.5:Creating an ISUP Interface|Create an ISUP Interface]]
***[[Toolpack v2.5:Creating ISUP CIC Groups|Create ISUP CIC Groups]]
**[[Toolpack v2.5:Creating a NAP (SIGTRAN)|Create a NAP]]

|}

=Configuring CAS R2=

Toolpack v2.5 allows you to configure CAS R2 signaling stacks. The following table lists the basic steps that must be followed in order to configure CAS R2.

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | Configuring a CAS R2 stack

|-
| valign="top" |
*[[Toolpack v2.5:Adding an Adapter|Adding an Adapter]]
*[[Toolpack_v2.5:Creating_a_Line_Interface|Create Line Interfaces]]
*[[Toolpack_v2.5:Creating_a_Line_Service|Create Line services]]
*[[Toolpack v2.5:Copy variant script|Copy variant script]] (optional)
*[[Toolpack v2.5:Create CAS R2 stack|Create CAS R2 stack]]
*[[Toolpack_v2.5:Creating_a_CAS_R2_NAP|Create a NAP]]

|}

=Configuring H.248=

The following table contains steps for configuring an H.248 media gateway control protocol

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 1) Add a Hardware Adapter
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 2) Allocate Physical Interfaces
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 3) Create IP Port Ranges
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 4) Configure Network Access Points (NAPs)

|-
| valign="top" |
*[[Toolpack_v2.5:Adding_an_Adapter|Adding an Adapter]]

| valign="top" |
*[[Toolpack_v2.5:Creating_a_Line_Interface|Create line interfaces]]
*[[Toolpack_v2.5:Creating_a_Line_Service|Create line services]]

| valign="top" |
*[[Toolpack_v2.5:Creating_an_IP_Port_Range|Create IP port ranges]]

| valign="top" |
*[[Toolpack_v2.5:Allocating_a_VoIP_Network_Access_Point_(NAP)|Allocate a VoIP network access point (NAP)]]
*[[Toolpack_v2.5:Allocating_a_TDM_Network_Access_Point_(NAP)|Allocate a TDM network access point (NAP)]]

|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 5) Configure the Media Gateway for H.248 mode
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 6) Create an H.248 Configuration
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 7) Add a New Media Gateway Controller
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 8) Associate NAPs with the H.248 Configuration

|-
| valign="top" |
*[[Toolpack_v2.5:Configure the Media_Gateway_for_H248_Mode|Configure the Media Gateway for H.248 mode]]

| valign="top" |
*[[Toolpack_v2.5:Creating_an_H.248_Configuration|Create a new H.248 configuration]]

| valign="top" |
*[[Toolpack_v2.5:Adding_a_Media_Gateway_Controller_(MGC)|Add a new media gateway controller (MGC)]]

| valign="top" |
*[[Toolpack_v2.5:Associating_NAPs_with_an_H.248_Configuration|Associate the NAPs with the H.248 configuration]]

|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 9) Select Timeslots for TDM Terminations

|-
| valign="top" |
*[[Toolpack_v2.5:Selecting_Timeslots_for_TDM_Interfaces|Select timeslots for the TDM interfaces]]
|}

=Configuring an H.323 to SIP Converter=

The following table contains steps for configuring NAPs that wil allow an interface between the web portal and a YATE H.323 to SIP signal converter:

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | Configuring an H.323 to SIP Signal Converter

|-
| valign="top" |

* [[Toolpack_v2.5:Creating_H.323_NAP_Columns|Create H.323 NAP columns]]
*[[Toolpack_v2.5:Creating_an_IP_Port_Range|Create an IP port range]]
*[[Toolpack_v2.5:Creating_a_SIP_Stack|Create a SIP stack]]
*[[Toolpack_v2.5:Creating_a_SIP_Transport_Server|Create a SIP transport server]]
*[[Toolpack_v2.5:Creating_a_Service_Access_Point_(SAP)|Create a service access point (SAP)]]
* [[Toolpack_v2.5:Creating_SIP_NAPs_(H.323)|Create SIP NAPs]]
|}

=Configuring SNMP=

To use the Simple Network Management Protocol (SNMP)on your machine, you must first configure the '''tbSnmpAgent'''.
 The '''tbSnmpAgent''' is a software application that interfaces between the TMedia system hardware and the [http://www.net-snmp.org NetSnmp] implementation of the SNMP that is supported by TelcoBridges.
By default, tbSnmpAgent is '''disabled'''. In order to use the SNMP protocol to monitor and manage your hardware, the following steps must be taken:
 
* tbSnmpAgent must be '''activated'''
* tbSnmpAgent must be '''configured''' to suit your needs
 
The aforementioned tasks can be accomplished through the [[Web Portal]]:
 
#[[Activating tbSnmpAgent|Activate tbSnmpAgent]]
#[[Configuring tbSnmpAgent|Configure tbSNMPAGENT to suit your needs]]
 
Once these tasks have been completed, your TMedia platform is ready to expose system variables for polling with the Simple Network management Protocol (SNMP).

=Status Menus=

The Web Portal configuration tool will guide you through a number of status menus, each of which indicate the current state of a certain hardware service (assuming said service has been configured).
The following table contains the general conventions of the Web Portal's display '''(A)''', as well as a variety of specific status menus '''(B)'''.

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (A) Menus Overview
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (B) Individual Menu Descriptions

|-
| valign="top" |

*[[Toolpack_v2.5:Tmedia_Status_Menus|Tmedia Status Menus]]
**[[Toolpack_v2.5:Status_Menus:Navigation|Navigation]]
**[[Toolpack_v2.5:Status_Menus:Screen_Conventions|Status Screen Conventions]]

| valign="top" |

*[[Toolpack_v2.5:Status_Menus:System|System]]
*[[Toolpack_v2.5:Status_Menus:Adapters_and_IP_Interfaces|Adapters and IP Interfaces]]
*[[Toolpack_v2.5:Status_Menus:Hosts|Hosts]]
*[[Toolpack_v2.5:Status_Menus:Applications|Applications]]
*[[Toolpack_v2.5:Status_Menus:TDM_Lines|TDM Lines]]
*[[Toolpack_v2.5:Status_Menus:SCTP|SCTP]]
*[[Toolpack_v2.5:Status_Menus:SS7_MTP2|SS7 MTP2]]
*[[Toolpack_v2.5:Status_Menus:SS7_M2UA|SS7 M2UA]]
*[[Toolpack_v2.5:Status_Menus:SS7_IUA|SS7 IUA]]
*[[Toolpack_v2.5:Status_Menus:SS7_M2PA|SS7 M2PA]]
*[[Toolpack_v2.5:Status_Menus:SS7_M3UA|SS7 M3UA]]
*[[Toolpack_v2.5:Status_Menus:SS7_MTP3|SS7 MTP3]]
*[[Toolpack_v2.5:Status_Menus:SS7_ISUP|SS7 ISUP]]
*[[Toolpack_v2.5:Status_Menus:SS7_SCCP|SS7 SCCP]]
*[[Toolpack_v2.5:Status_Menus:SS7_TCAP|SS7 TCAP]]
*[[Toolpack_v2.5:Status_Menus:ISDN|ISDN]]
**[[Toolpack_v2.5:Status_Menus:NFAS|NFAS]]
*[[Toolpack_v2.5:Status_Menus:CASR2|CASR2]]
*[[Toolpack_v2.5:Status_Menus:SIP|SIP]]
*[[Toolpack_v2.5:Status_Menus:Clock|Clock]]
*[[Toolpack_v2.5:Status_Menus:TMS|TMS]]
*[[Toolpack_v2.5:Status_Menus:NAP|NAP]]
*[[Toolpack_v2.5:Status_Menus:H.248|H.248]]
*[[Toolpack_v2.5:Status_Menus:CDR|CDR]]

|}

=Further Reading=
For further information, refer to the following reading list. Please note that all guides listed below are in portable document format (*.PDF), and can be downloaded:

*[[media:TMedia System Architecture Description.pdf|TMedia System Architecture Overview for Developers of VoIP and TDM Solutions]]
*[[Media:Tb640 user's guide.pdf|TB640 User's Guide]]
*[[media:SS7 user's guide.pdf|TelcoBridges SS7 User's Guide]]
*[[media:Tb640 sip user's guide.pdf|SIP User’s Guide]]

[[category:Toolpack]]

Web Portal Tutorial Guide v2.5

2011-10-28T14:48:44Z

Alexandre Lussier: /* Configuring H.248 */

=Introduction=
This guide is designed to provide users with a scenario-based approach to installing [[Tmedia]] and [[Tdev]] systems, using the Web Portal configuration tool. This means that users must first go through the steps that are general to all installations, and subsequently follow the instructions that are specific to their particular application scenario (this corresponds to the type of service, and hardware system being set up).

==Prerequisites==
This document assumes that the [[Tmedia]] or [[Tdev]] devices are installed as described in their Quick Reference Guides, and in the case of the Tmedia system communication has been established with the control network.

(Note: Tmedia devices are shipped with the Tmedia Web Portal pre-installed, while Tdev devices require that Toolpack be installed as described in the [http://download.distribution.telcobridges.com/documentation/TMP6400_Installation_Guide.pdf TMP6400 Installation Guide].)

Furthermore, in the case of a Tdev device and the initial configuration of the [[Toolpack]] application server, the following will have been provided:
*The Tdev device to which the Web Portal will first connect.
*The Tdev device will have been pre-configured with its physical TDM interface.
*The serial number of the Tdev device will have been entered into the configuration file.
*The application software for the Tdev device will have been pre-installed on the Toolpack application server, as described in the [http://download.distribution.telcobridges.com/documentation/TMP6400_Installation_Guide.pdf TMP6400 Installation Guide].

This document also assumes familiarity with topics, such as [[ISDN]] signaling, [[SIP]] signaling, [[SS7]], [[CAS|CAS R2]] signaling, and [[SIGTRAN]] signaling.

==Key Concepts==
*'''System:''' A system is defined as the complete solution that is designed for a network. If a system solution is comprised of 4 TMP6400’s and a TMS1600, then the combination of these TelcoBridges devices is termed a system.
*'''Hardware:''' Each TelcoBridges devices, whether it is a TMP6400, TMG3200, or TMS1600 is referred to as a hardware device or hardware adapter.
*'''Line Interface:''' The physical TDM module installed on the TelcoBridges device is referred to as a line interface.

== General Web Portal Applications ==

'''''IMPORTANT!''''' The Topics covered in the following table are common to all TMedia installations. Therefore, this section should be consulted before moving on to any other.

 '''Topics covered here:'''

*The basic knowledge needed to properly navigate through the Web Portal '''(A)'''.
*The fundamentals of user account management and permission masks '''(B)'''.
*The initial steps required for first starting the Web Portal, and verifying that it is functioning properly '''(C)'''.
*The process involved in backing up your database for the first time '''(D)'''.
*The process involved in first configuring your IP interfaces '''(E)'''.

 

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: none repeat scroll 0% 0% rgb(239, 239, 239); -moz-background-inline-policy: continuous;" | (Topic A) Web Portal Basics
! width="200" style="background: none repeat scroll 0% 0% rgb(239, 239, 239); -moz-background-inline-policy: continuous;" | (Topic B) Log-on and User Access Levels
! width="200" style="background: none repeat scroll 0% 0% rgb(239, 239, 239); -moz-background-inline-policy: continuous;" | (Topic C) Application Start-up and Verification
! width="200" style="background: none repeat scroll 0% 0% rgb(239, 239, 239); -moz-background-inline-policy: continuous;" | (Topic D) Database Backup
|-
| valign="top" |
*[[Toolpack v2.5:Navigating the Web Portal|Navigating the Web Portal]]
*[[Typographic conventions|Typographic Conventions]]

 

| valign="top" |
*[[Toolpack v2.5:Connecting to the Web Server and logging on to the web portal|Connect to the web server and log on to the Web Portal]]
*[[Toolpack:User access|User Access]]
**[[Toolpack v2.5:Viewing the User List|Viewing the User List]]
**[[Toolpack v2.5:Creating a New User|Creating a New User]]
**[[Toolpack v2.5:Deleting a User|Deleting a User]]
**[[Toolpack v2.5:Logging Off Toolpack|Logging Off]]
*[https://forums.telcobridges.com/viewtopic.php?f=12&t=248&p=1101&hilit=privilege#p1101 User privilege level]

| valign="top" |
*[[Toolpack v2.5:Viewing the List of Installed Applications|Viewing the List of Installed Applications]]
*[[Toolpack v2.5:Starting an Application|Starting an Application]]
*[[Toolpack:Verifying that an Application is Operating|Verifying that an Application is Operating]]
**[[Toolpack v2.5:Verifying the Application Path|Verifying the Application Path]]
*[[Toolpack v2.5:Activating the Configuration|Activating the Configuration]]
**[[Toolpack v2.5:Status Menus:Applications|Verifying status]]

| valign="top" |
*[[Toolpack v2.5:Database Backup|Carrying out a First Database Backup]]
*[[Toolpack v2.5:Downloading a Database Backup|Downloading a Database Backup]]
*[[Toolpack v2.5:Uploading a Database Backup|Uploading a Database Backup]]
*[[Toolpack v2.5:Restoring a Database Backup|Restoring a Database Backup]]

|-
! width="200" style="background: none repeat scroll 0% 0% rgb(239, 239, 239); -moz-background-inline-policy: continuous;" | (Topic E) Configure IP Interfaces
|-
| valign="top" |
*[[Toolpack v2.5:Configuring IP Interfaces|Configure IP Interfaces]]

|}

=ISDN-SIP Gateway Configuration=

The following tables contain a typical configuration scenario for an [[ISDN]] to [[SIP]] gateway. This type of installation allows for the transfer of information from traditional [[ISDN]] signaling to [[SIP]] protocol for [[VoIP]] applications. Please follow each step one after another as these are listed in logical order.

'''The steps are as follows:'''

*1) Log On and Create a New Configuration
*2) Allocate Physical Interfaces
*3) Configure ISDN-PRI Signaling
*4) Configure Clocking Source
*5) Configure SIP Signaling
*6) Configure Codecs and Tone Detection
*7) Configure Network Access Points (NAPs)
*8) Create Call Routing Rules

'''IMPORTANT!''' After completing the setup process, remember to '''activate the configuration''', as outlined in the [[Web_Portal_Tutorial_Guide_v2.5#General_Web_Portal_Applications|General Web Portal Applications section]].

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 1) Log On and Create a New Configuration

! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 2) Allocate Physical Interfaces

! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 3) Configure ISDN-PRI Signaling

! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 4) Configure Clocking Source

|-
| valign="top" |
*[[Toolpack_v2.5:Connecting_to_the_Web_Server_and logging on to the web portal|Connect to the web server and log on to the Web Portal]]
*[[Toolpack_v2.5:Copying_the_Default_Configuration|Copy the default configuration]]

| valign="top" |
*[[Toolpack_v2.5:Creating_a_Line_Interface|Create a new line interface]]
*[[Toolpack_v2.5:Creating_a_Line_Service|Create a new line service]]

| valign="top" |
*[[Toolpack_v2.5:Configuring_an_ISDN_Stack|Configure an ISDN stack]]
OR 
*[[Configure NFAS]]

| valign="top" |
*[[Toolpack_v2.5:Defining_a_Clocking_Source|Define a clocking source]]

|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 5) Configure SIP Signaling

! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 6) Configure Codecs and Tone Detection

! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 7) Configure Network Access Points (NAPs)

! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 8) Create Call Routing Rules

|-
| valign="top" |
*[[Toolpack_v2.5:Creating_an_IP_Port_Range|Create an IP port range]]
*[[Toolpack_v2.5:Creating_a_SIP_Stack|Create a SIP stack]]
*[[Toolpack_v2.5:Creating_a_SIP_Transport_Server|Create a SIP transport server]]
*[[Toolpack_v2.5:Creating_a_Service_Access_Point_(SAP)|Create a service access point (SAP)]]

| valign="top" |
*[[Toolpack_v2.5:Accessing_Codec_and_Tone_Detection_Profiles_and_Validating_Settings|Access profiles and validate settings]]

| valign="top" |
*[[Toolpack_v2.5:Allocating_an_ISDN_Network_Access_Point_(NAP)|Allocate an ISDN NAP]]
*[[Toolpack_v2.5:Allocating_a_SIP_Network_Access_Point_(NAP)|Allocate a SIP NAP]]

| valign="top" |
*[[Toolpack_v2.5:Creating_a_First_Call_Route|Create a first call route]]
|}

=Configuring SS7=

The following table contains information on configuring the [[SS7]] signaling protocol.
The various control layers of the [[SS7]] protocol are listed individually in each column. These layers are:

* [[MTP2_Layer|MTP2]] layer '''(Step 1)'''
* [[MTP3_Layer|MTP3]] layer '''(Step 2)'''
* [[ISUP]] layer '''(Step 3)'''
* [[SCCP]] layer '''(Step 4)'''
* [[TCAP]] layer '''(Step 5)'''

'''Follow the topics listed in each column from left to right in order to configure an SS7 protocol stack.'''

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 1) Configuring the MTP2 Layer
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 2) Configuring the MTP3 Layer
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 3) Configuring the ISUP Layer
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 4) Configuring the SCCP Layer
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 5) Configuring the TCAP Layer

|-
| valign="top" |
*[[Toolpack_v2.5:Creating_an_MTP2_Configuration|Create an MTP2 Configuration]]
*[[Toolpack_v2.5:Creating_MTP2_Links|Create an MTP2 Link]]

| valign="top" |
*[[Toolpack_v2.5:Creating_an_MTP3_Configuration|Create an MTP3 Configuration]]
*[[Toolpack_v2.5:Creating_an_MTP3_Network|Create an MTP3 Network]]
**[[Toolpack_v2.5:Creating_SS7_Point_Codes|Create an MTP3 Point Code]]
**[[Toolpack_v2.5:Creating_an_MTP3_Linkset|Create an MTP3 Linkset]]
***[[Toolpack_v2.5:Creating_MTP3_Links|Create MTP3 Links]]
**[[Toolpack_v2.5:Creating_an_MTP3_Route|Create an MTP3 Route]]

| valign="top" |
*[[Toolpack_v2.5:Creating_an_ISUP_Stack|Create an ISUP Stack]]
*[[Toolpack_v2.5:Creating_an_ISUP_Network|Create an ISUP Network]]
*[[Toolpack_v2.5:Creating_an_ISUP_User_Part|Create an ISUP User Part]]
*[[Toolpack_v2.5:Creating_an_ISUP_Interface|Create an ISUP Interface]]

| valign="top" |
*[[Toolpack_v2.5:Creating_an_SCCP_Stack| Create an SCCP Stack]]
*[[Toolpack_v2.5:Creating_an_SCCP_Network|Create an SCCP Network]]
**[[Toolpack_v2.5:Creating_an_SCCP_Userpart|Create an SCCP Userpart]]
**[[Toolpack_v2.5:Creating_an_SCCP_LSAP|Create an SCCP LSAP]]
***[[Toolpack_v2.5:Creating_an_SCCP_Route|Create an SCCP Route]]
****[[Toolpack_v2.5:Creating_an_SCCP_SSN|Create an SCCP SSN]]
*[[Toolpack_v2.5:Creating_an_SCCP_GTT_Association|Create an SCCP GTT Association]]
**[[Toolpack_v2.5:Creating_an_SCCP_GTT_Address_Map|Create an SCCP GTT Address Map]]

| valign="top" |
*[[Toolpack_v2.5:Creating_a_TCAP_Stack|Create a TCAP Stack]]
**[[Toolpack_v2.5:Creating_a_TCAP_Userpart| Create a TCAP Userpart]]
*[[Toolpack_v2.5:Activating_the_Configuration|Activating the Configuration]]

|}

=SIGTRAN Application Scenarios=

Toolpack version 2.5 enables you to configure SIGTRAN and thereby extend SS7 signalling functionality to the IP network. Toolpack enables you to configure a number of SIGTRAN applications based upon your requirements. These applications are listed below as follows: 

*[[M2PA]] system. See column '''(A)''' below. In this configuration the SS7 MTP2 layer is replaced by the SIGTRAN M2PA layer which extends MTP2 signalling functionality into the IP network. This application is typically used between a Signalling Gateway and an IP Signalling Point, or between two IP Signalling Points.

*[[M2UA]] system. See columns '''(B)''' and '''(C)''' below. An M2UA system on a Signalling Gateway Controller interfaces with an M2UA system on a Media Gateway Controller. In this configuration, M2UA bridges the SS7 MTP2 layer of a Signalling Gateway, across an IP network, with the SS7 MTP3 layer of a Media Gateway Controller.

*[[IUA]] system. See column '''(D)''' below. An IUA system on a Signalling Gateway Controller interfaces with an IUA system on a Media Gateway Controller. In this configuration, IUA bridges the SS7 MTP2 layer of a Signalling Gateway, across an IP network, with the SS7 MTP3 layer of a Media Gateway Controller.

*[[M3UA]] system on two IP signalling points. See column '''(E''') below. In this configuration the SS7 MTP2 and MTP3 layers are replaced entirely by the SIGTRAN M3UA layer. This application is typically used between two IP Signalling Points.

*[[M3UA]] system. See columns '''(F)''' and '''(G)''' below. An M3UA system on a Signalling Gateway Process interfaces with an M3UA system on an Application Server Process. In this configuration, the MTP3 links are extended across the IP network.

 '''A SIGTRAN scenario walkthrough is provided in the table columns below, to illustrate the order that must be followed when configuring SIGTRAN.''' 

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Scenario A) Configuring an M2PA System
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Scenario B) Configuring an M2UA System on a Signalling Gateway
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Scenario C) Configuring an M2UA System on a Media Gateway Controller
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Scenario D) Configuring an IUA System on a Signalling Gateway
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Scenario E) Configuring an M3UA System on IP Signalling Points
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Scenario F) Configuring an M3UA System on a Signalling Gateway
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Scenario G) Configuring an M3UA System on an Application Server
|-
|
*[[Toolpack v2.5:Adding an Adapter|Adding an Adapter]]
*[[Toolpack v2.5:Creating a Line Interface|Create Line Interfaces]]
*[[Toolpack v2.5:Creating a Line Service|Create Line services]]
*[[Toolpack v2.5:Editing the SCTP Configuration|Edit the SCTP Configuration]]
*[[Toolpack v2.5:Creating the M2PA Configuration|Create an M2PA Configuration]]
**[[Toolpack v2.5:Creating an M2PA SAP|Create an M2PA SAP]]
**[[Toolpack v2.5:Adding M2PA Links|Add M2PA Links]]
*[[Toolpack v2.5:Creating SS7 Point Codes|Create SS7 Point Codes]]
*[[Toolpack v2.5:Creating an MTP3 Configuration|Create an MTP3 Configuration]]
**[[Toolpack v2.5:Creating an MTP3 Network|Create an MTP3 Network]]
**[[Toolpack v2.5:Creating an MTP3 Linkset|Create an MTP3 Linkset]]
***[[Toolpack v2.5:Creating MTP3 Links (M2PA)|Create MTP3 Links]]
**[[Toolpack v2.5:Creating an MTP3 Route|Create an MTP3 Route]]
*[[Toolpack v2.5:Creating an ISUP Stack|Create an ISUP Stack]]
**[[Toolpack v2.5:Creating an ISUP Network|Create an ISUP Network]]
**[[Toolpack v2.5:Creating an ISUP User Part|Create an ISUP User Part]]
**[[Toolpack v2.5:Creating an ISUP Interface|Create an ISUP Interface]]
***[[Toolpack v2.5:Creating ISUP CIC Groups|Create ISUP CIC Groups]]
**[[Toolpack v2.5:Creating a NAP (SIGTRAN)|Create a NAP]]

| valign="top" |
*[[Toolpack v2.5:Adding an Adapter|Adding an Adapter]]
*[[Toolpack v2.5:Creating a Line Interface|Create Line Interfaces]]
*[[Toolpack v2.5:Creating a Line Service|Create Line services]]
*[[Toolpack v2.5:Creating an MTP2 Configuration|Create an MTP2 Configuration]]
**[[Toolpack v2.5:Creating MTP2 Links|Create MTP2 Links]]
*[[Toolpack v2.5:Creating the SCTP Configuration|Edit the SCTP Configuration]]
*[[Toolpack v2.5:Creating the M2UA Configuration|Create an M2UA Configuration]]
**[[Toolpack v2.5:Creating an M2UA SAP|Create an M2UA SAP]]
**[[Toolpack v2.5:Creating an M2UA Cluster|Create an M2UA Cluster]]
**[[Toolpack v2.5:Creating M2UA Links|Create M2UA Links]]
**[[Toolpack v2.5:Creating M2UA Peers|Create M2UA Peers]]

 

| valign="top" |
*[[Toolpack v2.5:Adding an Adapter|Adding an Adapter]]
*[[Toolpack v2.5:Editing the SCTP Configuration|Edit the SCTP Configuration]]
*[[Toolpack v2.5:Creating the M2UA Configuration|Create an M2UA Configuration]]
**[[Toolpack v2.5:Creating an M2UA SAP|Create an M2UA SAP]]
**[[Toolpack v2.5:Creating an M2UA Cluster|Create an M2UA Cluster]]
**[[Toolpack v2.5:Creating M2UA Links|Create M2UA Links]]
**[[Toolpack v2.5:Creating M2UA Peers|Create M2UA Peers]]
*[[Toolpack v2.5:Creating SS7 Point Codes|Create SS7 Point Codes]]
*[[Toolpack v2.5:Creating an MTP3 Configuration|Create an MTP3 Configuration]]
**[[Toolpack v2.5:Creating an MTP3 Network|Create an MTP3 Network]]
**[[Toolpack v2.5:Creating an MTP3 Linkset|Create an MTP3 Linkset]]
**[[Toolpack v2.5:Creating MTP3 Links (M2UA)|Create MTP3 Links]]
**[[Toolpack v2.5:Creating an MTP3 Route|Create an MTP3 Route]]
*[[Toolpack v2.5:Creating an ISUP Stack|Create an ISUP Stack]]
**[[Toolpack v2.5:Creating an ISUP Network|Create an ISUP Network]]
**[[Toolpack v2.5:Creating an ISUP User Part|Create an ISUP User Part]]
**[[Toolpack v2.5:Creating an ISUP Interface|Create an ISUP Interface]]
***[[Toolpack v2.5:Creating ISUP CIC Groups|Create ISUP CIC Groups]]
**[[Toolpack v2.5:Creating a NAP (SIGTRAN)|Create a NAP]]

| valign="top" |
*[[Toolpack v2.5:Adding an Adapter|Adding an Adapter]]
*[[Toolpack v2.5:Creating a Line Interface|Create Line Interfaces]]
*[[Toolpack v2.5:Creating a Line Service|Create Line services]]
*[[Toolpack v2.5:Creating the SCTP Configuration|Edit the SCTP Configuration]]
*[[Toolpack v2.5:Creating the IUA Configuration|Create an IUA Configuration]]
**[[Toolpack v2.5:Creating an IUA SAP|Create an IUA SAP]]
**[[Toolpack v2.5:Creating an IUA Cluster|Create an IUA Cluster]]
**[[Toolpack v2.5:Creating IUA Links|Create IUA Links]]
**[[Toolpack v2.5:Creating IUA Peers|Create IUA Peers]]

 

| valign="top" |
*[[Toolpack v2.5:Adding an Adapter|Adding an Adapter]]
*[[Toolpack v2.5:Editing the SCTP Configuration|Edit the SCTP Configuration]]
*[[Toolpack v2.5:Creating SS7 Point Codes|Create SS7 Point Codes]]
*[[Toolpack v2.5:Creating an M3UA Configuration (IPSP)|Create an M3UA Configuration]]
**[[Toolpack v2.5:Creating an M3UA SAP|Create an M3UA SAP]]
**[[Toolpack v2.5:Creating an M3UA Network|Create an M3UA Network]]
**[[Toolpack v2.5:Creating an M3UA User Part|Create an M3UA User Part]]
**[[Toolpack v2.5:Creating an M3UA Peer Signalling Process (IPSP)|Create an M3UA Peer Signalling Process]]
**[[Toolpack v2.5:Creating an M3UA Peer Server|Create an M3UA Peer Server]]
**[[Toolpack v2.5:Creating an M3UA Route|Create an M3UA Route]]
*[[Toolpack v2.5:Creating an ISUP Stack|Create an ISUP Stack]]
**[[Toolpack v2.5:Creating an ISUP Network|Create an ISUP Network]]
**[[Toolpack v2.5:Creating an ISUP User Part|Create an ISUP User Part]]
**[[Toolpack v2.5:Creating an ISUP Interface|Create an ISUP Interface]]
***[[Toolpack v2.5:Creating ISUP CIC Groups|Create ISUP CIC Groups]]
**[[Toolpack v2.5:Creating a NAP (SIGTRAN)|Create a NAP]]

| valign="top" |
*[[Toolpack v2.5:Adding an Adapter|Adding an Adapter]]
*[[Toolpack v2.5:Creating a Line Interface|Create Line Interfaces]]
*[[Toolpack v2.5:Creating an MTP2 Configuration|Create an MTP2 Configuration]]
*[[Toolpack v2.5:Creating MTP2 Links|Create MTP2 Links]]
*[[Toolpack v2.5:Editing the SCTP Configuration|Edit the SCTP Configuration]]
*[[Toolpack v2.5:Creating SS7 Point Codes|Create SS7 Point Codes]]
*[[Toolpack v2.5:Creating an MTP3 Configuration|Create an MTP3 Configuration]]
**[[Toolpack v2.5:Creating an MTP3 Network|Create an MTP3 Network]]
**[[Toolpack v2.5:Creating an MTP3 Linkset|Create an MTP3 Linkset]]
**[[Toolpack v2.5:Creating MTP3 Links (M3UA)|Create MTP3 Links]]
**[[Toolpack v2.5:Creating an MTP3 Route|Create an MTP3 Route]]
*[[Toolpack v2.5:Creating an M3UA Configuration (SGP)|Create an M3UA Configuration]]
**[[Toolpack v2.5:Creating an M3UA SAP|Create an M3UA SAP]]
**[[Toolpack v2.5:Creating an M3UA Network|Create an M3UA Network]]
**[[Toolpack v2.5:Creating an M3UA User Part|Create an M3UA User Part]]
**[[Toolpack v2.5:Creating an M3UA Peer Signalling Process (SGP)|Create an M3UA Peer Signalling Process]]
**[[Toolpack v2.5:Creating an M3UA Peer Server|Create an M3UA Peer Server]]
**[[Toolpack v2.5:Creating an M3UA Route (SGP)|Create an M3UA Route]] 

| valign="top" |
*[[Toolpack v2.5:Adding an Adapter|Adding an Adapter]]
*[[Toolpack v2.5:Editing the SCTP Configuration|Edit the SCTP Configuration]]
*[[Toolpack v2.5:Creating SS7 Point Codes|Create SS7 Point Codes]]
*[[Toolpack v2.5:Creating an M3UA Configuration (ASP)|Create an M3UA Configuration]]
**[[Toolpack v2.5:Creating an M3UA SAP|Create an M3UA SAP]]
**[[Toolpack v2.5:Creating an M3UA Network|Create an M3UA Network]]
**[[Toolpack v2.5:Creating an M3UA User Part|Create an M3UA User Part]]
**[[Toolpack v2.5:Creating an M3UA Peer Signalling Process (ASP)|Create an M3UA Peer Signalling Process]]
**[[Toolpack v2.5:Creating an M3UA Peer Server|Create an M3UA Peer Server]]
**[[Toolpack v2.5:Creating an M3UA Route|Create an M3UA Route]]
*[[Toolpack v2.5:Creating an ISUP Stack|Create an ISUP Stack]]
**[[Toolpack v2.5:Creating an M3UA ISUP Network|Create an M3UA ISUP Network]]
**[[Toolpack v2.5:Creating an ISUP User Part|Create an ISUP User Part]]
**[[Toolpack v2.5:Creating an ISUP Interface|Create an ISUP Interface]]
***[[Toolpack v2.5:Creating ISUP CIC Groups|Create ISUP CIC Groups]]
**[[Toolpack v2.5:Creating a NAP (SIGTRAN)|Create a NAP]]

|}

=Configuring CAS R2=

Toolpack v2.5 allows you to configure CAS R2 signaling stacks. The following table lists the basic steps that must be followed in order to configure CAS R2.

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | Configuring a CAS R2 stack

|-
| valign="top" |
*[[Toolpack v2.5:Adding an Adapter|Adding an Adapter]]
*[[Toolpack_v2.5:Creating_a_Line_Interface|Create Line Interfaces]]
*[[Toolpack_v2.5:Creating_a_Line_Service|Create Line services]]
*[[Toolpack v2.5:Copy variant script|Copy variant script]] (optional)
*[[Toolpack v2.5:Create CAS R2 stack|Create CAS R2 stack]]
*[[Toolpack_v2.5:Creating_a_CAS_R2_NAP|Create a NAP]]

|}

=Configuring H.248=

The following table contains steps for configuring an H.248 media gateway control protocol

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 1) Add a Hardware Adapter
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 2) Allocate Physical Interfaces
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 3) Create IP Port Ranges
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 4) Configure Network Access Points (NAPs)

|-
| valign="top" |
*[[Toolpack_v2.5:Adding_an_Adapter|Adding an Adapter]]

| valign="top" |
*[[Toolpack_v2.5:Creating_a_Line_Interface|Create line interfaces]]
*[[Toolpack_v2.5:Creating_a_Line_Service|Create line services]]

| valign="top" |
*[[Toolpack_v2.5:Creating_an_IP_Port_Range|Create IP port ranges]]

| valign="top" |
*[[Toolpack_v2.5:Allocating_a_VoIP_Network_Access_Point_(NAP)|Allocate a VoIP network access point (NAP)]]
*[[Toolpack_v2.5:Allocating_a_TDM_Network_Access_Point_(NAP)|Allocate a TDM network access point (NAP)]]

|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 5) Configure the Media Gateway for H.248 mode
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 6) Create an H.248 Configuration
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 7) Add a New Media Gateway Controller
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 8) Associate NAPs with the H.248 Configuration

|-
| valign="top" |
*[[Toolpack_v2.5:Creating_an_H.248_Configuration|Create a new H.248 configuration]]

| valign="top" |
*[[Toolpack_v2.5:Configure the Media_Gateway_for_H248_Mode|Configure the Media Gateway for H.248 mode]]

| valign="top" |
*[[Toolpack_v2.5:Adding_a_Media_Gateway_Controller_(MGC)|Add a new media gateway controller (MGC)]]

| valign="top" |
*[[Toolpack_v2.5:Associating_NAPs_with_an_H.248_Configuration|Associate the NAPs with the H.248 configuration]]

|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (Step 9) Select Timeslots for TDM Terminations

|-
| valign="top" |
*[[Toolpack_v2.5:Selecting_Timeslots_for_TDM_Interfaces|Select timeslots for the TDM interfaces]]
|}

=Configuring an H.323 to SIP Converter=

The following table contains steps for configuring NAPs that wil allow an interface between the web portal and a YATE H.323 to SIP signal converter:

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | Configuring an H.323 to SIP Signal Converter

|-
| valign="top" |

* [[Toolpack_v2.5:Creating_H.323_NAP_Columns|Create H.323 NAP columns]]
*[[Toolpack_v2.5:Creating_an_IP_Port_Range|Create an IP port range]]
*[[Toolpack_v2.5:Creating_a_SIP_Stack|Create a SIP stack]]
*[[Toolpack_v2.5:Creating_a_SIP_Transport_Server|Create a SIP transport server]]
*[[Toolpack_v2.5:Creating_a_Service_Access_Point_(SAP)|Create a service access point (SAP)]]
* [[Toolpack_v2.5:Creating_SIP_NAPs_(H.323)|Create SIP NAPs]]
|}

=Configuring SNMP=

To use the Simple Network Management Protocol (SNMP)on your machine, you must first configure the '''tbSnmpAgent'''.
 The '''tbSnmpAgent''' is a software application that interfaces between the TMedia system hardware and the [http://www.net-snmp.org NetSnmp] implementation of the SNMP that is supported by TelcoBridges.
By default, tbSnmpAgent is '''disabled'''. In order to use the SNMP protocol to monitor and manage your hardware, the following steps must be taken:
 
* tbSnmpAgent must be '''activated'''
* tbSnmpAgent must be '''configured''' to suit your needs
 
The aforementioned tasks can be accomplished through the [[Web Portal]]:
 
#[[Activating tbSnmpAgent|Activate tbSnmpAgent]]
#[[Configuring tbSnmpAgent|Configure tbSNMPAGENT to suit your needs]]
 
Once these tasks have been completed, your TMedia platform is ready to expose system variables for polling with the Simple Network management Protocol (SNMP).

=Status Menus=

The Web Portal configuration tool will guide you through a number of status menus, each of which indicate the current state of a certain hardware service (assuming said service has been configured).
The following table contains the general conventions of the Web Portal's display '''(A)''', as well as a variety of specific status menus '''(B)'''.

{| cellpadding="5" border="1" class="wikitable"
|-
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (A) Menus Overview
! width="200" style="background: rgb(239, 239, 239) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;" | (B) Individual Menu Descriptions

|-
| valign="top" |

*[[Toolpack_v2.5:Tmedia_Status_Menus|Tmedia Status Menus]]
**[[Toolpack_v2.5:Status_Menus:Navigation|Navigation]]
**[[Toolpack_v2.5:Status_Menus:Screen_Conventions|Status Screen Conventions]]

| valign="top" |

*[[Toolpack_v2.5:Status_Menus:System|System]]
*[[Toolpack_v2.5:Status_Menus:Adapters_and_IP_Interfaces|Adapters and IP Interfaces]]
*[[Toolpack_v2.5:Status_Menus:Hosts|Hosts]]
*[[Toolpack_v2.5:Status_Menus:Applications|Applications]]
*[[Toolpack_v2.5:Status_Menus:TDM_Lines|TDM Lines]]
*[[Toolpack_v2.5:Status_Menus:SCTP|SCTP]]
*[[Toolpack_v2.5:Status_Menus:SS7_MTP2|SS7 MTP2]]
*[[Toolpack_v2.5:Status_Menus:SS7_M2UA|SS7 M2UA]]
*[[Toolpack_v2.5:Status_Menus:SS7_IUA|SS7 IUA]]
*[[Toolpack_v2.5:Status_Menus:SS7_M2PA|SS7 M2PA]]
*[[Toolpack_v2.5:Status_Menus:SS7_M3UA|SS7 M3UA]]
*[[Toolpack_v2.5:Status_Menus:SS7_MTP3|SS7 MTP3]]
*[[Toolpack_v2.5:Status_Menus:SS7_ISUP|SS7 ISUP]]
*[[Toolpack_v2.5:Status_Menus:SS7_SCCP|SS7 SCCP]]
*[[Toolpack_v2.5:Status_Menus:SS7_TCAP|SS7 TCAP]]
*[[Toolpack_v2.5:Status_Menus:ISDN|ISDN]]
**[[Toolpack_v2.5:Status_Menus:NFAS|NFAS]]
*[[Toolpack_v2.5:Status_Menus:CASR2|CASR2]]
*[[Toolpack_v2.5:Status_Menus:SIP|SIP]]
*[[Toolpack_v2.5:Status_Menus:Clock|Clock]]
*[[Toolpack_v2.5:Status_Menus:TMS|TMS]]
*[[Toolpack_v2.5:Status_Menus:NAP|NAP]]
*[[Toolpack_v2.5:Status_Menus:H.248|H.248]]
*[[Toolpack_v2.5:Status_Menus:CDR|CDR]]

|}

=Further Reading=
For further information, refer to the following reading list. Please note that all guides listed below are in portable document format (*.PDF), and can be downloaded:

*[[media:TMedia System Architecture Description.pdf|TMedia System Architecture Overview for Developers of VoIP and TDM Solutions]]
*[[Media:Tb640 user's guide.pdf|TB640 User's Guide]]
*[[media:SS7 user's guide.pdf|TelcoBridges SS7 User's Guide]]
*[[media:Tb640 sip user's guide.pdf|SIP User’s Guide]]

[[category:Toolpack]]

Tone definitions

2011-10-07T21:23:46Z

Alexandre Lussier:

=== Tone definitions ===

It is possible through the [[Toolpack]] [[Web Portal]] to specify the parameters of ringing, busy, congestion (or fast busy) and warning call progress tones. These settings are available in
<pre>Profiles -> Tone Profile Params </pre>
The tones are described using a programmable string of characters as defined in the [[H.248]] Dynamic Tone Definition Package. To learn more about tone description strings, see the [[CAF: Working With Call Legs#Play_Tone_with_Signal_Id_String|section]] related to this subject.

=== Examples of Call Progress tones ===

The following table contains a few call progress tone definition strings that can be used to replace the default ones in the Toolpack Web Portal.

{| cellspacing="1" cellpadding="2" border="1"
|-
! 
! Ring
! Busy
! Congestion
! Warning
|-
! Australia 
| ((((#400)+(#450)),400),(#0,200),(((#400)+(#450)),400),(#0,2000))*0 
| ((#425,375),(#0,375))*0 
| ((#425,375),(#0,375))*0 
| ((#900),500) 
|-
! Bangladesh 
| ((#425,1000),(#0,4000))*0 
| ((#450,200),(#0,300),(#450,700),(#0,800))*0 
| ((#425,250),(#0,250))*0 
| ((#450,200),(#0,20),(#450,200),(#0,140))*0 
|-
! Brazil
| ((#425,1000),(#0,4000))*0
| ((#425,250),(#0,250))*0
| ((#425,750),(#0,250),(#425,250),(#0,250))*0
| ''unused''
|-
! China
| ((#450,1000),(#0,4000))*0
| ((#450,350),(#0,350))*0
| ((#450,700),(#0,700))*0
| ''unused''
|-
! France
| ((#440,1500),(#0,3500))*0
| ((#450,500),(#0,500))*0
| ''unused''
| ''unused''
|-
! Germany
| ((#425,1000),(#0,4000))*0
| ((#425,480),(#0,480))*0
| ((#425,240),(#0,240))*0
| ((#425,240),(#0,240),(#425,240),(#0,1280))*0
|-
! Hong Kong
| ((((#440)+(#480)),400),(#0,200),(((#440)+(#480)),400),(#0,3000))*0
| ((((#480)+(#620)),500),(#0,500))*0
| ((((#480)+(#620)),250),(#0,250))*0
| ''unused''
|-
! Netherlands 
| ((#425,1000),(#0,4000))*0 
| ((#425,500),(#0,500))*0 
| ((#425,250),(#0,250))*0 
| ''unused'' 
|-
! North America
| ((((#440)+(#480)),2000),(#0,4000))*0
| ((((#480)+(#620)),500),(#0,500))*0
| ((((#480)+(#620)),250),(#0,250))*0
| ((#1400),500)
|-
! Spain
| ((#425,1500),(#0,3000))*0
| ((#425,200),(#0,200))*0
| ((#425,200),(#0,200),(#425,200),(#0,200),(#425,200),(#0,600))*0
| (((#1400),400),(#0,5000))*0
|-
! United Kingdom
| ((((#400)+(#450)),400),(#0,200),(((#400)+(#450)),400),(#0,2000))*0
| ((#400,375),(#0,375))*0
| ((#400,400),(#0,350),(#400,225),(#0,525))*0
| ''unused''
|}

{| cellspacing="1" cellpadding="2" border="1"
|-
! The Moon...
| ((#262,2000),(#391,2000),(#523,4000),(((#659)+(#523)),250),(((#622)+(#523)),3750),(#262,400),(#196,400),(#262,400),(#196,400),(#262,400),(#196,400),(#262,400),(#196,400),(#262,420),(#196,460),(#262,540),(#196,620))*0
|}

=== Playing and collecting tones ===

To learn how to play these tones using the [[CAF: Working With Call Legs|Call Leg API]], refer to the [[CAF: Working With Call Legs#Playing_and_Collecting_Tones|Playing and Collecting Tones section]].

For example, to play the '''ringing''' tone, one could pass either directly <code>((((#440)+(#480)),2000),(#0,4000))*0</code> or <code>cg/rt</code> to the '''AddToneString()''' function. The <code>cg/rt</code> string refers to the current Tone Profile Params ringing tone setting from the Web Portal.

=== Tone volume ===

It is possible to change the ring tone volume. According to the syntax, you need to specify the desired volume after the tone duration. Here is an example:
((((#440)+(#480)),2000,'''-15'''),(#0,4000))*0

The possible values are: -19, -15, -10, -5 and 0 dB.

=== Available tones ===

Below is a comprehensive list of all the tone strings that can be passed to the '''AddToneString()''' function.

{|
|-
| valign="top" |
{| cellspacing="1" cellpadding="2" border="1"
|+ '''Tone generation'''
|-
! Package
! Signal
! String
|-
| valign="top" rowspan="16" | Basic DTMF generation
| 0
| dg/d0
|-
| 1
| dg/d1
|-
| 2
| dg/d2
|-
| 3
| dg/d3
|-
| 4
| dg/d4
|-
| 5
| dg/d5
|-
| 6
| dg/d6
|-
| 7
| dg/d7
|-
| 8
| dg/d8
|-
| 9
| dg/d9
|-
| *
| dg/ds
|-
| #
| dg/do
|-
| A
| dg/da
|-
| B
| dg/db
|-
| C
| dg/dc
|-
| D
| dg/dd
|-
| valign="top" rowspan="4" | Call Progress generation
| Ring
| cg/rt
|-
| Busy
| cg/bt
|-
| Congestion
| cg/ct
|-
| Warning
| cg/wt
|-
| valign="top" rowspan="12" | MF tone generation
| 0
| mfg/mf0
|-
| 1
| mfg/mf1
|-
| 2
| mfg/mf2
|-
| 3
| mfg/mf3
|-
| 4
| mfg/mf4
|-
| 5
| mfg/mf5
|-
| 6
| mfg/mf6
|-
| 7
| mfg/mf7
|-
| 8
| mfg/mf8
|-
| 9
| mfg/mf9
|-
| KP
| mfg/mfa
|-
| ST
| mfg/mfe
|-
| valign="top" rowspan="2" | Telcofax
| CNG
| telcofax/cng
|-
| g164
| telcofax/g164
|}

| valign="top" |
{| cellspacing="1" cellpadding="2" border="1"
|+ '''Tone detection'''
|-
! Package
! Signal
! String
|-
| valign="top" rowspan="16" | Basic DTMF detection
| 0
| dd/d0
|-
| 1
| dd/d1
|-
| 2
| dd/d2
|-
| 3
| dd/d3
|-
| 4
| dd/d4
|-
| 5
| dd/d5
|-
| 6
| dd/d6
|-
| 7
| dd/d7
|-
| 8
| dd/d8
|-
| 9
| dd/d9
|-
| *
| dd/ds
|-
| #
| dd/do
|-
| A
| dd/da
|-
| B
| dd/db
|-
| C
| dd/dc
|-
| D
| dd/dd
|-
| valign="top" rowspan="12" | MF tone generation
| 0
| mfd/mf0
|-
| 1
| mfd/mf1
|-
| 2
| mfd/mf2
|-
| 3
| mfd/mf3
|-
| 4
| mfd/mf4
|-
| 5
| mfd/mf5
|-
| 6
| mfd/mf6
|-
| 7
| mfd/mf7
|-
| 8
| mfd/mf8
|-
| 9
| mfd/mf9
|-
| KP
| mfd/mfa
|-
| ST
| mfd/mfe
|-
| valign="top" rowspan="3" | Telcofax
| CNG
| telcofax/cng
|-
| g164
| telcofax/g164
|-
| g165
| telcofax/g165
|}

|}

=== References ===

*[http://www.itu.int/publ/T-SP-E.180-2003/en Various tones used in national networks]
*[http://www.itu.int/rec/T-REC-H.248.6-200011-I/en H.248 Gateway Control Protocol Dynamic Tone Definition Package]
*[http://www.itu.int/rec/T-REC-H.248.1-200509-I/en H.248 Gateway Control Protocol] section E.7 (Call Progress Tone Definitions Package)

[[Category:Needs_revising]]

Toolpack Debug Application:Tbsigtrace

2011-06-23T17:29:17Z

Alexandre Lussier: /* Examples */

Tbsigtrace is a debug tool that is use to collect protocol messages. It can trace SS7, ISDN, SIP, Sigtran and CAS messages and put it in a [http://www.wireshark.org wireshark] format. 

 

== Application Location ==

The binary is located in the [InstallDir]/[PackageVersion]/bin/release/[Platform]/

Example:

Version 2.5.55, TMG unit (PPC 32bits)

/lib/tb/toolpack/pkg/2.5.55/bin/release/ppc-linux/tbsigtrace

Version 2.5.55, CentOS 64 bits system

/lib/tb/toolpack/pkg/2.5.55/bin/release/x86_64-linux64/tbsigtrace

Version 2.5.55, Windows system

C:\TelcoBridges\toolpack\pkg\2.5.55\bin\release\i586-win32\tbsigtrace.exe

== How to use it ==

=== Command line ===

Options available:

:-d Daemon mode
:-name XYZ Application name
:-db Not used
:-c XYZ Configuration file to load
:-gw XYZ [[System Id|SystemId]] (i.e. 12358)
:-adapter TBXYZ Adapter name to connect or "all" to connect to all adapter in the system
:-ss7 Default ss7 trace activation
:-isdn Default isdn trace activation
:-ip Default ip trace activation (sip, sigtran and iua)
:-h248 Default h248 trace activation
:-lapd Default lapd trace activation
:-cap CAP format enabled

==== Examples ====

This will gather all ss7 links from one blade and put this in a single cap file

tbsigtrace -gw 12358 -adapter TB000544 -ss7 -cap

This will gather all isdn links from one blade and put them in several files

tbsigtrace -gw 12358 -adapter TB000544 -isdn -cap

This will gather all sip traces and put them in a single cap file

tbsigtrace -gw 12358 -adapter TB000544 -sip -cap

 In release 2.4 This will gather all sip and sigtran traces and put them in a single cap file for all adapters in the system

tbsigtrace -gw 12358 -adapter all -ip -cap

This will gather all h248 messages on the system and put this in a single cap file

tbsigtrace -gw 12358 -adapter TB000544 -h248 -cap

This will gather all IUA (ip and tdm sides) messages on the system and put this in a single cap file

tbsigtrace -gw 12358 -adapter TB000544 -ip -lapd -cap

=== Configuration file (optional) ===

The configuration file will allow to get several blades in the same file

Example MTP2_LINK_0,MTP2_LINK_1 are on the same blade and MTP2_LINK_10,MTP2_LINK_11 are on an other blade

<signaling>

<sysmgr name = "MTP2_LINK_0" grpname="LS1" capfile="true" />
<sysmgr name = "MTP2_LINK_1" grpname="LS1" capfile="true" />
<sysmgr name = "MTP2_LINK_10" grpname="LS1" capfile="true" />
<sysmgr name = "MTP2_LINK_11" grpname="LS1" capfile="true" />

</signaling>

=== Web ===

You can start/stop tbsigtrace via web. 

Create a new application configuration:
<pre>Name -> oamsigtrace
Application Type -> User Specific
Bin Path -> @{PKG_BIN}/tbsigtrace
Working Path -> ../tbsigtrace
Command-line arguments -> -adapter all -ss7 -cap

</pre>
Create a new application instance: 
<pre>Name -> oamsigtrace
Host -> (put required host)
Application Config -> oamsigtrace

</pre>
You can control the application "oamsigtrace" with the application status page OR you can use the option 'o' in tboamapp (page=Application launch manager) and change the state of oamsigtrace application state (0=stop 1-mgmt 2-run). 

'''WARNING: tbsigtrace application should not be used all the time, otherwise it will reduce performance and fill completely your hard drive'''.

Toolpack Debug Application:Tbsigtrace

2011-06-23T17:28:05Z

Alexandre Lussier: /* Command line */

Tbsigtrace is a debug tool that is use to collect protocol messages. It can trace SS7, ISDN, SIP, Sigtran and CAS messages and put it in a [http://www.wireshark.org wireshark] format. 

 

== Application Location ==

The binary is located in the [InstallDir]/[PackageVersion]/bin/release/[Platform]/

Example:

Version 2.5.55, TMG unit (PPC 32bits)

/lib/tb/toolpack/pkg/2.5.55/bin/release/ppc-linux/tbsigtrace

Version 2.5.55, CentOS 64 bits system

/lib/tb/toolpack/pkg/2.5.55/bin/release/x86_64-linux64/tbsigtrace

Version 2.5.55, Windows system

C:\TelcoBridges\toolpack\pkg\2.5.55\bin\release\i586-win32\tbsigtrace.exe

== How to use it ==

=== Command line ===

Options available:

:-d Daemon mode
:-name XYZ Application name
:-db Not used
:-c XYZ Configuration file to load
:-gw XYZ [[System Id|SystemId]] (i.e. 12358)
:-adapter TBXYZ Adapter name to connect or "all" to connect to all adapter in the system
:-ss7 Default ss7 trace activation
:-isdn Default isdn trace activation
:-ip Default ip trace activation (sip, sigtran and iua)
:-h248 Default h248 trace activation
:-lapd Default lapd trace activation
:-cap CAP format enabled

==== Examples ====

This will gather all ss7 links from one blade and put this in a single cap file

tbsigtrace -gw 12358 -adapter TB000544 -ss7 -cap

This will gather all isdn links from one blade and put them in several files

tbsigtrace -gw 12358 -adapter TB000544 -isdn -cap

This will gather all sip traces and put them in a single cap file

tbsigtrace -gw 12358 -adapter TB000544 -sip -cap

 In release 2.4 This will gather all sip and sigtran traces and put them in a single cap file for all adapters in the system

tbsigtrace -gw 12358 -adapter all -ip -cap

This will gather all h248 messages on the system and put this in a single cap file

tbsigtrace -gw 12358 -adapter TB000544 -h248 -cap

=== Configuration file (optional) ===

The configuration file will allow to get several blades in the same file

Example MTP2_LINK_0,MTP2_LINK_1 are on the same blade and MTP2_LINK_10,MTP2_LINK_11 are on an other blade

<signaling>

<sysmgr name = "MTP2_LINK_0" grpname="LS1" capfile="true" />
<sysmgr name = "MTP2_LINK_1" grpname="LS1" capfile="true" />
<sysmgr name = "MTP2_LINK_10" grpname="LS1" capfile="true" />
<sysmgr name = "MTP2_LINK_11" grpname="LS1" capfile="true" />

</signaling>

=== Web ===

You can start/stop tbsigtrace via web. 

Create a new application configuration:
<pre>Name -> oamsigtrace
Application Type -> User Specific
Bin Path -> @{PKG_BIN}/tbsigtrace
Working Path -> ../tbsigtrace
Command-line arguments -> -adapter all -ss7 -cap

</pre>
Create a new application instance: 
<pre>Name -> oamsigtrace
Host -> (put required host)
Application Config -> oamsigtrace

</pre>
You can control the application "oamsigtrace" with the application status page OR you can use the option 'o' in tboamapp (page=Application launch manager) and change the state of oamsigtrace application state (0=stop 1-mgmt 2-run). 

'''WARNING: tbsigtrace application should not be used all the time, otherwise it will reduce performance and fill completely your hard drive'''.

Toolpack Debug Application:Tbsigtrace

2010-12-10T16:31:17Z

Alexandre Lussier: /* Command line */

Tbsigtrace is a Toolpack debug tool that is use to collect protocol messages.

== Where it is located ==

The binary is located in the [InstallDir]/[PackageVersion]/bin/release/[Platform]/

Example:

Version 2.3.3, Windows system
C:\TelcoBridges\toolpack\pkg\2.3.3\bin\release\i586-win32\tbsigtrace.exe
Version 2.3.5, CentOS 64 bits system
/lib/tb/toolpack/pkg/2.3.5/bin/release/x86_64-linux64/tbsigtrace

== How to use it ==

=== Command line ===

Options available:

:-d Daemon mode
:-name XYZ Application name
:-db Not used
:-c XYZ Configuration file to load
:-gw XYZ [[System Id|SystemId]] (i.e. 12358)
:-adapter TBXYZ Adapter name to connect or "all" to connect to all adapter in the system
:-ss7 Default ss7 trace activation
:-isdn Default isdn trace activation
:-ip Default ip trace activation (sip and sigtran)
:-h248 Default h248 trace activation
:-cap CAP format enabled
:-regroup Regroup entity of same type

==== Examples ====

This will gather all ss7 links from one blade and put this in a single cap file

tbsigtrace -gw 12358 -adapter TB000544 -ss7 -regroup -cap

This will gather all isdn links from one blade and put them in several files

tbsigtrace -gw 12358 -adapter TB000544 -isdn -cap

This will gather all sip traces and put them in a single cap file

tbsigtrace -gw 12358 -adapter TB000544 -sip -regroup -cap

 In release 2.4 This will gather all sip and sigtran traces and put them in a single cap file for all adapters in the system

tbsigtrace -gw 12358 -adapter all -ip -regroup -cap

This command will regroup all signaling types by group in 3 files (1 file for ss7, 1 for isdn and a last for sip( or ip)).

tbsigtrace -gw 12358 -adapter TB000544 -regroup -cap

This will gather all h248 messages on the system and put this in a single cap file

tbsigtrace -gw 12358 -adapter TB000544 -h248 -cap

=== Configuration file (optional) ===

The configuration file will allow to get several blades in the same file

Example MTP2_LINK_0,MTP2_LINK_1 are on the same blade and MTP2_LINK_10,MTP2_LINK_11 are on an other blade

<signaling>

<sysmgr name = "MTP2_LINK_0" grpname="LS1" capfile="true" />
<sysmgr name = "MTP2_LINK_1" grpname="LS1" capfile="true" />
<sysmgr name = "MTP2_LINK_10" grpname="LS1" capfile="true" />
<sysmgr name = "MTP2_LINK_11" grpname="LS1" capfile="true" />

</signaling>

=== Web ===

You can start/stop tbsigtrace via web. 

Create a new application configuration:
<pre>Name -> oamsigtrace
Application Type -> User Specific
Bin Path -> @{PKG_BIN}/tbsigtrace
Working Path -> ../tbsigtrace
Command-line arguments -> -adapter all -ss7 -regroup -cap

</pre>
Create a new application instance: 
<pre>Name -> oamsigtrace
Host -> (put required host)
Application Config -> oamsigtrace

</pre>
You can control the application "oamsigtrace" with the application status page OR you can use the option 'o' in tboamapp (page=Application launch manager) and change the state of oamsigtrace application state (0=stop 1-mgmt 2-run). 

'''WARNING: tbsigtrace application should not be used all the time, otherwise it will reduce performance and fill completely your hard drive'''.

H.248

2010-12-08T20:23:30Z

Alexandre Lussier: /* TelcoBridges and H.248 */

Also known as Megaco, H.248 is a protocol for controlling media gateways via a [[Softswitch|softswitch]] or a [[Media gateway controller|media gateway controller]].

== TelcoBridges and H.248 ==
[[Toolpack]] now supports the H.248 protocol.

As indicated in the diagram below, the H.248 stack is a module in the media gateway application residing on the application server. It communicates with the various Toolpack classes (CAFClass, [[CMC library|CMC Library]], CMC Class) as required via a new [[CAF:_Working_With_Call_Legs|Media Leg API]]. In turn, the media gateway application communicates with the softswitch / media gateway controller via the H.248 protocol.

[[Image:H.248 schematic.jpg|H.248 schematic.jpg]]

=== H.248 package support ===
[[Toolpack]] supports the following packages.

*'''H.248.1'''
**Protocol v2
**IPSec connection support
**Support UDP (2944 or user-defined)

*'''H.248.1 - Basic packages'''
**Generic
**Base Root
**Tone generator (for extension purposes only)
**Tone detection (for extension purposes only)
**Basic DTMF generation
**DTMF detection
**Call Progress Tones Generator
**Basic continuity package
**Network package
**RTP package
**TDM Circuit package

*'''H.248.2 Facsimile, text conversation and call discrimination packages'''
**Fax/TextPhone/Modem tones detection (fax and data only)
**Call type discrimination package (fax and data only)
**IP Fax (Event: Fax Connection Change - end of fax session, call terminating)

*'''H.248.4 Transport over Stream Control Transmission Protocol (SCTP)'''

*'''H.248.7 Generic announcement package'''
**Generic announcement package

*'''H.248.10 Media gateway resource congestion handling package'''
**Congestion handling package

*'''H.248.11 Media gateway overload control package'''
**Overload control package

*'''H.248.13 Quality alert ceasing package'''
**Quality alert ceasing package

*'''H.248.14 Inactivity timer package'''
**Inactivity timer package

== Additional details ==
*Support for text mode only
*Not supported on Solaris builds

== References ==
*[http://en.wikipedia.org/wiki/Megaco Wikipedia article]

[[category:Glossary]]
[[category:Needs revising]]

CAF: Working With Call Legs

2010-06-21T19:57:02Z

Alexandre Lussier: /* Play Tone with Custom Tone String */

== Call Leg Definition ==
The main mechanism through which the customer application controls the [[Toolpack]] system is via the management of call legs. The application creates a call leg (or more than one for conferencing and bridging) at the beginning of a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.

A call leg is represented by an instance of the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html CTBCMCLeg] class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 [[timeslot]]) or a [[SIP]] call with its associated [[VoIP]] [[Voice codecs|codec]] resource (attached to an IP/UDP endpoint). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (VOIP codec resource attached to an IP/UDP endpoint). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.

The CTBCMCLeg class allows a programmer to easily act upon the call leg to influence the signaling portion (e.g. accept, answer, terminate, etc) and to use the media portion as well (e.g play prompts, record voice, play or collect digits and tones).

Other member functions are available to retrieve (and change in some cases) the call leg attributes including the media profile (e.g. parameters to the media resource) or signaling information (e.g. protocol type, called and calling party numbers, etc). Joining/unjoining (connection/disconnection) of call legs is also a typical action handled by this class for ’gateway-type’ applications. It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse a ''call leg'' with a ''call''. A ''call leg'' represents one full-duplex link to a party while a ''call'' represents the agglomeration of multiple (two or more) call legs. For example, a ''bridge'' is a form of ''call'' that uses two ''call legs''.
* Do not confuse the base class CTBCMCLeg with the class [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_leg.html CTBCAFCallLeg]. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs. It is designed to represent a leg within a call. It cannot be instanciated as a standalone object without modifications to make it independent from the ITBCAFCallFlow interface.
* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

== Command Flow for Leg Actions in CAF ==
All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).

For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.

== Leg Creation ==
Creating a leg is always done through the definition of a ''call leg attribute''. The values entered in the ''call leg attribute'' will define the type of call leg created and its parameters. The following sections describe several scenarios in which you build a ''call leg''. Instruction will be given on how to fill the leg attributes and how to use them to create the ''call leg''.

=== Preparing Leg Attributes ===

==== Normal Call Leg Attributes ====
For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
* the called number,
* the calling number,
* the [[NAP | Network Access Point]].

Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|NAP Types]]).

The following code snippet shows how to build the attributes.
PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();

ptrOutgoingLegAttribute->GetCalledNumber() = "123-4567";
ptrOutgoingLegAttribute->GetCallingNumber() = "987-6543";
ptrOutgoingLegAttribute->GetNetworkAccessPoint() = "NAP_SS7_MONTREAL";

==== Media-only Leg Attributes ====
For media-only legs, no signaling information is needed but the user can specify which media channel to use and which media profile to use. The only required parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''MEDIA TDM'' or ''MEDIA VOIP'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;

ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();

ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;

When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. For ''MEDIA TDM'' NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For ''MEDIA VOIP'' NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and a timeslot number can be specified.

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc->Settings.TdmAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
pMediaDesc->Settings.TdmAudio.un8Timeslot = 5;
Strncpy
(
pMediaDesc->Settings.TdmAudio.szTrunkName,
"TRUNK_TORONTO_1",
sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
);

For VOIP legs, the user can control the media by providing local [[SDP]] and peer SDP. Setting the local SDP defines the codec and IP/port used to for the received media stream. Most of the time, the IP address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and IP/port used for the transmitted media stream. Note that Toolpack only allows for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in '''both''' SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].

TBX_RESULT Result;
TBX_SDP_INFO SdpInfo;
PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();
pMediaDesc->Settings.PacketAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;

// Set Local SDP
Result = BuildSdpInfo("", 0, SdpInfo); // No IP specified, Toolpack will choose one
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

// Set Peer SDP
Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo); // Using peer IP address and port
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetPeerSDP(SdpInfo);

=== Creating the Leg ===
Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CreateCall '''CreateCall()'''] on it. No action is taken when an instance of a CTBCMCLeg is created. Call resources are only allocated in the Toolpack system when '''CreateCall()''' is called on the object.

pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
pCallLeg->CreateCall();

For legs with signaling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).

[[Image:CallFlow SignalingMediaLeg Creation.JPG|thumb|center|350px|Call flow for creation of leg with signaling]]

For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.

[[Image:CallFlow MediaOnlyLeg Creation.JPG|thumb|center|350px|Call flow for media-only leg creation]]

Once a call is fully active (call answered and media allocated), event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnProfileChanged '''OnProfileChanged()'''] will be sent on the leg. In the cases where the user had not specified the IP/port to use, once this event is received, the media profile has been updated with the values chosen by Toolpack and the updated values can be retrieved using the functions '''GetLocalSDP()''' and '''GetPeerSDP()''' of the profile.
Note that the '''OnProfileChanged()''' event is also sent after the media profile has been modified with the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ChangeProfile '''ChangeProfile()'''] function (see [[#Modifying Media Profile|Modifying Media Profile]]) and when a connected peer has requested it (through a SIP re-INVITE for example).

See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.

=== Caveats ===
* The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).

== Interaction with Legs ==

=== Playing and Collecting Digits ===

You can play digits by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayDigit '''PlayDigit()'''] on a leg. Toolpack will receive the request and play the digits. Once digits are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitPlayingDone '''OnDigitPlayingDone()'''] event.

 You can also configure a leg to collect digits played. To start the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartDigitCollection '''StartDigitCollection()'''] on the leg. To stop the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopDigitCollection '''StopDigitCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitCollected '''OnDigitCollected()'''] event when there will be a match between the asked string and the digits collected.

 Here are examples how to play and collect digit.

===== Play Digit =====

<code></code>
<pre>ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
/* this will play the sequence of digit 5551234 */
ptrOutgoingLeg->PlayDigit( "5551234" );
}
</pre>
===== Collect Digit =====

<code></code>
<pre>ptrIncomingLeg = GetIncomingActiveLeg();
if( ptrIncomingLeg != NULL )
{
/*
this will collect digits 5, any sequences of 7 digits beginning by 3 or any sequences of 7 digits
beginning by 4,5,6 or 7 followed by 5 and 5.
*/
ptrIncomingLeg->StartDigitCollection( "5|3xxxxxx|[4-7]55xxxx" );
}
</pre>
=== Playing and Collecting Tones ===
Tones are defined as events, this is why to play and collect tones, you have to use general event functions. You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play events by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayEvent '''PlayEvent()'''] on a leg. Toolpack will receive the request and play the events. Once events are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventPlayingDone '''OnEventPlayingDone()'''] event. Note that you can cancel an event to be played by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CancelEvent '''CancelEvent()'''] on the leg after a '''PlayEvent()''' has been called.

Two kinds of string can be passed to '''AddToneString()''' to play a tone. The first type is to play well known tones such as dtmf and fax tone. The syntax is really simple and is based on H248 package and signal ids. The first component of the string is the package id and the second is the signal id, both formated in string. So, to play dtmf 0, you have to format the following string: "dg/d0", where "dg" is for package "dtmf generation" and "d0" is for "dtmf 0".

===== Play Tone with Signal Id String =====
<code><pre>
/* this will play dtmf 7 */

CTBCMC_EVENT_ATTRIBUTE Event;
Event.AddToneString( "dg/d7" );
ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
ptrOutgoingLeg->PlayEvent( Event );
}
</pre></code>

The second type of string is to play custom tone. The syntax is much more complicated than the first one, but it follows a well described syntax which can be found in [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.6-200011-I!!PDF-E&type=items/.pdf '''H248.6 Dynamic Tone Definition Package''']. This kind of string allows you to specify frequencies, duration, amplitude and repeating count of the tone. You can also specify well known tones and change their default duration, amplitude and repeating count. It is possible to describe a sequence of tones or frequencies that are played in one segment. Here are some examples of the syntax:

*;Frequencies 400Hz and 600Hz mixed together for 200ms, amplitude at -10dB and repeating 3 times (playing 4 times):
:*(((#400)+(#600)),200,-10)*3
:
*;Dtmf 5 repeated infinitly:
:*((0x0005,0x0015))*0
:
*;Multifrequency tone 8:
:*((mfg,mf8))
:
*;Frequency 440Hz played for 300ms at -10dB followed by frequency 600Hz played for 200ms at -5dB and then followed by dtmf 2, all this repeated infinitly:
:*((#440,300,-10),(#600,200,-5),(0x0005,0x0012))*0
:

===== Play Tone with Custom Tone String=====
<code><pre>
/* this will play frequencies 1000Hz and 2100Hz mixed together */

CTBCMC_EVENT_ATTRIBUTE Event;
Event.AddToneString( "(((#1000)+(#2100)),100,-10)" );
ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
ptrOutgoingLeg->PlayEvent( Event );
}
</pre></code>

You can also configure a leg to collect events played. To start the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartEventCollection '''StartEventCollection()'''] on the leg. Note that you will have to specify which events you want to collect before starting the event collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopEventCollection '''StopEventCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventCollected '''OnEventCollected()'''] event on each event received that correspond to a tone string specified when calling '''StartEventCollection()'''.

Only one type of string is accepted to specify which events to collect. The string is the same as the first type to play event. Signal ids that are also event id are accepted. This means that you can ask to collect "dg/d0" (dtmf generation/dtmf 0) and the detection will be done anyway. You can also detect all events from a package by putting a * as event id, so "dd/*" will detect all dtmf tones.

===== Collect Tone =====
<code><pre>
/* this will collect all dtmf tones */

CTBCMC_EVENT_ATTRIBUTE Event;
Event.AddToneString( "dd/*" );
ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
ptrOutgoingLeg->StartEventCollection( Event );
}
</pre></code>

The most commonly used package are 5 and 6 [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.1-200509-I!!PDF-E&type=items/.pdf '''(H248.1 Annex E)''']: dtmf generation and dtmf detection. As H248 does not define events and signals for fax tone, we added a special package to do so. Package telcofax (0x8001) contains three events and two signals. Signals are: cng (0x0080) and g164 (0x0081) and events are: cng (0x0080), g164 (0x0081) and g165 (0x0082).

=== Collecting digits and tones while call legs are joined ===
By default, when two call legs are joined together through function CTBCMCCallLeg::Join(), tone collection is automatically disabled.
One of the arguments of the Join() function ("in_fDisableToneWhileJoined") will allow to control if automatic tone collection feature is used or not on a call.

Why is Toolpack disabling tone collection on joined legs by default?
That's because tone collection introduces a 40ms delay in the audio connection (required to provide tone suppression), and most of the time it is no more require to collect digits while two call legs are joined, so it would be useless to leave 40ms delay while tone collection is no more required.

=== Playing and Recording Audio Files ===
You can play an audio stream on a leg by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayStream '''PlayStream()'''] on it. To specify which audio stream you want to play, you have to specify it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html#CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath '''AddPlayFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html CTBCMC_PLAY_ATTRIBUTE] class. Toolpack will receive the request and play the stream. Once it is played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingDone '''OnStreamPlayingDone()'''] event.

You can also configure a leg to record an audio stream. First you must specify file paths to record by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html#CTBCMC_RECORD_ATTRIBUTE::AddRecFilePath '''AddRecFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html CTBCMC_RECORD_ATTRIBUTE] class. The you can call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RecordStream '''RecordStream()'''] on a leg. Once the stream is recorded, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamRecordingDone '''OnStreamRecordingDone()'''] event.

You can pause an active playing or recording stream by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PauseStream '''PauseStream()'''] and you can resume it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ResumeStream '''ResumeStream()''']. If you want to stop an active playing or recording stream, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopStream '''StopStream()'''] on the leg.

=== Modifying Media Profile ===
It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.

The media profile is stored in the leg attributes and can be modified like this :
TBX_SDP_INFO SdpInfo;
PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;

pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
pMediaLegAttribute->GetProfile().GetLocalSDP(SdpInfo);
Strncpy
(
SdpInfo.aConnections[0].szIp,
"",
sizeof( SdpInfo.aConnections[0].szIp )
);
SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
pMediaLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

pCallLeg->ChangeProfile();

Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotiation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.

Once the profile change has completed (or failed), event '''OnProfileChanged()''' will be received on the leg.

For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.

=== Controlling the Signaling ===

When a call leg receives the '''OnCallLegPresent()''' event, it indicates an incoming call. To confirm that the call contains sufficient valid information to process the call on the system, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AcceptCall '''AcceptCall()'''] on the leg. If a call leg receives the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAccepted '''OnCallAccepted()'''] event, it means that an outgoing call has been accepted by the remote peer. This event usually means that the calling number has been accepted and that the call is currently being processed.

After an incoming call has been accepted, a call leg can notify the remote peer that the incoming call has been put in the "ringing" state by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AlertCall '''AlertCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAlerting '''OnCallAlerting()'''] event when an outgoing call has been put in the "ringing" state by the remote peer.

When an incoming call is answered, a call leg can notify the remote peer of the incoming call answered by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AnswerCall '''AnswerCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAnswered '''OnCallAnswered()'''] event when an outgoing call has been answered by the remote peer.

Call flow examples are available [[Call_Flow|here]].

SendCallSuppInfo/OnCallSuppInfo

== Leg Termination ==

Terminating a call leg is a 2 steps process:
# Call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::TerminateCall '''TerminateCall()''']
# Free leg object on [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminated '''OnCallTerminated()''']

When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resources freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Free '''Free()'''] on the leg's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::SetFreeListener '''SetFreeListener()'''] on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is deleted. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.

[[Image:TerminateCall from application.jpg|thumb|center|350px|Call flow for leg termination initiated by user application]]

In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other media resource or signaling error. In these cases, the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminatingIndication '''OnCallTerminatingIndication()'''] is sent to the leg. On reception of this event, the application should initiate call termination as shown below.

[[Image:TerminateCall from Toolpack.jpg|thumb|center|350px|Call flow for leg termination initiated by Toolpack]]

In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnLegTerminated '''OnLegTerminated()'''] event. This event indicates that the leg does not exist anymore on the Toolpack side and the user should free its object without trying any other interaction with Toolpack through it.

== Leg Synchronization on Failover ==
When a Toolpack application is restarted or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs through the '''OnCallLegSync()''' event of the [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_lib_user.html ITBCMCLibUser] interface (this interface must be implemented by all user applications). One event will be received for each leg being synchronized. The course of action to take when receiving a leg synchronization event depends on the ability of the application to resynchronize its states with theses legs.

Once all '''OnCallLegSync()''' have been sent, Toolpack will start synchronization of the links between legs through '''OnLinkSync()'''. This event indicates that two legs are connected together. It can be used by the application to rebuild its internal states. As for the legs, unwanted links can be refused by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()'''].

If the application can't resynchronize active legs or if it does not want to resychronize the leg for which it is receiving an '''OnCallLegSync()''' event, it must:
- Create call leg context for all synchronized legs, and keep them until links have been synchronized too (a leg linked to anther must be un-joined before it can be terminated)
- Wait until all links have been re-synchronized (or refused using the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()''']).
- Terminate all previously created call leg contexts that the application does not wish to keep, using the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLeg '''RefuseLeg()'''].

Tip: The helper class CTBCAFCallLegResync has been created to simplify re-synchronizing legs. It can create and accumulate re-synchronized legs, and automatically destroy them when appropriate.
- Call function AllocateCallLeg() for each synchronized leg
- For legs that must not be destroyed after re-synchronization, call RemoveCallLeg() to remove them from this CTBCAFCallLegResync object. Application now has the ownership of the leg.
- Upon '''OnCmcLibReady()''', application must destroy CTBCAFCallLegResync. The destructor of this class will properly refuse all legs that have been created with AllocateCallLeg(), and not removed by RemoveCallLeg().
You can refer to the code of the "Gateway" application for an example (search for variable mpCallLegResync).

When all links have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. At that moment, the application has all the information available on the Toolpack side to determine if the legs should be kept or release. Any leg that the application does not want to keep can be refused by calling '''RefuseLeg()''' on it. For all legs that have not been refused, an event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnSyncDone '''OnSyncDone()'''] will be sent on the leg. Once this event has been received on a leg, the leg is fully functional and the application can start calling any usual Toolpack function on it.

[[Image:CallFlow Sync After Application Restart.jpg|thumb|center|350px|Call flow for leg synchronization]]

===Loss of Communication with Toolpack Engine===
If communication is lost with the Toolpack Engine, event '''OnCmcLibNotReady()''' will be sent to the application. It indicates that the Toolpack framework is no more accessible. The legs are still valid at that time but no action can be executed on them as long the CmcLib is not ready. If the connection with the Toolpack Engine is not back up in less than 10 seconds, the CmcLib will declare a major communication loss and will call '''OnLegTerminated()''' on all the legs. In that case, when communication is regained with the Toolpack Engine, the synchronization sequence will start again from the beginning.

[[Image:CallFlow Sync After Comm Restart Passed 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart passed 10 seconds.]]

If the communication is regained before the 10 seconds timeout, event '''OnCmcLibReady()''' will be sent and the application can then continue working normally with its existing call legs. Note that you can also receive '''OnLegTerminated()''' on some legs before receiving the '''OnCmcLibReady()''' if those legs were in a transient state when disconnection occurred.

[[Image:CallFlow Sync After Comm Restart Within 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart within 10 seconds.]]

== Bridging the Media Path ==
=== Join ===

To bridge the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Join '''Join()'''] on one of the leg, giving the second leg as a parameter. This will connect the media path between the two legs according to the link properties set on the leg on which '''Join()''' is called. These link properties can be modified by overloading the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetJoinAttributes '''GetJoinAttributes()''']. The important attribute to set is '''IsFullDuplex()''' that indicates if the connection will be made full-duplex (A<-->B) or half-duplex (A-->B). Prior to release 2.5.2, the default connection mode is half-duplex. For all release version 2.5.2 or higher, the default connection mode is full-duplex.

'''Warning:''' If two legs are already connected in half-duplex and you want to connect them in full-duplex, you must first Unjoin() the legs, then Join() them in full-duplex. You can '''NOT''' only do another half-duplex in the opposite direction.

When legs are joined, it creates a link identified with a unique ''link id''. It is the responsibility of the application to provide this unique ''link id'' by implementing the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetLinkId '''GetLinkId()'''] function of the leg. It is planned to allow the user to provide a value of '0' to let the Toolpack system automatically choose a ''link id'', but as of this writing this feature is not yet available.

'''Warning:''' When two legs are joined, the application must ensure that '''GetLinkId()''' on both leg will return the right ''link id''. This will ensure that when the link needs to be removed, both A->Unjoin() and B->Unjoin() will work correctly.

==== Setting the link properties ====

In your leg class, add a member variable to store the join attributes for that leg.

CTBCMC_JOIN_ATTRIBUTE mJoinAttribute;

Then set the join properties you want in your leg class constructor (or at any other location that will run '''before''' the '''Join()''' is done:

mJoinAttribute.IsFullDuplex() = TBX_TRUE;

Last, implement the '''GetJoinAttributes()''' function.

CTBCMC_JOIN_ATTRIBUTE & CH248Termination::GetJoinAttributes()
{
return mJoinAttribute;
}

==== Broadcasting a media source ====
At the time of writing this, broadcast of a single media source to multiple destinations is not yet possible.

=== Unjoin ===
To disconnect the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Unjoin'''Unjoin()'''] on any of the legs. The '''GetLinkId()''' function of the leg on which '''Unjoin()''' is called must return the ''link id'' that was used when the legs were joined.

[[category:CAF]]
[[category:Needs revising]]

H.248

2010-06-21T15:24:41Z

Alexandre Lussier: /* Planned H.248 package support */

Also known as Megaco, H.248 is a protocol for controlling media gateways via a [[Softswitch|softswitch]] or a [[Media gateway controller|media gateway controller]].

== TelcoBridges and H.248 ==
A version of [[Toolpack]] that supports the H.248 protocol is currently in development and is targeted for release in the first half of 2010. Further details will be provided at that time.

As indicated in the diagram below, the H.248 stack will be implemented as a module in the media gateway application residing on the application server. It will communicate with the various Toolpack classes (CAFClass, [[CMC library|CMC Library]], CMC Class) as required via a new [[CAF:_Working_With_Call_Legs|Media Leg API]]. In turn, the media gateway application will communicate with the softswitch / media gateway controller via the H.248 protocol.

[[Image:H.248 schematic.jpg|H.248 schematic.jpg]]

=== Planned H.248 package support ===
Support for the following packages is currently in scope.

*'''H.248.1'''
**Protocol v2
**IPSec connection support
**Support UDP (2944 or user-defined)

*'''H.248.1 - Basic packages'''
**Generic
**Base Root
**Tone generator (for extension purposes only)
**Tone detection (for extension purposes only)
**Basic DTMF generation
**DTMF detection
**Basic continuity package
**Network package
**RTP package
**TDM Circuit package

*'''H.248.13 Quality alert ceasing package'''
**Quality alert ceasing package

*'''H.248.2 Facsimile, text conversation and call discrimination packages'''
**Fax/TextPhone/Modem tones detection (fax and data only)
**Call type discrimination package (fax and data only)

*'''H.248.4 Transport over Stream Control Transmission Protocol (SCTP)'''

*'''H.248.7 Generic announcement package'''
**Generic announcement package

*'''H.248.10 Media gateway resource congestion handling package'''
**Congestion handling package

*'''H.248.11 Media gateway overload control package'''
**Overload control package

*'''H.248.14 Inactivity timer package'''
**Inactivity timer package

== Additional details ==
*Support for text mode only

== References ==
*[http://en.wikipedia.org/wiki/Megaco Wikipedia article]

[[category:Glossary]]
[[category:Needs revising]]

H.248

2010-06-21T15:23:39Z

Alexandre Lussier: /* Planned H.248 package support */

Also known as Megaco, H.248 is a protocol for controlling media gateways via a [[Softswitch|softswitch]] or a [[Media gateway controller|media gateway controller]].

== TelcoBridges and H.248 ==
A version of [[Toolpack]] that supports the H.248 protocol is currently in development and is targeted for release in the first half of 2010. Further details will be provided at that time.

As indicated in the diagram below, the H.248 stack will be implemented as a module in the media gateway application residing on the application server. It will communicate with the various Toolpack classes (CAFClass, [[CMC library|CMC Library]], CMC Class) as required via a new [[CAF:_Working_With_Call_Legs|Media Leg API]]. In turn, the media gateway application will communicate with the softswitch / media gateway controller via the H.248 protocol.

[[Image:H.248 schematic.jpg|H.248 schematic.jpg]]

=== Planned H.248 package support ===
Support for the following packages is currently in scope.

*'''H.248.1'''
**Protocol v2
**IPSec connection support
**Support UDP (2944 or user-defined)

*'''H.248.1 - Basic packages'''
**Generic
**Base Root
**Tone generator (for extension purposes only)
**Tone detection (for extension purposes only)
**Basic DTMF generation
**DTMF detection
**Basic continuity package
**Network package
**RTP package
**TDM Circuit package

*'''H.248.13 Quality alert ceasing package'''
**Quality alert ceasing package

*'''H.248.2 Facsimile, text conversation and call discrimination packages'''
**Fax/TextPhone/Modem tones detection (fax and data only)
**Call type discrimination package (fax and data only)

*'''H.248.4 Transport over Stream Control Transmission Protocol (SCTP)'''

*'''H.248.7 Generic announcement package'''
**Generic announcement package

*'''H.248.9 Advanced media server packages'''
**Advanced audio server base package
**AAS Digit collection package
**AAS Recording package

*'''H.248.10 Media gateway resource congestion handling package'''
**Congestion handling package

*'''H.248.11 Media gateway overload control package'''
**Overload control package

*'''H.248.14 Inactivity timer package'''
**Inactivity timer package

*'''H.248.16 Enhanced digit collection'''
**Extended DTMF detection package
**Enhanced DTMF detection package

== Additional details ==
*Support for text mode only

== References ==
*[http://en.wikipedia.org/wiki/Megaco Wikipedia article]

[[category:Glossary]]
[[category:Needs revising]]

H.248

2010-06-21T15:23:13Z

Alexandre Lussier: /* Planned H.248 package support */

Also known as Megaco, H.248 is a protocol for controlling media gateways via a [[Softswitch|softswitch]] or a [[Media gateway controller|media gateway controller]].

== TelcoBridges and H.248 ==
A version of [[Toolpack]] that supports the H.248 protocol is currently in development and is targeted for release in the first half of 2010. Further details will be provided at that time.

As indicated in the diagram below, the H.248 stack will be implemented as a module in the media gateway application residing on the application server. It will communicate with the various Toolpack classes (CAFClass, [[CMC library|CMC Library]], CMC Class) as required via a new [[CAF:_Working_With_Call_Legs|Media Leg API]]. In turn, the media gateway application will communicate with the softswitch / media gateway controller via the H.248 protocol.

[[Image:H.248 schematic.jpg|H.248 schematic.jpg]]

=== Planned H.248 package support ===
Support for the following packages is currently in scope.

*'''H.248.1'''
**Protocol v2
**IPSec connection support
**Support UDP (2944 or user-defined)

*'''H.248.1 - Basic packages'''
**Generic
**Base Root
**Tone generator (for extension purposes only)
**Tone detection (for extension purposes only)
**Basic DTMF generation
**DTMF detection
**Basic continuity package
**Network package
**RTP package
**TDM Circuit package

*'''H.248.13 Quality alert ceasing package'''
**Quality alert ceasing package

*'''H.248.2 Facsimile, text conversation and call discrimination packages'''
**Fax/TextPhone/Modem tones detection (fax and data only)
**Call type discrimination package (fax and data only)

*'''H.248.4 Transport over Stream Control Transmission Protocol (SCTP)'''

*'''H.248.6 Dynamic tone definition package'''
**Dynamic tone definition

*'''H.248.7 Generic announcement package'''
**Generic announcement package

*'''H.248.9 Advanced media server packages'''
**Advanced audio server base package
**AAS Digit collection package
**AAS Recording package

*'''H.248.10 Media gateway resource congestion handling package'''
**Congestion handling package

*'''H.248.11 Media gateway overload control package'''
**Overload control package

*'''H.248.14 Inactivity timer package'''
**Inactivity timer package

*'''H.248.16 Enhanced digit collection'''
**Extended DTMF detection package
**Enhanced DTMF detection package

== Additional details ==
*Support for text mode only

== References ==
*[http://en.wikipedia.org/wiki/Megaco Wikipedia article]

[[category:Glossary]]
[[category:Needs revising]]

H.248

2010-06-21T15:06:09Z

Alexandre Lussier: /* Planned H.248 package support */

Also known as Megaco, H.248 is a protocol for controlling media gateways via a [[Softswitch|softswitch]] or a [[Media gateway controller|media gateway controller]].

== TelcoBridges and H.248 ==
A version of [[Toolpack]] that supports the H.248 protocol is currently in development and is targeted for release in the first half of 2010. Further details will be provided at that time.

As indicated in the diagram below, the H.248 stack will be implemented as a module in the media gateway application residing on the application server. It will communicate with the various Toolpack classes (CAFClass, [[CMC library|CMC Library]], CMC Class) as required via a new [[CAF:_Working_With_Call_Legs|Media Leg API]]. In turn, the media gateway application will communicate with the softswitch / media gateway controller via the H.248 protocol.

[[Image:H.248 schematic.jpg|H.248 schematic.jpg]]

=== Planned H.248 package support ===
Support for the following packages is currently in scope.

*'''H.248.1'''
**Protocol v2
**IPSec connection support
**Support UDP (2944 or user-defined)

*'''H.248.1 - Basic packages'''
**Generic
**Base Root
**Tone generator (for extension purposes only)
**Tone detection (for extension purposes only)
**Basic DTMF generation
**DTMF detection
**Basic continuity package
**Network package
**RTP package
**TDM Circuit package

*'''H.248.13 Quality alert ceasing package'''
**Quality alert ceasing package

*'''H.248.2 Facsimile, text conversation and call discrimination packages'''
**Fax/TextPhone/Modem tones detection (fax and data only)
**Call type discrimination package (fax and data only)
**IP fax package

*'''H.248.4 Transport over Stream Control Transmission Protocol (SCTP)'''

*'''H.248.6 Dynamic tone definition package'''
**Dynamic tone definition

*'''H.248.7 Generic announcement package'''
**Generic announcement package

*'''H.248.9 Advanced media server packages'''
**Advanced audio server base package
**AAS Digit collection package
**AAS Recording package

*'''H.248.10 Media gateway resource congestion handling package'''
**Congestion handling package

*'''H.248.11 Media gateway overload control package'''
**Overload control package

*'''H.248.14 Inactivity timer package'''
**Inactivity timer package

*'''H.248.16 Enhanced digit collection'''
**Extended DTMF detection package
**Enhanced DTMF detection package

== Additional details ==
*Support for text mode only

== References ==
*[http://en.wikipedia.org/wiki/Megaco Wikipedia article]

[[category:Glossary]]
[[category:Needs revising]]

CAF: Working With Call Legs

2010-02-10T15:34:37Z

Alexandre Lussier: /* Collect Tone */

== Call Leg Definition ==
The main mechanism through which the customer application controls the [[Toolpack]] system is via the management of call legs. The application creates a call leg (or more than one for conferencing and bridging) at the beginning of a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.

A call leg is represented by an instance of the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html CTBCMCLeg] class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 [[timeslot]]) or a [[SIP]] call with its associated [[VOIP]] [[Voice codecs|codec]] resource (attached to an IP/UDP endpoint). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (VOIP codec resource attached to an IP/UDP endpoint). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.

The CTBCMCLeg class allows a programmer to easily act upon the call leg to influence the signaling portion (e.g. accept, answer, terminate, etc) and to use the media portion as well (e.g play prompts, record voice, play or collect digits and tones).

Other member functions are available to retrieve (and change in some cases) the call leg attributes including the media profile (e.g. parameters to the media resource) or signaling information (e.g. protocol type, called and calling party numbers, etc). Joining/unjoining (connection/disconnection) of call legs is also a typical action handled by this class for ’gateway-type’ applications. It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse a ''call leg'' with a ''call''. A ''call leg'' represents one full-duplex link to a party while a ''call'' represents the agglomeration of multiple (two or more) call legs. For example, a ''bridge'' is a form of ''call'' that uses two ''call legs''.
* Do not confuse the base class CTBCMCLeg with the class [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_leg.html CTBCAFCallLeg]. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs. It is designed to represent a leg within a call. It cannot be instanciated as a standalone object without modifications to make it independent from the ITBCAFCallFlow interface.
* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

== Command Flow for Leg Actions in CAF ==
All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).

For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.

== Leg Creation ==
Creating a leg is always done through the definition of a ''call leg attribute''. The values entered in the ''call leg attribute'' will define the type of call leg created and its parameters. The following sections describe several scenarios in which you build a ''call leg''. Instruction will be given on how to fill the leg attributes and how to use them to create the ''call leg''.

=== Preparing Leg Attributes ===

==== Normal Call Leg Attributes ====
For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
* the called number,
* the calling number,
* the [[NAP | Network Access Point]].

Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|NAP Types]]).

The following code snippet shows how to build the attributes.
PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();

ptrOutgoingLegAttribute->GetCalledNumber() = "123-4567";
ptrOutgoingLegAttribute->GetCallingNumber() = "987-6543";
ptrOutgoingLegAttribute->GetNetworkAccessPoint() = "NAP_SS7_MONTREAL";

==== Media-only Leg Attributes ====
For media-only legs, no signaling information is needed but the user can specify which media channel to use and which media profile to use. The only required parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''MEDIA TDM'' or ''MEDIA VOIP'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;

ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();

ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;

When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. For ''MEDIA TDM'' NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For ''MEDIA VOIP'' NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and a timeslot number can be specified.

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc->Settings.TdmAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
pMediaDesc->Settings.TdmAudio.un8Timeslot = 5;
Strncpy
(
pMediaDesc->Settings.TdmAudio.szTrunkName,
"TRUNK_TORONTO_1",
sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
);

For VOIP legs, the user can control the media by providing local [[SDP]] and peer SDP. Setting the local SDP defines the codec and IP/port used to for the received media stream. Most of the time, the IP address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and IP/port used for the transmitted media stream. Note that Toolpack only allows for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in '''both''' SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].

TBX_RESULT Result;
TBX_SDP_INFO SdpInfo;
PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();
pMediaDesc->Settings.PacketAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;

// Set Local SDP
Result = BuildSdpInfo("", 0, SdpInfo); // No IP specified, Toolpack will choose one
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

// Set Peer SDP
Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo); // Using peer IP address and port
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetPeerSDP(SdpInfo);

=== Creating the Leg ===
Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CreateCall '''CreateCall()'''] on it. No action is taken when an instance of a CTBCMCLeg is created. Call resources are only allocated in the Toolpack system when '''CreateCall()''' is called on the object.

pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
pCallLeg->CreateCall();

For legs with signaling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).

[[Image:CallFlow SignalingMediaLeg Creation.JPG|thumb|center|350px|Call flow for creation of leg with signaling]]

For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.

[[Image:CallFlow MediaOnlyLeg Creation.JPG|thumb|center|350px|Call flow for media-only leg creation]]

Once a call is fully active (call answered and media allocated), event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnProfileChanged '''OnProfileChanged()'''] will be sent on the leg. In the cases where the user had not specified the IP/port to use, once this event is received, the media profile has been updated with the values chosen by Toolpack and the updated values can be retrieved using the functions '''GetLocalSDP()''' and '''GetPeerSDP()''' of the profile.
Note that the '''OnProfileChanged()''' event is also sent after the media profile has been modified with the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ChangeProfile '''ChangeProfile()'''] function (see [[#Modifying Media Profile|Modifying Media Profile]]) and when a connected peer has requested it (through a SIP re-INVITE for example).

See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.

=== Caveats ===
* The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).

== Interaction with Legs ==

=== Playing and Collecting Digits ===

You can play digits by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayDigit '''PlayDigit()'''] on a leg. Toolpack will receive the request and play the digits. Once digits are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitPlayingDone '''OnDigitPlayingDone()'''] event.

 You can also configure a leg to collect digits played. To start the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartDigitCollection '''StartDigitCollection()'''] on the leg. To stop the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopDigitCollection '''StopDigitCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitCollected '''OnDigitCollected()'''] event when there will be a match between the asked string and the digits collected.

 Here are examples how to play and collect digit.

===== Play Digit =====

<code></code>
<pre>ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
/* this will play the sequence of digit 5551234 */
ptrOutgoingLeg->PlayDigit( "5551234" );
}
</pre>
===== Collect Digit =====

<code></code>
<pre>ptrIncomingLeg = GetIncomingActiveLeg();
if( ptrIncomingLeg != NULL )
{
/*
this will collect digits 5, any sequences of 7 digits beginning by 3 or any sequences of 7 digits
beginning by 4,5,6 or 7 followed by 5 and 5.
*/
ptrIncomingLeg->StartDigitCollection( "5|3xxxxxx|[4-7]55xxxx" );
}
</pre>
=== Playing and Collecting Tones ===
Tones are defined as events, this is why to play and collect tones, you have to use general event functions. You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play events by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayEvent '''PlayEvent()'''] on a leg. Toolpack will receive the request and play the events. Once events are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventPlayingDone '''OnEventPlayingDone()'''] event. Note that you can cancel an event to be played by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CancelEvent '''CancelEvent()'''] on the leg after a '''PlayEvent()''' has been called.

Two kinds of string can be passed to '''AddToneString()''' to play a tone. The first type is to play well known tones such as dtmf and fax tone. The syntax is really simple and is based on H248 package and signal ids. The first component of the string is the package id and the second is the signal id, both formated in string. So, to play dtmf 0, you have to format the following string: "dg/d0", where "dg" is for package "dtmf generation" and "d0" is for "dtmf 0".

===== Play Tone with Signal Id String =====
<code><pre>
/* this will play dtmf 7 */

CTBCMC_EVENT_ATTRIBUTE Event;
Event.AddToneString( "dg/d7" );
ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
ptrOutgoingLeg->PlayEvent( Event );
}
</pre></code>

The second type of string is to play custom tone. The syntax is much more complicated than the first one, but it follows a well described syntax which can be found in [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.6-200011-I!!PDF-E&type=items/.pdf '''H248.6 Dynamic Tone Definition Package''']. This kind of string allows you to specify frequencies, duration, amplitude and repeating count of the tone. You can also specify well known tones and change their default duration, amplitude and repeating count. It is possible to describe a sequence of tones or frequencies that are played in one segment. Here are some examples of the syntax:

*;Frequencies 400Hz and 600Hz mixed together for 200ms, amplitude at -10dB and repeating 3 times (playing 4 times):
:*(((#400)+(#600)),200,-10)*3
:
*;Dtmf 5 repeated infinitly:
:*((0x0005,0x0015))*0
:
*;Multifrequency tone 8:
:*((mfg,mf8))
:
*;Frequency 440Hz played for 300ms at -10dB followed by frequency 600Hz played for 200ms at -5dB and then followed by dtmf 2, all this repeated infinitly:
:*((#440,300,-10),(#600,200,-5),(0x0005,0x0012))*0
:

===== Play Tone with Custom Tone String=====
<code><pre>
/* this will play frequencies 1000Hz and 2100Hz mixed together */

CTBCMC_EVENT_ATTRIBUTE Event;
Event.AddToneString( "(((#1000)+(#2100)),100,-10)" );
ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
ptrOutgoingLeg->PlayEvent( Event );
}
</pre></code>

You can also configure a leg to collect events played. To start the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartEventCollection '''StartEventCollection()'''] on the leg. Note that you will have to specify which events you want to collect before starting the event collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopEventCollection '''StopEventCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventCollected '''OnEventCollected()'''] event on each event received that correspond to a tone string specified when calling '''StartEventCollection()'''.

Only one type of string is accepted to specify which events to collect. The string is the same as the first type to play event. Signal ids that are also event id are accepted. This means that you can ask to collect "dg/d0" (dtmf generation/dtmf 0) and the detection will be done anyway. But, when the event is detected, it's the event id that will be returned, which means that "dd/d0" (dtmf detection/dtmf 0) will be returned instead of "dg/d0". You can also detect all events from a package by putting a * as event id, so "dd/*" will detect all dtmf tones.

===== Collect Tone =====
<code><pre>
/* this will collect all dtmf tones */

CTBCMC_EVENT_ATTRIBUTE Event;
Event.AddToneString( "dd/*" );
ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
ptrOutgoingLeg->StartEventCollection( Event );
}
</pre></code>

The most commonly used package are 5 and 6 [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.1-200509-I!!PDF-E&type=items/.pdf '''(H248.1 Annex E)''']: dtmf generation and dtmf detection. As H248 does not define events and signals for fax tone, we added a special package to do so. Package telcofax (0x8001) contains three events and two signals. Signals are: cng (0x0080) and g164 (0x0081) and events are: cng (0x0080), g164 (0x0081) and g165 (0x0082).

=== Collecting digits and tones while call legs are joined ===
By default, when two call legs are joined together through function CTBCMCCallLeg::Join(), tone collection is automatically disabled.
One of the arguments of the Join() function ("in_fDisableToneWhileJoined") will allow to control if automatic tone collection feature is used or not on a call.

Why is Toolpack disabling tone collection on joined legs by default?
That's because tone collection introduces a 40ms delay in the audio connection (required to provide tone suppression), and most of the time it is no more require to collect digits while two call legs are joined, so it would be useless to leave 40ms delay while tone collection is no more required.

=== Playing and Recording Audio Files ===
You can play an audio stream on a leg by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayStream '''PlayStream()'''] on it. To specify which audio stream you want to play, you have to specify it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html#CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath '''AddPlayFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html CTBCMC_PLAY_ATTRIBUTE] class. Toolpack will receive the request and play the stream. Once it is played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingDone '''OnStreamPlayingDone()'''] event.

You can also configure a leg to record an audio stream. First you must specify file paths to record by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html#CTBCMC_RECORD_ATTRIBUTE::AddRecFilePath '''AddRecFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html CTBCMC_RECORD_ATTRIBUTE] class. The you can call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RecordStream '''RecordStream()'''] on a leg. Once the stream is recorded, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamRecordingDone '''OnStreamRecordingDone()'''] event.

You can pause an active playing or recording stream by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PauseStream '''PauseStream()'''] and you can resume it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ResumeStream '''ResumeStream()''']. If you want to stop an active playing or recording stream, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopStream '''StopStream()'''] on the leg.

=== Modifying Media Profile ===
It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.

The media profile is stored in the leg attributes and can be modified like this :
TBX_SDP_INFO SdpInfo;
PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;

pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
pMediaLegAttribute->GetProfile().GetLocalSDP(SdpInfo);
Strncpy
(
SdpInfo.aConnections[0].szIp,
"",
sizeof( SdpInfo.aConnections[0].szIp )
);
SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
pMediaLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

pCallLeg->ChangeProfile();

Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotiation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.

Once the profile change has completed (or failed), event '''OnProfileChanged()''' will be received on the leg.

For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.

=== Controlling the Signaling ===
When a call leg receives the '''OnCallLegPresent()''' event, it indicates an incoming call. To confirm that the call contains sufficient valid information to process the call on the system, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AcceptCall '''AcceptCall()'''] on the leg. If a call leg receives the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAccepted '''OnCallAccepted()'''] event, it means that an outgoing call has been accepted by the remote peer. This event usually means that the calling number has been accepted and that the call is currently being processed.

After an incoming call has been accepted, a call leg can notify the remote peer that the incoming call has been put in the "ringing" state by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AlertCall '''AlertCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAlerting '''OnCallAlerting()'''] event when an outgoing call has been put in the "ringing" state by the remote peer.

When an incoming call is answered, a call leg can notify the remote peer of the incoming call answered by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AnswerCall '''AnswerCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAnswered '''OnCallAnswered()'''] event when an outgoing call has been answered by the remote peer.

SendCallSuppInfo/OnCallSuppInfo

== Leg Termination ==

Terminating a call leg is a 2 steps process:
# Call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::TerminateCall '''TerminateCall()''']
# Free leg object on [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminated '''OnCallTerminated()''']

When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resources freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Free '''Free()'''] on the leg's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::SetFreeListener '''SetFreeListener()'''] on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is deleted. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.

[[Image:TerminateCall from application.jpg|thumb|center|350px|Call flow for leg termination initiated by user application]]

In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other media resource or signaling error. In these cases, the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminatingIndication '''OnCallTerminatingIndication()'''] is sent to the leg. On reception of this event, the application should initiate call termination as shown below.

[[Image:TerminateCall from Toolpack.jpg|thumb|center|350px|Call flow for leg termination initiated by Toolpack]]

In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnLegTerminated '''OnLegTerminated()'''] event. This event indicates that the leg does not exist anymore on the Toolpack side and the user should free its object without trying any other interaction with Toolpack through it.

== Leg Synchronization on Failover ==
When a Toolpack application is restarted or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs through the '''OnCallLegSync()''' event of the [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_lib_user.html ITBCMCLibUser] interface (this interface must be implemented by all user applications). One event will be received for each leg being synchronized. The course of action to take when receiving a leg synchronization event depends on the ability of the application to resynchronize its states with theses legs.

* If the application can't resynchronize active legs or if it does not want to resychronize the leg for which it is receiving an '''OnCallLegSync()''' event, it must refuse the leg by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLeg '''RefuseLeg()'''].
*If the application wants the resynchronize the leg or if it does not yet have enough information to decide, it must create a CTBCMCLeg object using the leg attributes received in the event.

Once all '''OnCallLegSync()''' have been sent, Toolpack will start synchronization of the links between legs through '''OnLinkSync()'''. This event indicates that two legs are connected together. It can be used by the application to rebuild its internal states. As for the legs, unwanted links can be refused by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()'''].

When all links have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. At that moment, the application has all the information available on the Toolpack side to determine if the legs should be kept or release. Any leg that the application does not want to keep can be refused by calling '''RefuseLeg()''' on it. For all legs that have not been refused, an event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnSyncDone '''OnSyncDone()'''] will be sent on the leg. Once this event has been received on a leg, the leg is fully functional and the application can start calling any usual Toolpack function on it.

[[Image:CallFlow Sync After Application Restart.jpg|thumb|center|350px|Call flow for leg synchronization]]

===Loss of Communication with Toolpack Engine===
If communication is lost with the Toolpack Engine, event '''OnCmcLibNotReady()''' will be sent to the application. It indicates that the Toolpack framework is no more accessible. The legs are still valid at that time but no action can be executed on them as long the CmcLib is not ready. If the connection with the Toolpack Engine is not back up in less than 10 seconds, the CmcLib will declare a major communication loss and will call '''OnLegTerminated()''' on all the legs. In that case, when communication is regained with the Toolpack Engine, the synchronization sequence will start again from the beginning.

[[Image:CallFlow Sync After Comm Restart Passed 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart passed 10 seconds.]]

If the communication is regained before the 10 seconds timeout, event '''OnCmcLibReady()''' will be sent and the application can then continue working normally with its existing call legs. Note that you can also receive '''OnLegTerminated()''' on some legs before receiving the '''OnCmcLibReady()''' if those legs were in a transient state when disconnection occurred.

[[Image:CallFlow Sync After Comm Restart Within 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart within 10 seconds.]]

== Bridging the Media Path ==
=== Join ===

To bridge the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Join '''Join()'''] on one of the leg, giving the second leg as a parameter. This will connect the media path between the two legs according to the link properties set on the leg on which '''Join()''' is called. These link properties can be modified by overloading the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetJoinAttributes '''GetJoinAttributes()''']. The important attribute to set is '''IsFullDuplex()''' that indicates if the connection will be made full-duplex (A<-->B) or half-duplex (A-->B). Prior to release 2.5.2, the default connection mode is half-duplex. For all release version 2.5.2 or higher, the default connection mode is full-duplex.

'''Warning:''' If two legs are already connected in half-duplex and you want to connect them in full-duplex, you must first Unjoin() the legs, then Join() them in full-duplex. You can '''NOT''' only do another half-duplex in the opposite direction.

When legs are joined, it creates a link identified with a unique ''link id''. It is the responsibility of the application to provide this unique ''link id'' by implementing the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetLinkId '''GetLinkId()'''] function of the leg. It is planned to allow the user to provide a value of '0' to let the Toolpack system automatically choose a ''link id'', but as of this writing this feature is not yet available.

'''Warning:''' When two legs are joined, the application must ensure that '''GetLinkId()''' on both leg will return the right ''link id''. This will ensure that when the link needs to be removed, both A->Unjoin() and B->Unjoin() will work correctly.

==== Setting the link properties ====

In your leg class, add a member variable to store the join attributes for that leg.

CTBCMC_JOIN_ATTRIBUTE mJoinAttribute;

Then set the join properties you want in your leg class constructor (or at any other location that will run '''before''' the '''Join()''' is done:

mJoinAttribute.IsFullDuplex() = TBX_TRUE;

Last, implement the '''GetJoinAttributes()''' function.

CTBCMC_JOIN_ATTRIBUTE & CH248Termination::GetJoinAttributes()
{
return mJoinAttribute;
}

==== Broadcasting a media source ====
At the time of writing this, broadcast of a single media source to multiple destinations is not yet possible.

=== Unjoin ===
To disconnect the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Unjoin'''Unjoin()'''] on any of the legs. The '''GetLinkId()''' function of the leg on which '''Unjoin()''' is called must return the ''link id'' that was used when the legs were joined.

[[category:CAF]]
[[category:Needs revising]]

CAF: Working With Call Legs

2010-02-10T15:34:17Z

Alexandre Lussier: /* Play Tone with Custom Tone String */

== Call Leg Definition ==
The main mechanism through which the customer application controls the [[Toolpack]] system is via the management of call legs. The application creates a call leg (or more than one for conferencing and bridging) at the beginning of a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.

A call leg is represented by an instance of the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html CTBCMCLeg] class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 [[timeslot]]) or a [[SIP]] call with its associated [[VOIP]] [[Voice codecs|codec]] resource (attached to an IP/UDP endpoint). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (VOIP codec resource attached to an IP/UDP endpoint). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.

The CTBCMCLeg class allows a programmer to easily act upon the call leg to influence the signaling portion (e.g. accept, answer, terminate, etc) and to use the media portion as well (e.g play prompts, record voice, play or collect digits and tones).

Other member functions are available to retrieve (and change in some cases) the call leg attributes including the media profile (e.g. parameters to the media resource) or signaling information (e.g. protocol type, called and calling party numbers, etc). Joining/unjoining (connection/disconnection) of call legs is also a typical action handled by this class for ’gateway-type’ applications. It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse a ''call leg'' with a ''call''. A ''call leg'' represents one full-duplex link to a party while a ''call'' represents the agglomeration of multiple (two or more) call legs. For example, a ''bridge'' is a form of ''call'' that uses two ''call legs''.
* Do not confuse the base class CTBCMCLeg with the class [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_leg.html CTBCAFCallLeg]. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs. It is designed to represent a leg within a call. It cannot be instanciated as a standalone object without modifications to make it independent from the ITBCAFCallFlow interface.
* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

== Command Flow for Leg Actions in CAF ==
All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).

For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.

== Leg Creation ==
Creating a leg is always done through the definition of a ''call leg attribute''. The values entered in the ''call leg attribute'' will define the type of call leg created and its parameters. The following sections describe several scenarios in which you build a ''call leg''. Instruction will be given on how to fill the leg attributes and how to use them to create the ''call leg''.

=== Preparing Leg Attributes ===

==== Normal Call Leg Attributes ====
For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
* the called number,
* the calling number,
* the [[NAP | Network Access Point]].

Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|NAP Types]]).

The following code snippet shows how to build the attributes.
PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();

ptrOutgoingLegAttribute->GetCalledNumber() = "123-4567";
ptrOutgoingLegAttribute->GetCallingNumber() = "987-6543";
ptrOutgoingLegAttribute->GetNetworkAccessPoint() = "NAP_SS7_MONTREAL";

==== Media-only Leg Attributes ====
For media-only legs, no signaling information is needed but the user can specify which media channel to use and which media profile to use. The only required parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''MEDIA TDM'' or ''MEDIA VOIP'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;

ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();

ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;

When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. For ''MEDIA TDM'' NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For ''MEDIA VOIP'' NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and a timeslot number can be specified.

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc->Settings.TdmAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
pMediaDesc->Settings.TdmAudio.un8Timeslot = 5;
Strncpy
(
pMediaDesc->Settings.TdmAudio.szTrunkName,
"TRUNK_TORONTO_1",
sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
);

For VOIP legs, the user can control the media by providing local [[SDP]] and peer SDP. Setting the local SDP defines the codec and IP/port used to for the received media stream. Most of the time, the IP address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and IP/port used for the transmitted media stream. Note that Toolpack only allows for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in '''both''' SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].

TBX_RESULT Result;
TBX_SDP_INFO SdpInfo;
PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();
pMediaDesc->Settings.PacketAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;

// Set Local SDP
Result = BuildSdpInfo("", 0, SdpInfo); // No IP specified, Toolpack will choose one
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

// Set Peer SDP
Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo); // Using peer IP address and port
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetPeerSDP(SdpInfo);

=== Creating the Leg ===
Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CreateCall '''CreateCall()'''] on it. No action is taken when an instance of a CTBCMCLeg is created. Call resources are only allocated in the Toolpack system when '''CreateCall()''' is called on the object.

pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
pCallLeg->CreateCall();

For legs with signaling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).

[[Image:CallFlow SignalingMediaLeg Creation.JPG|thumb|center|350px|Call flow for creation of leg with signaling]]

For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.

[[Image:CallFlow MediaOnlyLeg Creation.JPG|thumb|center|350px|Call flow for media-only leg creation]]

Once a call is fully active (call answered and media allocated), event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnProfileChanged '''OnProfileChanged()'''] will be sent on the leg. In the cases where the user had not specified the IP/port to use, once this event is received, the media profile has been updated with the values chosen by Toolpack and the updated values can be retrieved using the functions '''GetLocalSDP()''' and '''GetPeerSDP()''' of the profile.
Note that the '''OnProfileChanged()''' event is also sent after the media profile has been modified with the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ChangeProfile '''ChangeProfile()'''] function (see [[#Modifying Media Profile|Modifying Media Profile]]) and when a connected peer has requested it (through a SIP re-INVITE for example).

See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.

=== Caveats ===
* The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).

== Interaction with Legs ==

=== Playing and Collecting Digits ===

You can play digits by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayDigit '''PlayDigit()'''] on a leg. Toolpack will receive the request and play the digits. Once digits are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitPlayingDone '''OnDigitPlayingDone()'''] event.

 You can also configure a leg to collect digits played. To start the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartDigitCollection '''StartDigitCollection()'''] on the leg. To stop the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopDigitCollection '''StopDigitCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitCollected '''OnDigitCollected()'''] event when there will be a match between the asked string and the digits collected.

 Here are examples how to play and collect digit.

===== Play Digit =====

<code></code>
<pre>ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
/* this will play the sequence of digit 5551234 */
ptrOutgoingLeg->PlayDigit( "5551234" );
}
</pre>
===== Collect Digit =====

<code></code>
<pre>ptrIncomingLeg = GetIncomingActiveLeg();
if( ptrIncomingLeg != NULL )
{
/*
this will collect digits 5, any sequences of 7 digits beginning by 3 or any sequences of 7 digits
beginning by 4,5,6 or 7 followed by 5 and 5.
*/
ptrIncomingLeg->StartDigitCollection( "5|3xxxxxx|[4-7]55xxxx" );
}
</pre>
=== Playing and Collecting Tones ===
Tones are defined as events, this is why to play and collect tones, you have to use general event functions. You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play events by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayEvent '''PlayEvent()'''] on a leg. Toolpack will receive the request and play the events. Once events are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventPlayingDone '''OnEventPlayingDone()'''] event. Note that you can cancel an event to be played by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CancelEvent '''CancelEvent()'''] on the leg after a '''PlayEvent()''' has been called.

Two kinds of string can be passed to '''AddToneString()''' to play a tone. The first type is to play well known tones such as dtmf and fax tone. The syntax is really simple and is based on H248 package and signal ids. The first component of the string is the package id and the second is the signal id, both formated in string. So, to play dtmf 0, you have to format the following string: "dg/d0", where "dg" is for package "dtmf generation" and "d0" is for "dtmf 0".

===== Play Tone with Signal Id String =====
<code><pre>
/* this will play dtmf 7 */

CTBCMC_EVENT_ATTRIBUTE Event;
Event.AddToneString( "dg/d7" );
ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
ptrOutgoingLeg->PlayEvent( Event );
}
</pre></code>

The second type of string is to play custom tone. The syntax is much more complicated than the first one, but it follows a well described syntax which can be found in [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.6-200011-I!!PDF-E&type=items/.pdf '''H248.6 Dynamic Tone Definition Package''']. This kind of string allows you to specify frequencies, duration, amplitude and repeating count of the tone. You can also specify well known tones and change their default duration, amplitude and repeating count. It is possible to describe a sequence of tones or frequencies that are played in one segment. Here are some examples of the syntax:

*;Frequencies 400Hz and 600Hz mixed together for 200ms, amplitude at -10dB and repeating 3 times (playing 4 times):
:*(((#400)+(#600)),200,-10)*3
:
*;Dtmf 5 repeated infinitly:
:*((0x0005,0x0015))*0
:
*;Multifrequency tone 8:
:*((mfg,mf8))
:
*;Frequency 440Hz played for 300ms at -10dB followed by frequency 600Hz played for 200ms at -5dB and then followed by dtmf 2, all this repeated infinitly:
:*((#440,300,-10),(#600,200,-5),(0x0005,0x0012))*0
:

===== Play Tone with Custom Tone String=====
<code><pre>
/* this will play frequencies 1000Hz and 2100Hz mixed together */

CTBCMC_EVENT_ATTRIBUTE Event;
Event.AddToneString( "(((#1000)+(#2100)),100,-10)" );
ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
ptrOutgoingLeg->PlayEvent( Event );
}
</pre></code>

You can also configure a leg to collect events played. To start the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartEventCollection '''StartEventCollection()'''] on the leg. Note that you will have to specify which events you want to collect before starting the event collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopEventCollection '''StopEventCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventCollected '''OnEventCollected()'''] event on each event received that correspond to a tone string specified when calling '''StartEventCollection()'''.

Only one type of string is accepted to specify which events to collect. The string is the same as the first type to play event. Signal ids that are also event id are accepted. This means that you can ask to collect "dg/d0" (dtmf generation/dtmf 0) and the detection will be done anyway. But, when the event is detected, it's the event id that will be returned, which means that "dd/d0" (dtmf detection/dtmf 0) will be returned instead of "dg/d0". You can also detect all events from a package by putting a * as event id, so "dd/*" will detect all dtmf tones.

===== Collect Tone =====
<code><pre>
/* this will collect all dtmf tones */

CTBCMC_EVENT_ATTRIBUTE Event;
Event.AddToneString( "dd/*" );
GetOutgoingActiveLeg()->StartEventCollection( Event );
</code></pre>

The most commonly used package are 5 and 6 [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.1-200509-I!!PDF-E&type=items/.pdf '''(H248.1 Annex E)''']: dtmf generation and dtmf detection. As H248 does not define events and signals for fax tone, we added a special package to do so. Package telcofax (0x8001) contains three events and two signals. Signals are: cng (0x0080) and g164 (0x0081) and events are: cng (0x0080), g164 (0x0081) and g165 (0x0082).

=== Collecting digits and tones while call legs are joined ===
By default, when two call legs are joined together through function CTBCMCCallLeg::Join(), tone collection is automatically disabled.
One of the arguments of the Join() function ("in_fDisableToneWhileJoined") will allow to control if automatic tone collection feature is used or not on a call.

Why is Toolpack disabling tone collection on joined legs by default?
That's because tone collection introduces a 40ms delay in the audio connection (required to provide tone suppression), and most of the time it is no more require to collect digits while two call legs are joined, so it would be useless to leave 40ms delay while tone collection is no more required.

=== Playing and Recording Audio Files ===
You can play an audio stream on a leg by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayStream '''PlayStream()'''] on it. To specify which audio stream you want to play, you have to specify it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html#CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath '''AddPlayFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html CTBCMC_PLAY_ATTRIBUTE] class. Toolpack will receive the request and play the stream. Once it is played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingDone '''OnStreamPlayingDone()'''] event.

You can also configure a leg to record an audio stream. First you must specify file paths to record by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html#CTBCMC_RECORD_ATTRIBUTE::AddRecFilePath '''AddRecFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html CTBCMC_RECORD_ATTRIBUTE] class. The you can call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RecordStream '''RecordStream()'''] on a leg. Once the stream is recorded, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamRecordingDone '''OnStreamRecordingDone()'''] event.

You can pause an active playing or recording stream by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PauseStream '''PauseStream()'''] and you can resume it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ResumeStream '''ResumeStream()''']. If you want to stop an active playing or recording stream, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopStream '''StopStream()'''] on the leg.

=== Modifying Media Profile ===
It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.

The media profile is stored in the leg attributes and can be modified like this :
TBX_SDP_INFO SdpInfo;
PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;

pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
pMediaLegAttribute->GetProfile().GetLocalSDP(SdpInfo);
Strncpy
(
SdpInfo.aConnections[0].szIp,
"",
sizeof( SdpInfo.aConnections[0].szIp )
);
SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
pMediaLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

pCallLeg->ChangeProfile();

Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotiation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.

Once the profile change has completed (or failed), event '''OnProfileChanged()''' will be received on the leg.

For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.

=== Controlling the Signaling ===
When a call leg receives the '''OnCallLegPresent()''' event, it indicates an incoming call. To confirm that the call contains sufficient valid information to process the call on the system, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AcceptCall '''AcceptCall()'''] on the leg. If a call leg receives the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAccepted '''OnCallAccepted()'''] event, it means that an outgoing call has been accepted by the remote peer. This event usually means that the calling number has been accepted and that the call is currently being processed.

After an incoming call has been accepted, a call leg can notify the remote peer that the incoming call has been put in the "ringing" state by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AlertCall '''AlertCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAlerting '''OnCallAlerting()'''] event when an outgoing call has been put in the "ringing" state by the remote peer.

When an incoming call is answered, a call leg can notify the remote peer of the incoming call answered by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AnswerCall '''AnswerCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAnswered '''OnCallAnswered()'''] event when an outgoing call has been answered by the remote peer.

SendCallSuppInfo/OnCallSuppInfo

== Leg Termination ==

Terminating a call leg is a 2 steps process:
# Call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::TerminateCall '''TerminateCall()''']
# Free leg object on [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminated '''OnCallTerminated()''']

When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resources freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Free '''Free()'''] on the leg's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::SetFreeListener '''SetFreeListener()'''] on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is deleted. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.

[[Image:TerminateCall from application.jpg|thumb|center|350px|Call flow for leg termination initiated by user application]]

In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other media resource or signaling error. In these cases, the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminatingIndication '''OnCallTerminatingIndication()'''] is sent to the leg. On reception of this event, the application should initiate call termination as shown below.

[[Image:TerminateCall from Toolpack.jpg|thumb|center|350px|Call flow for leg termination initiated by Toolpack]]

In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnLegTerminated '''OnLegTerminated()'''] event. This event indicates that the leg does not exist anymore on the Toolpack side and the user should free its object without trying any other interaction with Toolpack through it.

== Leg Synchronization on Failover ==
When a Toolpack application is restarted or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs through the '''OnCallLegSync()''' event of the [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_lib_user.html ITBCMCLibUser] interface (this interface must be implemented by all user applications). One event will be received for each leg being synchronized. The course of action to take when receiving a leg synchronization event depends on the ability of the application to resynchronize its states with theses legs.

* If the application can't resynchronize active legs or if it does not want to resychronize the leg for which it is receiving an '''OnCallLegSync()''' event, it must refuse the leg by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLeg '''RefuseLeg()'''].
*If the application wants the resynchronize the leg or if it does not yet have enough information to decide, it must create a CTBCMCLeg object using the leg attributes received in the event.

Once all '''OnCallLegSync()''' have been sent, Toolpack will start synchronization of the links between legs through '''OnLinkSync()'''. This event indicates that two legs are connected together. It can be used by the application to rebuild its internal states. As for the legs, unwanted links can be refused by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()'''].

When all links have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. At that moment, the application has all the information available on the Toolpack side to determine if the legs should be kept or release. Any leg that the application does not want to keep can be refused by calling '''RefuseLeg()''' on it. For all legs that have not been refused, an event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnSyncDone '''OnSyncDone()'''] will be sent on the leg. Once this event has been received on a leg, the leg is fully functional and the application can start calling any usual Toolpack function on it.

[[Image:CallFlow Sync After Application Restart.jpg|thumb|center|350px|Call flow for leg synchronization]]

===Loss of Communication with Toolpack Engine===
If communication is lost with the Toolpack Engine, event '''OnCmcLibNotReady()''' will be sent to the application. It indicates that the Toolpack framework is no more accessible. The legs are still valid at that time but no action can be executed on them as long the CmcLib is not ready. If the connection with the Toolpack Engine is not back up in less than 10 seconds, the CmcLib will declare a major communication loss and will call '''OnLegTerminated()''' on all the legs. In that case, when communication is regained with the Toolpack Engine, the synchronization sequence will start again from the beginning.

[[Image:CallFlow Sync After Comm Restart Passed 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart passed 10 seconds.]]

If the communication is regained before the 10 seconds timeout, event '''OnCmcLibReady()''' will be sent and the application can then continue working normally with its existing call legs. Note that you can also receive '''OnLegTerminated()''' on some legs before receiving the '''OnCmcLibReady()''' if those legs were in a transient state when disconnection occurred.

[[Image:CallFlow Sync After Comm Restart Within 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart within 10 seconds.]]

== Bridging the Media Path ==
=== Join ===

To bridge the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Join '''Join()'''] on one of the leg, giving the second leg as a parameter. This will connect the media path between the two legs according to the link properties set on the leg on which '''Join()''' is called. These link properties can be modified by overloading the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetJoinAttributes '''GetJoinAttributes()''']. The important attribute to set is '''IsFullDuplex()''' that indicates if the connection will be made full-duplex (A<-->B) or half-duplex (A-->B). Prior to release 2.5.2, the default connection mode is half-duplex. For all release version 2.5.2 or higher, the default connection mode is full-duplex.

'''Warning:''' If two legs are already connected in half-duplex and you want to connect them in full-duplex, you must first Unjoin() the legs, then Join() them in full-duplex. You can '''NOT''' only do another half-duplex in the opposite direction.

When legs are joined, it creates a link identified with a unique ''link id''. It is the responsibility of the application to provide this unique ''link id'' by implementing the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetLinkId '''GetLinkId()'''] function of the leg. It is planned to allow the user to provide a value of '0' to let the Toolpack system automatically choose a ''link id'', but as of this writing this feature is not yet available.

'''Warning:''' When two legs are joined, the application must ensure that '''GetLinkId()''' on both leg will return the right ''link id''. This will ensure that when the link needs to be removed, both A->Unjoin() and B->Unjoin() will work correctly.

==== Setting the link properties ====

In your leg class, add a member variable to store the join attributes for that leg.

CTBCMC_JOIN_ATTRIBUTE mJoinAttribute;

Then set the join properties you want in your leg class constructor (or at any other location that will run '''before''' the '''Join()''' is done:

mJoinAttribute.IsFullDuplex() = TBX_TRUE;

Last, implement the '''GetJoinAttributes()''' function.

CTBCMC_JOIN_ATTRIBUTE & CH248Termination::GetJoinAttributes()
{
return mJoinAttribute;
}

==== Broadcasting a media source ====
At the time of writing this, broadcast of a single media source to multiple destinations is not yet possible.

=== Unjoin ===
To disconnect the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Unjoin'''Unjoin()'''] on any of the legs. The '''GetLinkId()''' function of the leg on which '''Unjoin()''' is called must return the ''link id'' that was used when the legs were joined.

[[category:CAF]]
[[category:Needs revising]]

CAF: Working With Call Legs

2010-02-10T15:33:49Z

Alexandre Lussier: /* Play Tone with Custom Tone String */

== Call Leg Definition ==
The main mechanism through which the customer application controls the [[Toolpack]] system is via the management of call legs. The application creates a call leg (or more than one for conferencing and bridging) at the beginning of a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.

A call leg is represented by an instance of the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html CTBCMCLeg] class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 [[timeslot]]) or a [[SIP]] call with its associated [[VOIP]] [[Voice codecs|codec]] resource (attached to an IP/UDP endpoint). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (VOIP codec resource attached to an IP/UDP endpoint). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.

The CTBCMCLeg class allows a programmer to easily act upon the call leg to influence the signaling portion (e.g. accept, answer, terminate, etc) and to use the media portion as well (e.g play prompts, record voice, play or collect digits and tones).

Other member functions are available to retrieve (and change in some cases) the call leg attributes including the media profile (e.g. parameters to the media resource) or signaling information (e.g. protocol type, called and calling party numbers, etc). Joining/unjoining (connection/disconnection) of call legs is also a typical action handled by this class for ’gateway-type’ applications. It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse a ''call leg'' with a ''call''. A ''call leg'' represents one full-duplex link to a party while a ''call'' represents the agglomeration of multiple (two or more) call legs. For example, a ''bridge'' is a form of ''call'' that uses two ''call legs''.
* Do not confuse the base class CTBCMCLeg with the class [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_leg.html CTBCAFCallLeg]. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs. It is designed to represent a leg within a call. It cannot be instanciated as a standalone object without modifications to make it independent from the ITBCAFCallFlow interface.
* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

== Command Flow for Leg Actions in CAF ==
All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).

For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.

== Leg Creation ==
Creating a leg is always done through the definition of a ''call leg attribute''. The values entered in the ''call leg attribute'' will define the type of call leg created and its parameters. The following sections describe several scenarios in which you build a ''call leg''. Instruction will be given on how to fill the leg attributes and how to use them to create the ''call leg''.

=== Preparing Leg Attributes ===

==== Normal Call Leg Attributes ====
For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
* the called number,
* the calling number,
* the [[NAP | Network Access Point]].

Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|NAP Types]]).

The following code snippet shows how to build the attributes.
PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();

ptrOutgoingLegAttribute->GetCalledNumber() = "123-4567";
ptrOutgoingLegAttribute->GetCallingNumber() = "987-6543";
ptrOutgoingLegAttribute->GetNetworkAccessPoint() = "NAP_SS7_MONTREAL";

==== Media-only Leg Attributes ====
For media-only legs, no signaling information is needed but the user can specify which media channel to use and which media profile to use. The only required parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''MEDIA TDM'' or ''MEDIA VOIP'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;

ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();

ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;

When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. For ''MEDIA TDM'' NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For ''MEDIA VOIP'' NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and a timeslot number can be specified.

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc->Settings.TdmAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
pMediaDesc->Settings.TdmAudio.un8Timeslot = 5;
Strncpy
(
pMediaDesc->Settings.TdmAudio.szTrunkName,
"TRUNK_TORONTO_1",
sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
);

For VOIP legs, the user can control the media by providing local [[SDP]] and peer SDP. Setting the local SDP defines the codec and IP/port used to for the received media stream. Most of the time, the IP address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and IP/port used for the transmitted media stream. Note that Toolpack only allows for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in '''both''' SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].

TBX_RESULT Result;
TBX_SDP_INFO SdpInfo;
PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();
pMediaDesc->Settings.PacketAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;

// Set Local SDP
Result = BuildSdpInfo("", 0, SdpInfo); // No IP specified, Toolpack will choose one
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

// Set Peer SDP
Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo); // Using peer IP address and port
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetPeerSDP(SdpInfo);

=== Creating the Leg ===
Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CreateCall '''CreateCall()'''] on it. No action is taken when an instance of a CTBCMCLeg is created. Call resources are only allocated in the Toolpack system when '''CreateCall()''' is called on the object.

pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
pCallLeg->CreateCall();

For legs with signaling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).

[[Image:CallFlow SignalingMediaLeg Creation.JPG|thumb|center|350px|Call flow for creation of leg with signaling]]

For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.

[[Image:CallFlow MediaOnlyLeg Creation.JPG|thumb|center|350px|Call flow for media-only leg creation]]

Once a call is fully active (call answered and media allocated), event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnProfileChanged '''OnProfileChanged()'''] will be sent on the leg. In the cases where the user had not specified the IP/port to use, once this event is received, the media profile has been updated with the values chosen by Toolpack and the updated values can be retrieved using the functions '''GetLocalSDP()''' and '''GetPeerSDP()''' of the profile.
Note that the '''OnProfileChanged()''' event is also sent after the media profile has been modified with the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ChangeProfile '''ChangeProfile()'''] function (see [[#Modifying Media Profile|Modifying Media Profile]]) and when a connected peer has requested it (through a SIP re-INVITE for example).

See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.

=== Caveats ===
* The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).

== Interaction with Legs ==

=== Playing and Collecting Digits ===

You can play digits by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayDigit '''PlayDigit()'''] on a leg. Toolpack will receive the request and play the digits. Once digits are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitPlayingDone '''OnDigitPlayingDone()'''] event.

 You can also configure a leg to collect digits played. To start the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartDigitCollection '''StartDigitCollection()'''] on the leg. To stop the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopDigitCollection '''StopDigitCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitCollected '''OnDigitCollected()'''] event when there will be a match between the asked string and the digits collected.

 Here are examples how to play and collect digit.

===== Play Digit =====

<code></code>
<pre>ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
/* this will play the sequence of digit 5551234 */
ptrOutgoingLeg->PlayDigit( "5551234" );
}
</pre>
===== Collect Digit =====

<code></code>
<pre>ptrIncomingLeg = GetIncomingActiveLeg();
if( ptrIncomingLeg != NULL )
{
/*
this will collect digits 5, any sequences of 7 digits beginning by 3 or any sequences of 7 digits
beginning by 4,5,6 or 7 followed by 5 and 5.
*/
ptrIncomingLeg->StartDigitCollection( "5|3xxxxxx|[4-7]55xxxx" );
}
</pre>
=== Playing and Collecting Tones ===
Tones are defined as events, this is why to play and collect tones, you have to use general event functions. You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play events by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayEvent '''PlayEvent()'''] on a leg. Toolpack will receive the request and play the events. Once events are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventPlayingDone '''OnEventPlayingDone()'''] event. Note that you can cancel an event to be played by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CancelEvent '''CancelEvent()'''] on the leg after a '''PlayEvent()''' has been called.

Two kinds of string can be passed to '''AddToneString()''' to play a tone. The first type is to play well known tones such as dtmf and fax tone. The syntax is really simple and is based on H248 package and signal ids. The first component of the string is the package id and the second is the signal id, both formated in string. So, to play dtmf 0, you have to format the following string: "dg/d0", where "dg" is for package "dtmf generation" and "d0" is for "dtmf 0".

===== Play Tone with Signal Id String =====
<code><pre>
/* this will play dtmf 7 */

CTBCMC_EVENT_ATTRIBUTE Event;
Event.AddToneString( "dg/d7" );
ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
ptrOutgoingLeg->PlayEvent( Event );
}
</pre></code>

The second type of string is to play custom tone. The syntax is much more complicated than the first one, but it follows a well described syntax which can be found in [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.6-200011-I!!PDF-E&type=items/.pdf '''H248.6 Dynamic Tone Definition Package''']. This kind of string allows you to specify frequencies, duration, amplitude and repeating count of the tone. You can also specify well known tones and change their default duration, amplitude and repeating count. It is possible to describe a sequence of tones or frequencies that are played in one segment. Here are some examples of the syntax:

*;Frequencies 400Hz and 600Hz mixed together for 200ms, amplitude at -10dB and repeating 3 times (playing 4 times):
:*(((#400)+(#600)),200,-10)*3
:
*;Dtmf 5 repeated infinitly:
:*((0x0005,0x0015))*0
:
*;Multifrequency tone 8:
:*((mfg,mf8))
:
*;Frequency 440Hz played for 300ms at -10dB followed by frequency 600Hz played for 200ms at -5dB and then followed by dtmf 2, all this repeated infinitly:
:*((#440,300,-10),(#600,200,-5),(0x0005,0x0012))*0
:

===== Play Tone with Custom Tone String=====
<code><pre>
/* this will play frequencies 1000Hz and 2100Hz mixed together */

CTBCMC_EVENT_ATTRIBUTE Event;
Event.AddToneString( "(((#1000)+(#2100)),100,-10)" );
ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
ptrOutgoingLeg->PlayEvent( Event );
}
</code></pre>

You can also configure a leg to collect events played. To start the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartEventCollection '''StartEventCollection()'''] on the leg. Note that you will have to specify which events you want to collect before starting the event collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopEventCollection '''StopEventCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventCollected '''OnEventCollected()'''] event on each event received that correspond to a tone string specified when calling '''StartEventCollection()'''.

Only one type of string is accepted to specify which events to collect. The string is the same as the first type to play event. Signal ids that are also event id are accepted. This means that you can ask to collect "dg/d0" (dtmf generation/dtmf 0) and the detection will be done anyway. But, when the event is detected, it's the event id that will be returned, which means that "dd/d0" (dtmf detection/dtmf 0) will be returned instead of "dg/d0". You can also detect all events from a package by putting a * as event id, so "dd/*" will detect all dtmf tones.

===== Collect Tone =====
<code><pre>
/* this will collect all dtmf tones */

CTBCMC_EVENT_ATTRIBUTE Event;
Event.AddToneString( "dd/*" );
GetOutgoingActiveLeg()->StartEventCollection( Event );
</code></pre>

The most commonly used package are 5 and 6 [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.1-200509-I!!PDF-E&type=items/.pdf '''(H248.1 Annex E)''']: dtmf generation and dtmf detection. As H248 does not define events and signals for fax tone, we added a special package to do so. Package telcofax (0x8001) contains three events and two signals. Signals are: cng (0x0080) and g164 (0x0081) and events are: cng (0x0080), g164 (0x0081) and g165 (0x0082).

=== Collecting digits and tones while call legs are joined ===
By default, when two call legs are joined together through function CTBCMCCallLeg::Join(), tone collection is automatically disabled.
One of the arguments of the Join() function ("in_fDisableToneWhileJoined") will allow to control if automatic tone collection feature is used or not on a call.

Why is Toolpack disabling tone collection on joined legs by default?
That's because tone collection introduces a 40ms delay in the audio connection (required to provide tone suppression), and most of the time it is no more require to collect digits while two call legs are joined, so it would be useless to leave 40ms delay while tone collection is no more required.

=== Playing and Recording Audio Files ===
You can play an audio stream on a leg by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayStream '''PlayStream()'''] on it. To specify which audio stream you want to play, you have to specify it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html#CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath '''AddPlayFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html CTBCMC_PLAY_ATTRIBUTE] class. Toolpack will receive the request and play the stream. Once it is played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingDone '''OnStreamPlayingDone()'''] event.

You can also configure a leg to record an audio stream. First you must specify file paths to record by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html#CTBCMC_RECORD_ATTRIBUTE::AddRecFilePath '''AddRecFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html CTBCMC_RECORD_ATTRIBUTE] class. The you can call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RecordStream '''RecordStream()'''] on a leg. Once the stream is recorded, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamRecordingDone '''OnStreamRecordingDone()'''] event.

You can pause an active playing or recording stream by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PauseStream '''PauseStream()'''] and you can resume it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ResumeStream '''ResumeStream()''']. If you want to stop an active playing or recording stream, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopStream '''StopStream()'''] on the leg.

=== Modifying Media Profile ===
It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.

The media profile is stored in the leg attributes and can be modified like this :
TBX_SDP_INFO SdpInfo;
PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;

pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
pMediaLegAttribute->GetProfile().GetLocalSDP(SdpInfo);
Strncpy
(
SdpInfo.aConnections[0].szIp,
"",
sizeof( SdpInfo.aConnections[0].szIp )
);
SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
pMediaLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

pCallLeg->ChangeProfile();

Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotiation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.

Once the profile change has completed (or failed), event '''OnProfileChanged()''' will be received on the leg.

For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.

=== Controlling the Signaling ===
When a call leg receives the '''OnCallLegPresent()''' event, it indicates an incoming call. To confirm that the call contains sufficient valid information to process the call on the system, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AcceptCall '''AcceptCall()'''] on the leg. If a call leg receives the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAccepted '''OnCallAccepted()'''] event, it means that an outgoing call has been accepted by the remote peer. This event usually means that the calling number has been accepted and that the call is currently being processed.

After an incoming call has been accepted, a call leg can notify the remote peer that the incoming call has been put in the "ringing" state by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AlertCall '''AlertCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAlerting '''OnCallAlerting()'''] event when an outgoing call has been put in the "ringing" state by the remote peer.

When an incoming call is answered, a call leg can notify the remote peer of the incoming call answered by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AnswerCall '''AnswerCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAnswered '''OnCallAnswered()'''] event when an outgoing call has been answered by the remote peer.

SendCallSuppInfo/OnCallSuppInfo

== Leg Termination ==

Terminating a call leg is a 2 steps process:
# Call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::TerminateCall '''TerminateCall()''']
# Free leg object on [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminated '''OnCallTerminated()''']

When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resources freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Free '''Free()'''] on the leg's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::SetFreeListener '''SetFreeListener()'''] on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is deleted. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.

[[Image:TerminateCall from application.jpg|thumb|center|350px|Call flow for leg termination initiated by user application]]

In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other media resource or signaling error. In these cases, the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminatingIndication '''OnCallTerminatingIndication()'''] is sent to the leg. On reception of this event, the application should initiate call termination as shown below.

[[Image:TerminateCall from Toolpack.jpg|thumb|center|350px|Call flow for leg termination initiated by Toolpack]]

In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnLegTerminated '''OnLegTerminated()'''] event. This event indicates that the leg does not exist anymore on the Toolpack side and the user should free its object without trying any other interaction with Toolpack through it.

== Leg Synchronization on Failover ==
When a Toolpack application is restarted or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs through the '''OnCallLegSync()''' event of the [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_lib_user.html ITBCMCLibUser] interface (this interface must be implemented by all user applications). One event will be received for each leg being synchronized. The course of action to take when receiving a leg synchronization event depends on the ability of the application to resynchronize its states with theses legs.

* If the application can't resynchronize active legs or if it does not want to resychronize the leg for which it is receiving an '''OnCallLegSync()''' event, it must refuse the leg by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLeg '''RefuseLeg()'''].
*If the application wants the resynchronize the leg or if it does not yet have enough information to decide, it must create a CTBCMCLeg object using the leg attributes received in the event.

Once all '''OnCallLegSync()''' have been sent, Toolpack will start synchronization of the links between legs through '''OnLinkSync()'''. This event indicates that two legs are connected together. It can be used by the application to rebuild its internal states. As for the legs, unwanted links can be refused by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()'''].

When all links have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. At that moment, the application has all the information available on the Toolpack side to determine if the legs should be kept or release. Any leg that the application does not want to keep can be refused by calling '''RefuseLeg()''' on it. For all legs that have not been refused, an event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnSyncDone '''OnSyncDone()'''] will be sent on the leg. Once this event has been received on a leg, the leg is fully functional and the application can start calling any usual Toolpack function on it.

[[Image:CallFlow Sync After Application Restart.jpg|thumb|center|350px|Call flow for leg synchronization]]

===Loss of Communication with Toolpack Engine===
If communication is lost with the Toolpack Engine, event '''OnCmcLibNotReady()''' will be sent to the application. It indicates that the Toolpack framework is no more accessible. The legs are still valid at that time but no action can be executed on them as long the CmcLib is not ready. If the connection with the Toolpack Engine is not back up in less than 10 seconds, the CmcLib will declare a major communication loss and will call '''OnLegTerminated()''' on all the legs. In that case, when communication is regained with the Toolpack Engine, the synchronization sequence will start again from the beginning.

[[Image:CallFlow Sync After Comm Restart Passed 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart passed 10 seconds.]]

If the communication is regained before the 10 seconds timeout, event '''OnCmcLibReady()''' will be sent and the application can then continue working normally with its existing call legs. Note that you can also receive '''OnLegTerminated()''' on some legs before receiving the '''OnCmcLibReady()''' if those legs were in a transient state when disconnection occurred.

[[Image:CallFlow Sync After Comm Restart Within 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart within 10 seconds.]]

== Bridging the Media Path ==
=== Join ===

To bridge the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Join '''Join()'''] on one of the leg, giving the second leg as a parameter. This will connect the media path between the two legs according to the link properties set on the leg on which '''Join()''' is called. These link properties can be modified by overloading the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetJoinAttributes '''GetJoinAttributes()''']. The important attribute to set is '''IsFullDuplex()''' that indicates if the connection will be made full-duplex (A<-->B) or half-duplex (A-->B). Prior to release 2.5.2, the default connection mode is half-duplex. For all release version 2.5.2 or higher, the default connection mode is full-duplex.

'''Warning:''' If two legs are already connected in half-duplex and you want to connect them in full-duplex, you must first Unjoin() the legs, then Join() them in full-duplex. You can '''NOT''' only do another half-duplex in the opposite direction.

When legs are joined, it creates a link identified with a unique ''link id''. It is the responsibility of the application to provide this unique ''link id'' by implementing the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetLinkId '''GetLinkId()'''] function of the leg. It is planned to allow the user to provide a value of '0' to let the Toolpack system automatically choose a ''link id'', but as of this writing this feature is not yet available.

'''Warning:''' When two legs are joined, the application must ensure that '''GetLinkId()''' on both leg will return the right ''link id''. This will ensure that when the link needs to be removed, both A->Unjoin() and B->Unjoin() will work correctly.

==== Setting the link properties ====

In your leg class, add a member variable to store the join attributes for that leg.

CTBCMC_JOIN_ATTRIBUTE mJoinAttribute;

Then set the join properties you want in your leg class constructor (or at any other location that will run '''before''' the '''Join()''' is done:

mJoinAttribute.IsFullDuplex() = TBX_TRUE;

Last, implement the '''GetJoinAttributes()''' function.

CTBCMC_JOIN_ATTRIBUTE & CH248Termination::GetJoinAttributes()
{
return mJoinAttribute;
}

==== Broadcasting a media source ====
At the time of writing this, broadcast of a single media source to multiple destinations is not yet possible.

=== Unjoin ===
To disconnect the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Unjoin'''Unjoin()'''] on any of the legs. The '''GetLinkId()''' function of the leg on which '''Unjoin()''' is called must return the ''link id'' that was used when the legs were joined.

[[category:CAF]]
[[category:Needs revising]]

CAF: Working With Call Legs

2010-02-10T15:32:40Z

Alexandre Lussier: /* Play Tone with Signal Id String */

== Call Leg Definition ==
The main mechanism through which the customer application controls the [[Toolpack]] system is via the management of call legs. The application creates a call leg (or more than one for conferencing and bridging) at the beginning of a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.

A call leg is represented by an instance of the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html CTBCMCLeg] class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 [[timeslot]]) or a [[SIP]] call with its associated [[VOIP]] [[Voice codecs|codec]] resource (attached to an IP/UDP endpoint). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (VOIP codec resource attached to an IP/UDP endpoint). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.

The CTBCMCLeg class allows a programmer to easily act upon the call leg to influence the signaling portion (e.g. accept, answer, terminate, etc) and to use the media portion as well (e.g play prompts, record voice, play or collect digits and tones).

Other member functions are available to retrieve (and change in some cases) the call leg attributes including the media profile (e.g. parameters to the media resource) or signaling information (e.g. protocol type, called and calling party numbers, etc). Joining/unjoining (connection/disconnection) of call legs is also a typical action handled by this class for ’gateway-type’ applications. It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse a ''call leg'' with a ''call''. A ''call leg'' represents one full-duplex link to a party while a ''call'' represents the agglomeration of multiple (two or more) call legs. For example, a ''bridge'' is a form of ''call'' that uses two ''call legs''.
* Do not confuse the base class CTBCMCLeg with the class [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_leg.html CTBCAFCallLeg]. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs. It is designed to represent a leg within a call. It cannot be instanciated as a standalone object without modifications to make it independent from the ITBCAFCallFlow interface.
* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

== Command Flow for Leg Actions in CAF ==
All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).

For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.

== Leg Creation ==
Creating a leg is always done through the definition of a ''call leg attribute''. The values entered in the ''call leg attribute'' will define the type of call leg created and its parameters. The following sections describe several scenarios in which you build a ''call leg''. Instruction will be given on how to fill the leg attributes and how to use them to create the ''call leg''.

=== Preparing Leg Attributes ===

==== Normal Call Leg Attributes ====
For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
* the called number,
* the calling number,
* the [[NAP | Network Access Point]].

Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|NAP Types]]).

The following code snippet shows how to build the attributes.
PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();

ptrOutgoingLegAttribute->GetCalledNumber() = "123-4567";
ptrOutgoingLegAttribute->GetCallingNumber() = "987-6543";
ptrOutgoingLegAttribute->GetNetworkAccessPoint() = "NAP_SS7_MONTREAL";

==== Media-only Leg Attributes ====
For media-only legs, no signaling information is needed but the user can specify which media channel to use and which media profile to use. The only required parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''MEDIA TDM'' or ''MEDIA VOIP'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;

ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();

ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;

When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. For ''MEDIA TDM'' NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For ''MEDIA VOIP'' NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and a timeslot number can be specified.

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc->Settings.TdmAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
pMediaDesc->Settings.TdmAudio.un8Timeslot = 5;
Strncpy
(
pMediaDesc->Settings.TdmAudio.szTrunkName,
"TRUNK_TORONTO_1",
sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
);

For VOIP legs, the user can control the media by providing local [[SDP]] and peer SDP. Setting the local SDP defines the codec and IP/port used to for the received media stream. Most of the time, the IP address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and IP/port used for the transmitted media stream. Note that Toolpack only allows for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in '''both''' SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].

TBX_RESULT Result;
TBX_SDP_INFO SdpInfo;
PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();
pMediaDesc->Settings.PacketAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;

// Set Local SDP
Result = BuildSdpInfo("", 0, SdpInfo); // No IP specified, Toolpack will choose one
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

// Set Peer SDP
Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo); // Using peer IP address and port
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetPeerSDP(SdpInfo);

=== Creating the Leg ===
Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CreateCall '''CreateCall()'''] on it. No action is taken when an instance of a CTBCMCLeg is created. Call resources are only allocated in the Toolpack system when '''CreateCall()''' is called on the object.

pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
pCallLeg->CreateCall();

For legs with signaling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).

[[Image:CallFlow SignalingMediaLeg Creation.JPG|thumb|center|350px|Call flow for creation of leg with signaling]]

For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.

[[Image:CallFlow MediaOnlyLeg Creation.JPG|thumb|center|350px|Call flow for media-only leg creation]]

Once a call is fully active (call answered and media allocated), event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnProfileChanged '''OnProfileChanged()'''] will be sent on the leg. In the cases where the user had not specified the IP/port to use, once this event is received, the media profile has been updated with the values chosen by Toolpack and the updated values can be retrieved using the functions '''GetLocalSDP()''' and '''GetPeerSDP()''' of the profile.
Note that the '''OnProfileChanged()''' event is also sent after the media profile has been modified with the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ChangeProfile '''ChangeProfile()'''] function (see [[#Modifying Media Profile|Modifying Media Profile]]) and when a connected peer has requested it (through a SIP re-INVITE for example).

See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.

=== Caveats ===
* The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).

== Interaction with Legs ==

=== Playing and Collecting Digits ===

You can play digits by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayDigit '''PlayDigit()'''] on a leg. Toolpack will receive the request and play the digits. Once digits are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitPlayingDone '''OnDigitPlayingDone()'''] event.

 You can also configure a leg to collect digits played. To start the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartDigitCollection '''StartDigitCollection()'''] on the leg. To stop the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopDigitCollection '''StopDigitCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitCollected '''OnDigitCollected()'''] event when there will be a match between the asked string and the digits collected.

 Here are examples how to play and collect digit.

===== Play Digit =====

<code></code>
<pre>ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
/* this will play the sequence of digit 5551234 */
ptrOutgoingLeg->PlayDigit( "5551234" );
}
</pre>
===== Collect Digit =====

<code></code>
<pre>ptrIncomingLeg = GetIncomingActiveLeg();
if( ptrIncomingLeg != NULL )
{
/*
this will collect digits 5, any sequences of 7 digits beginning by 3 or any sequences of 7 digits
beginning by 4,5,6 or 7 followed by 5 and 5.
*/
ptrIncomingLeg->StartDigitCollection( "5|3xxxxxx|[4-7]55xxxx" );
}
</pre>
=== Playing and Collecting Tones ===
Tones are defined as events, this is why to play and collect tones, you have to use general event functions. You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play events by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayEvent '''PlayEvent()'''] on a leg. Toolpack will receive the request and play the events. Once events are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventPlayingDone '''OnEventPlayingDone()'''] event. Note that you can cancel an event to be played by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CancelEvent '''CancelEvent()'''] on the leg after a '''PlayEvent()''' has been called.

Two kinds of string can be passed to '''AddToneString()''' to play a tone. The first type is to play well known tones such as dtmf and fax tone. The syntax is really simple and is based on H248 package and signal ids. The first component of the string is the package id and the second is the signal id, both formated in string. So, to play dtmf 0, you have to format the following string: "dg/d0", where "dg" is for package "dtmf generation" and "d0" is for "dtmf 0".

===== Play Tone with Signal Id String =====
<code><pre>
/* this will play dtmf 7 */

CTBCMC_EVENT_ATTRIBUTE Event;
Event.AddToneString( "dg/d7" );
ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
ptrOutgoingLeg->PlayEvent( Event );
}
</pre></code>

The second type of string is to play custom tone. The syntax is much more complicated than the first one, but it follows a well described syntax which can be found in [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.6-200011-I!!PDF-E&type=items/.pdf '''H248.6 Dynamic Tone Definition Package''']. This kind of string allows you to specify frequencies, duration, amplitude and repeating count of the tone. You can also specify well known tones and change their default duration, amplitude and repeating count. It is possible to describe a sequence of tones or frequencies that are played in one segment. Here are some examples of the syntax:

*;Frequencies 400Hz and 600Hz mixed together for 200ms, amplitude at -10dB and repeating 3 times (playing 4 times):
:*(((#400)+(#600)),200,-10)*3
:
*;Dtmf 5 repeated infinitly:
:*((0x0005,0x0015))*0
:
*;Multifrequency tone 8:
:*((mfg,mf8))
:
*;Frequency 440Hz played for 300ms at -10dB followed by frequency 600Hz played for 200ms at -5dB and then followed by dtmf 2, all this repeated infinitly:
:*((#440,300,-10),(#600,200,-5),(0x0005,0x0012))*0
:

===== Play Tone with Custom Tone String=====
<code><pre>
/* this will play frequencies 1000Hz and 2100Hz mixed together */

CTBCMC_EVENT_ATTRIBUTE Event;
Event.AddToneString( "(((#1000)+(#2100)),100,-10)" );
GetOutgoingActiveLeg()->PlayEvent( Event );
</code></pre>

You can also configure a leg to collect events played. To start the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartEventCollection '''StartEventCollection()'''] on the leg. Note that you will have to specify which events you want to collect before starting the event collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopEventCollection '''StopEventCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventCollected '''OnEventCollected()'''] event on each event received that correspond to a tone string specified when calling '''StartEventCollection()'''.

Only one type of string is accepted to specify which events to collect. The string is the same as the first type to play event. Signal ids that are also event id are accepted. This means that you can ask to collect "dg/d0" (dtmf generation/dtmf 0) and the detection will be done anyway. But, when the event is detected, it's the event id that will be returned, which means that "dd/d0" (dtmf detection/dtmf 0) will be returned instead of "dg/d0". You can also detect all events from a package by putting a * as event id, so "dd/*" will detect all dtmf tones.

===== Collect Tone =====
<code><pre>
/* this will collect all dtmf tones */

CTBCMC_EVENT_ATTRIBUTE Event;
Event.AddToneString( "dd/*" );
GetOutgoingActiveLeg()->StartEventCollection( Event );
</code></pre>

The most commonly used package are 5 and 6 [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.1-200509-I!!PDF-E&type=items/.pdf '''(H248.1 Annex E)''']: dtmf generation and dtmf detection. As H248 does not define events and signals for fax tone, we added a special package to do so. Package telcofax (0x8001) contains three events and two signals. Signals are: cng (0x0080) and g164 (0x0081) and events are: cng (0x0080), g164 (0x0081) and g165 (0x0082).

=== Collecting digits and tones while call legs are joined ===
By default, when two call legs are joined together through function CTBCMCCallLeg::Join(), tone collection is automatically disabled.
One of the arguments of the Join() function ("in_fDisableToneWhileJoined") will allow to control if automatic tone collection feature is used or not on a call.

Why is Toolpack disabling tone collection on joined legs by default?
That's because tone collection introduces a 40ms delay in the audio connection (required to provide tone suppression), and most of the time it is no more require to collect digits while two call legs are joined, so it would be useless to leave 40ms delay while tone collection is no more required.

=== Playing and Recording Audio Files ===
You can play an audio stream on a leg by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayStream '''PlayStream()'''] on it. To specify which audio stream you want to play, you have to specify it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html#CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath '''AddPlayFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html CTBCMC_PLAY_ATTRIBUTE] class. Toolpack will receive the request and play the stream. Once it is played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingDone '''OnStreamPlayingDone()'''] event.

You can also configure a leg to record an audio stream. First you must specify file paths to record by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html#CTBCMC_RECORD_ATTRIBUTE::AddRecFilePath '''AddRecFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html CTBCMC_RECORD_ATTRIBUTE] class. The you can call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RecordStream '''RecordStream()'''] on a leg. Once the stream is recorded, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamRecordingDone '''OnStreamRecordingDone()'''] event.

You can pause an active playing or recording stream by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PauseStream '''PauseStream()'''] and you can resume it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ResumeStream '''ResumeStream()''']. If you want to stop an active playing or recording stream, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopStream '''StopStream()'''] on the leg.

=== Modifying Media Profile ===
It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.

The media profile is stored in the leg attributes and can be modified like this :
TBX_SDP_INFO SdpInfo;
PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;

pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
pMediaLegAttribute->GetProfile().GetLocalSDP(SdpInfo);
Strncpy
(
SdpInfo.aConnections[0].szIp,
"",
sizeof( SdpInfo.aConnections[0].szIp )
);
SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
pMediaLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

pCallLeg->ChangeProfile();

Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotiation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.

Once the profile change has completed (or failed), event '''OnProfileChanged()''' will be received on the leg.

For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.

=== Controlling the Signaling ===
When a call leg receives the '''OnCallLegPresent()''' event, it indicates an incoming call. To confirm that the call contains sufficient valid information to process the call on the system, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AcceptCall '''AcceptCall()'''] on the leg. If a call leg receives the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAccepted '''OnCallAccepted()'''] event, it means that an outgoing call has been accepted by the remote peer. This event usually means that the calling number has been accepted and that the call is currently being processed.

After an incoming call has been accepted, a call leg can notify the remote peer that the incoming call has been put in the "ringing" state by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AlertCall '''AlertCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAlerting '''OnCallAlerting()'''] event when an outgoing call has been put in the "ringing" state by the remote peer.

When an incoming call is answered, a call leg can notify the remote peer of the incoming call answered by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AnswerCall '''AnswerCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAnswered '''OnCallAnswered()'''] event when an outgoing call has been answered by the remote peer.

SendCallSuppInfo/OnCallSuppInfo

== Leg Termination ==

Terminating a call leg is a 2 steps process:
# Call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::TerminateCall '''TerminateCall()''']
# Free leg object on [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminated '''OnCallTerminated()''']

When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resources freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Free '''Free()'''] on the leg's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::SetFreeListener '''SetFreeListener()'''] on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is deleted. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.

[[Image:TerminateCall from application.jpg|thumb|center|350px|Call flow for leg termination initiated by user application]]

In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other media resource or signaling error. In these cases, the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminatingIndication '''OnCallTerminatingIndication()'''] is sent to the leg. On reception of this event, the application should initiate call termination as shown below.

[[Image:TerminateCall from Toolpack.jpg|thumb|center|350px|Call flow for leg termination initiated by Toolpack]]

In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnLegTerminated '''OnLegTerminated()'''] event. This event indicates that the leg does not exist anymore on the Toolpack side and the user should free its object without trying any other interaction with Toolpack through it.

== Leg Synchronization on Failover ==
When a Toolpack application is restarted or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs through the '''OnCallLegSync()''' event of the [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_lib_user.html ITBCMCLibUser] interface (this interface must be implemented by all user applications). One event will be received for each leg being synchronized. The course of action to take when receiving a leg synchronization event depends on the ability of the application to resynchronize its states with theses legs.

* If the application can't resynchronize active legs or if it does not want to resychronize the leg for which it is receiving an '''OnCallLegSync()''' event, it must refuse the leg by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLeg '''RefuseLeg()'''].
*If the application wants the resynchronize the leg or if it does not yet have enough information to decide, it must create a CTBCMCLeg object using the leg attributes received in the event.

Once all '''OnCallLegSync()''' have been sent, Toolpack will start synchronization of the links between legs through '''OnLinkSync()'''. This event indicates that two legs are connected together. It can be used by the application to rebuild its internal states. As for the legs, unwanted links can be refused by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()'''].

When all links have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. At that moment, the application has all the information available on the Toolpack side to determine if the legs should be kept or release. Any leg that the application does not want to keep can be refused by calling '''RefuseLeg()''' on it. For all legs that have not been refused, an event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnSyncDone '''OnSyncDone()'''] will be sent on the leg. Once this event has been received on a leg, the leg is fully functional and the application can start calling any usual Toolpack function on it.

[[Image:CallFlow Sync After Application Restart.jpg|thumb|center|350px|Call flow for leg synchronization]]

===Loss of Communication with Toolpack Engine===
If communication is lost with the Toolpack Engine, event '''OnCmcLibNotReady()''' will be sent to the application. It indicates that the Toolpack framework is no more accessible. The legs are still valid at that time but no action can be executed on them as long the CmcLib is not ready. If the connection with the Toolpack Engine is not back up in less than 10 seconds, the CmcLib will declare a major communication loss and will call '''OnLegTerminated()''' on all the legs. In that case, when communication is regained with the Toolpack Engine, the synchronization sequence will start again from the beginning.

[[Image:CallFlow Sync After Comm Restart Passed 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart passed 10 seconds.]]

If the communication is regained before the 10 seconds timeout, event '''OnCmcLibReady()''' will be sent and the application can then continue working normally with its existing call legs. Note that you can also receive '''OnLegTerminated()''' on some legs before receiving the '''OnCmcLibReady()''' if those legs were in a transient state when disconnection occurred.

[[Image:CallFlow Sync After Comm Restart Within 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart within 10 seconds.]]

== Bridging the Media Path ==
=== Join ===

To bridge the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Join '''Join()'''] on one of the leg, giving the second leg as a parameter. This will connect the media path between the two legs according to the link properties set on the leg on which '''Join()''' is called. These link properties can be modified by overloading the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetJoinAttributes '''GetJoinAttributes()''']. The important attribute to set is '''IsFullDuplex()''' that indicates if the connection will be made full-duplex (A<-->B) or half-duplex (A-->B). Prior to release 2.5.2, the default connection mode is half-duplex. For all release version 2.5.2 or higher, the default connection mode is full-duplex.

'''Warning:''' If two legs are already connected in half-duplex and you want to connect them in full-duplex, you must first Unjoin() the legs, then Join() them in full-duplex. You can '''NOT''' only do another half-duplex in the opposite direction.

When legs are joined, it creates a link identified with a unique ''link id''. It is the responsibility of the application to provide this unique ''link id'' by implementing the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetLinkId '''GetLinkId()'''] function of the leg. It is planned to allow the user to provide a value of '0' to let the Toolpack system automatically choose a ''link id'', but as of this writing this feature is not yet available.

'''Warning:''' When two legs are joined, the application must ensure that '''GetLinkId()''' on both leg will return the right ''link id''. This will ensure that when the link needs to be removed, both A->Unjoin() and B->Unjoin() will work correctly.

==== Setting the link properties ====

In your leg class, add a member variable to store the join attributes for that leg.

CTBCMC_JOIN_ATTRIBUTE mJoinAttribute;

Then set the join properties you want in your leg class constructor (or at any other location that will run '''before''' the '''Join()''' is done:

mJoinAttribute.IsFullDuplex() = TBX_TRUE;

Last, implement the '''GetJoinAttributes()''' function.

CTBCMC_JOIN_ATTRIBUTE & CH248Termination::GetJoinAttributes()
{
return mJoinAttribute;
}

==== Broadcasting a media source ====
At the time of writing this, broadcast of a single media source to multiple destinations is not yet possible.

=== Unjoin ===
To disconnect the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Unjoin'''Unjoin()'''] on any of the legs. The '''GetLinkId()''' function of the leg on which '''Unjoin()''' is called must return the ''link id'' that was used when the legs were joined.

[[category:CAF]]
[[category:Needs revising]]

CAF: Working With Call Legs

2010-02-10T15:31:28Z

Alexandre Lussier: /* Playing and Collecting Tones */

== Call Leg Definition ==
The main mechanism through which the customer application controls the [[Toolpack]] system is via the management of call legs. The application creates a call leg (or more than one for conferencing and bridging) at the beginning of a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.

A call leg is represented by an instance of the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html CTBCMCLeg] class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 [[timeslot]]) or a [[SIP]] call with its associated [[VOIP]] [[Voice codecs|codec]] resource (attached to an IP/UDP endpoint). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (VOIP codec resource attached to an IP/UDP endpoint). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.

The CTBCMCLeg class allows a programmer to easily act upon the call leg to influence the signaling portion (e.g. accept, answer, terminate, etc) and to use the media portion as well (e.g play prompts, record voice, play or collect digits and tones).

Other member functions are available to retrieve (and change in some cases) the call leg attributes including the media profile (e.g. parameters to the media resource) or signaling information (e.g. protocol type, called and calling party numbers, etc). Joining/unjoining (connection/disconnection) of call legs is also a typical action handled by this class for ’gateway-type’ applications. It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse a ''call leg'' with a ''call''. A ''call leg'' represents one full-duplex link to a party while a ''call'' represents the agglomeration of multiple (two or more) call legs. For example, a ''bridge'' is a form of ''call'' that uses two ''call legs''.
* Do not confuse the base class CTBCMCLeg with the class [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_leg.html CTBCAFCallLeg]. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs. It is designed to represent a leg within a call. It cannot be instanciated as a standalone object without modifications to make it independent from the ITBCAFCallFlow interface.
* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

== Command Flow for Leg Actions in CAF ==
All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).

For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.

== Leg Creation ==
Creating a leg is always done through the definition of a ''call leg attribute''. The values entered in the ''call leg attribute'' will define the type of call leg created and its parameters. The following sections describe several scenarios in which you build a ''call leg''. Instruction will be given on how to fill the leg attributes and how to use them to create the ''call leg''.

=== Preparing Leg Attributes ===

==== Normal Call Leg Attributes ====
For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
* the called number,
* the calling number,
* the [[NAP | Network Access Point]].

Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|NAP Types]]).

The following code snippet shows how to build the attributes.
PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();

ptrOutgoingLegAttribute->GetCalledNumber() = "123-4567";
ptrOutgoingLegAttribute->GetCallingNumber() = "987-6543";
ptrOutgoingLegAttribute->GetNetworkAccessPoint() = "NAP_SS7_MONTREAL";

==== Media-only Leg Attributes ====
For media-only legs, no signaling information is needed but the user can specify which media channel to use and which media profile to use. The only required parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''MEDIA TDM'' or ''MEDIA VOIP'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;

ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();

ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;

When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. For ''MEDIA TDM'' NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For ''MEDIA VOIP'' NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and a timeslot number can be specified.

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc->Settings.TdmAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
pMediaDesc->Settings.TdmAudio.un8Timeslot = 5;
Strncpy
(
pMediaDesc->Settings.TdmAudio.szTrunkName,
"TRUNK_TORONTO_1",
sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
);

For VOIP legs, the user can control the media by providing local [[SDP]] and peer SDP. Setting the local SDP defines the codec and IP/port used to for the received media stream. Most of the time, the IP address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and IP/port used for the transmitted media stream. Note that Toolpack only allows for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in '''both''' SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].

TBX_RESULT Result;
TBX_SDP_INFO SdpInfo;
PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();
pMediaDesc->Settings.PacketAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;

// Set Local SDP
Result = BuildSdpInfo("", 0, SdpInfo); // No IP specified, Toolpack will choose one
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

// Set Peer SDP
Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo); // Using peer IP address and port
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetPeerSDP(SdpInfo);

=== Creating the Leg ===
Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CreateCall '''CreateCall()'''] on it. No action is taken when an instance of a CTBCMCLeg is created. Call resources are only allocated in the Toolpack system when '''CreateCall()''' is called on the object.

pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
pCallLeg->CreateCall();

For legs with signaling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).

[[Image:CallFlow SignalingMediaLeg Creation.JPG|thumb|center|350px|Call flow for creation of leg with signaling]]

For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.

[[Image:CallFlow MediaOnlyLeg Creation.JPG|thumb|center|350px|Call flow for media-only leg creation]]

Once a call is fully active (call answered and media allocated), event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnProfileChanged '''OnProfileChanged()'''] will be sent on the leg. In the cases where the user had not specified the IP/port to use, once this event is received, the media profile has been updated with the values chosen by Toolpack and the updated values can be retrieved using the functions '''GetLocalSDP()''' and '''GetPeerSDP()''' of the profile.
Note that the '''OnProfileChanged()''' event is also sent after the media profile has been modified with the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ChangeProfile '''ChangeProfile()'''] function (see [[#Modifying Media Profile|Modifying Media Profile]]) and when a connected peer has requested it (through a SIP re-INVITE for example).

See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.

=== Caveats ===
* The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).

== Interaction with Legs ==

=== Playing and Collecting Digits ===

You can play digits by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayDigit '''PlayDigit()'''] on a leg. Toolpack will receive the request and play the digits. Once digits are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitPlayingDone '''OnDigitPlayingDone()'''] event.

 You can also configure a leg to collect digits played. To start the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartDigitCollection '''StartDigitCollection()'''] on the leg. To stop the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopDigitCollection '''StopDigitCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitCollected '''OnDigitCollected()'''] event when there will be a match between the asked string and the digits collected.

 Here are examples how to play and collect digit.

===== Play Digit =====

<code></code>
<pre>ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
/* this will play the sequence of digit 5551234 */
ptrOutgoingLeg->PlayDigit( "5551234" );
}
</pre>
===== Collect Digit =====

<code></code>
<pre>ptrIncomingLeg = GetIncomingActiveLeg();
if( ptrIncomingLeg != NULL )
{
/*
this will collect digits 5, any sequences of 7 digits beginning by 3 or any sequences of 7 digits
beginning by 4,5,6 or 7 followed by 5 and 5.
*/
ptrIncomingLeg->StartDigitCollection( "5|3xxxxxx|[4-7]55xxxx" );
}
</pre>
=== Playing and Collecting Tones ===
Tones are defined as events, this is why to play and collect tones, you have to use general event functions. You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play events by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayEvent '''PlayEvent()'''] on a leg. Toolpack will receive the request and play the events. Once events are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventPlayingDone '''OnEventPlayingDone()'''] event. Note that you can cancel an event to be played by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CancelEvent '''CancelEvent()'''] on the leg after a '''PlayEvent()''' has been called.

Two kinds of string can be passed to '''AddToneString()''' to play a tone. The first type is to play well known tones such as dtmf and fax tone. The syntax is really simple and is based on H248 package and signal ids. The first component of the string is the package id and the second is the signal id, both formated in string. So, to play dtmf 0, you have to format the following string: "dg/d0", where "dg" is for package "dtmf generation" and "d0" is for "dtmf 0".

===== Play Tone with Signal Id String =====
<code><pre>
/* this will play dtmf 7 */

CTBCMC_EVENT_ATTRIBUTE Event;
Event.AddToneString( "dg/d7" );
GetOutgoingActiveLeg()->PlayEvent( Event );
</pre></code>

The second type of string is to play custom tone. The syntax is much more complicated than the first one, but it follows a well described syntax which can be found in [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.6-200011-I!!PDF-E&type=items/.pdf '''H248.6 Dynamic Tone Definition Package''']. This kind of string allows you to specify frequencies, duration, amplitude and repeating count of the tone. You can also specify well known tones and change their default duration, amplitude and repeating count. It is possible to describe a sequence of tones or frequencies that are played in one segment. Here are some examples of the syntax:

*;Frequencies 400Hz and 600Hz mixed together for 200ms, amplitude at -10dB and repeating 3 times (playing 4 times):
:*(((#400)+(#600)),200,-10)*3
:
*;Dtmf 5 repeated infinitly:
:*((0x0005,0x0015))*0
:
*;Multifrequency tone 8:
:*((mfg,mf8))
:
*;Frequency 440Hz played for 300ms at -10dB followed by frequency 600Hz played for 200ms at -5dB and then followed by dtmf 2, all this repeated infinitly:
:*((#440,300,-10),(#600,200,-5),(0x0005,0x0012))*0
:

===== Play Tone with Custom Tone String=====
<code><pre>
/* this will play frequencies 1000Hz and 2100Hz mixed together */

CTBCMC_EVENT_ATTRIBUTE Event;
Event.AddToneString( "(((#1000)+(#2100)),100,-10)" );
GetOutgoingActiveLeg()->PlayEvent( Event );
</code></pre>

You can also configure a leg to collect events played. To start the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartEventCollection '''StartEventCollection()'''] on the leg. Note that you will have to specify which events you want to collect before starting the event collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopEventCollection '''StopEventCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventCollected '''OnEventCollected()'''] event on each event received that correspond to a tone string specified when calling '''StartEventCollection()'''.

Only one type of string is accepted to specify which events to collect. The string is the same as the first type to play event. Signal ids that are also event id are accepted. This means that you can ask to collect "dg/d0" (dtmf generation/dtmf 0) and the detection will be done anyway. But, when the event is detected, it's the event id that will be returned, which means that "dd/d0" (dtmf detection/dtmf 0) will be returned instead of "dg/d0". You can also detect all events from a package by putting a * as event id, so "dd/*" will detect all dtmf tones.

===== Collect Tone =====
<code><pre>
/* this will collect all dtmf tones */

CTBCMC_EVENT_ATTRIBUTE Event;
Event.AddToneString( "dd/*" );
GetOutgoingActiveLeg()->StartEventCollection( Event );
</code></pre>

The most commonly used package are 5 and 6 [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.1-200509-I!!PDF-E&type=items/.pdf '''(H248.1 Annex E)''']: dtmf generation and dtmf detection. As H248 does not define events and signals for fax tone, we added a special package to do so. Package telcofax (0x8001) contains three events and two signals. Signals are: cng (0x0080) and g164 (0x0081) and events are: cng (0x0080), g164 (0x0081) and g165 (0x0082).

=== Collecting digits and tones while call legs are joined ===
By default, when two call legs are joined together through function CTBCMCCallLeg::Join(), tone collection is automatically disabled.
One of the arguments of the Join() function ("in_fDisableToneWhileJoined") will allow to control if automatic tone collection feature is used or not on a call.

Why is Toolpack disabling tone collection on joined legs by default?
That's because tone collection introduces a 40ms delay in the audio connection (required to provide tone suppression), and most of the time it is no more require to collect digits while two call legs are joined, so it would be useless to leave 40ms delay while tone collection is no more required.

=== Playing and Recording Audio Files ===
You can play an audio stream on a leg by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayStream '''PlayStream()'''] on it. To specify which audio stream you want to play, you have to specify it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html#CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath '''AddPlayFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html CTBCMC_PLAY_ATTRIBUTE] class. Toolpack will receive the request and play the stream. Once it is played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingDone '''OnStreamPlayingDone()'''] event.

You can also configure a leg to record an audio stream. First you must specify file paths to record by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html#CTBCMC_RECORD_ATTRIBUTE::AddRecFilePath '''AddRecFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html CTBCMC_RECORD_ATTRIBUTE] class. The you can call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RecordStream '''RecordStream()'''] on a leg. Once the stream is recorded, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamRecordingDone '''OnStreamRecordingDone()'''] event.

You can pause an active playing or recording stream by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PauseStream '''PauseStream()'''] and you can resume it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ResumeStream '''ResumeStream()''']. If you want to stop an active playing or recording stream, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopStream '''StopStream()'''] on the leg.

=== Modifying Media Profile ===
It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.

The media profile is stored in the leg attributes and can be modified like this :
TBX_SDP_INFO SdpInfo;
PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;

pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
pMediaLegAttribute->GetProfile().GetLocalSDP(SdpInfo);
Strncpy
(
SdpInfo.aConnections[0].szIp,
"",
sizeof( SdpInfo.aConnections[0].szIp )
);
SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
pMediaLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

pCallLeg->ChangeProfile();

Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotiation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.

Once the profile change has completed (or failed), event '''OnProfileChanged()''' will be received on the leg.

For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.

=== Controlling the Signaling ===
When a call leg receives the '''OnCallLegPresent()''' event, it indicates an incoming call. To confirm that the call contains sufficient valid information to process the call on the system, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AcceptCall '''AcceptCall()'''] on the leg. If a call leg receives the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAccepted '''OnCallAccepted()'''] event, it means that an outgoing call has been accepted by the remote peer. This event usually means that the calling number has been accepted and that the call is currently being processed.

After an incoming call has been accepted, a call leg can notify the remote peer that the incoming call has been put in the "ringing" state by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AlertCall '''AlertCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAlerting '''OnCallAlerting()'''] event when an outgoing call has been put in the "ringing" state by the remote peer.

When an incoming call is answered, a call leg can notify the remote peer of the incoming call answered by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AnswerCall '''AnswerCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAnswered '''OnCallAnswered()'''] event when an outgoing call has been answered by the remote peer.

SendCallSuppInfo/OnCallSuppInfo

== Leg Termination ==

Terminating a call leg is a 2 steps process:
# Call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::TerminateCall '''TerminateCall()''']
# Free leg object on [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminated '''OnCallTerminated()''']

When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resources freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Free '''Free()'''] on the leg's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::SetFreeListener '''SetFreeListener()'''] on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is deleted. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.

[[Image:TerminateCall from application.jpg|thumb|center|350px|Call flow for leg termination initiated by user application]]

In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other media resource or signaling error. In these cases, the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminatingIndication '''OnCallTerminatingIndication()'''] is sent to the leg. On reception of this event, the application should initiate call termination as shown below.

[[Image:TerminateCall from Toolpack.jpg|thumb|center|350px|Call flow for leg termination initiated by Toolpack]]

In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnLegTerminated '''OnLegTerminated()'''] event. This event indicates that the leg does not exist anymore on the Toolpack side and the user should free its object without trying any other interaction with Toolpack through it.

== Leg Synchronization on Failover ==
When a Toolpack application is restarted or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs through the '''OnCallLegSync()''' event of the [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_lib_user.html ITBCMCLibUser] interface (this interface must be implemented by all user applications). One event will be received for each leg being synchronized. The course of action to take when receiving a leg synchronization event depends on the ability of the application to resynchronize its states with theses legs.

* If the application can't resynchronize active legs or if it does not want to resychronize the leg for which it is receiving an '''OnCallLegSync()''' event, it must refuse the leg by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLeg '''RefuseLeg()'''].
*If the application wants the resynchronize the leg or if it does not yet have enough information to decide, it must create a CTBCMCLeg object using the leg attributes received in the event.

Once all '''OnCallLegSync()''' have been sent, Toolpack will start synchronization of the links between legs through '''OnLinkSync()'''. This event indicates that two legs are connected together. It can be used by the application to rebuild its internal states. As for the legs, unwanted links can be refused by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()'''].

When all links have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. At that moment, the application has all the information available on the Toolpack side to determine if the legs should be kept or release. Any leg that the application does not want to keep can be refused by calling '''RefuseLeg()''' on it. For all legs that have not been refused, an event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnSyncDone '''OnSyncDone()'''] will be sent on the leg. Once this event has been received on a leg, the leg is fully functional and the application can start calling any usual Toolpack function on it.

[[Image:CallFlow Sync After Application Restart.jpg|thumb|center|350px|Call flow for leg synchronization]]

===Loss of Communication with Toolpack Engine===
If communication is lost with the Toolpack Engine, event '''OnCmcLibNotReady()''' will be sent to the application. It indicates that the Toolpack framework is no more accessible. The legs are still valid at that time but no action can be executed on them as long the CmcLib is not ready. If the connection with the Toolpack Engine is not back up in less than 10 seconds, the CmcLib will declare a major communication loss and will call '''OnLegTerminated()''' on all the legs. In that case, when communication is regained with the Toolpack Engine, the synchronization sequence will start again from the beginning.

[[Image:CallFlow Sync After Comm Restart Passed 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart passed 10 seconds.]]

If the communication is regained before the 10 seconds timeout, event '''OnCmcLibReady()''' will be sent and the application can then continue working normally with its existing call legs. Note that you can also receive '''OnLegTerminated()''' on some legs before receiving the '''OnCmcLibReady()''' if those legs were in a transient state when disconnection occurred.

[[Image:CallFlow Sync After Comm Restart Within 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart within 10 seconds.]]

== Bridging the Media Path ==
=== Join ===

To bridge the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Join '''Join()'''] on one of the leg, giving the second leg as a parameter. This will connect the media path between the two legs according to the link properties set on the leg on which '''Join()''' is called. These link properties can be modified by overloading the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetJoinAttributes '''GetJoinAttributes()''']. The important attribute to set is '''IsFullDuplex()''' that indicates if the connection will be made full-duplex (A<-->B) or half-duplex (A-->B). Prior to release 2.5.2, the default connection mode is half-duplex. For all release version 2.5.2 or higher, the default connection mode is full-duplex.

'''Warning:''' If two legs are already connected in half-duplex and you want to connect them in full-duplex, you must first Unjoin() the legs, then Join() them in full-duplex. You can '''NOT''' only do another half-duplex in the opposite direction.

When legs are joined, it creates a link identified with a unique ''link id''. It is the responsibility of the application to provide this unique ''link id'' by implementing the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetLinkId '''GetLinkId()'''] function of the leg. It is planned to allow the user to provide a value of '0' to let the Toolpack system automatically choose a ''link id'', but as of this writing this feature is not yet available.

'''Warning:''' When two legs are joined, the application must ensure that '''GetLinkId()''' on both leg will return the right ''link id''. This will ensure that when the link needs to be removed, both A->Unjoin() and B->Unjoin() will work correctly.

==== Setting the link properties ====

In your leg class, add a member variable to store the join attributes for that leg.

CTBCMC_JOIN_ATTRIBUTE mJoinAttribute;

Then set the join properties you want in your leg class constructor (or at any other location that will run '''before''' the '''Join()''' is done:

mJoinAttribute.IsFullDuplex() = TBX_TRUE;

Last, implement the '''GetJoinAttributes()''' function.

CTBCMC_JOIN_ATTRIBUTE & CH248Termination::GetJoinAttributes()
{
return mJoinAttribute;
}

==== Broadcasting a media source ====
At the time of writing this, broadcast of a single media source to multiple destinations is not yet possible.

=== Unjoin ===
To disconnect the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Unjoin'''Unjoin()'''] on any of the legs. The '''GetLinkId()''' function of the leg on which '''Unjoin()''' is called must return the ''link id'' that was used when the legs were joined.

[[category:CAF]]
[[category:Needs revising]]

CAF: Working With Call Legs

2010-02-10T15:26:32Z

Alexandre Lussier: /* Playing and Collecting Tones */

== Call Leg Definition ==
The main mechanism through which the customer application controls the [[Toolpack]] system is via the management of call legs. The application creates a call leg (or more than one for conferencing and bridging) at the beginning of a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.

A call leg is represented by an instance of the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html CTBCMCLeg] class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 [[timeslot]]) or a [[SIP]] call with its associated [[VOIP]] [[Voice codecs|codec]] resource (attached to an IP/UDP endpoint). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (VOIP codec resource attached to an IP/UDP endpoint). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.

The CTBCMCLeg class allows a programmer to easily act upon the call leg to influence the signaling portion (e.g. accept, answer, terminate, etc) and to use the media portion as well (e.g play prompts, record voice, play or collect digits and tones).

Other member functions are available to retrieve (and change in some cases) the call leg attributes including the media profile (e.g. parameters to the media resource) or signaling information (e.g. protocol type, called and calling party numbers, etc). Joining/unjoining (connection/disconnection) of call legs is also a typical action handled by this class for ’gateway-type’ applications. It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse a ''call leg'' with a ''call''. A ''call leg'' represents one full-duplex link to a party while a ''call'' represents the agglomeration of multiple (two or more) call legs. For example, a ''bridge'' is a form of ''call'' that uses two ''call legs''.
* Do not confuse the base class CTBCMCLeg with the class [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_leg.html CTBCAFCallLeg]. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs. It is designed to represent a leg within a call. It cannot be instanciated as a standalone object without modifications to make it independent from the ITBCAFCallFlow interface.
* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

== Command Flow for Leg Actions in CAF ==
All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).

For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.

== Leg Creation ==
Creating a leg is always done through the definition of a ''call leg attribute''. The values entered in the ''call leg attribute'' will define the type of call leg created and its parameters. The following sections describe several scenarios in which you build a ''call leg''. Instruction will be given on how to fill the leg attributes and how to use them to create the ''call leg''.

=== Preparing Leg Attributes ===

==== Normal Call Leg Attributes ====
For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
* the called number,
* the calling number,
* the [[NAP | Network Access Point]].

Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|NAP Types]]).

The following code snippet shows how to build the attributes.
PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();

ptrOutgoingLegAttribute->GetCalledNumber() = "123-4567";
ptrOutgoingLegAttribute->GetCallingNumber() = "987-6543";
ptrOutgoingLegAttribute->GetNetworkAccessPoint() = "NAP_SS7_MONTREAL";

==== Media-only Leg Attributes ====
For media-only legs, no signaling information is needed but the user can specify which media channel to use and which media profile to use. The only required parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''MEDIA TDM'' or ''MEDIA VOIP'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;

ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();

ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;

When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. For ''MEDIA TDM'' NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For ''MEDIA VOIP'' NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and a timeslot number can be specified.

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc->Settings.TdmAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
pMediaDesc->Settings.TdmAudio.un8Timeslot = 5;
Strncpy
(
pMediaDesc->Settings.TdmAudio.szTrunkName,
"TRUNK_TORONTO_1",
sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
);

For VOIP legs, the user can control the media by providing local [[SDP]] and peer SDP. Setting the local SDP defines the codec and IP/port used to for the received media stream. Most of the time, the IP address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and IP/port used for the transmitted media stream. Note that Toolpack only allows for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in '''both''' SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].

TBX_RESULT Result;
TBX_SDP_INFO SdpInfo;
PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();
pMediaDesc->Settings.PacketAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;

// Set Local SDP
Result = BuildSdpInfo("", 0, SdpInfo); // No IP specified, Toolpack will choose one
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

// Set Peer SDP
Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo); // Using peer IP address and port
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetPeerSDP(SdpInfo);

=== Creating the Leg ===
Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CreateCall '''CreateCall()'''] on it. No action is taken when an instance of a CTBCMCLeg is created. Call resources are only allocated in the Toolpack system when '''CreateCall()''' is called on the object.

pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
pCallLeg->CreateCall();

For legs with signaling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).

[[Image:CallFlow SignalingMediaLeg Creation.JPG|thumb|center|350px|Call flow for creation of leg with signaling]]

For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.

[[Image:CallFlow MediaOnlyLeg Creation.JPG|thumb|center|350px|Call flow for media-only leg creation]]

Once a call is fully active (call answered and media allocated), event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnProfileChanged '''OnProfileChanged()'''] will be sent on the leg. In the cases where the user had not specified the IP/port to use, once this event is received, the media profile has been updated with the values chosen by Toolpack and the updated values can be retrieved using the functions '''GetLocalSDP()''' and '''GetPeerSDP()''' of the profile.
Note that the '''OnProfileChanged()''' event is also sent after the media profile has been modified with the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ChangeProfile '''ChangeProfile()'''] function (see [[#Modifying Media Profile|Modifying Media Profile]]) and when a connected peer has requested it (through a SIP re-INVITE for example).

See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.

=== Caveats ===
* The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).

== Interaction with Legs ==

=== Playing and Collecting Digits ===

You can play digits by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayDigit '''PlayDigit()'''] on a leg. Toolpack will receive the request and play the digits. Once digits are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitPlayingDone '''OnDigitPlayingDone()'''] event.

 You can also configure a leg to collect digits played. To start the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartDigitCollection '''StartDigitCollection()'''] on the leg. To stop the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopDigitCollection '''StopDigitCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitCollected '''OnDigitCollected()'''] event when there will be a match between the asked string and the digits collected.

 Here are examples how to play and collect digit.

===== Play Digit =====

<code></code>
<pre>ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
/* this will play the sequence of digit 5551234 */
ptrOutgoingLeg->PlayDigit( "5551234" );
}
</pre>
===== Collect Digit =====

<code></code>
<pre>ptrIncomingLeg = GetIncomingActiveLeg();
if( ptrIncomingLeg != NULL )
{
/*
this will collect digits 5, any sequences of 7 digits beginning by 3 or any sequences of 7 digits
beginning by 4,5,6 or 7 followed by 5 and 5.
*/
ptrIncomingLeg->StartDigitCollection( "5|3xxxxxx|[4-7]55xxxx" );
}
</pre>
=== Playing and Collecting Tones ===
Tones are defined as events, this is why to play and collect tones, you have to use general event functions. You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play events by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayEvent '''PlayEvent()'''] on a leg. Toolpack will receive the request and play the events. Once events are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventPlayingDone '''OnEventPlayingDone()'''] event. Note that you can cancel an event to be played by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CancelEvent '''CancelEvent()'''] on the leg after a '''PlayEvent()''' has been called.

Two kinds of string can be passed to '''AddToneString()''' to play a tone. The first type is to play well known tones such as dtmf and fax tone. The syntax is really simple and is based on H248 package and signal ids. The first component of the string is the package id and the second is the signal id, both formated in string. So, to play dtmf 0, you have to format the following string: "dg/d0", where "dg" is for package "dtmf generation" and "d0" is for "dtmf 0".

===== Play Tone with Signal Id String =====
<code><pre>
/* this will play dtmf 7 */

CTBCMC_EVENT_ATTRIBUTE Event;
Event.AddToneString( "dg/d7" );
GetOutgoingActiveLeg()->PlayEvent( Event );
</pre></code>

The second type of string is to play custom tone. The syntax is much more complicated than the first one, but it follows a well described syntax which can be found in [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.6-200011-I!!PDF-E&type=items/.pdf '''H248.6 Dynamic Tone Definition Package''']. This kind of string allows you to specify frequencies, duration, amplitude and repeating count of the tone. You can also specify well known tones and change their default duration, amplitude and repeating count. It is possible to describe a sequence of tones or frequencies that are played in one segment. Here are some examples of the syntax:

*;Frequencies 400Hz and 600Hz mixed together for 200ms, amplitude at -10dB and repeating 3 times (playing 4 times):
:*(((#400)+(#600)),200,-10)*3
:
*;Dtmf 5 repeated infinitly:
:*((0x0005,0x0015))*0
:
*;Multifrequency tone 8:
:*((mfg,mf8))
:
*;Frequency 440Hz played for 300ms at -10dB followed by frequency 600Hz played for 200ms at -5dB and then followed by dtmf 2, all this repeated infinitly:
:*((#440,300,-10),(#600,200,-5),(0x0005,0x0012))*0
:

You can also configure a leg to collect events played. To start the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartEventCollection '''StartEventCollection()'''] on the leg. Note that you will have to specify which events you want to collect before starting the event collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopEventCollection '''StopEventCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventCollected '''OnEventCollected()'''] event on each event received that correspond to a tone string specified when calling '''StartEventCollection()'''.

Only one type of string is accepted to specify which events to collect. The string is the same as the first type to play event. Signal ids that are also event id are accepted. This means that you can ask to collect "dg/d0" (dtmf generation/dtmf 0) and the detection will be done anyway. But, when the event is detected, it's the event id that will be returned, which means that "dd/d0" (dtmf detection/dtmf 0) will be returned instead of "dg/d0". You can also detect all events from a package by putting a * as event id, so "dd/*" will detect all dtmf tones.

The most commonly used package are 5 and 6 [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.1-200509-I!!PDF-E&type=items/.pdf '''(H248.1 Annex E)''']: dtmf generation and dtmf detection. As H248 does not define events and signals for fax tone, we added a special package to do so. Package telcofax (0x8001) contains three events and two signals. Signals are: cng (0x0080) and g164 (0x0081) and events are: cng (0x0080), g164 (0x0081) and g165 (0x0082).

=== Collecting digits and tones while call legs are joined ===
By default, when two call legs are joined together through function CTBCMCCallLeg::Join(), tone collection is automatically disabled.
One of the arguments of the Join() function ("in_fDisableToneWhileJoined") will allow to control if automatic tone collection feature is used or not on a call.

Why is Toolpack disabling tone collection on joined legs by default?
That's because tone collection introduces a 40ms delay in the audio connection (required to provide tone suppression), and most of the time it is no more require to collect digits while two call legs are joined, so it would be useless to leave 40ms delay while tone collection is no more required.

=== Playing and Recording Audio Files ===
You can play an audio stream on a leg by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayStream '''PlayStream()'''] on it. To specify which audio stream you want to play, you have to specify it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html#CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath '''AddPlayFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html CTBCMC_PLAY_ATTRIBUTE] class. Toolpack will receive the request and play the stream. Once it is played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingDone '''OnStreamPlayingDone()'''] event.

You can also configure a leg to record an audio stream. First you must specify file paths to record by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html#CTBCMC_RECORD_ATTRIBUTE::AddRecFilePath '''AddRecFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html CTBCMC_RECORD_ATTRIBUTE] class. The you can call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RecordStream '''RecordStream()'''] on a leg. Once the stream is recorded, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamRecordingDone '''OnStreamRecordingDone()'''] event.

You can pause an active playing or recording stream by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PauseStream '''PauseStream()'''] and you can resume it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ResumeStream '''ResumeStream()''']. If you want to stop an active playing or recording stream, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopStream '''StopStream()'''] on the leg.

=== Modifying Media Profile ===
It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.

The media profile is stored in the leg attributes and can be modified like this :
TBX_SDP_INFO SdpInfo;
PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;

pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
pMediaLegAttribute->GetProfile().GetLocalSDP(SdpInfo);
Strncpy
(
SdpInfo.aConnections[0].szIp,
"",
sizeof( SdpInfo.aConnections[0].szIp )
);
SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
pMediaLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

pCallLeg->ChangeProfile();

Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotiation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.

Once the profile change has completed (or failed), event '''OnProfileChanged()''' will be received on the leg.

For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.

=== Controlling the Signaling ===
When a call leg receives the '''OnCallLegPresent()''' event, it indicates an incoming call. To confirm that the call contains sufficient valid information to process the call on the system, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AcceptCall '''AcceptCall()'''] on the leg. If a call leg receives the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAccepted '''OnCallAccepted()'''] event, it means that an outgoing call has been accepted by the remote peer. This event usually means that the calling number has been accepted and that the call is currently being processed.

After an incoming call has been accepted, a call leg can notify the remote peer that the incoming call has been put in the "ringing" state by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AlertCall '''AlertCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAlerting '''OnCallAlerting()'''] event when an outgoing call has been put in the "ringing" state by the remote peer.

When an incoming call is answered, a call leg can notify the remote peer of the incoming call answered by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AnswerCall '''AnswerCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAnswered '''OnCallAnswered()'''] event when an outgoing call has been answered by the remote peer.

SendCallSuppInfo/OnCallSuppInfo

== Leg Termination ==

Terminating a call leg is a 2 steps process:
# Call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::TerminateCall '''TerminateCall()''']
# Free leg object on [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminated '''OnCallTerminated()''']

When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resources freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Free '''Free()'''] on the leg's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::SetFreeListener '''SetFreeListener()'''] on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is deleted. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.

[[Image:TerminateCall from application.jpg|thumb|center|350px|Call flow for leg termination initiated by user application]]

In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other media resource or signaling error. In these cases, the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminatingIndication '''OnCallTerminatingIndication()'''] is sent to the leg. On reception of this event, the application should initiate call termination as shown below.

[[Image:TerminateCall from Toolpack.jpg|thumb|center|350px|Call flow for leg termination initiated by Toolpack]]

In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnLegTerminated '''OnLegTerminated()'''] event. This event indicates that the leg does not exist anymore on the Toolpack side and the user should free its object without trying any other interaction with Toolpack through it.

== Leg Synchronization on Failover ==
When a Toolpack application is restarted or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs through the '''OnCallLegSync()''' event of the [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_lib_user.html ITBCMCLibUser] interface (this interface must be implemented by all user applications). One event will be received for each leg being synchronized. The course of action to take when receiving a leg synchronization event depends on the ability of the application to resynchronize its states with theses legs.

* If the application can't resynchronize active legs or if it does not want to resychronize the leg for which it is receiving an '''OnCallLegSync()''' event, it must refuse the leg by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLeg '''RefuseLeg()'''].
*If the application wants the resynchronize the leg or if it does not yet have enough information to decide, it must create a CTBCMCLeg object using the leg attributes received in the event.

Once all '''OnCallLegSync()''' have been sent, Toolpack will start synchronization of the links between legs through '''OnLinkSync()'''. This event indicates that two legs are connected together. It can be used by the application to rebuild its internal states. As for the legs, unwanted links can be refused by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()'''].

When all links have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. At that moment, the application has all the information available on the Toolpack side to determine if the legs should be kept or release. Any leg that the application does not want to keep can be refused by calling '''RefuseLeg()''' on it. For all legs that have not been refused, an event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnSyncDone '''OnSyncDone()'''] will be sent on the leg. Once this event has been received on a leg, the leg is fully functional and the application can start calling any usual Toolpack function on it.

[[Image:CallFlow Sync After Application Restart.jpg|thumb|center|350px|Call flow for leg synchronization]]

===Loss of Communication with Toolpack Engine===
If communication is lost with the Toolpack Engine, event '''OnCmcLibNotReady()''' will be sent to the application. It indicates that the Toolpack framework is no more accessible. The legs are still valid at that time but no action can be executed on them as long the CmcLib is not ready. If the connection with the Toolpack Engine is not back up in less than 10 seconds, the CmcLib will declare a major communication loss and will call '''OnLegTerminated()''' on all the legs. In that case, when communication is regained with the Toolpack Engine, the synchronization sequence will start again from the beginning.

[[Image:CallFlow Sync After Comm Restart Passed 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart passed 10 seconds.]]

If the communication is regained before the 10 seconds timeout, event '''OnCmcLibReady()''' will be sent and the application can then continue working normally with its existing call legs. Note that you can also receive '''OnLegTerminated()''' on some legs before receiving the '''OnCmcLibReady()''' if those legs were in a transient state when disconnection occurred.

[[Image:CallFlow Sync After Comm Restart Within 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart within 10 seconds.]]

== Bridging the Media Path ==
=== Join ===

To bridge the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Join '''Join()'''] on one of the leg, giving the second leg as a parameter. This will connect the media path between the two legs according to the link properties set on the leg on which '''Join()''' is called. These link properties can be modified by overloading the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetJoinAttributes '''GetJoinAttributes()''']. The important attribute to set is '''IsFullDuplex()''' that indicates if the connection will be made full-duplex (A<-->B) or half-duplex (A-->B). Prior to release 2.5.2, the default connection mode is half-duplex. For all release version 2.5.2 or higher, the default connection mode is full-duplex.

'''Warning:''' If two legs are already connected in half-duplex and you want to connect them in full-duplex, you must first Unjoin() the legs, then Join() them in full-duplex. You can '''NOT''' only do another half-duplex in the opposite direction.

When legs are joined, it creates a link identified with a unique ''link id''. It is the responsibility of the application to provide this unique ''link id'' by implementing the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetLinkId '''GetLinkId()'''] function of the leg. It is planned to allow the user to provide a value of '0' to let the Toolpack system automatically choose a ''link id'', but as of this writing this feature is not yet available.

'''Warning:''' When two legs are joined, the application must ensure that '''GetLinkId()''' on both leg will return the right ''link id''. This will ensure that when the link needs to be removed, both A->Unjoin() and B->Unjoin() will work correctly.

==== Setting the link properties ====

In your leg class, add a member variable to store the join attributes for that leg.

CTBCMC_JOIN_ATTRIBUTE mJoinAttribute;

Then set the join properties you want in your leg class constructor (or at any other location that will run '''before''' the '''Join()''' is done:

mJoinAttribute.IsFullDuplex() = TBX_TRUE;

Last, implement the '''GetJoinAttributes()''' function.

CTBCMC_JOIN_ATTRIBUTE & CH248Termination::GetJoinAttributes()
{
return mJoinAttribute;
}

==== Broadcasting a media source ====
At the time of writing this, broadcast of a single media source to multiple destinations is not yet possible.

=== Unjoin ===
To disconnect the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Unjoin'''Unjoin()'''] on any of the legs. The '''GetLinkId()''' function of the leg on which '''Unjoin()''' is called must return the ''link id'' that was used when the legs were joined.

[[category:CAF]]
[[category:Needs revising]]

CAF: Working With Call Legs

2010-02-10T15:22:34Z

Alexandre Lussier: /* Playing and Collecting Tones */

== Call Leg Definition ==
The main mechanism through which the customer application controls the [[Toolpack]] system is via the management of call legs. The application creates a call leg (or more than one for conferencing and bridging) at the beginning of a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.

A call leg is represented by an instance of the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html CTBCMCLeg] class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 [[timeslot]]) or a [[SIP]] call with its associated [[VOIP]] [[Voice codecs|codec]] resource (attached to an IP/UDP endpoint). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (VOIP codec resource attached to an IP/UDP endpoint). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.

The CTBCMCLeg class allows a programmer to easily act upon the call leg to influence the signaling portion (e.g. accept, answer, terminate, etc) and to use the media portion as well (e.g play prompts, record voice, play or collect digits and tones).

Other member functions are available to retrieve (and change in some cases) the call leg attributes including the media profile (e.g. parameters to the media resource) or signaling information (e.g. protocol type, called and calling party numbers, etc). Joining/unjoining (connection/disconnection) of call legs is also a typical action handled by this class for ’gateway-type’ applications. It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse a ''call leg'' with a ''call''. A ''call leg'' represents one full-duplex link to a party while a ''call'' represents the agglomeration of multiple (two or more) call legs. For example, a ''bridge'' is a form of ''call'' that uses two ''call legs''.
* Do not confuse the base class CTBCMCLeg with the class [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_leg.html CTBCAFCallLeg]. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs. It is designed to represent a leg within a call. It cannot be instanciated as a standalone object without modifications to make it independent from the ITBCAFCallFlow interface.
* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

== Command Flow for Leg Actions in CAF ==
All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).

For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.

== Leg Creation ==
Creating a leg is always done through the definition of a ''call leg attribute''. The values entered in the ''call leg attribute'' will define the type of call leg created and its parameters. The following sections describe several scenarios in which you build a ''call leg''. Instruction will be given on how to fill the leg attributes and how to use them to create the ''call leg''.

=== Preparing Leg Attributes ===

==== Normal Call Leg Attributes ====
For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
* the called number,
* the calling number,
* the [[NAP | Network Access Point]].

Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|NAP Types]]).

The following code snippet shows how to build the attributes.
PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();

ptrOutgoingLegAttribute->GetCalledNumber() = "123-4567";
ptrOutgoingLegAttribute->GetCallingNumber() = "987-6543";
ptrOutgoingLegAttribute->GetNetworkAccessPoint() = "NAP_SS7_MONTREAL";

==== Media-only Leg Attributes ====
For media-only legs, no signaling information is needed but the user can specify which media channel to use and which media profile to use. The only required parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''MEDIA TDM'' or ''MEDIA VOIP'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;

ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();

ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;

When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. For ''MEDIA TDM'' NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For ''MEDIA VOIP'' NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and a timeslot number can be specified.

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc->Settings.TdmAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
pMediaDesc->Settings.TdmAudio.un8Timeslot = 5;
Strncpy
(
pMediaDesc->Settings.TdmAudio.szTrunkName,
"TRUNK_TORONTO_1",
sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
);

For VOIP legs, the user can control the media by providing local [[SDP]] and peer SDP. Setting the local SDP defines the codec and IP/port used to for the received media stream. Most of the time, the IP address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and IP/port used for the transmitted media stream. Note that Toolpack only allows for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in '''both''' SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].

TBX_RESULT Result;
TBX_SDP_INFO SdpInfo;
PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();
pMediaDesc->Settings.PacketAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;

// Set Local SDP
Result = BuildSdpInfo("", 0, SdpInfo); // No IP specified, Toolpack will choose one
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

// Set Peer SDP
Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo); // Using peer IP address and port
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetPeerSDP(SdpInfo);

=== Creating the Leg ===
Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CreateCall '''CreateCall()'''] on it. No action is taken when an instance of a CTBCMCLeg is created. Call resources are only allocated in the Toolpack system when '''CreateCall()''' is called on the object.

pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
pCallLeg->CreateCall();

For legs with signaling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).

[[Image:CallFlow SignalingMediaLeg Creation.JPG|thumb|center|350px|Call flow for creation of leg with signaling]]

For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.

[[Image:CallFlow MediaOnlyLeg Creation.JPG|thumb|center|350px|Call flow for media-only leg creation]]

Once a call is fully active (call answered and media allocated), event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnProfileChanged '''OnProfileChanged()'''] will be sent on the leg. In the cases where the user had not specified the IP/port to use, once this event is received, the media profile has been updated with the values chosen by Toolpack and the updated values can be retrieved using the functions '''GetLocalSDP()''' and '''GetPeerSDP()''' of the profile.
Note that the '''OnProfileChanged()''' event is also sent after the media profile has been modified with the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ChangeProfile '''ChangeProfile()'''] function (see [[#Modifying Media Profile|Modifying Media Profile]]) and when a connected peer has requested it (through a SIP re-INVITE for example).

See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.

=== Caveats ===
* The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).

== Interaction with Legs ==

=== Playing and Collecting Digits ===

You can play digits by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayDigit '''PlayDigit()'''] on a leg. Toolpack will receive the request and play the digits. Once digits are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitPlayingDone '''OnDigitPlayingDone()'''] event.

 You can also configure a leg to collect digits played. To start the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartDigitCollection '''StartDigitCollection()'''] on the leg. To stop the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopDigitCollection '''StopDigitCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitCollected '''OnDigitCollected()'''] event when there will be a match between the asked string and the digits collected.

 Here are examples how to play and collect digit.

===== Play Digit =====

<code></code>
<pre>ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
/* this will play the sequence of digit 5551234 */
ptrOutgoingLeg->PlayDigit( "5551234" );
}
</pre>
===== Collect Digit =====

<code></code>
<pre>ptrIncomingLeg = GetIncomingActiveLeg();
if( ptrIncomingLeg != NULL )
{
/*
this will collect digits 5, any sequences of 7 digits beginning by 3 or any sequences of 7 digits
beginning by 4,5,6 or 7 followed by 5 and 5.
*/
ptrIncomingLeg->StartDigitCollection( "5|3xxxxxx|[4-7]55xxxx" );
}
</pre>
=== Playing and Collecting Tones ===
Tones are defined as events, this is why to play and collect tones, you have to use general event functions. You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play events by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayEvent '''PlayEvent()'''] on a leg. Toolpack will receive the request and play the events. Once events are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventPlayingDone '''OnEventPlayingDone()'''] event. Note that you can cancel an event to be played by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CancelEvent '''CancelEvent()'''] on the leg after a '''PlayEvent()''' has been called.

Two kinds of string can be passed to '''AddToneString()''' to play a tone. The first type is to play well known tones such as dtmf and fax tone. The syntax is really simple and is based on H248 package and signal ids. The first component of the string is the package id and the second is the signal id, both formated in string. So, to play dtmf 0, you have to format the following string: "dg/d0", where "dg" is for package "dtmf generation" and "d0" is for "dtmf 0".

<code><pre>
CTBCMC_EVENT_ATTRIBUTE Event;
Event.AddToneString( "dg/d7" );
(*pptrMediaLeg)->PlayEvent( Event );
</pre></code>

The second type of string is to play custom tone. The syntax is much more complicated than the first one, but it follows a well described syntax which can be found in [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.6-200011-I!!PDF-E&type=items/.pdf '''H248.6 Dynamic Tone Definition Package''']. This kind of string allows you to specify frequencies, duration, amplitude and repeating count of the tone. You can also specify well known tones and change their default duration, amplitude and repeating count. It is possible to describe a sequence of tones or frequencies that are played in one segment. Here are some examples of the syntax:

*;Frequencies 400Hz and 600Hz mixed together for 200ms, amplitude at -10dB and repeating 3 times (playing 4 times):
:*(((#400)+(#600)),200,-10)*3
:
*;Dtmf 5 repeated infinitly:
:*((0x0005,0x0015))*0
:
*;Multifrequency tone 8:
:*((mfg,mf8))
:
*;Frequency 440Hz played for 300ms at -10dB followed by frequency 600Hz played for 200ms at -5dB and then followed by dtmf 2, all this repeated infinitly:
:*((#440,300,-10),(#600,200,-5),(0x0005,0x0012))*0
:

You can also configure a leg to collect events played. To start the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartEventCollection '''StartEventCollection()'''] on the leg. Note that you will have to specify which events you want to collect before starting the event collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopEventCollection '''StopEventCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventCollected '''OnEventCollected()'''] event on each event received that correspond to a tone string specified when calling '''StartEventCollection()'''.

Only one type of string is accepted to specify which events to collect. The string is the same as the first type to play event. Signal ids that are also event id are accepted. This means that you can ask to collect "dg/d0" (dtmf generation/dtmf 0) and the detection will be done anyway. But, when the event is detected, it's the event id that will be returned, which means that "dd/d0" (dtmf detection/dtmf 0) will be returned instead of "dg/d0". You can also detect all events from a package by putting a * as event id, so "dd/*" will detect all dtmf tones.

The most commonly used package are 5 and 6 [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.1-200509-I!!PDF-E&type=items/.pdf '''(H248.1 Annex E)''']: dtmf generation and dtmf detection. As H248 does not define events and signals for fax tone, we added a special package to do so. Package telcofax (0x8001) contains three events and two signals. Signals are: cng (0x0080) and g164 (0x0081) and events are: cng (0x0080), g164 (0x0081) and g165 (0x0082).

=== Collecting digits and tones while call legs are joined ===
By default, when two call legs are joined together through function CTBCMCCallLeg::Join(), tone collection is automatically disabled.
One of the arguments of the Join() function ("in_fDisableToneWhileJoined") will allow to control if automatic tone collection feature is used or not on a call.

Why is Toolpack disabling tone collection on joined legs by default?
That's because tone collection introduces a 40ms delay in the audio connection (required to provide tone suppression), and most of the time it is no more require to collect digits while two call legs are joined, so it would be useless to leave 40ms delay while tone collection is no more required.

=== Playing and Recording Audio Files ===
You can play an audio stream on a leg by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayStream '''PlayStream()'''] on it. To specify which audio stream you want to play, you have to specify it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html#CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath '''AddPlayFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html CTBCMC_PLAY_ATTRIBUTE] class. Toolpack will receive the request and play the stream. Once it is played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingDone '''OnStreamPlayingDone()'''] event.

You can also configure a leg to record an audio stream. First you must specify file paths to record by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html#CTBCMC_RECORD_ATTRIBUTE::AddRecFilePath '''AddRecFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html CTBCMC_RECORD_ATTRIBUTE] class. The you can call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RecordStream '''RecordStream()'''] on a leg. Once the stream is recorded, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamRecordingDone '''OnStreamRecordingDone()'''] event.

You can pause an active playing or recording stream by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PauseStream '''PauseStream()'''] and you can resume it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ResumeStream '''ResumeStream()''']. If you want to stop an active playing or recording stream, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopStream '''StopStream()'''] on the leg.

=== Modifying Media Profile ===
It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.

The media profile is stored in the leg attributes and can be modified like this :
TBX_SDP_INFO SdpInfo;
PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;

pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
pMediaLegAttribute->GetProfile().GetLocalSDP(SdpInfo);
Strncpy
(
SdpInfo.aConnections[0].szIp,
"",
sizeof( SdpInfo.aConnections[0].szIp )
);
SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
pMediaLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

pCallLeg->ChangeProfile();

Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotiation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.

Once the profile change has completed (or failed), event '''OnProfileChanged()''' will be received on the leg.

For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.

=== Controlling the Signaling ===
When a call leg receives the '''OnCallLegPresent()''' event, it indicates an incoming call. To confirm that the call contains sufficient valid information to process the call on the system, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AcceptCall '''AcceptCall()'''] on the leg. If a call leg receives the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAccepted '''OnCallAccepted()'''] event, it means that an outgoing call has been accepted by the remote peer. This event usually means that the calling number has been accepted and that the call is currently being processed.

After an incoming call has been accepted, a call leg can notify the remote peer that the incoming call has been put in the "ringing" state by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AlertCall '''AlertCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAlerting '''OnCallAlerting()'''] event when an outgoing call has been put in the "ringing" state by the remote peer.

When an incoming call is answered, a call leg can notify the remote peer of the incoming call answered by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AnswerCall '''AnswerCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAnswered '''OnCallAnswered()'''] event when an outgoing call has been answered by the remote peer.

SendCallSuppInfo/OnCallSuppInfo

== Leg Termination ==

Terminating a call leg is a 2 steps process:
# Call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::TerminateCall '''TerminateCall()''']
# Free leg object on [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminated '''OnCallTerminated()''']

When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resources freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Free '''Free()'''] on the leg's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::SetFreeListener '''SetFreeListener()'''] on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is deleted. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.

[[Image:TerminateCall from application.jpg|thumb|center|350px|Call flow for leg termination initiated by user application]]

In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other media resource or signaling error. In these cases, the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminatingIndication '''OnCallTerminatingIndication()'''] is sent to the leg. On reception of this event, the application should initiate call termination as shown below.

[[Image:TerminateCall from Toolpack.jpg|thumb|center|350px|Call flow for leg termination initiated by Toolpack]]

In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnLegTerminated '''OnLegTerminated()'''] event. This event indicates that the leg does not exist anymore on the Toolpack side and the user should free its object without trying any other interaction with Toolpack through it.

== Leg Synchronization on Failover ==
When a Toolpack application is restarted or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs through the '''OnCallLegSync()''' event of the [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_lib_user.html ITBCMCLibUser] interface (this interface must be implemented by all user applications). One event will be received for each leg being synchronized. The course of action to take when receiving a leg synchronization event depends on the ability of the application to resynchronize its states with theses legs.

* If the application can't resynchronize active legs or if it does not want to resychronize the leg for which it is receiving an '''OnCallLegSync()''' event, it must refuse the leg by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLeg '''RefuseLeg()'''].
*If the application wants the resynchronize the leg or if it does not yet have enough information to decide, it must create a CTBCMCLeg object using the leg attributes received in the event.

Once all '''OnCallLegSync()''' have been sent, Toolpack will start synchronization of the links between legs through '''OnLinkSync()'''. This event indicates that two legs are connected together. It can be used by the application to rebuild its internal states. As for the legs, unwanted links can be refused by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()'''].

When all links have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. At that moment, the application has all the information available on the Toolpack side to determine if the legs should be kept or release. Any leg that the application does not want to keep can be refused by calling '''RefuseLeg()''' on it. For all legs that have not been refused, an event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnSyncDone '''OnSyncDone()'''] will be sent on the leg. Once this event has been received on a leg, the leg is fully functional and the application can start calling any usual Toolpack function on it.

[[Image:CallFlow Sync After Application Restart.jpg|thumb|center|350px|Call flow for leg synchronization]]

===Loss of Communication with Toolpack Engine===
If communication is lost with the Toolpack Engine, event '''OnCmcLibNotReady()''' will be sent to the application. It indicates that the Toolpack framework is no more accessible. The legs are still valid at that time but no action can be executed on them as long the CmcLib is not ready. If the connection with the Toolpack Engine is not back up in less than 10 seconds, the CmcLib will declare a major communication loss and will call '''OnLegTerminated()''' on all the legs. In that case, when communication is regained with the Toolpack Engine, the synchronization sequence will start again from the beginning.

[[Image:CallFlow Sync After Comm Restart Passed 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart passed 10 seconds.]]

If the communication is regained before the 10 seconds timeout, event '''OnCmcLibReady()''' will be sent and the application can then continue working normally with its existing call legs. Note that you can also receive '''OnLegTerminated()''' on some legs before receiving the '''OnCmcLibReady()''' if those legs were in a transient state when disconnection occurred.

[[Image:CallFlow Sync After Comm Restart Within 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart within 10 seconds.]]

== Bridging the Media Path ==
=== Join ===

To bridge the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Join '''Join()'''] on one of the leg, giving the second leg as a parameter. This will connect the media path between the two legs according to the link properties set on the leg on which '''Join()''' is called. These link properties can be modified by overloading the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetJoinAttributes '''GetJoinAttributes()''']. The important attribute to set is '''IsFullDuplex()''' that indicates if the connection will be made full-duplex (A<-->B) or half-duplex (A-->B). Prior to release 2.5.2, the default connection mode is half-duplex. For all release version 2.5.2 or higher, the default connection mode is full-duplex.

'''Warning:''' If two legs are already connected in half-duplex and you want to connect them in full-duplex, you must first Unjoin() the legs, then Join() them in full-duplex. You can '''NOT''' only do another half-duplex in the opposite direction.

When legs are joined, it creates a link identified with a unique ''link id''. It is the responsibility of the application to provide this unique ''link id'' by implementing the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetLinkId '''GetLinkId()'''] function of the leg. It is planned to allow the user to provide a value of '0' to let the Toolpack system automatically choose a ''link id'', but as of this writing this feature is not yet available.

'''Warning:''' When two legs are joined, the application must ensure that '''GetLinkId()''' on both leg will return the right ''link id''. This will ensure that when the link needs to be removed, both A->Unjoin() and B->Unjoin() will work correctly.

==== Setting the link properties ====

In your leg class, add a member variable to store the join attributes for that leg.

CTBCMC_JOIN_ATTRIBUTE mJoinAttribute;

Then set the join properties you want in your leg class constructor (or at any other location that will run '''before''' the '''Join()''' is done:

mJoinAttribute.IsFullDuplex() = TBX_TRUE;

Last, implement the '''GetJoinAttributes()''' function.

CTBCMC_JOIN_ATTRIBUTE & CH248Termination::GetJoinAttributes()
{
return mJoinAttribute;
}

==== Broadcasting a media source ====
At the time of writing this, broadcast of a single media source to multiple destinations is not yet possible.

=== Unjoin ===
To disconnect the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Unjoin'''Unjoin()'''] on any of the legs. The '''GetLinkId()''' function of the leg on which '''Unjoin()''' is called must return the ''link id'' that was used when the legs were joined.

[[category:CAF]]
[[category:Needs revising]]

CAF: Working With Call Legs

2010-02-10T14:54:10Z

Alexandre Lussier: /* Headline text */

== Call Leg Definition ==
The main mechanism through which the customer application controls the [[Toolpack]] system is via the management of call legs. The application creates a call leg (or more than one for conferencing and bridging) at the beginning of a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.

A call leg is represented by an instance of the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html CTBCMCLeg] class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 [[timeslot]]) or a [[SIP]] call with its associated [[VOIP]] [[Voice codecs|codec]] resource (attached to an IP/UDP endpoint). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (VOIP codec resource attached to an IP/UDP endpoint). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.

The CTBCMCLeg class allows a programmer to easily act upon the call leg to influence the signaling portion (e.g. accept, answer, terminate, etc) and to use the media portion as well (e.g play prompts, record voice, play or collect digits and tones).

Other member functions are available to retrieve (and change in some cases) the call leg attributes including the media profile (e.g. parameters to the media resource) or signaling information (e.g. protocol type, called and calling party numbers, etc). Joining/unjoining (connection/disconnection) of call legs is also a typical action handled by this class for ’gateway-type’ applications. It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse a ''call leg'' with a ''call''. A ''call leg'' represents one full-duplex link to a party while a ''call'' represents the agglomeration of multiple (two or more) call legs. For example, a ''bridge'' is a form of ''call'' that uses two ''call legs''.
* Do not confuse the base class CTBCMCLeg with the class [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_leg.html CTBCAFCallLeg]. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs. It is designed to represent a leg within a call. It cannot be instanciated as a standalone object without modifications to make it independent from the ITBCAFCallFlow interface.
* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

== Command Flow for Leg Actions in CAF ==
All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).

For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.

== Leg Creation ==
Creating a leg is always done through the definition of a ''call leg attribute''. The values entered in the ''call leg attribute'' will define the type of call leg created and its parameters. The following sections describe several scenarios in which you build a ''call leg''. Instruction will be given on how to fill the leg attributes and how to use them to create the ''call leg''.

=== Preparing Leg Attributes ===

==== Normal Call Leg Attributes ====
For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
* the called number,
* the calling number,
* the [[NAP | Network Access Point]].

Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|NAP Types]]).

The following code snippet shows how to build the attributes.
PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();

ptrOutgoingLegAttribute->GetCalledNumber() = "123-4567";
ptrOutgoingLegAttribute->GetCallingNumber() = "987-6543";
ptrOutgoingLegAttribute->GetNetworkAccessPoint() = "NAP_SS7_MONTREAL";

==== Media-only Leg Attributes ====
For media-only legs, no signaling information is needed but the user can specify which media channel to use and which media profile to use. The only required parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''MEDIA TDM'' or ''MEDIA VOIP'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;

ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();

ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;

When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. For ''MEDIA TDM'' NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For ''MEDIA VOIP'' NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and a timeslot number can be specified.

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc->Settings.TdmAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
pMediaDesc->Settings.TdmAudio.un8Timeslot = 5;
Strncpy
(
pMediaDesc->Settings.TdmAudio.szTrunkName,
"TRUNK_TORONTO_1",
sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
);

For VOIP legs, the user can control the media by providing local [[SDP]] and peer SDP. Setting the local SDP defines the codec and IP/port used to for the received media stream. Most of the time, the IP address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and IP/port used for the transmitted media stream. Note that Toolpack only allows for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in '''both''' SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].

TBX_RESULT Result;
TBX_SDP_INFO SdpInfo;
PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();
pMediaDesc->Settings.PacketAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;

// Set Local SDP
Result = BuildSdpInfo("", 0, SdpInfo); // No IP specified, Toolpack will choose one
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

// Set Peer SDP
Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo); // Using peer IP address and port
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetPeerSDP(SdpInfo);

=== Creating the Leg ===
Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CreateCall '''CreateCall()'''] on it. No action is taken when an instance of a CTBCMCLeg is created. Call resources are only allocated in the Toolpack system when '''CreateCall()''' is called on the object.

pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
pCallLeg->CreateCall();

For legs with signaling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).

[[Image:CallFlow SignalingMediaLeg Creation.JPG|thumb|center|350px|Call flow for creation of leg with signaling]]

For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.

[[Image:CallFlow MediaOnlyLeg Creation.JPG|thumb|center|350px|Call flow for media-only leg creation]]

Once a call is fully active (call answered and media allocated), event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnProfileChanged '''OnProfileChanged()'''] will be sent on the leg. In the cases where the user had not specified the IP/port to use, once this event is received, the media profile has been updated with the values chosen by Toolpack and the updated values can be retrieved using the functions '''GetLocalSDP()''' and '''GetPeerSDP()''' of the profile.
Note that the '''OnProfileChanged()''' event is also sent after the media profile has been modified with the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ChangeProfile '''ChangeProfile()'''] function (see [[#Modifying Media Profile|Modifying Media Profile]]) and when a connected peer has requested it (through a SIP re-INVITE for example).

See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.

=== Caveats ===
* The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).

== Interaction with Legs ==

=== Playing and Collecting Digits ===

You can play digits by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayDigit '''PlayDigit()'''] on a leg. Toolpack will receive the request and play the digits. Once digits are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitPlayingDone '''OnDigitPlayingDone()'''] event.

 You can also configure a leg to collect digits played. To start the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartDigitCollection '''StartDigitCollection()'''] on the leg. To stop the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopDigitCollection '''StopDigitCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitCollected '''OnDigitCollected()'''] event when there will be a match between the asked string and the digits collected.

 Here are examples how to play and collect digit.

===== Play Digit =====

<code></code>
<pre>ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
/* this will play the sequence of digit 5551234 */
ptrOutgoingLeg->PlayDigit( "5551234" );
}
</pre>
===== Collect Digit =====

<code></code>
<pre>ptrIncomingLeg = GetIncomingActiveLeg();
if( ptrIncomingLeg != NULL )
{
/*
this will collect digits 5, any sequences of 7 digits beginning by 3 or any sequences of 7 digits
beginning by 4,5,6 or 7 followed by 5 and 5.
*/
ptrIncomingLeg->StartDigitCollection( "5|3xxxxxx|[4-7]55xxxx" );
}
</pre>
=== Playing and Collecting Tones ===
You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play events by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayEvent '''PlayEvent()'''] on a leg. Toolpack will receive the request and play the events. Once events are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventPlayingDone '''OnEventPlayingDone()'''] event. Note that you can cancel an event to be played by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CancelEvent '''CancelEvent()'''] on the leg after a '''PlayEvent()''' has been called.

Two kinds of string can be passed to '''AddToneString()''' to play a tone. The first type is to play well known tones such as dtmf and fax tone. The syntax is really simple and is based on H248 package and signal ids. The first component of the string is the package id and the second is the signal id, both formated in string. So, to play dtmf 0, you have to format the following string: "dg/d0", where "dg" is for package "dtmf generation" and "d0" is for "dtmf 0".

The second type of string is to play custom tone. The syntax is much more complicated than the first one, but it follows a well described syntax which can be found in [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.6-200011-I!!PDF-E&type=items/.pdf '''H248.6 Dynamic Tone Definition Package''']. This kind of string allows you to specify frequencies, duration, amplitude and repeating count of the tone. You can also specify well known tones and change their default duration, amplitude and repeating count. It is possible to describe a sequence of tones or frequencies that are played in one segment. Here are some examples of the syntax:

*;Frequencies 400Hz and 600Hz mixed together for 200ms, amplitude at -10dB and repeating 3 times (playing 4 times):
:*(((#400)+(#600)),200,-10)*3
:
*;Dtmf 5 repeated infinitly:
:*((0x0005,0x0015))*0
:
*;Multifrequency tone 8:
:*((mfg,mf8))
:
*;Frequency 440Hz played for 300ms at -10dB followed by frequency 600Hz played for 200ms at -5dB and then followed by dtmf 2, all this repeated infinitly:
:*((#440,300,-10),(#600,200,-5),(0x0005,0x0012))*0
:

You can also configure a leg to collect events played. To start the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartEventCollection '''StartEventCollection()'''] on the leg. Note that you will have to specify which events you want to collect before starting the event collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopEventCollection '''StopEventCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventCollected '''OnEventCollected()'''] event on each event received that correspond to a tone string specified when calling '''StartEventCollection()'''.

Only one type of string is accepted to specify which events to collect. The string is the same as the first type to play event. Signal ids that are also event id are accepted. This means that you can ask to collect "dg/d0" (dtmf generation/dtmf 0) and the detection will be done anyway. But, when the event is detected, it's the event id that will be returned, which means that "dd/d0" (dtmf detection/dtmf 0) will be returned instead of "dg/d0". You can also detect all events from a package by putting a * as event id, so "dd/*" will detect all dtmf tones.

The most commonly used package are 5 and 6 [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.1-200509-I!!PDF-E&type=items/.pdf '''(H248.1 Annex E)''']: dtmf generation and dtmf detection. As H248 does not define events and signals for fax tone, we added a special package to do so. Package telcofax (0x8001) contains three events and two signals. Signals are: cng (0x0080) and g164 (0x0081) and events are: cng (0x0080), g164 (0x0081) and g165 (0x0082).



=== Collecting digits and tones while call legs are joined ===
By default, when two call legs are joined together through function CTBCMCCallLeg::Join(), tone collection is automatically disabled.
One of the arguments of the Join() function ("in_fDisableToneWhileJoined") will allow to control if automatic tone collection feature is used or not on a call.

Why is Toolpack disabling tone collection on joined legs by default?
That's because tone collection introduces a 40ms delay in the audio connection (required to provide tone suppression), and most of the time it is no more require to collect digits while two call legs are joined, so it would be useless to leave 40ms delay while tone collection is no more required.

=== Playing and Recording Audio Files ===
You can play an audio stream on a leg by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayStream '''PlayStream()'''] on it. To specify which audio stream you want to play, you have to specify it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html#CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath '''AddPlayFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html CTBCMC_PLAY_ATTRIBUTE] class. Toolpack will receive the request and play the stream. Once it is played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingDone '''OnStreamPlayingDone()'''] event.

You can also configure a leg to record an audio stream. First you must specify file paths to record by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html#CTBCMC_RECORD_ATTRIBUTE::AddRecFilePath '''AddRecFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html CTBCMC_RECORD_ATTRIBUTE] class. The you can call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RecordStream '''RecordStream()'''] on a leg. Once the stream is recorded, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamRecordingDone '''OnStreamRecordingDone()'''] event.

You can pause an active playing or recording stream by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PauseStream '''PauseStream()'''] and you can resume it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ResumeStream '''ResumeStream()''']. If you want to stop an active playing or recording stream, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopStream '''StopStream()'''] on the leg.

=== Modifying Media Profile ===
It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.

The media profile is stored in the leg attributes and can be modified like this :
TBX_SDP_INFO SdpInfo;
PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;

pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
pMediaLegAttribute->GetProfile().GetLocalSDP(SdpInfo);
Strncpy
(
SdpInfo.aConnections[0].szIp,
"",
sizeof( SdpInfo.aConnections[0].szIp )
);
SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
pMediaLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

pCallLeg->ChangeProfile();

Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotiation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.

Once the profile change has completed (or failed), event '''OnProfileChanged()''' will be received on the leg.

For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.

=== Controlling the Signaling ===
When a call leg receives the '''OnCallLegPresent()''' event, it indicates an incoming call. To confirm that the call contains sufficient valid information to process the call on the system, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AcceptCall '''AcceptCall()'''] on the leg. If a call leg receives the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAccepted '''OnCallAccepted()'''] event, it means that an outgoing call has been accepted by the remote peer. This event usually means that the calling number has been accepted and that the call is currently being processed.

After an incoming call has been accepted, a call leg can notify the remote peer that the incoming call has been put in the "ringing" state by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AlertCall '''AlertCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAlerting '''OnCallAlerting()'''] event when an outgoing call has been put in the "ringing" state by the remote peer.

When an incoming call is answered, a call leg can notify the remote peer of the incoming call answered by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AnswerCall '''AnswerCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAnswered '''OnCallAnswered()'''] event when an outgoing call has been answered by the remote peer.

SendCallSuppInfo/OnCallSuppInfo

== Leg Termination ==

Terminating a call leg is a 2 steps process:
# Call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::TerminateCall '''TerminateCall()''']
# Free leg object on [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminated '''OnCallTerminated()''']

When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resources freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Free '''Free()'''] on the leg's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::SetFreeListener '''SetFreeListener()'''] on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is deleted. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.

[[Image:TerminateCall from application.jpg|thumb|center|350px|Call flow for leg termination initiated by user application]]

In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other media resource or signaling error. In these cases, the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminatingIndication '''OnCallTerminatingIndication()'''] is sent to the leg. On reception of this event, the application should initiate call termination as shown below.

[[Image:TerminateCall from Toolpack.jpg|thumb|center|350px|Call flow for leg termination initiated by Toolpack]]

In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnLegTerminated '''OnLegTerminated()'''] event. This event indicates that the leg does not exist anymore on the Toolpack side and the user should free its object without trying any other interaction with Toolpack through it.

== Leg Synchronization on Failover ==
When a Toolpack application is restarted or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs through the '''OnCallLegSync()''' event of the [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_lib_user.html ITBCMCLibUser] interface (this interface must be implemented by all user applications). One event will be received for each leg being synchronized. The course of action to take when receiving a leg synchronization event depends on the ability of the application to resynchronize its states with theses legs.

* If the application can't resynchronize active legs or if it does not want to resychronize the leg for which it is receiving an '''OnCallLegSync()''' event, it must refuse the leg by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLeg '''RefuseLeg()'''].
*If the application wants the resynchronize the leg or if it does not yet have enough information to decide, it must create a CTBCMCLeg object using the leg attributes received in the event.

Once all '''OnCallLegSync()''' have been sent, Toolpack will start synchronization of the links between legs through '''OnLinkSync()'''. This event indicates that two legs are connected together. It can be used by the application to rebuild its internal states. As for the legs, unwanted links can be refused by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()'''].

When all links have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. At that moment, the application has all the information available on the Toolpack side to determine if the legs should be kept or release. Any leg that the application does not want to keep can be refused by calling '''RefuseLeg()''' on it. For all legs that have not been refused, an event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnSyncDone '''OnSyncDone()'''] will be sent on the leg. Once this event has been received on a leg, the leg is fully functional and the application can start calling any usual Toolpack function on it.

[[Image:CallFlow Sync After Application Restart.jpg|thumb|center|350px|Call flow for leg synchronization]]

===Loss of Communication with Toolpack Engine===
If communication is lost with the Toolpack Engine, event '''OnCmcLibNotReady()''' will be sent to the application. It indicates that the Toolpack framework is no more accessible. The legs are still valid at that time but no action can be executed on them as long the CmcLib is not ready. If the connection with the Toolpack Engine is not back up in less than 10 seconds, the CmcLib will declare a major communication loss and will call '''OnLegTerminated()''' on all the legs. In that case, when communication is regained with the Toolpack Engine, the synchronization sequence will start again from the beginning.

[[Image:CallFlow Sync After Comm Restart Passed 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart passed 10 seconds.]]

If the communication is regained before the 10 seconds timeout, event '''OnCmcLibReady()''' will be sent and the application can then continue working normally with its existing call legs. Note that you can also receive '''OnLegTerminated()''' on some legs before receiving the '''OnCmcLibReady()''' if those legs were in a transient state when disconnection occurred.

[[Image:CallFlow Sync After Comm Restart Within 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart within 10 seconds.]]

== Bridging the Media Path ==
=== Join ===

To bridge the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Join '''Join()'''] on one of the leg, giving the second leg as a parameter. This will connect the media path between the two legs according to the link properties set on the leg on which '''Join()''' is called. These link properties can be modified by overloading the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetJoinAttributes '''GetJoinAttributes()''']. The important attribute to set is '''IsFullDuplex()''' that indicates if the connection will be made full-duplex (A<-->B) or half-duplex (A-->B). Prior to release 2.5.2, the default connection mode is half-duplex. For all release version 2.5.2 or higher, the default connection mode is full-duplex.

'''Warning:''' If two legs are already connected in half-duplex and you want to connect them in full-duplex, you must first Unjoin() the legs, then Join() them in full-duplex. You can '''NOT''' only do another half-duplex in the opposite direction.

When legs are joined, it creates a link identified with a unique ''link id''. It is the responsibility of the application to provide this unique ''link id'' by implementing the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetLinkId '''GetLinkId()'''] function of the leg. It is planned to allow the user to provide a value of '0' to let the Toolpack system automatically choose a ''link id'', but as of this writing this feature is not yet available.

'''Warning:''' When two legs are joined, the application must ensure that '''GetLinkId()''' on both leg will return the right ''link id''. This will ensure that when the link needs to be removed, both A->Unjoin() and B->Unjoin() will work correctly.

==== Setting the link properties ====

In your leg class, add a member variable to store the join attributes for that leg.

CTBCMC_JOIN_ATTRIBUTE mJoinAttribute;

Then set the join properties you want in your leg class constructor (or at any other location that will run '''before''' the '''Join()''' is done:

mJoinAttribute.IsFullDuplex() = TBX_TRUE;

Last, implement the '''GetJoinAttributes()''' function.

CTBCMC_JOIN_ATTRIBUTE & CH248Termination::GetJoinAttributes()
{
return mJoinAttribute;
}

==== Broadcasting a media source ====
At the time of writing this, broadcast of a single media source to multiple destinations is not yet possible.

=== Unjoin ===
To disconnect the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Unjoin'''Unjoin()'''] on any of the legs. The '''GetLinkId()''' function of the leg on which '''Unjoin()''' is called must return the ''link id'' that was used when the legs were joined.

[[category:CAF]]
[[category:Needs revising]]

CAF: Working With Call Legs

2010-02-10T14:53:32Z

Alexandre Lussier: /* Playing and Collecting Digits */

== Call Leg Definition ==
The main mechanism through which the customer application controls the [[Toolpack]] system is via the management of call legs. The application creates a call leg (or more than one for conferencing and bridging) at the beginning of a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.

A call leg is represented by an instance of the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html CTBCMCLeg] class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 [[timeslot]]) or a [[SIP]] call with its associated [[VOIP]] [[Voice codecs|codec]] resource (attached to an IP/UDP endpoint). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (VOIP codec resource attached to an IP/UDP endpoint). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.

The CTBCMCLeg class allows a programmer to easily act upon the call leg to influence the signaling portion (e.g. accept, answer, terminate, etc) and to use the media portion as well (e.g play prompts, record voice, play or collect digits and tones).

Other member functions are available to retrieve (and change in some cases) the call leg attributes including the media profile (e.g. parameters to the media resource) or signaling information (e.g. protocol type, called and calling party numbers, etc). Joining/unjoining (connection/disconnection) of call legs is also a typical action handled by this class for ’gateway-type’ applications. It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse a ''call leg'' with a ''call''. A ''call leg'' represents one full-duplex link to a party while a ''call'' represents the agglomeration of multiple (two or more) call legs. For example, a ''bridge'' is a form of ''call'' that uses two ''call legs''.
* Do not confuse the base class CTBCMCLeg with the class [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_leg.html CTBCAFCallLeg]. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs. It is designed to represent a leg within a call. It cannot be instanciated as a standalone object without modifications to make it independent from the ITBCAFCallFlow interface.
* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

== Command Flow for Leg Actions in CAF ==
All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).

For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.

== Leg Creation ==
Creating a leg is always done through the definition of a ''call leg attribute''. The values entered in the ''call leg attribute'' will define the type of call leg created and its parameters. The following sections describe several scenarios in which you build a ''call leg''. Instruction will be given on how to fill the leg attributes and how to use them to create the ''call leg''.

=== Preparing Leg Attributes ===

==== Normal Call Leg Attributes ====
For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
* the called number,
* the calling number,
* the [[NAP | Network Access Point]].

Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|NAP Types]]).

The following code snippet shows how to build the attributes.
PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();

ptrOutgoingLegAttribute->GetCalledNumber() = "123-4567";
ptrOutgoingLegAttribute->GetCallingNumber() = "987-6543";
ptrOutgoingLegAttribute->GetNetworkAccessPoint() = "NAP_SS7_MONTREAL";

==== Media-only Leg Attributes ====
For media-only legs, no signaling information is needed but the user can specify which media channel to use and which media profile to use. The only required parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''MEDIA TDM'' or ''MEDIA VOIP'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;

ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();

ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;

When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. For ''MEDIA TDM'' NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For ''MEDIA VOIP'' NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and a timeslot number can be specified.

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc->Settings.TdmAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
pMediaDesc->Settings.TdmAudio.un8Timeslot = 5;
Strncpy
(
pMediaDesc->Settings.TdmAudio.szTrunkName,
"TRUNK_TORONTO_1",
sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
);

For VOIP legs, the user can control the media by providing local [[SDP]] and peer SDP. Setting the local SDP defines the codec and IP/port used to for the received media stream. Most of the time, the IP address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and IP/port used for the transmitted media stream. Note that Toolpack only allows for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in '''both''' SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].

TBX_RESULT Result;
TBX_SDP_INFO SdpInfo;
PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();
pMediaDesc->Settings.PacketAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;

// Set Local SDP
Result = BuildSdpInfo("", 0, SdpInfo); // No IP specified, Toolpack will choose one
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

// Set Peer SDP
Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo); // Using peer IP address and port
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetPeerSDP(SdpInfo);

=== Creating the Leg ===
Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CreateCall '''CreateCall()'''] on it. No action is taken when an instance of a CTBCMCLeg is created. Call resources are only allocated in the Toolpack system when '''CreateCall()''' is called on the object.

pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
pCallLeg->CreateCall();

For legs with signaling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).

[[Image:CallFlow SignalingMediaLeg Creation.JPG|thumb|center|350px|Call flow for creation of leg with signaling]]

For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.

[[Image:CallFlow MediaOnlyLeg Creation.JPG|thumb|center|350px|Call flow for media-only leg creation]]

Once a call is fully active (call answered and media allocated), event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnProfileChanged '''OnProfileChanged()'''] will be sent on the leg. In the cases where the user had not specified the IP/port to use, once this event is received, the media profile has been updated with the values chosen by Toolpack and the updated values can be retrieved using the functions '''GetLocalSDP()''' and '''GetPeerSDP()''' of the profile.
Note that the '''OnProfileChanged()''' event is also sent after the media profile has been modified with the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ChangeProfile '''ChangeProfile()'''] function (see [[#Modifying Media Profile|Modifying Media Profile]]) and when a connected peer has requested it (through a SIP re-INVITE for example).

See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.

=== Caveats ===
* The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).

== Interaction with Legs ==

=== Playing and Collecting Digits ===

You can play digits by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayDigit '''PlayDigit()'''] on a leg. Toolpack will receive the request and play the digits. Once digits are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitPlayingDone '''OnDigitPlayingDone()'''] event.

 You can also configure a leg to collect digits played. To start the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartDigitCollection '''StartDigitCollection()'''] on the leg. To stop the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopDigitCollection '''StopDigitCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitCollected '''OnDigitCollected()'''] event when there will be a match between the asked string and the digits collected.

 Here are examples how to play and collect digit.

===== Play Digit =====

<code></code>
<pre>ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
/* this will play the sequence of digit 5551234 */
ptrOutgoingLeg->PlayDigit( "5551234" );
}
</pre>
===== Collect Digit =====

<code></code>
<pre>ptrIncomingLeg = GetIncomingActiveLeg();
if( ptrIncomingLeg != NULL )
{
/*
this will collect digits 5, any sequences of 7 digits beginning by 3 or any sequences of 7 digits
beginning by 4,5,6 or 7 followed by 5 and 5.
*/
ptrIncomingLeg->StartDigitCollection( "5|3xxxxxx|[4-7]55xxxx" );
}
</pre>
== Headline text ==

=== Playing and Collecting Tones ===
You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play events by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayEvent '''PlayEvent()'''] on a leg. Toolpack will receive the request and play the events. Once events are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventPlayingDone '''OnEventPlayingDone()'''] event. Note that you can cancel an event to be played by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CancelEvent '''CancelEvent()'''] on the leg after a '''PlayEvent()''' has been called.

Two kinds of string can be passed to '''AddToneString()''' to play a tone. The first type is to play well known tones such as dtmf and fax tone. The syntax is really simple and is based on H248 package and signal ids. The first component of the string is the package id and the second is the signal id, both formated in string. So, to play dtmf 0, you have to format the following string: "dg/d0", where "dg" is for package "dtmf generation" and "d0" is for "dtmf 0".

The second type of string is to play custom tone. The syntax is much more complicated than the first one, but it follows a well described syntax which can be found in [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.6-200011-I!!PDF-E&type=items/.pdf '''H248.6 Dynamic Tone Definition Package''']. This kind of string allows you to specify frequencies, duration, amplitude and repeating count of the tone. You can also specify well known tones and change their default duration, amplitude and repeating count. It is possible to describe a sequence of tones or frequencies that are played in one segment. Here are some examples of the syntax:

*;Frequencies 400Hz and 600Hz mixed together for 200ms, amplitude at -10dB and repeating 3 times (playing 4 times):
:*(((#400)+(#600)),200,-10)*3
:
*;Dtmf 5 repeated infinitly:
:*((0x0005,0x0015))*0
:
*;Multifrequency tone 8:
:*((mfg,mf8))
:
*;Frequency 440Hz played for 300ms at -10dB followed by frequency 600Hz played for 200ms at -5dB and then followed by dtmf 2, all this repeated infinitly:
:*((#440,300,-10),(#600,200,-5),(0x0005,0x0012))*0
:

You can also configure a leg to collect events played. To start the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartEventCollection '''StartEventCollection()'''] on the leg. Note that you will have to specify which events you want to collect before starting the event collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopEventCollection '''StopEventCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventCollected '''OnEventCollected()'''] event on each event received that correspond to a tone string specified when calling '''StartEventCollection()'''.

Only one type of string is accepted to specify which events to collect. The string is the same as the first type to play event. Signal ids that are also event id are accepted. This means that you can ask to collect "dg/d0" (dtmf generation/dtmf 0) and the detection will be done anyway. But, when the event is detected, it's the event id that will be returned, which means that "dd/d0" (dtmf detection/dtmf 0) will be returned instead of "dg/d0". You can also detect all events from a package by putting a * as event id, so "dd/*" will detect all dtmf tones.

The most commonly used package are 5 and 6 [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.1-200509-I!!PDF-E&type=items/.pdf '''(H248.1 Annex E)''']: dtmf generation and dtmf detection. As H248 does not define events and signals for fax tone, we added a special package to do so. Package telcofax (0x8001) contains three events and two signals. Signals are: cng (0x0080) and g164 (0x0081) and events are: cng (0x0080), g164 (0x0081) and g165 (0x0082).



=== Collecting digits and tones while call legs are joined ===
By default, when two call legs are joined together through function CTBCMCCallLeg::Join(), tone collection is automatically disabled.
One of the arguments of the Join() function ("in_fDisableToneWhileJoined") will allow to control if automatic tone collection feature is used or not on a call.

Why is Toolpack disabling tone collection on joined legs by default?
That's because tone collection introduces a 40ms delay in the audio connection (required to provide tone suppression), and most of the time it is no more require to collect digits while two call legs are joined, so it would be useless to leave 40ms delay while tone collection is no more required.

=== Playing and Recording Audio Files ===
You can play an audio stream on a leg by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayStream '''PlayStream()'''] on it. To specify which audio stream you want to play, you have to specify it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html#CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath '''AddPlayFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html CTBCMC_PLAY_ATTRIBUTE] class. Toolpack will receive the request and play the stream. Once it is played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingDone '''OnStreamPlayingDone()'''] event.

You can also configure a leg to record an audio stream. First you must specify file paths to record by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html#CTBCMC_RECORD_ATTRIBUTE::AddRecFilePath '''AddRecFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html CTBCMC_RECORD_ATTRIBUTE] class. The you can call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RecordStream '''RecordStream()'''] on a leg. Once the stream is recorded, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamRecordingDone '''OnStreamRecordingDone()'''] event.

You can pause an active playing or recording stream by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PauseStream '''PauseStream()'''] and you can resume it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ResumeStream '''ResumeStream()''']. If you want to stop an active playing or recording stream, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopStream '''StopStream()'''] on the leg.

=== Modifying Media Profile ===
It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.

The media profile is stored in the leg attributes and can be modified like this :
TBX_SDP_INFO SdpInfo;
PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;

pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
pMediaLegAttribute->GetProfile().GetLocalSDP(SdpInfo);
Strncpy
(
SdpInfo.aConnections[0].szIp,
"",
sizeof( SdpInfo.aConnections[0].szIp )
);
SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
pMediaLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

pCallLeg->ChangeProfile();

Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotiation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.

Once the profile change has completed (or failed), event '''OnProfileChanged()''' will be received on the leg.

For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.

=== Controlling the Signaling ===
When a call leg receives the '''OnCallLegPresent()''' event, it indicates an incoming call. To confirm that the call contains sufficient valid information to process the call on the system, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AcceptCall '''AcceptCall()'''] on the leg. If a call leg receives the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAccepted '''OnCallAccepted()'''] event, it means that an outgoing call has been accepted by the remote peer. This event usually means that the calling number has been accepted and that the call is currently being processed.

After an incoming call has been accepted, a call leg can notify the remote peer that the incoming call has been put in the "ringing" state by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AlertCall '''AlertCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAlerting '''OnCallAlerting()'''] event when an outgoing call has been put in the "ringing" state by the remote peer.

When an incoming call is answered, a call leg can notify the remote peer of the incoming call answered by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AnswerCall '''AnswerCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAnswered '''OnCallAnswered()'''] event when an outgoing call has been answered by the remote peer.

SendCallSuppInfo/OnCallSuppInfo

== Leg Termination ==

Terminating a call leg is a 2 steps process:
# Call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::TerminateCall '''TerminateCall()''']
# Free leg object on [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminated '''OnCallTerminated()''']

When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resources freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Free '''Free()'''] on the leg's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::SetFreeListener '''SetFreeListener()'''] on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is deleted. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.

[[Image:TerminateCall from application.jpg|thumb|center|350px|Call flow for leg termination initiated by user application]]

In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other media resource or signaling error. In these cases, the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminatingIndication '''OnCallTerminatingIndication()'''] is sent to the leg. On reception of this event, the application should initiate call termination as shown below.

[[Image:TerminateCall from Toolpack.jpg|thumb|center|350px|Call flow for leg termination initiated by Toolpack]]

In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnLegTerminated '''OnLegTerminated()'''] event. This event indicates that the leg does not exist anymore on the Toolpack side and the user should free its object without trying any other interaction with Toolpack through it.

== Leg Synchronization on Failover ==
When a Toolpack application is restarted or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs through the '''OnCallLegSync()''' event of the [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_lib_user.html ITBCMCLibUser] interface (this interface must be implemented by all user applications). One event will be received for each leg being synchronized. The course of action to take when receiving a leg synchronization event depends on the ability of the application to resynchronize its states with theses legs.

* If the application can't resynchronize active legs or if it does not want to resychronize the leg for which it is receiving an '''OnCallLegSync()''' event, it must refuse the leg by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLeg '''RefuseLeg()'''].
*If the application wants the resynchronize the leg or if it does not yet have enough information to decide, it must create a CTBCMCLeg object using the leg attributes received in the event.

Once all '''OnCallLegSync()''' have been sent, Toolpack will start synchronization of the links between legs through '''OnLinkSync()'''. This event indicates that two legs are connected together. It can be used by the application to rebuild its internal states. As for the legs, unwanted links can be refused by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()'''].

When all links have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. At that moment, the application has all the information available on the Toolpack side to determine if the legs should be kept or release. Any leg that the application does not want to keep can be refused by calling '''RefuseLeg()''' on it. For all legs that have not been refused, an event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnSyncDone '''OnSyncDone()'''] will be sent on the leg. Once this event has been received on a leg, the leg is fully functional and the application can start calling any usual Toolpack function on it.

[[Image:CallFlow Sync After Application Restart.jpg|thumb|center|350px|Call flow for leg synchronization]]

===Loss of Communication with Toolpack Engine===
If communication is lost with the Toolpack Engine, event '''OnCmcLibNotReady()''' will be sent to the application. It indicates that the Toolpack framework is no more accessible. The legs are still valid at that time but no action can be executed on them as long the CmcLib is not ready. If the connection with the Toolpack Engine is not back up in less than 10 seconds, the CmcLib will declare a major communication loss and will call '''OnLegTerminated()''' on all the legs. In that case, when communication is regained with the Toolpack Engine, the synchronization sequence will start again from the beginning.

[[Image:CallFlow Sync After Comm Restart Passed 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart passed 10 seconds.]]

If the communication is regained before the 10 seconds timeout, event '''OnCmcLibReady()''' will be sent and the application can then continue working normally with its existing call legs. Note that you can also receive '''OnLegTerminated()''' on some legs before receiving the '''OnCmcLibReady()''' if those legs were in a transient state when disconnection occurred.

[[Image:CallFlow Sync After Comm Restart Within 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart within 10 seconds.]]

== Bridging the Media Path ==
=== Join ===

To bridge the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Join '''Join()'''] on one of the leg, giving the second leg as a parameter. This will connect the media path between the two legs according to the link properties set on the leg on which '''Join()''' is called. These link properties can be modified by overloading the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetJoinAttributes '''GetJoinAttributes()''']. The important attribute to set is '''IsFullDuplex()''' that indicates if the connection will be made full-duplex (A<-->B) or half-duplex (A-->B). Prior to release 2.5.2, the default connection mode is half-duplex. For all release version 2.5.2 or higher, the default connection mode is full-duplex.

'''Warning:''' If two legs are already connected in half-duplex and you want to connect them in full-duplex, you must first Unjoin() the legs, then Join() them in full-duplex. You can '''NOT''' only do another half-duplex in the opposite direction.

When legs are joined, it creates a link identified with a unique ''link id''. It is the responsibility of the application to provide this unique ''link id'' by implementing the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetLinkId '''GetLinkId()'''] function of the leg. It is planned to allow the user to provide a value of '0' to let the Toolpack system automatically choose a ''link id'', but as of this writing this feature is not yet available.

'''Warning:''' When two legs are joined, the application must ensure that '''GetLinkId()''' on both leg will return the right ''link id''. This will ensure that when the link needs to be removed, both A->Unjoin() and B->Unjoin() will work correctly.

==== Setting the link properties ====

In your leg class, add a member variable to store the join attributes for that leg.

CTBCMC_JOIN_ATTRIBUTE mJoinAttribute;

Then set the join properties you want in your leg class constructor (or at any other location that will run '''before''' the '''Join()''' is done:

mJoinAttribute.IsFullDuplex() = TBX_TRUE;

Last, implement the '''GetJoinAttributes()''' function.

CTBCMC_JOIN_ATTRIBUTE & CH248Termination::GetJoinAttributes()
{
return mJoinAttribute;
}

==== Broadcasting a media source ====
At the time of writing this, broadcast of a single media source to multiple destinations is not yet possible.

=== Unjoin ===
To disconnect the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Unjoin'''Unjoin()'''] on any of the legs. The '''GetLinkId()''' function of the leg on which '''Unjoin()''' is called must return the ''link id'' that was used when the legs were joined.

[[category:CAF]]
[[category:Needs revising]]

CAF: Working With Call Legs

2010-02-10T14:52:28Z

Alexandre Lussier: /* Playing and Collecting Digits */

== Call Leg Definition ==
The main mechanism through which the customer application controls the [[Toolpack]] system is via the management of call legs. The application creates a call leg (or more than one for conferencing and bridging) at the beginning of a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.

A call leg is represented by an instance of the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html CTBCMCLeg] class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 [[timeslot]]) or a [[SIP]] call with its associated [[VOIP]] [[Voice codecs|codec]] resource (attached to an IP/UDP endpoint). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (VOIP codec resource attached to an IP/UDP endpoint). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.

The CTBCMCLeg class allows a programmer to easily act upon the call leg to influence the signaling portion (e.g. accept, answer, terminate, etc) and to use the media portion as well (e.g play prompts, record voice, play or collect digits and tones).

Other member functions are available to retrieve (and change in some cases) the call leg attributes including the media profile (e.g. parameters to the media resource) or signaling information (e.g. protocol type, called and calling party numbers, etc). Joining/unjoining (connection/disconnection) of call legs is also a typical action handled by this class for ’gateway-type’ applications. It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse a ''call leg'' with a ''call''. A ''call leg'' represents one full-duplex link to a party while a ''call'' represents the agglomeration of multiple (two or more) call legs. For example, a ''bridge'' is a form of ''call'' that uses two ''call legs''.
* Do not confuse the base class CTBCMCLeg with the class [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_leg.html CTBCAFCallLeg]. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs. It is designed to represent a leg within a call. It cannot be instanciated as a standalone object without modifications to make it independent from the ITBCAFCallFlow interface.
* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

== Command Flow for Leg Actions in CAF ==
All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).

For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.

== Leg Creation ==
Creating a leg is always done through the definition of a ''call leg attribute''. The values entered in the ''call leg attribute'' will define the type of call leg created and its parameters. The following sections describe several scenarios in which you build a ''call leg''. Instruction will be given on how to fill the leg attributes and how to use them to create the ''call leg''.

=== Preparing Leg Attributes ===

==== Normal Call Leg Attributes ====
For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
* the called number,
* the calling number,
* the [[NAP | Network Access Point]].

Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|NAP Types]]).

The following code snippet shows how to build the attributes.
PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();

ptrOutgoingLegAttribute->GetCalledNumber() = "123-4567";
ptrOutgoingLegAttribute->GetCallingNumber() = "987-6543";
ptrOutgoingLegAttribute->GetNetworkAccessPoint() = "NAP_SS7_MONTREAL";

==== Media-only Leg Attributes ====
For media-only legs, no signaling information is needed but the user can specify which media channel to use and which media profile to use. The only required parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''MEDIA TDM'' or ''MEDIA VOIP'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;

ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();

ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;

When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. For ''MEDIA TDM'' NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For ''MEDIA VOIP'' NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and a timeslot number can be specified.

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc->Settings.TdmAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
pMediaDesc->Settings.TdmAudio.un8Timeslot = 5;
Strncpy
(
pMediaDesc->Settings.TdmAudio.szTrunkName,
"TRUNK_TORONTO_1",
sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
);

For VOIP legs, the user can control the media by providing local [[SDP]] and peer SDP. Setting the local SDP defines the codec and IP/port used to for the received media stream. Most of the time, the IP address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and IP/port used for the transmitted media stream. Note that Toolpack only allows for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in '''both''' SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].

TBX_RESULT Result;
TBX_SDP_INFO SdpInfo;
PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();
pMediaDesc->Settings.PacketAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;

// Set Local SDP
Result = BuildSdpInfo("", 0, SdpInfo); // No IP specified, Toolpack will choose one
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

// Set Peer SDP
Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo); // Using peer IP address and port
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetPeerSDP(SdpInfo);

=== Creating the Leg ===
Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CreateCall '''CreateCall()'''] on it. No action is taken when an instance of a CTBCMCLeg is created. Call resources are only allocated in the Toolpack system when '''CreateCall()''' is called on the object.

pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
pCallLeg->CreateCall();

For legs with signaling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).

[[Image:CallFlow SignalingMediaLeg Creation.JPG|thumb|center|350px|Call flow for creation of leg with signaling]]

For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.

[[Image:CallFlow MediaOnlyLeg Creation.JPG|thumb|center|350px|Call flow for media-only leg creation]]

Once a call is fully active (call answered and media allocated), event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnProfileChanged '''OnProfileChanged()'''] will be sent on the leg. In the cases where the user had not specified the IP/port to use, once this event is received, the media profile has been updated with the values chosen by Toolpack and the updated values can be retrieved using the functions '''GetLocalSDP()''' and '''GetPeerSDP()''' of the profile.
Note that the '''OnProfileChanged()''' event is also sent after the media profile has been modified with the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ChangeProfile '''ChangeProfile()'''] function (see [[#Modifying Media Profile|Modifying Media Profile]]) and when a connected peer has requested it (through a SIP re-INVITE for example).

See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.

=== Caveats ===
* The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).

== Interaction with Legs ==

=== Playing and Collecting Digits ===
You can play digits by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayDigit '''PlayDigit()'''] on a leg. Toolpack will receive the request and play the digits. Once digits are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitPlayingDone '''OnDigitPlayingDone()'''] event.

You can also configure a leg to collect digits played. To start the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartDigitCollection '''StartDigitCollection()'''] on the leg. To stop the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopDigitCollection '''StopDigitCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitCollected '''OnDigitCollected()'''] event when there will be a match between the asked string and the digits collected.

Here are examples how to play and collect digit.

==== Play Digit ====
<code><pre>
ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
/* this will play the sequence of digit 5551234 */
ptrOutgoingLeg->PlayDigit( "5551234" );
}
</pre></code>

==== Collect Digit ====
<code><pre>
ptrIncomingLeg = GetIncomingActiveLeg();
if( ptrIncomingLeg != NULL )
{
/*
this will collect digits 5, any sequences of 7 digits beginning by 3 or any sequences of 7 digits
beginning by 4,5,6 or 7 followed by 5 and 5.
*/
ptrIncomingLeg->StartDigitCollection( "5|3xxxxxx|[4-7]55xxxx" );
}
</pre></code>

=== Playing and Collecting Tones ===
You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play events by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayEvent '''PlayEvent()'''] on a leg. Toolpack will receive the request and play the events. Once events are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventPlayingDone '''OnEventPlayingDone()'''] event. Note that you can cancel an event to be played by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CancelEvent '''CancelEvent()'''] on the leg after a '''PlayEvent()''' has been called.

Two kinds of string can be passed to '''AddToneString()''' to play a tone. The first type is to play well known tones such as dtmf and fax tone. The syntax is really simple and is based on H248 package and signal ids. The first component of the string is the package id and the second is the signal id, both formated in string. So, to play dtmf 0, you have to format the following string: "dg/d0", where "dg" is for package "dtmf generation" and "d0" is for "dtmf 0".

The second type of string is to play custom tone. The syntax is much more complicated than the first one, but it follows a well described syntax which can be found in [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.6-200011-I!!PDF-E&type=items/.pdf '''H248.6 Dynamic Tone Definition Package''']. This kind of string allows you to specify frequencies, duration, amplitude and repeating count of the tone. You can also specify well known tones and change their default duration, amplitude and repeating count. It is possible to describe a sequence of tones or frequencies that are played in one segment. Here are some examples of the syntax:

*;Frequencies 400Hz and 600Hz mixed together for 200ms, amplitude at -10dB and repeating 3 times (playing 4 times):
:*(((#400)+(#600)),200,-10)*3
:
*;Dtmf 5 repeated infinitly:
:*((0x0005,0x0015))*0
:
*;Multifrequency tone 8:
:*((mfg,mf8))
:
*;Frequency 440Hz played for 300ms at -10dB followed by frequency 600Hz played for 200ms at -5dB and then followed by dtmf 2, all this repeated infinitly:
:*((#440,300,-10),(#600,200,-5),(0x0005,0x0012))*0
:

You can also configure a leg to collect events played. To start the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartEventCollection '''StartEventCollection()'''] on the leg. Note that you will have to specify which events you want to collect before starting the event collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopEventCollection '''StopEventCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventCollected '''OnEventCollected()'''] event on each event received that correspond to a tone string specified when calling '''StartEventCollection()'''.

Only one type of string is accepted to specify which events to collect. The string is the same as the first type to play event. Signal ids that are also event id are accepted. This means that you can ask to collect "dg/d0" (dtmf generation/dtmf 0) and the detection will be done anyway. But, when the event is detected, it's the event id that will be returned, which means that "dd/d0" (dtmf detection/dtmf 0) will be returned instead of "dg/d0". You can also detect all events from a package by putting a * as event id, so "dd/*" will detect all dtmf tones.

The most commonly used package are 5 and 6 [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.1-200509-I!!PDF-E&type=items/.pdf '''(H248.1 Annex E)''']: dtmf generation and dtmf detection. As H248 does not define events and signals for fax tone, we added a special package to do so. Package telcofax (0x8001) contains three events and two signals. Signals are: cng (0x0080) and g164 (0x0081) and events are: cng (0x0080), g164 (0x0081) and g165 (0x0082).



=== Collecting digits and tones while call legs are joined ===
By default, when two call legs are joined together through function CTBCMCCallLeg::Join(), tone collection is automatically disabled.
One of the arguments of the Join() function ("in_fDisableToneWhileJoined") will allow to control if automatic tone collection feature is used or not on a call.

Why is Toolpack disabling tone collection on joined legs by default?
That's because tone collection introduces a 40ms delay in the audio connection (required to provide tone suppression), and most of the time it is no more require to collect digits while two call legs are joined, so it would be useless to leave 40ms delay while tone collection is no more required.

=== Playing and Recording Audio Files ===
You can play an audio stream on a leg by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayStream '''PlayStream()'''] on it. To specify which audio stream you want to play, you have to specify it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html#CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath '''AddPlayFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html CTBCMC_PLAY_ATTRIBUTE] class. Toolpack will receive the request and play the stream. Once it is played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingDone '''OnStreamPlayingDone()'''] event.

You can also configure a leg to record an audio stream. First you must specify file paths to record by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html#CTBCMC_RECORD_ATTRIBUTE::AddRecFilePath '''AddRecFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html CTBCMC_RECORD_ATTRIBUTE] class. The you can call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RecordStream '''RecordStream()'''] on a leg. Once the stream is recorded, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamRecordingDone '''OnStreamRecordingDone()'''] event.

You can pause an active playing or recording stream by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PauseStream '''PauseStream()'''] and you can resume it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ResumeStream '''ResumeStream()''']. If you want to stop an active playing or recording stream, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopStream '''StopStream()'''] on the leg.

=== Modifying Media Profile ===
It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.

The media profile is stored in the leg attributes and can be modified like this :
TBX_SDP_INFO SdpInfo;
PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;

pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
pMediaLegAttribute->GetProfile().GetLocalSDP(SdpInfo);
Strncpy
(
SdpInfo.aConnections[0].szIp,
"",
sizeof( SdpInfo.aConnections[0].szIp )
);
SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
pMediaLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

pCallLeg->ChangeProfile();

Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotiation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.

Once the profile change has completed (or failed), event '''OnProfileChanged()''' will be received on the leg.

For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.

=== Controlling the Signaling ===
When a call leg receives the '''OnCallLegPresent()''' event, it indicates an incoming call. To confirm that the call contains sufficient valid information to process the call on the system, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AcceptCall '''AcceptCall()'''] on the leg. If a call leg receives the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAccepted '''OnCallAccepted()'''] event, it means that an outgoing call has been accepted by the remote peer. This event usually means that the calling number has been accepted and that the call is currently being processed.

After an incoming call has been accepted, a call leg can notify the remote peer that the incoming call has been put in the "ringing" state by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AlertCall '''AlertCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAlerting '''OnCallAlerting()'''] event when an outgoing call has been put in the "ringing" state by the remote peer.

When an incoming call is answered, a call leg can notify the remote peer of the incoming call answered by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AnswerCall '''AnswerCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAnswered '''OnCallAnswered()'''] event when an outgoing call has been answered by the remote peer.

SendCallSuppInfo/OnCallSuppInfo

== Leg Termination ==

Terminating a call leg is a 2 steps process:
# Call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::TerminateCall '''TerminateCall()''']
# Free leg object on [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminated '''OnCallTerminated()''']

When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resources freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Free '''Free()'''] on the leg's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::SetFreeListener '''SetFreeListener()'''] on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is deleted. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.

[[Image:TerminateCall from application.jpg|thumb|center|350px|Call flow for leg termination initiated by user application]]

In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other media resource or signaling error. In these cases, the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminatingIndication '''OnCallTerminatingIndication()'''] is sent to the leg. On reception of this event, the application should initiate call termination as shown below.

[[Image:TerminateCall from Toolpack.jpg|thumb|center|350px|Call flow for leg termination initiated by Toolpack]]

In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnLegTerminated '''OnLegTerminated()'''] event. This event indicates that the leg does not exist anymore on the Toolpack side and the user should free its object without trying any other interaction with Toolpack through it.

== Leg Synchronization on Failover ==
When a Toolpack application is restarted or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs through the '''OnCallLegSync()''' event of the [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_lib_user.html ITBCMCLibUser] interface (this interface must be implemented by all user applications). One event will be received for each leg being synchronized. The course of action to take when receiving a leg synchronization event depends on the ability of the application to resynchronize its states with theses legs.

* If the application can't resynchronize active legs or if it does not want to resychronize the leg for which it is receiving an '''OnCallLegSync()''' event, it must refuse the leg by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLeg '''RefuseLeg()'''].
*If the application wants the resynchronize the leg or if it does not yet have enough information to decide, it must create a CTBCMCLeg object using the leg attributes received in the event.

Once all '''OnCallLegSync()''' have been sent, Toolpack will start synchronization of the links between legs through '''OnLinkSync()'''. This event indicates that two legs are connected together. It can be used by the application to rebuild its internal states. As for the legs, unwanted links can be refused by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()'''].

When all links have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. At that moment, the application has all the information available on the Toolpack side to determine if the legs should be kept or release. Any leg that the application does not want to keep can be refused by calling '''RefuseLeg()''' on it. For all legs that have not been refused, an event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnSyncDone '''OnSyncDone()'''] will be sent on the leg. Once this event has been received on a leg, the leg is fully functional and the application can start calling any usual Toolpack function on it.

[[Image:CallFlow Sync After Application Restart.jpg|thumb|center|350px|Call flow for leg synchronization]]

===Loss of Communication with Toolpack Engine===
If communication is lost with the Toolpack Engine, event '''OnCmcLibNotReady()''' will be sent to the application. It indicates that the Toolpack framework is no more accessible. The legs are still valid at that time but no action can be executed on them as long the CmcLib is not ready. If the connection with the Toolpack Engine is not back up in less than 10 seconds, the CmcLib will declare a major communication loss and will call '''OnLegTerminated()''' on all the legs. In that case, when communication is regained with the Toolpack Engine, the synchronization sequence will start again from the beginning.

[[Image:CallFlow Sync After Comm Restart Passed 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart passed 10 seconds.]]

If the communication is regained before the 10 seconds timeout, event '''OnCmcLibReady()''' will be sent and the application can then continue working normally with its existing call legs. Note that you can also receive '''OnLegTerminated()''' on some legs before receiving the '''OnCmcLibReady()''' if those legs were in a transient state when disconnection occurred.

[[Image:CallFlow Sync After Comm Restart Within 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart within 10 seconds.]]

== Bridging the Media Path ==
=== Join ===

To bridge the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Join '''Join()'''] on one of the leg, giving the second leg as a parameter. This will connect the media path between the two legs according to the link properties set on the leg on which '''Join()''' is called. These link properties can be modified by overloading the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetJoinAttributes '''GetJoinAttributes()''']. The important attribute to set is '''IsFullDuplex()''' that indicates if the connection will be made full-duplex (A<-->B) or half-duplex (A-->B). Prior to release 2.5.2, the default connection mode is half-duplex. For all release version 2.5.2 or higher, the default connection mode is full-duplex.

'''Warning:''' If two legs are already connected in half-duplex and you want to connect them in full-duplex, you must first Unjoin() the legs, then Join() them in full-duplex. You can '''NOT''' only do another half-duplex in the opposite direction.

When legs are joined, it creates a link identified with a unique ''link id''. It is the responsibility of the application to provide this unique ''link id'' by implementing the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetLinkId '''GetLinkId()'''] function of the leg. It is planned to allow the user to provide a value of '0' to let the Toolpack system automatically choose a ''link id'', but as of this writing this feature is not yet available.

'''Warning:''' When two legs are joined, the application must ensure that '''GetLinkId()''' on both leg will return the right ''link id''. This will ensure that when the link needs to be removed, both A->Unjoin() and B->Unjoin() will work correctly.

==== Setting the link properties ====

In your leg class, add a member variable to store the join attributes for that leg.

CTBCMC_JOIN_ATTRIBUTE mJoinAttribute;

Then set the join properties you want in your leg class constructor (or at any other location that will run '''before''' the '''Join()''' is done:

mJoinAttribute.IsFullDuplex() = TBX_TRUE;

Last, implement the '''GetJoinAttributes()''' function.

CTBCMC_JOIN_ATTRIBUTE & CH248Termination::GetJoinAttributes()
{
return mJoinAttribute;
}

==== Broadcasting a media source ====
At the time of writing this, broadcast of a single media source to multiple destinations is not yet possible.

=== Unjoin ===
To disconnect the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Unjoin'''Unjoin()'''] on any of the legs. The '''GetLinkId()''' function of the leg on which '''Unjoin()''' is called must return the ''link id'' that was used when the legs were joined.

[[category:CAF]]
[[category:Needs revising]]

CAF: Working With Call Legs

2010-02-10T14:12:34Z

Alexandre Lussier: /* Playing and Collecting Digits */

== Call Leg Definition ==
The main mechanism through which the customer application controls the [[Toolpack]] system is via the management of call legs. The application creates a call leg (or more than one for conferencing and bridging) at the beginning of a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.

A call leg is represented by an instance of the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html CTBCMCLeg] class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 [[timeslot]]) or a [[SIP]] call with its associated [[VOIP]] [[Voice codecs|codec]] resource (attached to an IP/UDP endpoint). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (VOIP codec resource attached to an IP/UDP endpoint). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.

The CTBCMCLeg class allows a programmer to easily act upon the call leg to influence the signaling portion (e.g. accept, answer, terminate, etc) and to use the media portion as well (e.g play prompts, record voice, play or collect digits and tones).

Other member functions are available to retrieve (and change in some cases) the call leg attributes including the media profile (e.g. parameters to the media resource) or signaling information (e.g. protocol type, called and calling party numbers, etc). Joining/unjoining (connection/disconnection) of call legs is also a typical action handled by this class for ’gateway-type’ applications. It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse a ''call leg'' with a ''call''. A ''call leg'' represents one full-duplex link to a party while a ''call'' represents the agglomeration of multiple (two or more) call legs. For example, a ''bridge'' is a form of ''call'' that uses two ''call legs''.
* Do not confuse the base class CTBCMCLeg with the class [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_leg.html CTBCAFCallLeg]. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs. It is designed to represent a leg within a call. It cannot be instanciated as a standalone object without modifications to make it independent from the ITBCAFCallFlow interface.
* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

== Command Flow for Leg Actions in CAF ==
All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).

For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.

== Leg Creation ==
Creating a leg is always done through the definition of a ''call leg attribute''. The values entered in the ''call leg attribute'' will define the type of call leg created and its parameters. The following sections describe several scenarios in which you build a ''call leg''. Instruction will be given on how to fill the leg attributes and how to use them to create the ''call leg''.

=== Preparing Leg Attributes ===

==== Normal Call Leg Attributes ====
For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
* the called number,
* the calling number,
* the [[NAP | Network Access Point]].

Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|NAP Types]]).

The following code snippet shows how to build the attributes.
PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();

ptrOutgoingLegAttribute->GetCalledNumber() = "123-4567";
ptrOutgoingLegAttribute->GetCallingNumber() = "987-6543";
ptrOutgoingLegAttribute->GetNetworkAccessPoint() = "NAP_SS7_MONTREAL";

==== Media-only Leg Attributes ====
For media-only legs, no signaling information is needed but the user can specify which media channel to use and which media profile to use. The only required parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''MEDIA TDM'' or ''MEDIA VOIP'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;

ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();

ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;

When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. For ''MEDIA TDM'' NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For ''MEDIA VOIP'' NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and a timeslot number can be specified.

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc->Settings.TdmAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
pMediaDesc->Settings.TdmAudio.un8Timeslot = 5;
Strncpy
(
pMediaDesc->Settings.TdmAudio.szTrunkName,
"TRUNK_TORONTO_1",
sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
);

For VOIP legs, the user can control the media by providing local [[SDP]] and peer SDP. Setting the local SDP defines the codec and IP/port used to for the received media stream. Most of the time, the IP address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and IP/port used for the transmitted media stream. Note that Toolpack only allows for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in '''both''' SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].

TBX_RESULT Result;
TBX_SDP_INFO SdpInfo;
PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();
pMediaDesc->Settings.PacketAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;

// Set Local SDP
Result = BuildSdpInfo("", 0, SdpInfo); // No IP specified, Toolpack will choose one
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

// Set Peer SDP
Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo); // Using peer IP address and port
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetPeerSDP(SdpInfo);

=== Creating the Leg ===
Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CreateCall '''CreateCall()'''] on it. No action is taken when an instance of a CTBCMCLeg is created. Call resources are only allocated in the Toolpack system when '''CreateCall()''' is called on the object.

pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
pCallLeg->CreateCall();

For legs with signaling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).

[[Image:CallFlow SignalingMediaLeg Creation.JPG|thumb|center|350px|Call flow for creation of leg with signaling]]

For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.

[[Image:CallFlow MediaOnlyLeg Creation.JPG|thumb|center|350px|Call flow for media-only leg creation]]

Once a call is fully active (call answered and media allocated), event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnProfileChanged '''OnProfileChanged()'''] will be sent on the leg. In the cases where the user had not specified the IP/port to use, once this event is received, the media profile has been updated with the values chosen by Toolpack and the updated values can be retrieved using the functions '''GetLocalSDP()''' and '''GetPeerSDP()''' of the profile.
Note that the '''OnProfileChanged()''' event is also sent after the media profile has been modified with the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ChangeProfile '''ChangeProfile()'''] function (see [[#Modifying Media Profile|Modifying Media Profile]]) and when a connected peer has requested it (through a SIP re-INVITE for example).

See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.

=== Caveats ===
* The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).

== Interaction with Legs ==

=== Playing and Collecting Digits ===
You can play digits by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayDigit '''PlayDigit()'''] on a leg. Toolpack will receive the request and play the digits. Once digits are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitPlayingDone '''OnDigitPlayingDone()'''] event.

You can also configure a leg to collect digits played. To start the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartDigitCollection '''StartDigitCollection()'''] on the leg. To stop the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopDigitCollection '''StopDigitCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitCollected '''OnDigitCollected()'''] event when there will be a match between the asked string and the digits collected.

Here is an example how to play and collect digit. This example plays digit 5 on the outgoing leg and collects 5 on the incoming leg when the call is answered.

<code><pre>
TBX_RESULT CTBCAFCallTones::OnCallLegAnswered
(
IN PCTBCAFCallLeg in_pCallLeg,
IN CTBCMC_PROTOCOL_ATTRIBUTE & in_ProtocolAttribute
)
{
PTRCTBCAFCallLeg ptrIncomingLeg;
PTRCTBCAFCallLeg ptrOutgoingLeg;

/*---------------------------------------------------------------------------------------------------------------------------
| Code section
*--------------------------------------------------------------------------------------------------------------------------*/
CAFCODE( CTBCAFCallTones::OnCallLegAnswered )
{
/* play ready tone */
ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
ptrOutgoingLeg->PlayDigit( "5" );
}

// Start the digit collection of the ready digit
ptrIncomingLeg = GetIncomingActiveLeg();
if( ptrIncomingLeg != NULL )
{
ptrIncomingLeg->StartDigitCollection( "5" );
}

TBX_EXIT_SUCCESS( TBX_RESULT_OK );
}
.
.
.
}
</pre></code>

=== Playing and Collecting Tones ===
You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play events by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayEvent '''PlayEvent()'''] on a leg. Toolpack will receive the request and play the events. Once events are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventPlayingDone '''OnEventPlayingDone()'''] event. Note that you can cancel an event to be played by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CancelEvent '''CancelEvent()'''] on the leg after a '''PlayEvent()''' has been called.

Two kinds of string can be passed to '''AddToneString()''' to play a tone. The first type is to play well known tones such as dtmf and fax tone. The syntax is really simple and is based on H248 package and signal ids. The first component of the string is the package id and the second is the signal id, both formated in string. So, to play dtmf 0, you have to format the following string: "dg/d0", where "dg" is for package "dtmf generation" and "d0" is for "dtmf 0".

The second type of string is to play custom tone. The syntax is much more complicated than the first one, but it follows a well described syntax which can be found in [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.6-200011-I!!PDF-E&type=items/.pdf '''H248.6 Dynamic Tone Definition Package''']. This kind of string allows you to specify frequencies, duration, amplitude and repeating count of the tone. You can also specify well known tones and change their default duration, amplitude and repeating count. It is possible to describe a sequence of tones or frequencies that are played in one segment. Here are some examples of the syntax:

*;Frequencies 400Hz and 600Hz mixed together for 200ms, amplitude at -10dB and repeating 3 times (playing 4 times):
:*(((#400)+(#600)),200,-10)*3
:
*;Dtmf 5 repeated infinitly:
:*((0x0005,0x0015))*0
:
*;Multifrequency tone 8:
:*((mfg,mf8))
:
*;Frequency 440Hz played for 300ms at -10dB followed by frequency 600Hz played for 200ms at -5dB and then followed by dtmf 2, all this repeated infinitly:
:*((#440,300,-10),(#600,200,-5),(0x0005,0x0012))*0
:

You can also configure a leg to collect events played. To start the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartEventCollection '''StartEventCollection()'''] on the leg. Note that you will have to specify which events you want to collect before starting the event collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopEventCollection '''StopEventCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventCollected '''OnEventCollected()'''] event on each event received that correspond to a tone string specified when calling '''StartEventCollection()'''.

Only one type of string is accepted to specify which events to collect. The string is the same as the first type to play event. Signal ids that are also event id are accepted. This means that you can ask to collect "dg/d0" (dtmf generation/dtmf 0) and the detection will be done anyway. But, when the event is detected, it's the event id that will be returned, which means that "dd/d0" (dtmf detection/dtmf 0) will be returned instead of "dg/d0". You can also detect all events from a package by putting a * as event id, so "dd/*" will detect all dtmf tones.

The most commonly used package are 5 and 6 [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.1-200509-I!!PDF-E&type=items/.pdf '''(H248.1 Annex E)''']: dtmf generation and dtmf detection. As H248 does not define events and signals for fax tone, we added a special package to do so. Package telcofax (0x8001) contains three events and two signals. Signals are: cng (0x0080) and g164 (0x0081) and events are: cng (0x0080), g164 (0x0081) and g165 (0x0082).



=== Collecting digits and tones while call legs are joined ===
By default, when two call legs are joined together through function CTBCMCCallLeg::Join(), tone collection is automatically disabled.
One of the arguments of the Join() function ("in_fDisableToneWhileJoined") will allow to control if automatic tone collection feature is used or not on a call.

Why is Toolpack disabling tone collection on joined legs by default?
That's because tone collection introduces a 40ms delay in the audio connection (required to provide tone suppression), and most of the time it is no more require to collect digits while two call legs are joined, so it would be useless to leave 40ms delay while tone collection is no more required.

=== Playing and Recording Audio Files ===
You can play an audio stream on a leg by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayStream '''PlayStream()'''] on it. To specify which audio stream you want to play, you have to specify it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html#CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath '''AddPlayFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html CTBCMC_PLAY_ATTRIBUTE] class. Toolpack will receive the request and play the stream. Once it is played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingDone '''OnStreamPlayingDone()'''] event.

You can also configure a leg to record an audio stream. First you must specify file paths to record by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html#CTBCMC_RECORD_ATTRIBUTE::AddRecFilePath '''AddRecFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html CTBCMC_RECORD_ATTRIBUTE] class. The you can call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RecordStream '''RecordStream()'''] on a leg. Once the stream is recorded, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamRecordingDone '''OnStreamRecordingDone()'''] event.

You can pause an active playing or recording stream by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PauseStream '''PauseStream()'''] and you can resume it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ResumeStream '''ResumeStream()''']. If you want to stop an active playing or recording stream, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopStream '''StopStream()'''] on the leg.

=== Modifying Media Profile ===
It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.

The media profile is stored in the leg attributes and can be modified like this :
TBX_SDP_INFO SdpInfo;
PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;

pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
pMediaLegAttribute->GetProfile().GetLocalSDP(SdpInfo);
Strncpy
(
SdpInfo.aConnections[0].szIp,
"",
sizeof( SdpInfo.aConnections[0].szIp )
);
SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
pMediaLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

pCallLeg->ChangeProfile();

Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotiation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.

Once the profile change has completed (or failed), event '''OnProfileChanged()''' will be received on the leg.

For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.

=== Controlling the Signaling ===
When a call leg receives the '''OnCallLegPresent()''' event, it indicates an incoming call. To confirm that the call contains sufficient valid information to process the call on the system, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AcceptCall '''AcceptCall()'''] on the leg. If a call leg receives the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAccepted '''OnCallAccepted()'''] event, it means that an outgoing call has been accepted by the remote peer. This event usually means that the calling number has been accepted and that the call is currently being processed.

After an incoming call has been accepted, a call leg can notify the remote peer that the incoming call has been put in the "ringing" state by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AlertCall '''AlertCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAlerting '''OnCallAlerting()'''] event when an outgoing call has been put in the "ringing" state by the remote peer.

When an incoming call is answered, a call leg can notify the remote peer of the incoming call answered by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AnswerCall '''AnswerCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAnswered '''OnCallAnswered()'''] event when an outgoing call has been answered by the remote peer.

SendCallSuppInfo/OnCallSuppInfo

== Leg Termination ==

Terminating a call leg is a 2 steps process:
# Call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::TerminateCall '''TerminateCall()''']
# Free leg object on [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminated '''OnCallTerminated()''']

When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resources freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Free '''Free()'''] on the leg's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::SetFreeListener '''SetFreeListener()'''] on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is deleted. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.

[[Image:TerminateCall from application.jpg|thumb|center|350px|Call flow for leg termination initiated by user application]]

In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other media resource or signaling error. In these cases, the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminatingIndication '''OnCallTerminatingIndication()'''] is sent to the leg. On reception of this event, the application should initiate call termination as shown below.

[[Image:TerminateCall from Toolpack.jpg|thumb|center|350px|Call flow for leg termination initiated by Toolpack]]

In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnLegTerminated '''OnLegTerminated()'''] event. This event indicates that the leg does not exist anymore on the Toolpack side and the user should free its object without trying any other interaction with Toolpack through it.

== Leg Synchronization on Failover ==
When a Toolpack application is restarted or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs through the '''OnCallLegSync()''' event of the [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_lib_user.html ITBCMCLibUser] interface (this interface must be implemented by all user applications). One event will be received for each leg being synchronized. The course of action to take when receiving a leg synchronization event depends on the ability of the application to resynchronize its states with theses legs.

* If the application can't resynchronize active legs or if it does not want to resychronize the leg for which it is receiving an '''OnCallLegSync()''' event, it must refuse the leg by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLeg '''RefuseLeg()'''].
*If the application wants the resynchronize the leg or if it does not yet have enough information to decide, it must create a CTBCMCLeg object using the leg attributes received in the event.

Once all '''OnCallLegSync()''' have been sent, Toolpack will start synchronization of the links between legs through '''OnLinkSync()'''. This event indicates that two legs are connected together. It can be used by the application to rebuild its internal states. As for the legs, unwanted links can be refused by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()'''].

When all links have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. At that moment, the application has all the information available on the Toolpack side to determine if the legs should be kept or release. Any leg that the application does not want to keep can be refused by calling '''RefuseLeg()''' on it. For all legs that have not been refused, an event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnSyncDone '''OnSyncDone()'''] will be sent on the leg. Once this event has been received on a leg, the leg is fully functional and the application can start calling any usual Toolpack function on it.

[[Image:CallFlow Sync After Application Restart.jpg|thumb|center|350px|Call flow for leg synchronization]]

===Loss of Communication with Toolpack Engine===
If communication is lost with the Toolpack Engine, event '''OnCmcLibNotReady()''' will be sent to the application. It indicates that the Toolpack framework is no more accessible. The legs are still valid at that time but no action can be executed on them as long the CmcLib is not ready. If the connection with the Toolpack Engine is not back up in less than 10 seconds, the CmcLib will declare a major communication loss and will call '''OnLegTerminated()''' on all the legs. In that case, when communication is regained with the Toolpack Engine, the synchronization sequence will start again from the beginning.

[[Image:CallFlow Sync After Comm Restart Passed 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart passed 10 seconds.]]

If the communication is regained before the 10 seconds timeout, event '''OnCmcLibReady()''' will be sent and the application can then continue working normally with its existing call legs. Note that you can also receive '''OnLegTerminated()''' on some legs before receiving the '''OnCmcLibReady()''' if those legs were in a transient state when disconnection occurred.

[[Image:CallFlow Sync After Comm Restart Within 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart within 10 seconds.]]

== Bridging the Media Path ==
=== Join ===

To bridge the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Join '''Join()'''] on one of the leg, giving the second leg as a parameter. This will connect the media path between the two legs according to the link properties set on the leg on which '''Join()''' is called. These link properties can be modified by overloading the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetJoinAttributes '''GetJoinAttributes()''']. The important attribute to set is '''IsFullDuplex()''' that indicates if the connection will be made full-duplex (A<-->B) or half-duplex (A-->B). Prior to release 2.5.2, the default connection mode is half-duplex. For all release version 2.5.2 or higher, the default connection mode is full-duplex.

'''Warning:''' If two legs are already connected in half-duplex and you want to connect them in full-duplex, you must first Unjoin() the legs, then Join() them in full-duplex. You can '''NOT''' only do another half-duplex in the opposite direction.

When legs are joined, it creates a link identified with a unique ''link id''. It is the responsibility of the application to provide this unique ''link id'' by implementing the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetLinkId '''GetLinkId()'''] function of the leg. It is planned to allow the user to provide a value of '0' to let the Toolpack system automatically choose a ''link id'', but as of this writing this feature is not yet available.

'''Warning:''' When two legs are joined, the application must ensure that '''GetLinkId()''' on both leg will return the right ''link id''. This will ensure that when the link needs to be removed, both A->Unjoin() and B->Unjoin() will work correctly.

==== Setting the link properties ====

In your leg class, add a member variable to store the join attributes for that leg.

CTBCMC_JOIN_ATTRIBUTE mJoinAttribute;

Then set the join properties you want in your leg class constructor (or at any other location that will run '''before''' the '''Join()''' is done:

mJoinAttribute.IsFullDuplex() = TBX_TRUE;

Last, implement the '''GetJoinAttributes()''' function.

CTBCMC_JOIN_ATTRIBUTE & CH248Termination::GetJoinAttributes()
{
return mJoinAttribute;
}

==== Broadcasting a media source ====
At the time of writing this, broadcast of a single media source to multiple destinations is not yet possible.

=== Unjoin ===
To disconnect the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Unjoin'''Unjoin()'''] on any of the legs. The '''GetLinkId()''' function of the leg on which '''Unjoin()''' is called must return the ''link id'' that was used when the legs were joined.

[[category:CAF]]
[[category:Needs revising]]

CAF: Working With Call Legs

2010-02-10T14:10:57Z

Alexandre Lussier: /* Playing and Collecting Digits */

== Call Leg Definition ==
The main mechanism through which the customer application controls the [[Toolpack]] system is via the management of call legs. The application creates a call leg (or more than one for conferencing and bridging) at the beginning of a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.

A call leg is represented by an instance of the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html CTBCMCLeg] class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 [[timeslot]]) or a [[SIP]] call with its associated [[VOIP]] [[Voice codecs|codec]] resource (attached to an IP/UDP endpoint). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (VOIP codec resource attached to an IP/UDP endpoint). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.

The CTBCMCLeg class allows a programmer to easily act upon the call leg to influence the signaling portion (e.g. accept, answer, terminate, etc) and to use the media portion as well (e.g play prompts, record voice, play or collect digits and tones).

Other member functions are available to retrieve (and change in some cases) the call leg attributes including the media profile (e.g. parameters to the media resource) or signaling information (e.g. protocol type, called and calling party numbers, etc). Joining/unjoining (connection/disconnection) of call legs is also a typical action handled by this class for ’gateway-type’ applications. It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse a ''call leg'' with a ''call''. A ''call leg'' represents one full-duplex link to a party while a ''call'' represents the agglomeration of multiple (two or more) call legs. For example, a ''bridge'' is a form of ''call'' that uses two ''call legs''.
* Do not confuse the base class CTBCMCLeg with the class [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_leg.html CTBCAFCallLeg]. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs. It is designed to represent a leg within a call. It cannot be instanciated as a standalone object without modifications to make it independent from the ITBCAFCallFlow interface.
* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

== Command Flow for Leg Actions in CAF ==
All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).

For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.

== Leg Creation ==
Creating a leg is always done through the definition of a ''call leg attribute''. The values entered in the ''call leg attribute'' will define the type of call leg created and its parameters. The following sections describe several scenarios in which you build a ''call leg''. Instruction will be given on how to fill the leg attributes and how to use them to create the ''call leg''.

=== Preparing Leg Attributes ===

==== Normal Call Leg Attributes ====
For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
* the called number,
* the calling number,
* the [[NAP | Network Access Point]].

Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|NAP Types]]).

The following code snippet shows how to build the attributes.
PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();

ptrOutgoingLegAttribute->GetCalledNumber() = "123-4567";
ptrOutgoingLegAttribute->GetCallingNumber() = "987-6543";
ptrOutgoingLegAttribute->GetNetworkAccessPoint() = "NAP_SS7_MONTREAL";

==== Media-only Leg Attributes ====
For media-only legs, no signaling information is needed but the user can specify which media channel to use and which media profile to use. The only required parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''MEDIA TDM'' or ''MEDIA VOIP'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;

ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();

ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;

When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. For ''MEDIA TDM'' NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For ''MEDIA VOIP'' NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and a timeslot number can be specified.

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc->Settings.TdmAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
pMediaDesc->Settings.TdmAudio.un8Timeslot = 5;
Strncpy
(
pMediaDesc->Settings.TdmAudio.szTrunkName,
"TRUNK_TORONTO_1",
sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
);

For VOIP legs, the user can control the media by providing local [[SDP]] and peer SDP. Setting the local SDP defines the codec and IP/port used to for the received media stream. Most of the time, the IP address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and IP/port used for the transmitted media stream. Note that Toolpack only allows for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in '''both''' SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].

TBX_RESULT Result;
TBX_SDP_INFO SdpInfo;
PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();
pMediaDesc->Settings.PacketAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;

// Set Local SDP
Result = BuildSdpInfo("", 0, SdpInfo); // No IP specified, Toolpack will choose one
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

// Set Peer SDP
Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo); // Using peer IP address and port
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetPeerSDP(SdpInfo);

=== Creating the Leg ===
Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CreateCall '''CreateCall()'''] on it. No action is taken when an instance of a CTBCMCLeg is created. Call resources are only allocated in the Toolpack system when '''CreateCall()''' is called on the object.

pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
pCallLeg->CreateCall();

For legs with signaling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).

[[Image:CallFlow SignalingMediaLeg Creation.JPG|thumb|center|350px|Call flow for creation of leg with signaling]]

For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.

[[Image:CallFlow MediaOnlyLeg Creation.JPG|thumb|center|350px|Call flow for media-only leg creation]]

Once a call is fully active (call answered and media allocated), event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnProfileChanged '''OnProfileChanged()'''] will be sent on the leg. In the cases where the user had not specified the IP/port to use, once this event is received, the media profile has been updated with the values chosen by Toolpack and the updated values can be retrieved using the functions '''GetLocalSDP()''' and '''GetPeerSDP()''' of the profile.
Note that the '''OnProfileChanged()''' event is also sent after the media profile has been modified with the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ChangeProfile '''ChangeProfile()'''] function (see [[#Modifying Media Profile|Modifying Media Profile]]) and when a connected peer has requested it (through a SIP re-INVITE for example).

See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.

=== Caveats ===
* The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).

== Interaction with Legs ==

=== Playing and Collecting Digits ===
You can play digits by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayDigit '''PlayDigit()'''] on a leg. Toolpack will receive the request and play the digits. Once digits are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitPlayingDone '''OnDigitPlayingDone()'''] event.

You can also configure a leg to collect digits played. To start the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartDigitCollection '''StartDigitCollection()'''] on the leg. To stop the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopDigitCollection '''StopDigitCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitCollected '''OnDigitCollected()'''] event when there will be a match between the asked string and the digits collected.

Here is an example how to play and collect digit. This example plays digit 5 on the outgoing leg and collects 5 on the incoming leg when the call is answered.

<code><pre>
TBX_RESULT CTBCAFCallBehaviorTones::OnCallLegAnswered
(
IN PCTBCAFCallLeg in_pCallLeg,
IN CTBCMC_PROTOCOL_ATTRIBUTE & in_ProtocolAttribute
)
{
TBCAF_MUTEX_GET_SCOPE_BEGIN( mpParentMutex )
PTRCTBCAFCallLeg ptrIncomingLeg;
PTRCTBCAFCallLeg ptrOutgoingLeg;

/*---------------------------------------------------------------------------------------------------------------------------
| Code section
*--------------------------------------------------------------------------------------------------------------------------*/
CAFCODE( CTBCAFCallBehaviorTones::OnCallLegAnswered )
{
/* play ready tone */
ptrOutgoingLeg = GetOutgoingActiveLeg();
if( ptrOutgoingLeg != NULL )
{
ptrOutgoingLeg->PlayDigit( "5" );
}

// Start the digit collection of the ready digit
ptrIncomingLeg = GetIncomingActiveLeg();
if( ptrIncomingLeg != NULL )
{
ptrIncomingLeg->StartDigitCollection( "5" );
}

TBX_EXIT_SUCCESS( TBX_RESULT_OK );
}
.
.
.
}
</pre></code>

=== Playing and Collecting Tones ===
You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play events by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayEvent '''PlayEvent()'''] on a leg. Toolpack will receive the request and play the events. Once events are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventPlayingDone '''OnEventPlayingDone()'''] event. Note that you can cancel an event to be played by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CancelEvent '''CancelEvent()'''] on the leg after a '''PlayEvent()''' has been called.

Two kinds of string can be passed to '''AddToneString()''' to play a tone. The first type is to play well known tones such as dtmf and fax tone. The syntax is really simple and is based on H248 package and signal ids. The first component of the string is the package id and the second is the signal id, both formated in string. So, to play dtmf 0, you have to format the following string: "dg/d0", where "dg" is for package "dtmf generation" and "d0" is for "dtmf 0".

The second type of string is to play custom tone. The syntax is much more complicated than the first one, but it follows a well described syntax which can be found in [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.6-200011-I!!PDF-E&type=items/.pdf '''H248.6 Dynamic Tone Definition Package''']. This kind of string allows you to specify frequencies, duration, amplitude and repeating count of the tone. You can also specify well known tones and change their default duration, amplitude and repeating count. It is possible to describe a sequence of tones or frequencies that are played in one segment. Here are some examples of the syntax:

*;Frequencies 400Hz and 600Hz mixed together for 200ms, amplitude at -10dB and repeating 3 times (playing 4 times):
:*(((#400)+(#600)),200,-10)*3
:
*;Dtmf 5 repeated infinitly:
:*((0x0005,0x0015))*0
:
*;Multifrequency tone 8:
:*((mfg,mf8))
:
*;Frequency 440Hz played for 300ms at -10dB followed by frequency 600Hz played for 200ms at -5dB and then followed by dtmf 2, all this repeated infinitly:
:*((#440,300,-10),(#600,200,-5),(0x0005,0x0012))*0
:

You can also configure a leg to collect events played. To start the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartEventCollection '''StartEventCollection()'''] on the leg. Note that you will have to specify which events you want to collect before starting the event collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopEventCollection '''StopEventCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventCollected '''OnEventCollected()'''] event on each event received that correspond to a tone string specified when calling '''StartEventCollection()'''.

Only one type of string is accepted to specify which events to collect. The string is the same as the first type to play event. Signal ids that are also event id are accepted. This means that you can ask to collect "dg/d0" (dtmf generation/dtmf 0) and the detection will be done anyway. But, when the event is detected, it's the event id that will be returned, which means that "dd/d0" (dtmf detection/dtmf 0) will be returned instead of "dg/d0". You can also detect all events from a package by putting a * as event id, so "dd/*" will detect all dtmf tones.

The most commonly used package are 5 and 6 [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.1-200509-I!!PDF-E&type=items/.pdf '''(H248.1 Annex E)''']: dtmf generation and dtmf detection. As H248 does not define events and signals for fax tone, we added a special package to do so. Package telcofax (0x8001) contains three events and two signals. Signals are: cng (0x0080) and g164 (0x0081) and events are: cng (0x0080), g164 (0x0081) and g165 (0x0082).



=== Collecting digits and tones while call legs are joined ===
By default, when two call legs are joined together through function CTBCMCCallLeg::Join(), tone collection is automatically disabled.
One of the arguments of the Join() function ("in_fDisableToneWhileJoined") will allow to control if automatic tone collection feature is used or not on a call.

Why is Toolpack disabling tone collection on joined legs by default?
That's because tone collection introduces a 40ms delay in the audio connection (required to provide tone suppression), and most of the time it is no more require to collect digits while two call legs are joined, so it would be useless to leave 40ms delay while tone collection is no more required.

=== Playing and Recording Audio Files ===
You can play an audio stream on a leg by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayStream '''PlayStream()'''] on it. To specify which audio stream you want to play, you have to specify it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html#CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath '''AddPlayFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html CTBCMC_PLAY_ATTRIBUTE] class. Toolpack will receive the request and play the stream. Once it is played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingDone '''OnStreamPlayingDone()'''] event.

You can also configure a leg to record an audio stream. First you must specify file paths to record by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html#CTBCMC_RECORD_ATTRIBUTE::AddRecFilePath '''AddRecFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html CTBCMC_RECORD_ATTRIBUTE] class. The you can call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RecordStream '''RecordStream()'''] on a leg. Once the stream is recorded, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamRecordingDone '''OnStreamRecordingDone()'''] event.

You can pause an active playing or recording stream by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PauseStream '''PauseStream()'''] and you can resume it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ResumeStream '''ResumeStream()''']. If you want to stop an active playing or recording stream, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopStream '''StopStream()'''] on the leg.

=== Modifying Media Profile ===
It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.

The media profile is stored in the leg attributes and can be modified like this :
TBX_SDP_INFO SdpInfo;
PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;

pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
pMediaLegAttribute->GetProfile().GetLocalSDP(SdpInfo);
Strncpy
(
SdpInfo.aConnections[0].szIp,
"",
sizeof( SdpInfo.aConnections[0].szIp )
);
SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
pMediaLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

pCallLeg->ChangeProfile();

Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotiation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.

Once the profile change has completed (or failed), event '''OnProfileChanged()''' will be received on the leg.

For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.

=== Controlling the Signaling ===
When a call leg receives the '''OnCallLegPresent()''' event, it indicates an incoming call. To confirm that the call contains sufficient valid information to process the call on the system, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AcceptCall '''AcceptCall()'''] on the leg. If a call leg receives the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAccepted '''OnCallAccepted()'''] event, it means that an outgoing call has been accepted by the remote peer. This event usually means that the calling number has been accepted and that the call is currently being processed.

After an incoming call has been accepted, a call leg can notify the remote peer that the incoming call has been put in the "ringing" state by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AlertCall '''AlertCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAlerting '''OnCallAlerting()'''] event when an outgoing call has been put in the "ringing" state by the remote peer.

When an incoming call is answered, a call leg can notify the remote peer of the incoming call answered by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AnswerCall '''AnswerCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAnswered '''OnCallAnswered()'''] event when an outgoing call has been answered by the remote peer.

SendCallSuppInfo/OnCallSuppInfo

== Leg Termination ==

Terminating a call leg is a 2 steps process:
# Call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::TerminateCall '''TerminateCall()''']
# Free leg object on [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminated '''OnCallTerminated()''']

When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resources freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Free '''Free()'''] on the leg's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::SetFreeListener '''SetFreeListener()'''] on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is deleted. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.

[[Image:TerminateCall from application.jpg|thumb|center|350px|Call flow for leg termination initiated by user application]]

In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other media resource or signaling error. In these cases, the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminatingIndication '''OnCallTerminatingIndication()'''] is sent to the leg. On reception of this event, the application should initiate call termination as shown below.

[[Image:TerminateCall from Toolpack.jpg|thumb|center|350px|Call flow for leg termination initiated by Toolpack]]

In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnLegTerminated '''OnLegTerminated()'''] event. This event indicates that the leg does not exist anymore on the Toolpack side and the user should free its object without trying any other interaction with Toolpack through it.

== Leg Synchronization on Failover ==
When a Toolpack application is restarted or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs through the '''OnCallLegSync()''' event of the [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_lib_user.html ITBCMCLibUser] interface (this interface must be implemented by all user applications). One event will be received for each leg being synchronized. The course of action to take when receiving a leg synchronization event depends on the ability of the application to resynchronize its states with theses legs.

* If the application can't resynchronize active legs or if it does not want to resychronize the leg for which it is receiving an '''OnCallLegSync()''' event, it must refuse the leg by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLeg '''RefuseLeg()'''].
*If the application wants the resynchronize the leg or if it does not yet have enough information to decide, it must create a CTBCMCLeg object using the leg attributes received in the event.

Once all '''OnCallLegSync()''' have been sent, Toolpack will start synchronization of the links between legs through '''OnLinkSync()'''. This event indicates that two legs are connected together. It can be used by the application to rebuild its internal states. As for the legs, unwanted links can be refused by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()'''].

When all links have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. At that moment, the application has all the information available on the Toolpack side to determine if the legs should be kept or release. Any leg that the application does not want to keep can be refused by calling '''RefuseLeg()''' on it. For all legs that have not been refused, an event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnSyncDone '''OnSyncDone()'''] will be sent on the leg. Once this event has been received on a leg, the leg is fully functional and the application can start calling any usual Toolpack function on it.

[[Image:CallFlow Sync After Application Restart.jpg|thumb|center|350px|Call flow for leg synchronization]]

===Loss of Communication with Toolpack Engine===
If communication is lost with the Toolpack Engine, event '''OnCmcLibNotReady()''' will be sent to the application. It indicates that the Toolpack framework is no more accessible. The legs are still valid at that time but no action can be executed on them as long the CmcLib is not ready. If the connection with the Toolpack Engine is not back up in less than 10 seconds, the CmcLib will declare a major communication loss and will call '''OnLegTerminated()''' on all the legs. In that case, when communication is regained with the Toolpack Engine, the synchronization sequence will start again from the beginning.

[[Image:CallFlow Sync After Comm Restart Passed 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart passed 10 seconds.]]

If the communication is regained before the 10 seconds timeout, event '''OnCmcLibReady()''' will be sent and the application can then continue working normally with its existing call legs. Note that you can also receive '''OnLegTerminated()''' on some legs before receiving the '''OnCmcLibReady()''' if those legs were in a transient state when disconnection occurred.

[[Image:CallFlow Sync After Comm Restart Within 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart within 10 seconds.]]

== Bridging the Media Path ==
=== Join ===

To bridge the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Join '''Join()'''] on one of the leg, giving the second leg as a parameter. This will connect the media path between the two legs according to the link properties set on the leg on which '''Join()''' is called. These link properties can be modified by overloading the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetJoinAttributes '''GetJoinAttributes()''']. The important attribute to set is '''IsFullDuplex()''' that indicates if the connection will be made full-duplex (A<-->B) or half-duplex (A-->B). Prior to release 2.5.2, the default connection mode is half-duplex. For all release version 2.5.2 or higher, the default connection mode is full-duplex.

'''Warning:''' If two legs are already connected in half-duplex and you want to connect them in full-duplex, you must first Unjoin() the legs, then Join() them in full-duplex. You can '''NOT''' only do another half-duplex in the opposite direction.

When legs are joined, it creates a link identified with a unique ''link id''. It is the responsibility of the application to provide this unique ''link id'' by implementing the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetLinkId '''GetLinkId()'''] function of the leg. It is planned to allow the user to provide a value of '0' to let the Toolpack system automatically choose a ''link id'', but as of this writing this feature is not yet available.

'''Warning:''' When two legs are joined, the application must ensure that '''GetLinkId()''' on both leg will return the right ''link id''. This will ensure that when the link needs to be removed, both A->Unjoin() and B->Unjoin() will work correctly.

==== Setting the link properties ====

In your leg class, add a member variable to store the join attributes for that leg.

CTBCMC_JOIN_ATTRIBUTE mJoinAttribute;

Then set the join properties you want in your leg class constructor (or at any other location that will run '''before''' the '''Join()''' is done:

mJoinAttribute.IsFullDuplex() = TBX_TRUE;

Last, implement the '''GetJoinAttributes()''' function.

CTBCMC_JOIN_ATTRIBUTE & CH248Termination::GetJoinAttributes()
{
return mJoinAttribute;
}

==== Broadcasting a media source ====
At the time of writing this, broadcast of a single media source to multiple destinations is not yet possible.

=== Unjoin ===
To disconnect the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Unjoin'''Unjoin()'''] on any of the legs. The '''GetLinkId()''' function of the leg on which '''Unjoin()''' is called must return the ''link id'' that was used when the legs were joined.

[[category:CAF]]
[[category:Needs revising]]

CAF: Working With Call Legs

2010-02-09T21:42:09Z

Alexandre Lussier: /* Playing and Collecting Tones */

== Call Leg Definition ==
The main mechanism through which the customer application controls the [[Toolpack]] system is via the management of call legs. The application creates a call leg (or more than one for conferencing and bridging) at the beginning of a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.

A call leg is represented by an instance of the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html CTBCMCLeg] class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 [[timeslot]]) or a [[SIP]] call with its associated [[VOIP]] [[Voice codecs|codec]] resource (attached to an IP/UDP endpoint). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (VOIP codec resource attached to an IP/UDP endpoint). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.

The CTBCMCLeg class allows a programmer to easily act upon the call leg to influence the signaling portion (e.g. accept, answer, terminate, etc) and to use the media portion as well (e.g play prompts, record voice, play or collect digits and tones).

Other member functions are available to retrieve (and change in some cases) the call leg attributes including the media profile (e.g. parameters to the media resource) or signaling information (e.g. protocol type, called and calling party numbers, etc). Joining/unjoining (connection/disconnection) of call legs is also a typical action handled by this class for ’gateway-type’ applications. It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse a ''call leg'' with a ''call''. A ''call leg'' represents one full-duplex link to a party while a ''call'' represents the agglomeration of multiple (two or more) call legs. For example, a ''bridge'' is a form of ''call'' that uses two ''call legs''.
* Do not confuse the base class CTBCMCLeg with the class [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_leg.html CTBCAFCallLeg]. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs. It is designed to represent a leg within a call. It cannot be instanciated as a standalone object without modifications to make it independent from the ITBCAFCallFlow interface.
* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

== Command Flow for Leg Actions in CAF ==
All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).

For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.

== Leg Creation ==
Creating a leg is always done through the definition of a ''call leg attribute''. The values entered in the ''call leg attribute'' will define the type of call leg created and its parameters. The following sections describe several scenarios in which you build a ''call leg''. Instruction will be given on how to fill the leg attributes and how to use them to create the ''call leg''.

=== Preparing Leg Attributes ===

==== Normal Call Leg Attributes ====
For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
* the called number,
* the calling number,
* the [[NAP | Network Access Point]].

Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|NAP Types]]).

The following code snippet shows how to build the attributes.
PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();

ptrOutgoingLegAttribute->GetCalledNumber() = "123-4567";
ptrOutgoingLegAttribute->GetCallingNumber() = "987-6543";
ptrOutgoingLegAttribute->GetNetworkAccessPoint() = "NAP_SS7_MONTREAL";

==== Media-only Leg Attributes ====
For media-only legs, no signaling information is needed but the user can specify which media channel to use and which media profile to use. The only required parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''MEDIA TDM'' or ''MEDIA VOIP'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;

ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();

ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;

When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. For ''MEDIA TDM'' NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For ''MEDIA VOIP'' NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and a timeslot number can be specified.

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc->Settings.TdmAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
pMediaDesc->Settings.TdmAudio.un8Timeslot = 5;
Strncpy
(
pMediaDesc->Settings.TdmAudio.szTrunkName,
"TRUNK_TORONTO_1",
sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
);

For VOIP legs, the user can control the media by providing local [[SDP]] and peer SDP. Setting the local SDP defines the codec and IP/port used to for the received media stream. Most of the time, the IP address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and IP/port used for the transmitted media stream. Note that Toolpack only allows for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in '''both''' SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].

TBX_RESULT Result;
TBX_SDP_INFO SdpInfo;
PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();
pMediaDesc->Settings.PacketAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;

// Set Local SDP
Result = BuildSdpInfo("", 0, SdpInfo); // No IP specified, Toolpack will choose one
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

// Set Peer SDP
Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo); // Using peer IP address and port
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetPeerSDP(SdpInfo);

=== Creating the Leg ===
Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CreateCall '''CreateCall()'''] on it. No action is taken when an instance of a CTBCMCLeg is created. Call resources are only allocated in the Toolpack system when '''CreateCall()''' is called on the object.

pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
pCallLeg->CreateCall();

For legs with signaling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).

[[Image:CallFlow SignalingMediaLeg Creation.JPG|thumb|center|350px|Call flow for creation of leg with signaling]]

For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.

[[Image:CallFlow MediaOnlyLeg Creation.JPG|thumb|center|350px|Call flow for media-only leg creation]]

Once a call is fully active (call answered and media allocated), event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnProfileChanged '''OnProfileChanged()'''] will be sent on the leg. In the cases where the user had not specified the IP/port to use, once this event is received, the media profile has been updated with the values chosen by Toolpack and the updated values can be retrieved using the functions '''GetLocalSDP()''' and '''GetPeerSDP()''' of the profile.
Note that the '''OnProfileChanged()''' event is also sent after the media profile has been modified with the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ChangeProfile '''ChangeProfile()'''] function (see [[#Modifying Media Profile|Modifying Media Profile]]) and when a connected peer has requested it (through a SIP re-INVITE for example).

See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.

=== Caveats ===
* The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).

== Interaction with Legs ==

=== Playing and Collecting Digits ===
You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play digits defined by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayDigit '''PlayDigit()'''] on a leg. Toolpack will receive the request and play the digits. Once digits are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitPlayingDone '''OnDigitPlayingDone()'''] event.

You can also configure a leg to collect digits played. To start the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartDigitCollection '''StartDigitCollection()'''] on the leg. Note that you will have to specify which digits you want to collect before starting the digit collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopDigitCollection '''StopDigitCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitCollected '''OnDigitCollected()'''] event on each digit received that correspond to a tone string specified with the previously call to '''AddToneString()'''.

=== Playing and Collecting Tones ===
You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play events by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayEvent '''PlayEvent()'''] on a leg. Toolpack will receive the request and play the events. Once events are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventPlayingDone '''OnEventPlayingDone()'''] event. Note that you can cancel an event to be played by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CancelEvent '''CancelEvent()'''] on the leg after a '''PlayEvent()''' has been called.

Two kinds of string can be passed to '''AddToneString()''' to play a tone. The first type is to play well known tones such as dtmf and fax tone. The syntax is really simple and is based on H248 package and signal ids. The first component of the string is the package id and the second is the signal id, both formated in string. So, to play dtmf 0, you have to format the following string: "dg/d0", where "dg" is for package "dtmf generation" and "d0" is for "dtmf 0".

The second type of string is to play custom tone. The syntax is much more complicated than the first one, but it follows a well described syntax which can be found in [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.6-200011-I!!PDF-E&type=items/.pdf '''H248.6 Dynamic Tone Definition Package''']. This kind of string allows you to specify frequencies, duration, amplitude and repeating count of the tone. You can also specify well known tones and change their default duration, amplitude and repeating count. It is possible to describe a sequence of tones or frequencies that are played in one segment. Here are some examples of the syntax:

*;Frequencies 400Hz and 600Hz mixed together for 200ms, amplitude at -10dB and repeating 3 times (playing 4 times):
:*(((#400)+(#600)),200,-10)*3
:
*;Dtmf 5 repeated infinitly:
:*((0x0005,0x0015))*0
:
*;Multifrequency tone 8:
:*((mfg,mf8))
:
*;Frequency 440Hz played for 300ms at -10dB followed by frequency 600Hz played for 200ms at -5dB and then followed by dtmf 2, all this repeated infinitly:
:*((#440,300,-10),(#600,200,-5),(0x0005,0x0012))*0
:

You can also configure a leg to collect events played. To start the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartEventCollection '''StartEventCollection()'''] on the leg. Note that you will have to specify which events you want to collect before starting the event collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopEventCollection '''StopEventCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventCollected '''OnEventCollected()'''] event on each event received that correspond to a tone string specified when calling '''StartEventCollection()'''.

Only one type of string is accepted to specify which events to collect. The string is the same as the first type to play event. Signal ids that are also event id are accepted. This means that you can ask to collect "dg/d0" (dtmf generation/dtmf 0) and the detection will be done anyway. But, when the event is detected, it's the event id that will be returned, which means that "dd/d0" (dtmf detection/dtmf 0) will be returned instead of "dg/d0". You can also detect all events from a package by putting a * as event id, so "dd/*" will detect all dtmf tones.

The most commonly used package are 5 and 6 [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.1-200509-I!!PDF-E&type=items/.pdf '''(H248.1 Annex E)''']: dtmf generation and dtmf detection. As H248 does not define events and signals for fax tone, we added a special package to do so. Package telcofax (0x8001) contains three events and two signals. Signals are: cng (0x0080) and g164 (0x0081) and events are: cng (0x0080), g164 (0x0081) and g165 (0x0082).



=== Collecting digits and tones while call legs are joined ===
By default, when two call legs are joined together through function CTBCMCCallLeg::Join(), tone collection is automatically disabled.
One of the arguments of the Join() function ("in_fDisableToneWhileJoined") will allow to control if automatic tone collection feature is used or not on a call.

Why is Toolpack disabling tone collection on joined legs by default?
That's because tone collection introduces a 40ms delay in the audio connection (required to provide tone suppression), and most of the time it is no more require to collect digits while two call legs are joined, so it would be useless to leave 40ms delay while tone collection is no more required.

=== Playing and Recording Audio Files ===
You can play an audio stream on a leg by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayStream '''PlayStream()'''] on it. To specify which audio stream you want to play, you have to specify it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html#CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath '''AddPlayFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html CTBCMC_PLAY_ATTRIBUTE] class. Toolpack will receive the request and play the stream. Once it is played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingDone '''OnStreamPlayingDone()'''] event.

You can also configure a leg to record an audio stream. First you must specify file paths to record by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html#CTBCMC_RECORD_ATTRIBUTE::AddRecFilePath '''AddRecFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html CTBCMC_RECORD_ATTRIBUTE] class. The you can call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RecordStream '''RecordStream()'''] on a leg. Once the stream is recorded, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamRecordingDone '''OnStreamRecordingDone()'''] event.

You can pause an active playing or recording stream by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PauseStream '''PauseStream()'''] and you can resume it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ResumeStream '''ResumeStream()''']. If you want to stop an active playing or recording stream, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopStream '''StopStream()'''] on the leg.

=== Modifying Media Profile ===
It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.

The media profile is stored in the leg attributes and can be modified like this :
TBX_SDP_INFO SdpInfo;
PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;

pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
pMediaLegAttribute->GetProfile().GetLocalSDP(SdpInfo);
Strncpy
(
SdpInfo.aConnections[0].szIp,
"",
sizeof( SdpInfo.aConnections[0].szIp )
);
SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
pMediaLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

pCallLeg->ChangeProfile();

Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotiation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.

Once the profile change has completed (or failed), event '''OnProfileChanged()''' will be received on the leg.

For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.

=== Controlling the Signaling ===
When a call leg receives the '''OnCallLegPresent()''' event, it indicates an incoming call. To confirm that the call contains sufficient valid information to process the call on the system, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AcceptCall '''AcceptCall()'''] on the leg. If a call leg receives the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAccepted '''OnCallAccepted()'''] event, it means that an outgoing call has been accepted by the remote peer. This event usually means that the calling number has been accepted and that the call is currently being processed.

After an incoming call has been accepted, a call leg can notify the remote peer that the incoming call has been put in the "ringing" state by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AlertCall '''AlertCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAlerting '''OnCallAlerting()'''] event when an outgoing call has been put in the "ringing" state by the remote peer.

When an incoming call is answered, a call leg can notify the remote peer of the incoming call answered by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AnswerCall '''AnswerCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAnswered '''OnCallAnswered()'''] event when an outgoing call has been answered by the remote peer.

SendCallSuppInfo/OnCallSuppInfo

== Leg Termination ==

Terminating a call leg is a 2 steps process:
# Call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::TerminateCall '''TerminateCall()''']
# Free leg object on [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminated '''OnCallTerminated()''']

When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resources freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Free '''Free()'''] on the leg's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::SetFreeListener '''SetFreeListener()'''] on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is deleted. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.

[[Image:TerminateCall from application.jpg|thumb|center|350px|Call flow for leg termination initiated by user application]]

In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other media resource or signaling error. In these cases, the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminatingIndication '''OnCallTerminatingIndication()'''] is sent to the leg. On reception of this event, the application should initiate call termination as shown below.

[[Image:TerminateCall from Toolpack.jpg|thumb|center|350px|Call flow for leg termination initiated by Toolpack]]

In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnLegTerminated '''OnLegTerminated()'''] event. This event indicates that the leg does not exist anymore on the Toolpack side and the user should free its object without trying any other interaction with Toolpack through it.

== Leg Synchronization on Failover ==
When a Toolpack application is restarted or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs through the '''OnCallLegSync()''' event of the [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_lib_user.html ITBCMCLibUser] interface (this interface must be implemented by all user applications). One event will be received for each leg being synchronized. The course of action to take when receiving a leg synchronization event depends on the ability of the application to resynchronize its states with theses legs.

* If the application can't resynchronize active legs or if it does not want to resychronize the leg for which it is receiving an '''OnCallLegSync()''' event, it must refuse the leg by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLeg '''RefuseLeg()'''].
*If the application wants the resynchronize the leg or if it does not yet have enough information to decide, it must create a CTBCMCLeg object using the leg attributes received in the event.

Once all '''OnCallLegSync()''' have been sent, Toolpack will start synchronization of the links between legs through '''OnLinkSync()'''. This event indicates that two legs are connected together. It can be used by the application to rebuild its internal states. As for the legs, unwanted links can be refused by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()'''].

When all links have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. At that moment, the application has all the information available on the Toolpack side to determine if the legs should be kept or release. Any leg that the application does not want to keep can be refused by calling '''RefuseLeg()''' on it. For all legs that have not been refused, an event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnSyncDone '''OnSyncDone()'''] will be sent on the leg. Once this event has been received on a leg, the leg is fully functional and the application can start calling any usual Toolpack function on it.

[[Image:CallFlow Sync After Application Restart.jpg|thumb|center|350px|Call flow for leg synchronization]]

===Loss of Communication with Toolpack Engine===
If communication is lost with the Toolpack Engine, event '''OnCmcLibNotReady()''' will be sent to the application. It indicates that the Toolpack framework is no more accessible. The legs are still valid at that time but no action can be executed on them as long the CmcLib is not ready. If the connection with the Toolpack Engine is not back up in less than 10 seconds, the CmcLib will declare a major communication loss and will call '''OnLegTerminated()''' on all the legs. In that case, when communication is regained with the Toolpack Engine, the synchronization sequence will start again from the beginning.

[[Image:CallFlow Sync After Comm Restart Passed 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart passed 10 seconds.]]

If the communication is regained before the 10 seconds timeout, event '''OnCmcLibReady()''' will be sent and the application can then continue working normally with its existing call legs. Note that you can also receive '''OnLegTerminated()''' on some legs before receiving the '''OnCmcLibReady()''' if those legs were in a transient state when disconnection occurred.

[[Image:CallFlow Sync After Comm Restart Within 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart within 10 seconds.]]

== Bridging the Media Path ==
=== Join ===

To bridge the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Join '''Join()'''] on one of the leg, giving the second leg as a parameter. This will connect the media path between the two legs according to the link properties set on the leg on which '''Join()''' is called. These link properties can be modified by overloading the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetJoinAttributes '''GetJoinAttributes()''']. The important attribute to set is '''IsFullDuplex()''' that indicates if the connection will be made full-duplex (A<-->B) or half-duplex (A-->B). Prior to release 2.5.2, the default connection mode is half-duplex. For all release version 2.5.2 or higher, the default connection mode is full-duplex.

'''Warning:''' If two legs are already connected in half-duplex and you want to connect them in full-duplex, you must first Unjoin() the legs, then Join() them in full-duplex. You can '''NOT''' only do another half-duplex in the opposite direction.

When legs are joined, it creates a link identified with a unique ''link id''. It is the responsibility of the application to provide this unique ''link id'' by implementing the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetLinkId '''GetLinkId()'''] function of the leg. It is planned to allow the user to provide a value of '0' to let the Toolpack system automatically choose a ''link id'', but as of this writing this feature is not yet available.

'''Warning:''' When two legs are joined, the application must ensure that '''GetLinkId()''' on both leg will return the right ''link id''. This will ensure that when the link needs to be removed, both A->Unjoin() and B->Unjoin() will work correctly.

==== Setting the link properties ====

In your leg class, add a member variable to store the join attributes for that leg.

CTBCMC_JOIN_ATTRIBUTE mJoinAttribute;

Then set the join properties you want in your leg class constructor (or at any other location that will run '''before''' the '''Join()''' is done:

mJoinAttribute.IsFullDuplex() = TBX_TRUE;

Last, implement the '''GetJoinAttributes()''' function.

CTBCMC_JOIN_ATTRIBUTE & CH248Termination::GetJoinAttributes()
{
return mJoinAttribute;
}

==== Broadcasting a media source ====
At the time of writing this, broadcast of a single media source to multiple destinations is not yet possible.

=== Unjoin ===
To disconnect the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Unjoin'''Unjoin()'''] on any of the legs. The '''GetLinkId()''' function of the leg on which '''Unjoin()''' is called must return the ''link id'' that was used when the legs were joined.

[[category:CAF]]
[[category:Needs revising]]

CAF: Working With Call Legs

2010-02-09T21:22:02Z

Alexandre Lussier: /* Playing and Collecting Tones */

== Call Leg Definition ==
The main mechanism through which the customer application controls the [[Toolpack]] system is via the management of call legs. The application creates a call leg (or more than one for conferencing and bridging) at the beginning of a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.

A call leg is represented by an instance of the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html CTBCMCLeg] class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 [[timeslot]]) or a [[SIP]] call with its associated [[VOIP]] [[Voice codecs|codec]] resource (attached to an IP/UDP endpoint). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (VOIP codec resource attached to an IP/UDP endpoint). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.

The CTBCMCLeg class allows a programmer to easily act upon the call leg to influence the signaling portion (e.g. accept, answer, terminate, etc) and to use the media portion as well (e.g play prompts, record voice, play or collect digits and tones).

Other member functions are available to retrieve (and change in some cases) the call leg attributes including the media profile (e.g. parameters to the media resource) or signaling information (e.g. protocol type, called and calling party numbers, etc). Joining/unjoining (connection/disconnection) of call legs is also a typical action handled by this class for ’gateway-type’ applications. It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse a ''call leg'' with a ''call''. A ''call leg'' represents one full-duplex link to a party while a ''call'' represents the agglomeration of multiple (two or more) call legs. For example, a ''bridge'' is a form of ''call'' that uses two ''call legs''.
* Do not confuse the base class CTBCMCLeg with the class [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_leg.html CTBCAFCallLeg]. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs. It is designed to represent a leg within a call. It cannot be instanciated as a standalone object without modifications to make it independent from the ITBCAFCallFlow interface.
* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

== Command Flow for Leg Actions in CAF ==
All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).

For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.

== Leg Creation ==
Creating a leg is always done through the definition of a ''call leg attribute''. The values entered in the ''call leg attribute'' will define the type of call leg created and its parameters. The following sections describe several scenarios in which you build a ''call leg''. Instruction will be given on how to fill the leg attributes and how to use them to create the ''call leg''.

=== Preparing Leg Attributes ===

==== Normal Call Leg Attributes ====
For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
* the called number,
* the calling number,
* the [[NAP | Network Access Point]].

Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|NAP Types]]).

The following code snippet shows how to build the attributes.
PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();

ptrOutgoingLegAttribute->GetCalledNumber() = "123-4567";
ptrOutgoingLegAttribute->GetCallingNumber() = "987-6543";
ptrOutgoingLegAttribute->GetNetworkAccessPoint() = "NAP_SS7_MONTREAL";

==== Media-only Leg Attributes ====
For media-only legs, no signaling information is needed but the user can specify which media channel to use and which media profile to use. The only required parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''MEDIA TDM'' or ''MEDIA VOIP'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;

ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();

ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;

When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. For ''MEDIA TDM'' NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For ''MEDIA VOIP'' NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and a timeslot number can be specified.

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc->Settings.TdmAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
pMediaDesc->Settings.TdmAudio.un8Timeslot = 5;
Strncpy
(
pMediaDesc->Settings.TdmAudio.szTrunkName,
"TRUNK_TORONTO_1",
sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
);

For VOIP legs, the user can control the media by providing local [[SDP]] and peer SDP. Setting the local SDP defines the codec and IP/port used to for the received media stream. Most of the time, the IP address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and IP/port used for the transmitted media stream. Note that Toolpack only allows for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in '''both''' SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].

TBX_RESULT Result;
TBX_SDP_INFO SdpInfo;
PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();
pMediaDesc->Settings.PacketAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;

// Set Local SDP
Result = BuildSdpInfo("", 0, SdpInfo); // No IP specified, Toolpack will choose one
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

// Set Peer SDP
Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo); // Using peer IP address and port
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetPeerSDP(SdpInfo);

=== Creating the Leg ===
Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CreateCall '''CreateCall()'''] on it. No action is taken when an instance of a CTBCMCLeg is created. Call resources are only allocated in the Toolpack system when '''CreateCall()''' is called on the object.

pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
pCallLeg->CreateCall();

For legs with signaling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).

[[Image:CallFlow SignalingMediaLeg Creation.JPG|thumb|center|350px|Call flow for creation of leg with signaling]]

For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.

[[Image:CallFlow MediaOnlyLeg Creation.JPG|thumb|center|350px|Call flow for media-only leg creation]]

Once a call is fully active (call answered and media allocated), event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnProfileChanged '''OnProfileChanged()'''] will be sent on the leg. In the cases where the user had not specified the IP/port to use, once this event is received, the media profile has been updated with the values chosen by Toolpack and the updated values can be retrieved using the functions '''GetLocalSDP()''' and '''GetPeerSDP()''' of the profile.
Note that the '''OnProfileChanged()''' event is also sent after the media profile has been modified with the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ChangeProfile '''ChangeProfile()'''] function (see [[#Modifying Media Profile|Modifying Media Profile]]) and when a connected peer has requested it (through a SIP re-INVITE for example).

See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.

=== Caveats ===
* The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).

== Interaction with Legs ==

=== Playing and Collecting Digits ===
You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play digits defined by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayDigit '''PlayDigit()'''] on a leg. Toolpack will receive the request and play the digits. Once digits are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitPlayingDone '''OnDigitPlayingDone()'''] event.

You can also configure a leg to collect digits played. To start the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartDigitCollection '''StartDigitCollection()'''] on the leg. Note that you will have to specify which digits you want to collect before starting the digit collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopDigitCollection '''StopDigitCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitCollected '''OnDigitCollected()'''] event on each digit received that correspond to a tone string specified with the previously call to '''AddToneString()'''.

=== Playing and Collecting Tones ===
You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play events by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayEvent '''PlayEvent()'''] on a leg. Toolpack will receive the request and play the events. Once events are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventPlayingDone '''OnEventPlayingDone()'''] event. Note that you can cancel an event to be played by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CancelEvent '''CancelEvent()'''] on the leg after a '''PlayEvent()''' has been called.

Two kinds of string can be passed to '''AddToneString()''' to play a tone. The first type is to play well known tones such as dtmf and fax tone. The syntax is really simple and is based on H248 package and signal ids. The first component of the string is the package id and the second is the signal id, both formated in string. So, to play dtmf 0, you have to format the following string: "dg/d0", where "dg" is for package "dtmf generation" and "d0" is for "dtmf 0".

The second type of string is to play custom tone. The syntax is much more complicated than the first one, but it follows a well described syntax which can be found in [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.6-200011-I!!PDF-E&type=items/.pdf '''H248.6 Dynamic Tone Definition Package''']. This kind of string allows you to specify frequencies, duration, amplitude and repeating count of the tone. You can also specify well known tones and change their default duration, amplitude and repeating count. It is possible to describe a sequence of tones or frequencies that are played in one segment. Here are some examples of the syntax:

*;Frequencies 400Hz and 600Hz mixed together for 200ms, amplitude at -10dB and repeating 3 times (playing 4 times):
:*(((#400)+(#600)),200,-10)*3
:
*;Dtmf 5 repeated infinitly:
:*((0x0005,0x0015))*0
:
*;Multifrequency tone 8:
:*((mfg,mf8))
:
*;Frequency 440Hz played for 300ms at -10dB followed by frequency 600Hz played for 200ms at -5dB and then followed by dtmf 2, all this repeated infinitly:
:*((#440,300,-10),(#600,200,-5),(0x0005,0x0012))*0
:

You can also configure a leg to collect events played. To start the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartEventCollection '''StartEventCollection()'''] on the leg. Note that you will have to specify which events you want to collect before starting the event collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopEventCollection '''StopEventCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventCollected '''OnEventCollected()'''] event on each event received that correspond to a tone string specified when calling '''StartEventCollection()'''.

Only one type of string is accepted to specify which events to collect. The string is the same as the first type to play event. Signal ids that are also event id are accepted. This means that you can ask to collect "dg/d0" (dtmf generation/dtmf 0) and the detection will be done anyway. But, when the event is detected, it's the event id that will be returned, which means that "dd/d0" (dtmf detection/dtmf 0) will be returned instead of "dg/d0". You can also detect all events from a package by putting a * as event id, so "dd/*" will detect all dtmf tones.

The most commonly used package are 5 and 6 [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.1-200509-I!!PDF-E&type=items/.pdf '''(H248.1 Annex E)''']: dtmf generation and dtmf detection. As H248 does not define events and signals for fax tone, we added a special package to do so. Package tbfax (0x0251) contains three events and two signals: cng (0x0080), g164 (0x0081) and only for detection g165 (0x0082).



=== Collecting digits and tones while call legs are joined ===
By default, when two call legs are joined together through function CTBCMCCallLeg::Join(), tone collection is automatically disabled.
One of the arguments of the Join() function ("in_fDisableToneWhileJoined") will allow to control if automatic tone collection feature is used or not on a call.

Why is Toolpack disabling tone collection on joined legs by default?
That's because tone collection introduces a 40ms delay in the audio connection (required to provide tone suppression), and most of the time it is no more require to collect digits while two call legs are joined, so it would be useless to leave 40ms delay while tone collection is no more required.

=== Playing and Recording Audio Files ===
You can play an audio stream on a leg by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayStream '''PlayStream()'''] on it. To specify which audio stream you want to play, you have to specify it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html#CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath '''AddPlayFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html CTBCMC_PLAY_ATTRIBUTE] class. Toolpack will receive the request and play the stream. Once it is played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingDone '''OnStreamPlayingDone()'''] event.

You can also configure a leg to record an audio stream. First you must specify file paths to record by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html#CTBCMC_RECORD_ATTRIBUTE::AddRecFilePath '''AddRecFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html CTBCMC_RECORD_ATTRIBUTE] class. The you can call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RecordStream '''RecordStream()'''] on a leg. Once the stream is recorded, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamRecordingDone '''OnStreamRecordingDone()'''] event.

You can pause an active playing or recording stream by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PauseStream '''PauseStream()'''] and you can resume it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ResumeStream '''ResumeStream()''']. If you want to stop an active playing or recording stream, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopStream '''StopStream()'''] on the leg.

=== Modifying Media Profile ===
It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.

The media profile is stored in the leg attributes and can be modified like this :
TBX_SDP_INFO SdpInfo;
PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;

pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
pMediaLegAttribute->GetProfile().GetLocalSDP(SdpInfo);
Strncpy
(
SdpInfo.aConnections[0].szIp,
"",
sizeof( SdpInfo.aConnections[0].szIp )
);
SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
pMediaLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

pCallLeg->ChangeProfile();

Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotiation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.

Once the profile change has completed (or failed), event '''OnProfileChanged()''' will be received on the leg.

For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.

=== Controlling the Signaling ===
When a call leg receives the '''OnCallLegPresent()''' event, it indicates an incoming call. To confirm that the call contains sufficient valid information to process the call on the system, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AcceptCall '''AcceptCall()'''] on the leg. If a call leg receives the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAccepted '''OnCallAccepted()'''] event, it means that an outgoing call has been accepted by the remote peer. This event usually means that the calling number has been accepted and that the call is currently being processed.

After an incoming call has been accepted, a call leg can notify the remote peer that the incoming call has been put in the "ringing" state by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AlertCall '''AlertCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAlerting '''OnCallAlerting()'''] event when an outgoing call has been put in the "ringing" state by the remote peer.

When an incoming call is answered, a call leg can notify the remote peer of the incoming call answered by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AnswerCall '''AnswerCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAnswered '''OnCallAnswered()'''] event when an outgoing call has been answered by the remote peer.

SendCallSuppInfo/OnCallSuppInfo

== Leg Termination ==

Terminating a call leg is a 2 steps process:
# Call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::TerminateCall '''TerminateCall()''']
# Free leg object on [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminated '''OnCallTerminated()''']

When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resources freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Free '''Free()'''] on the leg's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::SetFreeListener '''SetFreeListener()'''] on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is deleted. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.

[[Image:TerminateCall from application.jpg|thumb|center|350px|Call flow for leg termination initiated by user application]]

In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other media resource or signaling error. In these cases, the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminatingIndication '''OnCallTerminatingIndication()'''] is sent to the leg. On reception of this event, the application should initiate call termination as shown below.

[[Image:TerminateCall from Toolpack.jpg|thumb|center|350px|Call flow for leg termination initiated by Toolpack]]

In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnLegTerminated '''OnLegTerminated()'''] event. This event indicates that the leg does not exist anymore on the Toolpack side and the user should free its object without trying any other interaction with Toolpack through it.

== Leg Synchronization on Failover ==
When a Toolpack application is restarted or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs through the '''OnCallLegSync()''' event of the [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_lib_user.html ITBCMCLibUser] interface (this interface must be implemented by all user applications). One event will be received for each leg being synchronized. The course of action to take when receiving a leg synchronization event depends on the ability of the application to resynchronize its states with theses legs.

* If the application can't resynchronize active legs or if it does not want to resychronize the leg for which it is receiving an '''OnCallLegSync()''' event, it must refuse the leg by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLeg '''RefuseLeg()'''].
*If the application wants the resynchronize the leg or if it does not yet have enough information to decide, it must create a CTBCMCLeg object using the leg attributes received in the event.

Once all '''OnCallLegSync()''' have been sent, Toolpack will start synchronization of the links between legs through '''OnLinkSync()'''. This event indicates that two legs are connected together. It can be used by the application to rebuild its internal states. As for the legs, unwanted links can be refused by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()'''].

When all links have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. At that moment, the application has all the information available on the Toolpack side to determine if the legs should be kept or release. Any leg that the application does not want to keep can be refused by calling '''RefuseLeg()''' on it. For all legs that have not been refused, an event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnSyncDone '''OnSyncDone()'''] will be sent on the leg. Once this event has been received on a leg, the leg is fully functional and the application can start calling any usual Toolpack function on it.

[[Image:CallFlow Sync After Application Restart.jpg|thumb|center|350px|Call flow for leg synchronization]]

===Loss of Communication with Toolpack Engine===
If communication is lost with the Toolpack Engine, event '''OnCmcLibNotReady()''' will be sent to the application. It indicates that the Toolpack framework is no more accessible. The legs are still valid at that time but no action can be executed on them as long the CmcLib is not ready. If the connection with the Toolpack Engine is not back up in less than 10 seconds, the CmcLib will declare a major communication loss and will call '''OnLegTerminated()''' on all the legs. In that case, when communication is regained with the Toolpack Engine, the synchronization sequence will start again from the beginning.

[[Image:CallFlow Sync After Comm Restart Passed 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart passed 10 seconds.]]

If the communication is regained before the 10 seconds timeout, event '''OnCmcLibReady()''' will be sent and the application can then continue working normally with its existing call legs. Note that you can also receive '''OnLegTerminated()''' on some legs before receiving the '''OnCmcLibReady()''' if those legs were in a transient state when disconnection occurred.

[[Image:CallFlow Sync After Comm Restart Within 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart within 10 seconds.]]

== Bridging the Media Path ==
=== Join ===

To bridge the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Join '''Join()'''] on one of the leg, giving the second leg as a parameter. This will connect the media path between the two legs according to the link properties set on the leg on which '''Join()''' is called. These link properties can be modified by overloading the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetJoinAttributes '''GetJoinAttributes()''']. The important attribute to set is '''IsFullDuplex()''' that indicates if the connection will be made full-duplex (A<-->B) or half-duplex (A-->B). Prior to release 2.5.2, the default connection mode is half-duplex. For all release version 2.5.2 or higher, the default connection mode is full-duplex.

'''Warning:''' If two legs are already connected in half-duplex and you want to connect them in full-duplex, you must first Unjoin() the legs, then Join() them in full-duplex. You can '''NOT''' only do another half-duplex in the opposite direction.

When legs are joined, it creates a link identified with a unique ''link id''. It is the responsibility of the application to provide this unique ''link id'' by implementing the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetLinkId '''GetLinkId()'''] function of the leg. It is planned to allow the user to provide a value of '0' to let the Toolpack system automatically choose a ''link id'', but as of this writing this feature is not yet available.

'''Warning:''' When two legs are joined, the application must ensure that '''GetLinkId()''' on both leg will return the right ''link id''. This will ensure that when the link needs to be removed, both A->Unjoin() and B->Unjoin() will work correctly.

==== Setting the link properties ====

In your leg class, add a member variable to store the join attributes for that leg.

CTBCMC_JOIN_ATTRIBUTE mJoinAttribute;

Then set the join properties you want in your leg class constructor (or at any other location that will run '''before''' the '''Join()''' is done:

mJoinAttribute.IsFullDuplex() = TBX_TRUE;

Last, implement the '''GetJoinAttributes()''' function.

CTBCMC_JOIN_ATTRIBUTE & CH248Termination::GetJoinAttributes()
{
return mJoinAttribute;
}

==== Broadcasting a media source ====
At the time of writing this, broadcast of a single media source to multiple destinations is not yet possible.

=== Unjoin ===
To disconnect the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Unjoin'''Unjoin()'''] on any of the legs. The '''GetLinkId()''' function of the leg on which '''Unjoin()''' is called must return the ''link id'' that was used when the legs were joined.

[[category:CAF]]
[[category:Needs revising]]

CAF: Working With Call Legs

2010-02-09T21:21:47Z

Alexandre Lussier: /* Playing and Collecting Tones */

== Call Leg Definition ==
The main mechanism through which the customer application controls the [[Toolpack]] system is via the management of call legs. The application creates a call leg (or more than one for conferencing and bridging) at the beginning of a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.

A call leg is represented by an instance of the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html CTBCMCLeg] class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 [[timeslot]]) or a [[SIP]] call with its associated [[VOIP]] [[Voice codecs|codec]] resource (attached to an IP/UDP endpoint). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (VOIP codec resource attached to an IP/UDP endpoint). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.

The CTBCMCLeg class allows a programmer to easily act upon the call leg to influence the signaling portion (e.g. accept, answer, terminate, etc) and to use the media portion as well (e.g play prompts, record voice, play or collect digits and tones).

Other member functions are available to retrieve (and change in some cases) the call leg attributes including the media profile (e.g. parameters to the media resource) or signaling information (e.g. protocol type, called and calling party numbers, etc). Joining/unjoining (connection/disconnection) of call legs is also a typical action handled by this class for ’gateway-type’ applications. It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse a ''call leg'' with a ''call''. A ''call leg'' represents one full-duplex link to a party while a ''call'' represents the agglomeration of multiple (two or more) call legs. For example, a ''bridge'' is a form of ''call'' that uses two ''call legs''.
* Do not confuse the base class CTBCMCLeg with the class [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_leg.html CTBCAFCallLeg]. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs. It is designed to represent a leg within a call. It cannot be instanciated as a standalone object without modifications to make it independent from the ITBCAFCallFlow interface.
* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

== Command Flow for Leg Actions in CAF ==
All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).

For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.

== Leg Creation ==
Creating a leg is always done through the definition of a ''call leg attribute''. The values entered in the ''call leg attribute'' will define the type of call leg created and its parameters. The following sections describe several scenarios in which you build a ''call leg''. Instruction will be given on how to fill the leg attributes and how to use them to create the ''call leg''.

=== Preparing Leg Attributes ===

==== Normal Call Leg Attributes ====
For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
* the called number,
* the calling number,
* the [[NAP | Network Access Point]].

Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|NAP Types]]).

The following code snippet shows how to build the attributes.
PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();

ptrOutgoingLegAttribute->GetCalledNumber() = "123-4567";
ptrOutgoingLegAttribute->GetCallingNumber() = "987-6543";
ptrOutgoingLegAttribute->GetNetworkAccessPoint() = "NAP_SS7_MONTREAL";

==== Media-only Leg Attributes ====
For media-only legs, no signaling information is needed but the user can specify which media channel to use and which media profile to use. The only required parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''MEDIA TDM'' or ''MEDIA VOIP'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;

ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();

ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;

When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. For ''MEDIA TDM'' NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For ''MEDIA VOIP'' NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and a timeslot number can be specified.

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc->Settings.TdmAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
pMediaDesc->Settings.TdmAudio.un8Timeslot = 5;
Strncpy
(
pMediaDesc->Settings.TdmAudio.szTrunkName,
"TRUNK_TORONTO_1",
sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
);

For VOIP legs, the user can control the media by providing local [[SDP]] and peer SDP. Setting the local SDP defines the codec and IP/port used to for the received media stream. Most of the time, the IP address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and IP/port used for the transmitted media stream. Note that Toolpack only allows for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in '''both''' SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].

TBX_RESULT Result;
TBX_SDP_INFO SdpInfo;
PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();
pMediaDesc->Settings.PacketAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;

// Set Local SDP
Result = BuildSdpInfo("", 0, SdpInfo); // No IP specified, Toolpack will choose one
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

// Set Peer SDP
Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo); // Using peer IP address and port
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetPeerSDP(SdpInfo);

=== Creating the Leg ===
Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CreateCall '''CreateCall()'''] on it. No action is taken when an instance of a CTBCMCLeg is created. Call resources are only allocated in the Toolpack system when '''CreateCall()''' is called on the object.

pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
pCallLeg->CreateCall();

For legs with signaling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).

[[Image:CallFlow SignalingMediaLeg Creation.JPG|thumb|center|350px|Call flow for creation of leg with signaling]]

For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.

[[Image:CallFlow MediaOnlyLeg Creation.JPG|thumb|center|350px|Call flow for media-only leg creation]]

Once a call is fully active (call answered and media allocated), event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnProfileChanged '''OnProfileChanged()'''] will be sent on the leg. In the cases where the user had not specified the IP/port to use, once this event is received, the media profile has been updated with the values chosen by Toolpack and the updated values can be retrieved using the functions '''GetLocalSDP()''' and '''GetPeerSDP()''' of the profile.
Note that the '''OnProfileChanged()''' event is also sent after the media profile has been modified with the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ChangeProfile '''ChangeProfile()'''] function (see [[#Modifying Media Profile|Modifying Media Profile]]) and when a connected peer has requested it (through a SIP re-INVITE for example).

See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.

=== Caveats ===
* The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).

== Interaction with Legs ==

=== Playing and Collecting Digits ===
You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play digits defined by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayDigit '''PlayDigit()'''] on a leg. Toolpack will receive the request and play the digits. Once digits are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitPlayingDone '''OnDigitPlayingDone()'''] event.

You can also configure a leg to collect digits played. To start the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartDigitCollection '''StartDigitCollection()'''] on the leg. Note that you will have to specify which digits you want to collect before starting the digit collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopDigitCollection '''StopDigitCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitCollected '''OnDigitCollected()'''] event on each digit received that correspond to a tone string specified with the previously call to '''AddToneString()'''.

=== Playing and Collecting Tones ===
You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play events by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayEvent '''PlayEvent()'''] on a leg. Toolpack will receive the request and play the events. Once events are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventPlayingDone '''OnEventPlayingDone()'''] event. Note that you can cancel an event to be played by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CancelEvent '''CancelEvent()'''] on the leg after a '''PlayEvent()''' has been called.

Two kinds of string can be passed to '''AddToneString()''' to play a tone. The first type is to play well known tones such as dtmf and fax tone. The syntax is really simple and is based on H248 package and signal ids. The first component of the string is the package id and the second is the signal id, both formated in string. So, to play dtmf 0, you have to format the following string: "dg/d0", where "dg" is for package "dtmf generation" and "d0" is for "dtmf 0".

The second type of string is to play custom tone. The syntax is much more complicated than the first one, but it follows a well described syntax which can be found in [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.6-200011-I!!PDF-E&type=items/.pdf '''H248.6 Dynamic Tone Definition Package''']. This kind of string allows you to specify frequencies, duration, amplitude and repeating count of the tone. You can also specify well known tones and change their default duration, amplitude and repeating count. It is possible to describe a sequence of tones or frequencies that are played in one segment. Here are some examples of the syntax:

*;Frequencies 400Hz and 600Hz mixed together for 200ms, amplitude at -10dB and repeating 3 times (playing 4 times):
:*(((#400)+(#600)),200,-10)*3
:
*;Dtmf 5 repeated infinitly:
:*((0x0005,0x0015))*0
:
*;Multifrequency tone 8:
:*((mfg,mf8))
:
*;Frequency 440Hz played for 300ms at -10dB followed by frequency 600Hz played for 200ms at -5dB and then followed by dtmf 2, all this repeated infinitly:
:*((#440,300,-10),(#600,200,-5),(0x0005,0x0012))*0
:

You can also configure a leg to collect events played. To start the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartEventCollection '''StartEventCollection()'''] on the leg. Note that you will have to specify which events you want to collect before starting the event collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopEventCollection '''StopEventCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventCollected '''OnEventCollected()'''] event on each event received that correspond to a tone string specified when calling '''StartEventCollection()'''.

Only one type of string is accepted to specify which events to collect. The string is the same as the first type to play event. Signal ids that are also event id are accepted. This means that you can ask to collect "dg/d0" (dtmf generation/dtmf 0) and the detection will be done anyway. But, when the event is detected, it's the event id that will be returned, which means that "dd/d0" (dtmf detection/dtmf 0) will be returned instead of "dg/d0". You can also detect all events from a package by putting a * as event id, so "dd/*" will detect all dtmf tones.

The most commonly used package are 5 and 6 [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.1-200509-I!!PDF-E&type=items/.pdf '''(H248.1 Annex E)''']: dtmf generation and dtmf detection. As H248 does not define events and signals for fax tone, we added a special package to do so. Package tbfax (0x0251) contains three events and two signals: cng (0x0080), g164 (0x0081) and only for detection g165 (0x0082).

<code>test test</code>

=== Collecting digits and tones while call legs are joined ===
By default, when two call legs are joined together through function CTBCMCCallLeg::Join(), tone collection is automatically disabled.
One of the arguments of the Join() function ("in_fDisableToneWhileJoined") will allow to control if automatic tone collection feature is used or not on a call.

Why is Toolpack disabling tone collection on joined legs by default?
That's because tone collection introduces a 40ms delay in the audio connection (required to provide tone suppression), and most of the time it is no more require to collect digits while two call legs are joined, so it would be useless to leave 40ms delay while tone collection is no more required.

=== Playing and Recording Audio Files ===
You can play an audio stream on a leg by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayStream '''PlayStream()'''] on it. To specify which audio stream you want to play, you have to specify it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html#CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath '''AddPlayFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html CTBCMC_PLAY_ATTRIBUTE] class. Toolpack will receive the request and play the stream. Once it is played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingDone '''OnStreamPlayingDone()'''] event.

You can also configure a leg to record an audio stream. First you must specify file paths to record by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html#CTBCMC_RECORD_ATTRIBUTE::AddRecFilePath '''AddRecFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html CTBCMC_RECORD_ATTRIBUTE] class. The you can call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RecordStream '''RecordStream()'''] on a leg. Once the stream is recorded, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamRecordingDone '''OnStreamRecordingDone()'''] event.

You can pause an active playing or recording stream by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PauseStream '''PauseStream()'''] and you can resume it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ResumeStream '''ResumeStream()''']. If you want to stop an active playing or recording stream, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopStream '''StopStream()'''] on the leg.

=== Modifying Media Profile ===
It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.

The media profile is stored in the leg attributes and can be modified like this :
TBX_SDP_INFO SdpInfo;
PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;

pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
pMediaLegAttribute->GetProfile().GetLocalSDP(SdpInfo);
Strncpy
(
SdpInfo.aConnections[0].szIp,
"",
sizeof( SdpInfo.aConnections[0].szIp )
);
SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
pMediaLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

pCallLeg->ChangeProfile();

Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotiation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.

Once the profile change has completed (or failed), event '''OnProfileChanged()''' will be received on the leg.

For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.

=== Controlling the Signaling ===
When a call leg receives the '''OnCallLegPresent()''' event, it indicates an incoming call. To confirm that the call contains sufficient valid information to process the call on the system, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AcceptCall '''AcceptCall()'''] on the leg. If a call leg receives the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAccepted '''OnCallAccepted()'''] event, it means that an outgoing call has been accepted by the remote peer. This event usually means that the calling number has been accepted and that the call is currently being processed.

After an incoming call has been accepted, a call leg can notify the remote peer that the incoming call has been put in the "ringing" state by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AlertCall '''AlertCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAlerting '''OnCallAlerting()'''] event when an outgoing call has been put in the "ringing" state by the remote peer.

When an incoming call is answered, a call leg can notify the remote peer of the incoming call answered by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AnswerCall '''AnswerCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAnswered '''OnCallAnswered()'''] event when an outgoing call has been answered by the remote peer.

SendCallSuppInfo/OnCallSuppInfo

== Leg Termination ==

Terminating a call leg is a 2 steps process:
# Call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::TerminateCall '''TerminateCall()''']
# Free leg object on [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminated '''OnCallTerminated()''']

When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resources freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Free '''Free()'''] on the leg's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::SetFreeListener '''SetFreeListener()'''] on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is deleted. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.

[[Image:TerminateCall from application.jpg|thumb|center|350px|Call flow for leg termination initiated by user application]]

In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other media resource or signaling error. In these cases, the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminatingIndication '''OnCallTerminatingIndication()'''] is sent to the leg. On reception of this event, the application should initiate call termination as shown below.

[[Image:TerminateCall from Toolpack.jpg|thumb|center|350px|Call flow for leg termination initiated by Toolpack]]

In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnLegTerminated '''OnLegTerminated()'''] event. This event indicates that the leg does not exist anymore on the Toolpack side and the user should free its object without trying any other interaction with Toolpack through it.

== Leg Synchronization on Failover ==
When a Toolpack application is restarted or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs through the '''OnCallLegSync()''' event of the [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_lib_user.html ITBCMCLibUser] interface (this interface must be implemented by all user applications). One event will be received for each leg being synchronized. The course of action to take when receiving a leg synchronization event depends on the ability of the application to resynchronize its states with theses legs.

* If the application can't resynchronize active legs or if it does not want to resychronize the leg for which it is receiving an '''OnCallLegSync()''' event, it must refuse the leg by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLeg '''RefuseLeg()'''].
*If the application wants the resynchronize the leg or if it does not yet have enough information to decide, it must create a CTBCMCLeg object using the leg attributes received in the event.

Once all '''OnCallLegSync()''' have been sent, Toolpack will start synchronization of the links between legs through '''OnLinkSync()'''. This event indicates that two legs are connected together. It can be used by the application to rebuild its internal states. As for the legs, unwanted links can be refused by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()'''].

When all links have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. At that moment, the application has all the information available on the Toolpack side to determine if the legs should be kept or release. Any leg that the application does not want to keep can be refused by calling '''RefuseLeg()''' on it. For all legs that have not been refused, an event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnSyncDone '''OnSyncDone()'''] will be sent on the leg. Once this event has been received on a leg, the leg is fully functional and the application can start calling any usual Toolpack function on it.

[[Image:CallFlow Sync After Application Restart.jpg|thumb|center|350px|Call flow for leg synchronization]]

===Loss of Communication with Toolpack Engine===
If communication is lost with the Toolpack Engine, event '''OnCmcLibNotReady()''' will be sent to the application. It indicates that the Toolpack framework is no more accessible. The legs are still valid at that time but no action can be executed on them as long the CmcLib is not ready. If the connection with the Toolpack Engine is not back up in less than 10 seconds, the CmcLib will declare a major communication loss and will call '''OnLegTerminated()''' on all the legs. In that case, when communication is regained with the Toolpack Engine, the synchronization sequence will start again from the beginning.

[[Image:CallFlow Sync After Comm Restart Passed 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart passed 10 seconds.]]

If the communication is regained before the 10 seconds timeout, event '''OnCmcLibReady()''' will be sent and the application can then continue working normally with its existing call legs. Note that you can also receive '''OnLegTerminated()''' on some legs before receiving the '''OnCmcLibReady()''' if those legs were in a transient state when disconnection occurred.

[[Image:CallFlow Sync After Comm Restart Within 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart within 10 seconds.]]

== Bridging the Media Path ==
=== Join ===

To bridge the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Join '''Join()'''] on one of the leg, giving the second leg as a parameter. This will connect the media path between the two legs according to the link properties set on the leg on which '''Join()''' is called. These link properties can be modified by overloading the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetJoinAttributes '''GetJoinAttributes()''']. The important attribute to set is '''IsFullDuplex()''' that indicates if the connection will be made full-duplex (A<-->B) or half-duplex (A-->B). Prior to release 2.5.2, the default connection mode is half-duplex. For all release version 2.5.2 or higher, the default connection mode is full-duplex.

'''Warning:''' If two legs are already connected in half-duplex and you want to connect them in full-duplex, you must first Unjoin() the legs, then Join() them in full-duplex. You can '''NOT''' only do another half-duplex in the opposite direction.

When legs are joined, it creates a link identified with a unique ''link id''. It is the responsibility of the application to provide this unique ''link id'' by implementing the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetLinkId '''GetLinkId()'''] function of the leg. It is planned to allow the user to provide a value of '0' to let the Toolpack system automatically choose a ''link id'', but as of this writing this feature is not yet available.

'''Warning:''' When two legs are joined, the application must ensure that '''GetLinkId()''' on both leg will return the right ''link id''. This will ensure that when the link needs to be removed, both A->Unjoin() and B->Unjoin() will work correctly.

==== Setting the link properties ====

In your leg class, add a member variable to store the join attributes for that leg.

CTBCMC_JOIN_ATTRIBUTE mJoinAttribute;

Then set the join properties you want in your leg class constructor (or at any other location that will run '''before''' the '''Join()''' is done:

mJoinAttribute.IsFullDuplex() = TBX_TRUE;

Last, implement the '''GetJoinAttributes()''' function.

CTBCMC_JOIN_ATTRIBUTE & CH248Termination::GetJoinAttributes()
{
return mJoinAttribute;
}

==== Broadcasting a media source ====
At the time of writing this, broadcast of a single media source to multiple destinations is not yet possible.

=== Unjoin ===
To disconnect the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Unjoin'''Unjoin()'''] on any of the legs. The '''GetLinkId()''' function of the leg on which '''Unjoin()''' is called must return the ''link id'' that was used when the legs were joined.

[[category:CAF]]
[[category:Needs revising]]

CAF: Working With Call Legs

2010-02-09T21:16:11Z

Alexandre Lussier: /* Playing and Collecting Tones */

== Call Leg Definition ==
The main mechanism through which the customer application controls the [[Toolpack]] system is via the management of call legs. The application creates a call leg (or more than one for conferencing and bridging) at the beginning of a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.

A call leg is represented by an instance of the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html CTBCMCLeg] class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 [[timeslot]]) or a [[SIP]] call with its associated [[VOIP]] [[Voice codecs|codec]] resource (attached to an IP/UDP endpoint). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (VOIP codec resource attached to an IP/UDP endpoint). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.

The CTBCMCLeg class allows a programmer to easily act upon the call leg to influence the signaling portion (e.g. accept, answer, terminate, etc) and to use the media portion as well (e.g play prompts, record voice, play or collect digits and tones).

Other member functions are available to retrieve (and change in some cases) the call leg attributes including the media profile (e.g. parameters to the media resource) or signaling information (e.g. protocol type, called and calling party numbers, etc). Joining/unjoining (connection/disconnection) of call legs is also a typical action handled by this class for ’gateway-type’ applications. It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse a ''call leg'' with a ''call''. A ''call leg'' represents one full-duplex link to a party while a ''call'' represents the agglomeration of multiple (two or more) call legs. For example, a ''bridge'' is a form of ''call'' that uses two ''call legs''.
* Do not confuse the base class CTBCMCLeg with the class [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_leg.html CTBCAFCallLeg]. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs. It is designed to represent a leg within a call. It cannot be instanciated as a standalone object without modifications to make it independent from the ITBCAFCallFlow interface.
* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

== Command Flow for Leg Actions in CAF ==
All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).

For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.

== Leg Creation ==
Creating a leg is always done through the definition of a ''call leg attribute''. The values entered in the ''call leg attribute'' will define the type of call leg created and its parameters. The following sections describe several scenarios in which you build a ''call leg''. Instruction will be given on how to fill the leg attributes and how to use them to create the ''call leg''.

=== Preparing Leg Attributes ===

==== Normal Call Leg Attributes ====
For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
* the called number,
* the calling number,
* the [[NAP | Network Access Point]].

Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|NAP Types]]).

The following code snippet shows how to build the attributes.
PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();

ptrOutgoingLegAttribute->GetCalledNumber() = "123-4567";
ptrOutgoingLegAttribute->GetCallingNumber() = "987-6543";
ptrOutgoingLegAttribute->GetNetworkAccessPoint() = "NAP_SS7_MONTREAL";

==== Media-only Leg Attributes ====
For media-only legs, no signaling information is needed but the user can specify which media channel to use and which media profile to use. The only required parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''MEDIA TDM'' or ''MEDIA VOIP'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;

ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();

ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;

When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. For ''MEDIA TDM'' NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For ''MEDIA VOIP'' NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and a timeslot number can be specified.

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc->Settings.TdmAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
pMediaDesc->Settings.TdmAudio.un8Timeslot = 5;
Strncpy
(
pMediaDesc->Settings.TdmAudio.szTrunkName,
"TRUNK_TORONTO_1",
sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
);

For VOIP legs, the user can control the media by providing local [[SDP]] and peer SDP. Setting the local SDP defines the codec and IP/port used to for the received media stream. Most of the time, the IP address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and IP/port used for the transmitted media stream. Note that Toolpack only allows for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in '''both''' SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].

TBX_RESULT Result;
TBX_SDP_INFO SdpInfo;
PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();
pMediaDesc->Settings.PacketAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;

// Set Local SDP
Result = BuildSdpInfo("", 0, SdpInfo); // No IP specified, Toolpack will choose one
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

// Set Peer SDP
Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo); // Using peer IP address and port
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetPeerSDP(SdpInfo);

=== Creating the Leg ===
Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CreateCall '''CreateCall()'''] on it. No action is taken when an instance of a CTBCMCLeg is created. Call resources are only allocated in the Toolpack system when '''CreateCall()''' is called on the object.

pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
pCallLeg->CreateCall();

For legs with signaling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).

[[Image:CallFlow SignalingMediaLeg Creation.JPG|thumb|center|350px|Call flow for creation of leg with signaling]]

For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.

[[Image:CallFlow MediaOnlyLeg Creation.JPG|thumb|center|350px|Call flow for media-only leg creation]]

Once a call is fully active (call answered and media allocated), event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnProfileChanged '''OnProfileChanged()'''] will be sent on the leg. In the cases where the user had not specified the IP/port to use, once this event is received, the media profile has been updated with the values chosen by Toolpack and the updated values can be retrieved using the functions '''GetLocalSDP()''' and '''GetPeerSDP()''' of the profile.
Note that the '''OnProfileChanged()''' event is also sent after the media profile has been modified with the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ChangeProfile '''ChangeProfile()'''] function (see [[#Modifying Media Profile|Modifying Media Profile]]) and when a connected peer has requested it (through a SIP re-INVITE for example).

See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.

=== Caveats ===
* The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).

== Interaction with Legs ==

=== Playing and Collecting Digits ===
You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play digits defined by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayDigit '''PlayDigit()'''] on a leg. Toolpack will receive the request and play the digits. Once digits are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitPlayingDone '''OnDigitPlayingDone()'''] event.

You can also configure a leg to collect digits played. To start the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartDigitCollection '''StartDigitCollection()'''] on the leg. Note that you will have to specify which digits you want to collect before starting the digit collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopDigitCollection '''StopDigitCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitCollected '''OnDigitCollected()'''] event on each digit received that correspond to a tone string specified with the previously call to '''AddToneString()'''.

=== Playing and Collecting Tones ===
You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play events by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayEvent '''PlayEvent()'''] on a leg. Toolpack will receive the request and play the events. Once events are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventPlayingDone '''OnEventPlayingDone()'''] event. Note that you can cancel an event to be played by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CancelEvent '''CancelEvent()'''] on the leg after a '''PlayEvent()''' has been called.

Two kinds of string can be passed to '''AddToneString()''' to play a tone. The first type is to play well known tones such as dtmf and fax tone. The syntax is really simple and is based on H248 package and signal ids. The first component of the string is the package id and the second is the signal id, both formated in string. So, to play dtmf 0, you have to format the following string: "dg/d0", where "dg" is for package "dtmf generation" and "d0" is for "dtmf 0".

The second type of string is to play custom tone. The syntax is much more complicated than the first one, but it follows a well described syntax which can be found in [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.6-200011-I!!PDF-E&type=items/.pdf '''H248.6 Dynamic Tone Definition Package''']. This kind of string allows you to specify frequencies, duration, amplitude and repeating count of the tone. You can also specify well known tones and change their default duration, amplitude and repeating count. It is possible to describe a sequence of tones or frequencies that are played in one segment. Here are some examples of the syntax:

*;Frequencies 400Hz and 600Hz mixed together for 200ms, amplitude at -10dB and repeating 3 times (playing 4 times):
:*(((#400)+(#600)),200,-10)*3
:
*;Dtmf 5 repeated infinitly:
:*((0x0005,0x0015))*0
:
*;Multifrequency tone 8:
:*((mfg,mf8))
:
*;Frequency 440Hz played for 300ms at -10dB followed by frequency 600Hz played for 200ms at -5dB and then followed by dtmf 2, all this repeated infinitly:
:*((#440,300,-10),(#600,200,-5),(0x0005,0x0012))*0
:

You can also configure a leg to collect events played. To start the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartEventCollection '''StartEventCollection()'''] on the leg. Note that you will have to specify which events you want to collect before starting the event collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopEventCollection '''StopEventCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventCollected '''OnEventCollected()'''] event on each event received that correspond to a tone string specified with the previously call to '''AddToneString()'''.

Only one string is accepted to collect events. The string is the same as the first type to play event. Signal ids that are also event id are accepted. This means that you can ask to collect "dg/d0" (dtmf generation/dtmf 0) and the detection will be done anyway. But, when the event is detected, it's the event id that will be returned, which means that "dd/d0" (dtmf detection/dtmf 0) will be returned instead of "dg/d0". You can also detect all events from a package by putting a * as event id, so "dd/*" will detect all dtmf tones.

The most commonly used package are 5 and 6 [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.1-200509-I!!PDF-E&type=items/.pdf '''(H248.1 Annex E)''']: dtmf generation and dtmf detection. As H248 does not define events and signals for fax tone, we added a special package to do so. Package tbfax (0x0251) contains three events and two signals: cng (0x0080), g164 (0x0081) and only for detection g165 (0x0082).

=== Collecting digits and tones while call legs are joined ===
By default, when two call legs are joined together through function CTBCMCCallLeg::Join(), tone collection is automatically disabled.
One of the arguments of the Join() function ("in_fDisableToneWhileJoined") will allow to control if automatic tone collection feature is used or not on a call.

Why is Toolpack disabling tone collection on joined legs by default?
That's because tone collection introduces a 40ms delay in the audio connection (required to provide tone suppression), and most of the time it is no more require to collect digits while two call legs are joined, so it would be useless to leave 40ms delay while tone collection is no more required.

=== Playing and Recording Audio Files ===
You can play an audio stream on a leg by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayStream '''PlayStream()'''] on it. To specify which audio stream you want to play, you have to specify it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html#CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath '''AddPlayFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html CTBCMC_PLAY_ATTRIBUTE] class. Toolpack will receive the request and play the stream. Once it is played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingDone '''OnStreamPlayingDone()'''] event.

You can also configure a leg to record an audio stream. First you must specify file paths to record by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html#CTBCMC_RECORD_ATTRIBUTE::AddRecFilePath '''AddRecFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html CTBCMC_RECORD_ATTRIBUTE] class. The you can call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RecordStream '''RecordStream()'''] on a leg. Once the stream is recorded, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamRecordingDone '''OnStreamRecordingDone()'''] event.

You can pause an active playing or recording stream by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PauseStream '''PauseStream()'''] and you can resume it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ResumeStream '''ResumeStream()''']. If you want to stop an active playing or recording stream, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopStream '''StopStream()'''] on the leg.

=== Modifying Media Profile ===
It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.

The media profile is stored in the leg attributes and can be modified like this :
TBX_SDP_INFO SdpInfo;
PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;

pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
pMediaLegAttribute->GetProfile().GetLocalSDP(SdpInfo);
Strncpy
(
SdpInfo.aConnections[0].szIp,
"",
sizeof( SdpInfo.aConnections[0].szIp )
);
SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
pMediaLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

pCallLeg->ChangeProfile();

Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotiation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.

Once the profile change has completed (or failed), event '''OnProfileChanged()''' will be received on the leg.

For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.

=== Controlling the Signaling ===
When a call leg receives the '''OnCallLegPresent()''' event, it indicates an incoming call. To confirm that the call contains sufficient valid information to process the call on the system, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AcceptCall '''AcceptCall()'''] on the leg. If a call leg receives the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAccepted '''OnCallAccepted()'''] event, it means that an outgoing call has been accepted by the remote peer. This event usually means that the calling number has been accepted and that the call is currently being processed.

After an incoming call has been accepted, a call leg can notify the remote peer that the incoming call has been put in the "ringing" state by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AlertCall '''AlertCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAlerting '''OnCallAlerting()'''] event when an outgoing call has been put in the "ringing" state by the remote peer.

When an incoming call is answered, a call leg can notify the remote peer of the incoming call answered by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AnswerCall '''AnswerCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAnswered '''OnCallAnswered()'''] event when an outgoing call has been answered by the remote peer.

SendCallSuppInfo/OnCallSuppInfo

== Leg Termination ==

Terminating a call leg is a 2 steps process:
# Call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::TerminateCall '''TerminateCall()''']
# Free leg object on [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminated '''OnCallTerminated()''']

When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resources freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Free '''Free()'''] on the leg's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::SetFreeListener '''SetFreeListener()'''] on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is deleted. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.

[[Image:TerminateCall from application.jpg|thumb|center|350px|Call flow for leg termination initiated by user application]]

In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other media resource or signaling error. In these cases, the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminatingIndication '''OnCallTerminatingIndication()'''] is sent to the leg. On reception of this event, the application should initiate call termination as shown below.

[[Image:TerminateCall from Toolpack.jpg|thumb|center|350px|Call flow for leg termination initiated by Toolpack]]

In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnLegTerminated '''OnLegTerminated()'''] event. This event indicates that the leg does not exist anymore on the Toolpack side and the user should free its object without trying any other interaction with Toolpack through it.

== Leg Synchronization on Failover ==
When a Toolpack application is restarted or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs through the '''OnCallLegSync()''' event of the [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_lib_user.html ITBCMCLibUser] interface (this interface must be implemented by all user applications). One event will be received for each leg being synchronized. The course of action to take when receiving a leg synchronization event depends on the ability of the application to resynchronize its states with theses legs.

* If the application can't resynchronize active legs or if it does not want to resychronize the leg for which it is receiving an '''OnCallLegSync()''' event, it must refuse the leg by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLeg '''RefuseLeg()'''].
*If the application wants the resynchronize the leg or if it does not yet have enough information to decide, it must create a CTBCMCLeg object using the leg attributes received in the event.

Once all '''OnCallLegSync()''' have been sent, Toolpack will start synchronization of the links between legs through '''OnLinkSync()'''. This event indicates that two legs are connected together. It can be used by the application to rebuild its internal states. As for the legs, unwanted links can be refused by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()'''].

When all links have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. At that moment, the application has all the information available on the Toolpack side to determine if the legs should be kept or release. Any leg that the application does not want to keep can be refused by calling '''RefuseLeg()''' on it. For all legs that have not been refused, an event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnSyncDone '''OnSyncDone()'''] will be sent on the leg. Once this event has been received on a leg, the leg is fully functional and the application can start calling any usual Toolpack function on it.

[[Image:CallFlow Sync After Application Restart.jpg|thumb|center|350px|Call flow for leg synchronization]]

===Loss of Communication with Toolpack Engine===
If communication is lost with the Toolpack Engine, event '''OnCmcLibNotReady()''' will be sent to the application. It indicates that the Toolpack framework is no more accessible. The legs are still valid at that time but no action can be executed on them as long the CmcLib is not ready. If the connection with the Toolpack Engine is not back up in less than 10 seconds, the CmcLib will declare a major communication loss and will call '''OnLegTerminated()''' on all the legs. In that case, when communication is regained with the Toolpack Engine, the synchronization sequence will start again from the beginning.

[[Image:CallFlow Sync After Comm Restart Passed 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart passed 10 seconds.]]

If the communication is regained before the 10 seconds timeout, event '''OnCmcLibReady()''' will be sent and the application can then continue working normally with its existing call legs. Note that you can also receive '''OnLegTerminated()''' on some legs before receiving the '''OnCmcLibReady()''' if those legs were in a transient state when disconnection occurred.

[[Image:CallFlow Sync After Comm Restart Within 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart within 10 seconds.]]

== Bridging the Media Path ==
=== Join ===

To bridge the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Join '''Join()'''] on one of the leg, giving the second leg as a parameter. This will connect the media path between the two legs according to the link properties set on the leg on which '''Join()''' is called. These link properties can be modified by overloading the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetJoinAttributes '''GetJoinAttributes()''']. The important attribute to set is '''IsFullDuplex()''' that indicates if the connection will be made full-duplex (A<-->B) or half-duplex (A-->B). Prior to release 2.5.2, the default connection mode is half-duplex. For all release version 2.5.2 or higher, the default connection mode is full-duplex.

'''Warning:''' If two legs are already connected in half-duplex and you want to connect them in full-duplex, you must first Unjoin() the legs, then Join() them in full-duplex. You can '''NOT''' only do another half-duplex in the opposite direction.

When legs are joined, it creates a link identified with a unique ''link id''. It is the responsibility of the application to provide this unique ''link id'' by implementing the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetLinkId '''GetLinkId()'''] function of the leg. It is planned to allow the user to provide a value of '0' to let the Toolpack system automatically choose a ''link id'', but as of this writing this feature is not yet available.

'''Warning:''' When two legs are joined, the application must ensure that '''GetLinkId()''' on both leg will return the right ''link id''. This will ensure that when the link needs to be removed, both A->Unjoin() and B->Unjoin() will work correctly.

==== Setting the link properties ====

In your leg class, add a member variable to store the join attributes for that leg.

CTBCMC_JOIN_ATTRIBUTE mJoinAttribute;

Then set the join properties you want in your leg class constructor (or at any other location that will run '''before''' the '''Join()''' is done:

mJoinAttribute.IsFullDuplex() = TBX_TRUE;

Last, implement the '''GetJoinAttributes()''' function.

CTBCMC_JOIN_ATTRIBUTE & CH248Termination::GetJoinAttributes()
{
return mJoinAttribute;
}

==== Broadcasting a media source ====
At the time of writing this, broadcast of a single media source to multiple destinations is not yet possible.

=== Unjoin ===
To disconnect the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Unjoin'''Unjoin()'''] on any of the legs. The '''GetLinkId()''' function of the leg on which '''Unjoin()''' is called must return the ''link id'' that was used when the legs were joined.

[[category:CAF]]
[[category:Needs revising]]

CAF: Working With Call Legs

2010-02-09T21:13:24Z

Alexandre Lussier: /* Playing and Collecting Tones */

== Call Leg Definition ==
The main mechanism through which the customer application controls the [[Toolpack]] system is via the management of call legs. The application creates a call leg (or more than one for conferencing and bridging) at the beginning of a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.

A call leg is represented by an instance of the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html CTBCMCLeg] class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 [[timeslot]]) or a [[SIP]] call with its associated [[VOIP]] [[Voice codecs|codec]] resource (attached to an IP/UDP endpoint). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (VOIP codec resource attached to an IP/UDP endpoint). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.

The CTBCMCLeg class allows a programmer to easily act upon the call leg to influence the signaling portion (e.g. accept, answer, terminate, etc) and to use the media portion as well (e.g play prompts, record voice, play or collect digits and tones).

Other member functions are available to retrieve (and change in some cases) the call leg attributes including the media profile (e.g. parameters to the media resource) or signaling information (e.g. protocol type, called and calling party numbers, etc). Joining/unjoining (connection/disconnection) of call legs is also a typical action handled by this class for ’gateway-type’ applications. It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse a ''call leg'' with a ''call''. A ''call leg'' represents one full-duplex link to a party while a ''call'' represents the agglomeration of multiple (two or more) call legs. For example, a ''bridge'' is a form of ''call'' that uses two ''call legs''.
* Do not confuse the base class CTBCMCLeg with the class [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_leg.html CTBCAFCallLeg]. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs. It is designed to represent a leg within a call. It cannot be instanciated as a standalone object without modifications to make it independent from the ITBCAFCallFlow interface.
* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

== Command Flow for Leg Actions in CAF ==
All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).

For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.

== Leg Creation ==
Creating a leg is always done through the definition of a ''call leg attribute''. The values entered in the ''call leg attribute'' will define the type of call leg created and its parameters. The following sections describe several scenarios in which you build a ''call leg''. Instruction will be given on how to fill the leg attributes and how to use them to create the ''call leg''.

=== Preparing Leg Attributes ===

==== Normal Call Leg Attributes ====
For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
* the called number,
* the calling number,
* the [[NAP | Network Access Point]].

Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|NAP Types]]).

The following code snippet shows how to build the attributes.
PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();

ptrOutgoingLegAttribute->GetCalledNumber() = "123-4567";
ptrOutgoingLegAttribute->GetCallingNumber() = "987-6543";
ptrOutgoingLegAttribute->GetNetworkAccessPoint() = "NAP_SS7_MONTREAL";

==== Media-only Leg Attributes ====
For media-only legs, no signaling information is needed but the user can specify which media channel to use and which media profile to use. The only required parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''MEDIA TDM'' or ''MEDIA VOIP'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;

ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();

ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;

When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. For ''MEDIA TDM'' NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For ''MEDIA VOIP'' NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and a timeslot number can be specified.

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc->Settings.TdmAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
pMediaDesc->Settings.TdmAudio.un8Timeslot = 5;
Strncpy
(
pMediaDesc->Settings.TdmAudio.szTrunkName,
"TRUNK_TORONTO_1",
sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
);

For VOIP legs, the user can control the media by providing local [[SDP]] and peer SDP. Setting the local SDP defines the codec and IP/port used to for the received media stream. Most of the time, the IP address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and IP/port used for the transmitted media stream. Note that Toolpack only allows for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in '''both''' SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].

TBX_RESULT Result;
TBX_SDP_INFO SdpInfo;
PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();
pMediaDesc->Settings.PacketAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;

// Set Local SDP
Result = BuildSdpInfo("", 0, SdpInfo); // No IP specified, Toolpack will choose one
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

// Set Peer SDP
Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo); // Using peer IP address and port
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetPeerSDP(SdpInfo);

=== Creating the Leg ===
Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CreateCall '''CreateCall()'''] on it. No action is taken when an instance of a CTBCMCLeg is created. Call resources are only allocated in the Toolpack system when '''CreateCall()''' is called on the object.

pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
pCallLeg->CreateCall();

For legs with signaling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).

[[Image:CallFlow SignalingMediaLeg Creation.JPG|thumb|center|350px|Call flow for creation of leg with signaling]]

For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.

[[Image:CallFlow MediaOnlyLeg Creation.JPG|thumb|center|350px|Call flow for media-only leg creation]]

Once a call is fully active (call answered and media allocated), event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnProfileChanged '''OnProfileChanged()'''] will be sent on the leg. In the cases where the user had not specified the IP/port to use, once this event is received, the media profile has been updated with the values chosen by Toolpack and the updated values can be retrieved using the functions '''GetLocalSDP()''' and '''GetPeerSDP()''' of the profile.
Note that the '''OnProfileChanged()''' event is also sent after the media profile has been modified with the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ChangeProfile '''ChangeProfile()'''] function (see [[#Modifying Media Profile|Modifying Media Profile]]) and when a connected peer has requested it (through a SIP re-INVITE for example).

See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.

=== Caveats ===
* The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).

== Interaction with Legs ==

=== Playing and Collecting Digits ===
You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play digits defined by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayDigit '''PlayDigit()'''] on a leg. Toolpack will receive the request and play the digits. Once digits are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitPlayingDone '''OnDigitPlayingDone()'''] event.

You can also configure a leg to collect digits played. To start the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartDigitCollection '''StartDigitCollection()'''] on the leg. Note that you will have to specify which digits you want to collect before starting the digit collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopDigitCollection '''StopDigitCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitCollected '''OnDigitCollected()'''] event on each digit received that correspond to a tone string specified with the previously call to '''AddToneString()'''.

=== Playing and Collecting Tones ===
You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play events by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayEvent '''PlayEvent()'''] on a leg. Toolpack will receive the request and play the events. Once events are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventPlayingDone '''OnEventPlayingDone()'''] event. Note that you can cancel an event to be played by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CancelEvent '''CancelEvent()'''] on the leg after a '''PlayEvent()''' has been called.

Two kinds of string can be passed to '''AddToneString()''' to play a tone. The first type is to play well known tones such as dtmf and fax tone. The syntax is really simple and is based on H248 package and signal ids. The first component of the string is the package id and the second is the signal id, both formated in string. So, to play dtmf 0, you have to format the following string: "dg/d0", where "dg" is for package "dtmf generation" and "d0" is for "dtmf 0".

The second type of string is to play custom tone. The syntax is much complicated than the first one, but it follows a well described syntax which can be found in [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.6-200011-I!!PDF-E&type=items/.pdf '''H248.6 Dynamic Tone Definition Package''']. This kind of string allows you to specify frequencies, duration, amplitude and repeating count of the tone. You can also specify well known tones and change their default duration, amplitude and repeating count. It is possible to describe a sequence of tones or frequencies that are played in one segment. Here are some examples of the syntax:

*;Frequencies 400Hz and 600Hz mixed together for 200ms, amplitude at -10dB and repeating 3 times (playing 4 times):
:*(((#400)+(#600)),200,-10)*3
:
*;Dtmf 5 repeated infinitly:
:*((0x0005,0x0015))*0
:
*;Multifrequency tone 8:
:*((mfg,mf8))
:
*;Frequency 440Hz played for 300ms at -10dB followed by frequency 600Hz played for 200ms at -5dB and then followed by dtmf 2, all this repeated infinitly:
:*((#440,300,-10),(#600,200,-5),(0x0005,0x0012))*0
:

You can also configure a leg to collect events played. To start the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartEventCollection '''StartEventCollection()'''] on the leg. Note that you will have to specify which events you want to collect before starting the event collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopEventCollection '''StopEventCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventCollected '''OnEventCollected()'''] event on each event received that correspond to a tone string specified with the previously call to '''AddToneString()'''.

Only one string is accepted to collect events. The string is the same as the first type to play event. Signal ids that are also event id are accepted. This means that you can ask to collect "dg/d0" (dtmf generation/dtmf 0) and the detection will be done anyway. But, when the event is detected, it's the event id that will be returned, which means that "dd/d0" (dtmf detection/dtmf 0) will be returned instead of "dg/d0". You can also detect all events from a package by putting a * as event id, so "dd/*" will detect all dtmf tones.

The most commonly used package are 5 and 6 [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.1-200509-I!!PDF-E&type=items/.pdf '''(H248.1 Annex E)''']: dtmf generation and dtmf detection. As H248 does not define events and signals for fax tone, we added a special package to do so. Package tbfax (0x0251) contains three events and two signals: cng (0x0080), g164 (0x0081) and only for detection g165 (0x0082).

=== Collecting digits and tones while call legs are joined ===
By default, when two call legs are joined together through function CTBCMCCallLeg::Join(), tone collection is automatically disabled.
One of the arguments of the Join() function ("in_fDisableToneWhileJoined") will allow to control if automatic tone collection feature is used or not on a call.

Why is Toolpack disabling tone collection on joined legs by default?
That's because tone collection introduces a 40ms delay in the audio connection (required to provide tone suppression), and most of the time it is no more require to collect digits while two call legs are joined, so it would be useless to leave 40ms delay while tone collection is no more required.

=== Playing and Recording Audio Files ===
You can play an audio stream on a leg by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayStream '''PlayStream()'''] on it. To specify which audio stream you want to play, you have to specify it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html#CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath '''AddPlayFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html CTBCMC_PLAY_ATTRIBUTE] class. Toolpack will receive the request and play the stream. Once it is played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingDone '''OnStreamPlayingDone()'''] event.

You can also configure a leg to record an audio stream. First you must specify file paths to record by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html#CTBCMC_RECORD_ATTRIBUTE::AddRecFilePath '''AddRecFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html CTBCMC_RECORD_ATTRIBUTE] class. The you can call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RecordStream '''RecordStream()'''] on a leg. Once the stream is recorded, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamRecordingDone '''OnStreamRecordingDone()'''] event.

You can pause an active playing or recording stream by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PauseStream '''PauseStream()'''] and you can resume it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ResumeStream '''ResumeStream()''']. If you want to stop an active playing or recording stream, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopStream '''StopStream()'''] on the leg.

=== Modifying Media Profile ===
It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.

The media profile is stored in the leg attributes and can be modified like this :
TBX_SDP_INFO SdpInfo;
PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;

pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
pMediaLegAttribute->GetProfile().GetLocalSDP(SdpInfo);
Strncpy
(
SdpInfo.aConnections[0].szIp,
"",
sizeof( SdpInfo.aConnections[0].szIp )
);
SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
pMediaLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

pCallLeg->ChangeProfile();

Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotiation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.

Once the profile change has completed (or failed), event '''OnProfileChanged()''' will be received on the leg.

For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.

=== Controlling the Signaling ===
When a call leg receives the '''OnCallLegPresent()''' event, it indicates an incoming call. To confirm that the call contains sufficient valid information to process the call on the system, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AcceptCall '''AcceptCall()'''] on the leg. If a call leg receives the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAccepted '''OnCallAccepted()'''] event, it means that an outgoing call has been accepted by the remote peer. This event usually means that the calling number has been accepted and that the call is currently being processed.

After an incoming call has been accepted, a call leg can notify the remote peer that the incoming call has been put in the "ringing" state by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AlertCall '''AlertCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAlerting '''OnCallAlerting()'''] event when an outgoing call has been put in the "ringing" state by the remote peer.

When an incoming call is answered, a call leg can notify the remote peer of the incoming call answered by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AnswerCall '''AnswerCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAnswered '''OnCallAnswered()'''] event when an outgoing call has been answered by the remote peer.

SendCallSuppInfo/OnCallSuppInfo

== Leg Termination ==

Terminating a call leg is a 2 steps process:
# Call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::TerminateCall '''TerminateCall()''']
# Free leg object on [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminated '''OnCallTerminated()''']

When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resources freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Free '''Free()'''] on the leg's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::SetFreeListener '''SetFreeListener()'''] on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is deleted. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.

[[Image:TerminateCall from application.jpg|thumb|center|350px|Call flow for leg termination initiated by user application]]

In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other media resource or signaling error. In these cases, the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminatingIndication '''OnCallTerminatingIndication()'''] is sent to the leg. On reception of this event, the application should initiate call termination as shown below.

[[Image:TerminateCall from Toolpack.jpg|thumb|center|350px|Call flow for leg termination initiated by Toolpack]]

In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnLegTerminated '''OnLegTerminated()'''] event. This event indicates that the leg does not exist anymore on the Toolpack side and the user should free its object without trying any other interaction with Toolpack through it.

== Leg Synchronization on Failover ==
When a Toolpack application is restarted or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs through the '''OnCallLegSync()''' event of the [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_lib_user.html ITBCMCLibUser] interface (this interface must be implemented by all user applications). One event will be received for each leg being synchronized. The course of action to take when receiving a leg synchronization event depends on the ability of the application to resynchronize its states with theses legs.

* If the application can't resynchronize active legs or if it does not want to resychronize the leg for which it is receiving an '''OnCallLegSync()''' event, it must refuse the leg by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLeg '''RefuseLeg()'''].
*If the application wants the resynchronize the leg or if it does not yet have enough information to decide, it must create a CTBCMCLeg object using the leg attributes received in the event.

Once all '''OnCallLegSync()''' have been sent, Toolpack will start synchronization of the links between legs through '''OnLinkSync()'''. This event indicates that two legs are connected together. It can be used by the application to rebuild its internal states. As for the legs, unwanted links can be refused by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()'''].

When all links have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. At that moment, the application has all the information available on the Toolpack side to determine if the legs should be kept or release. Any leg that the application does not want to keep can be refused by calling '''RefuseLeg()''' on it. For all legs that have not been refused, an event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnSyncDone '''OnSyncDone()'''] will be sent on the leg. Once this event has been received on a leg, the leg is fully functional and the application can start calling any usual Toolpack function on it.

[[Image:CallFlow Sync After Application Restart.jpg|thumb|center|350px|Call flow for leg synchronization]]

===Loss of Communication with Toolpack Engine===
If communication is lost with the Toolpack Engine, event '''OnCmcLibNotReady()''' will be sent to the application. It indicates that the Toolpack framework is no more accessible. The legs are still valid at that time but no action can be executed on them as long the CmcLib is not ready. If the connection with the Toolpack Engine is not back up in less than 10 seconds, the CmcLib will declare a major communication loss and will call '''OnLegTerminated()''' on all the legs. In that case, when communication is regained with the Toolpack Engine, the synchronization sequence will start again from the beginning.

[[Image:CallFlow Sync After Comm Restart Passed 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart passed 10 seconds.]]

If the communication is regained before the 10 seconds timeout, event '''OnCmcLibReady()''' will be sent and the application can then continue working normally with its existing call legs. Note that you can also receive '''OnLegTerminated()''' on some legs before receiving the '''OnCmcLibReady()''' if those legs were in a transient state when disconnection occurred.

[[Image:CallFlow Sync After Comm Restart Within 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart within 10 seconds.]]

== Bridging the Media Path ==
=== Join ===

To bridge the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Join '''Join()'''] on one of the leg, giving the second leg as a parameter. This will connect the media path between the two legs according to the link properties set on the leg on which '''Join()''' is called. These link properties can be modified by overloading the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetJoinAttributes '''GetJoinAttributes()''']. The important attribute to set is '''IsFullDuplex()''' that indicates if the connection will be made full-duplex (A<-->B) or half-duplex (A-->B). Prior to release 2.5.2, the default connection mode is half-duplex. For all release version 2.5.2 or higher, the default connection mode is full-duplex.

'''Warning:''' If two legs are already connected in half-duplex and you want to connect them in full-duplex, you must first Unjoin() the legs, then Join() them in full-duplex. You can '''NOT''' only do another half-duplex in the opposite direction.

When legs are joined, it creates a link identified with a unique ''link id''. It is the responsibility of the application to provide this unique ''link id'' by implementing the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetLinkId '''GetLinkId()'''] function of the leg. It is planned to allow the user to provide a value of '0' to let the Toolpack system automatically choose a ''link id'', but as of this writing this feature is not yet available.

'''Warning:''' When two legs are joined, the application must ensure that '''GetLinkId()''' on both leg will return the right ''link id''. This will ensure that when the link needs to be removed, both A->Unjoin() and B->Unjoin() will work correctly.

==== Setting the link properties ====

In your leg class, add a member variable to store the join attributes for that leg.

CTBCMC_JOIN_ATTRIBUTE mJoinAttribute;

Then set the join properties you want in your leg class constructor (or at any other location that will run '''before''' the '''Join()''' is done:

mJoinAttribute.IsFullDuplex() = TBX_TRUE;

Last, implement the '''GetJoinAttributes()''' function.

CTBCMC_JOIN_ATTRIBUTE & CH248Termination::GetJoinAttributes()
{
return mJoinAttribute;
}

==== Broadcasting a media source ====
At the time of writing this, broadcast of a single media source to multiple destinations is not yet possible.

=== Unjoin ===
To disconnect the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Unjoin'''Unjoin()'''] on any of the legs. The '''GetLinkId()''' function of the leg on which '''Unjoin()''' is called must return the ''link id'' that was used when the legs were joined.

[[category:CAF]]
[[category:Needs revising]]

CAF: Working With Call Legs

2010-02-09T21:12:32Z

Alexandre Lussier: /* Playing and Collecting Tones */

== Call Leg Definition ==
The main mechanism through which the customer application controls the [[Toolpack]] system is via the management of call legs. The application creates a call leg (or more than one for conferencing and bridging) at the beginning of a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.

A call leg is represented by an instance of the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html CTBCMCLeg] class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 [[timeslot]]) or a [[SIP]] call with its associated [[VOIP]] [[Voice codecs|codec]] resource (attached to an IP/UDP endpoint). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (VOIP codec resource attached to an IP/UDP endpoint). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.

The CTBCMCLeg class allows a programmer to easily act upon the call leg to influence the signaling portion (e.g. accept, answer, terminate, etc) and to use the media portion as well (e.g play prompts, record voice, play or collect digits and tones).

Other member functions are available to retrieve (and change in some cases) the call leg attributes including the media profile (e.g. parameters to the media resource) or signaling information (e.g. protocol type, called and calling party numbers, etc). Joining/unjoining (connection/disconnection) of call legs is also a typical action handled by this class for ’gateway-type’ applications. It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse a ''call leg'' with a ''call''. A ''call leg'' represents one full-duplex link to a party while a ''call'' represents the agglomeration of multiple (two or more) call legs. For example, a ''bridge'' is a form of ''call'' that uses two ''call legs''.
* Do not confuse the base class CTBCMCLeg with the class [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_leg.html CTBCAFCallLeg]. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs. It is designed to represent a leg within a call. It cannot be instanciated as a standalone object without modifications to make it independent from the ITBCAFCallFlow interface.
* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

== Command Flow for Leg Actions in CAF ==
All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).

For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.

== Leg Creation ==
Creating a leg is always done through the definition of a ''call leg attribute''. The values entered in the ''call leg attribute'' will define the type of call leg created and its parameters. The following sections describe several scenarios in which you build a ''call leg''. Instruction will be given on how to fill the leg attributes and how to use them to create the ''call leg''.

=== Preparing Leg Attributes ===

==== Normal Call Leg Attributes ====
For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
* the called number,
* the calling number,
* the [[NAP | Network Access Point]].

Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|NAP Types]]).

The following code snippet shows how to build the attributes.
PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();

ptrOutgoingLegAttribute->GetCalledNumber() = "123-4567";
ptrOutgoingLegAttribute->GetCallingNumber() = "987-6543";
ptrOutgoingLegAttribute->GetNetworkAccessPoint() = "NAP_SS7_MONTREAL";

==== Media-only Leg Attributes ====
For media-only legs, no signaling information is needed but the user can specify which media channel to use and which media profile to use. The only required parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''MEDIA TDM'' or ''MEDIA VOIP'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;

ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();

ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;

When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. For ''MEDIA TDM'' NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For ''MEDIA VOIP'' NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and a timeslot number can be specified.

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc->Settings.TdmAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
pMediaDesc->Settings.TdmAudio.un8Timeslot = 5;
Strncpy
(
pMediaDesc->Settings.TdmAudio.szTrunkName,
"TRUNK_TORONTO_1",
sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
);

For VOIP legs, the user can control the media by providing local [[SDP]] and peer SDP. Setting the local SDP defines the codec and IP/port used to for the received media stream. Most of the time, the IP address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and IP/port used for the transmitted media stream. Note that Toolpack only allows for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in '''both''' SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].

TBX_RESULT Result;
TBX_SDP_INFO SdpInfo;
PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();
pMediaDesc->Settings.PacketAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;

// Set Local SDP
Result = BuildSdpInfo("", 0, SdpInfo); // No IP specified, Toolpack will choose one
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

// Set Peer SDP
Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo); // Using peer IP address and port
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetPeerSDP(SdpInfo);

=== Creating the Leg ===
Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CreateCall '''CreateCall()'''] on it. No action is taken when an instance of a CTBCMCLeg is created. Call resources are only allocated in the Toolpack system when '''CreateCall()''' is called on the object.

pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
pCallLeg->CreateCall();

For legs with signaling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).

[[Image:CallFlow SignalingMediaLeg Creation.JPG|thumb|center|350px|Call flow for creation of leg with signaling]]

For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.

[[Image:CallFlow MediaOnlyLeg Creation.JPG|thumb|center|350px|Call flow for media-only leg creation]]

Once a call is fully active (call answered and media allocated), event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnProfileChanged '''OnProfileChanged()'''] will be sent on the leg. In the cases where the user had not specified the IP/port to use, once this event is received, the media profile has been updated with the values chosen by Toolpack and the updated values can be retrieved using the functions '''GetLocalSDP()''' and '''GetPeerSDP()''' of the profile.
Note that the '''OnProfileChanged()''' event is also sent after the media profile has been modified with the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ChangeProfile '''ChangeProfile()'''] function (see [[#Modifying Media Profile|Modifying Media Profile]]) and when a connected peer has requested it (through a SIP re-INVITE for example).

See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.

=== Caveats ===
* The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).

== Interaction with Legs ==

=== Playing and Collecting Digits ===
You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play digits defined by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayDigit '''PlayDigit()'''] on a leg. Toolpack will receive the request and play the digits. Once digits are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitPlayingDone '''OnDigitPlayingDone()'''] event.

You can also configure a leg to collect digits played. To start the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartDigitCollection '''StartDigitCollection()'''] on the leg. Note that you will have to specify which digits you want to collect before starting the digit collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopDigitCollection '''StopDigitCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitCollected '''OnDigitCollected()'''] event on each digit received that correspond to a tone string specified with the previously call to '''AddToneString()'''.

=== Playing and Collecting Tones ===
You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play events by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayEvent '''PlayEvent()'''] on a leg. Toolpack will receive the request and play the events. Once events are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventPlayingDone '''OnEventPlayingDone()'''] event. Note that you can cancel an event to be played by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CancelEvent '''CancelEvent()'''] on the leg after a '''PlayEvent()''' has been called.

Two kinds of string can be passed to '''AddToneString()''' to play a tone. The first type is to play well known tones such as dtmf and fax tone. The syntax is really simple and is based on H248 package and signal ids. The first component of the string is the package id and the second is the signal id, both formated in string. So, to play dtmf 0, you have to format the following string: "dg/d0", where "dg" is for package "dtmf generation" and "d0" is for "dtmf 0".

The second type of string is to play custom tone such as ring tone. The syntax is much complicated than the first one, but it follows a well described syntax which can be found in [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.6-200011-I!!PDF-E&type=items/.pdf '''H248.6 Dynamic Tone Definition Package''']. This kind of string allows you to specify frequencies, duration, amplitude and repeating count of the tone. You can also specify well known tones and change their default duration, amplitude and repeating count. It is possible to describe a sequence of tones or frequencies that are played in one segment. Here are some examples of the syntax:

*;Frequencies 400Hz and 600Hz mixed together for 200ms, amplitude at -10dB and repeating 3 times (playing 4 times):
:*(((#400)+(#600)),200,-10)*3
:
*;Dtmf 5 repeated infinitly:
:*((0x0005,0x0015))*0
:
*;Multifrequency tone 8:
:*((mfg,mf8))
:
*;Frequency 440Hz played for 300ms at -10dB followed by frequency 600Hz played for 200ms at -5dB and then followed by dtmf 2, all this repeated infinitly:
:*((#440,300,-10),(#600,200,-5),(0x0005,0x0012))*0
:

You can also configure a leg to collect events played. To start the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartEventCollection '''StartEventCollection()'''] on the leg. Note that you will have to specify which events you want to collect before starting the event collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopEventCollection '''StopEventCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventCollected '''OnEventCollected()'''] event on each event received that correspond to a tone string specified with the previously call to '''AddToneString()'''.

Only one string is accepted to collect events. The string is the same as the first type to play event. Signal ids that are also event id are accepted. This means that you can ask to collect "dg/d0" (dtmf generation/dtmf 0) and the detection will be done anyway. But, when the event is detected, it's the event id that will be returned, which means that "dd/d0" (dtmf detection/dtmf 0) will be returned instead of "dg/d0". You can also detect all events from a package by putting a * as event id, so "dd/*" will detect all dtmf tones.

The most commonly used package are 5 and 6 [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.1-200509-I!!PDF-E&type=items/.pdf '''(H248.1 Annex E)''']: dtmf generation and dtmf detection. As H248 does not define events and signals for fax tone, we added a special package to do so. Package tbfax (0x0251) contains three events and two signals: cng (0x0080), g164 (0x0081) and only for detection g165 (0x0082).

=== Collecting digits and tones while call legs are joined ===
By default, when two call legs are joined together through function CTBCMCCallLeg::Join(), tone collection is automatically disabled.
One of the arguments of the Join() function ("in_fDisableToneWhileJoined") will allow to control if automatic tone collection feature is used or not on a call.

Why is Toolpack disabling tone collection on joined legs by default?
That's because tone collection introduces a 40ms delay in the audio connection (required to provide tone suppression), and most of the time it is no more require to collect digits while two call legs are joined, so it would be useless to leave 40ms delay while tone collection is no more required.

=== Playing and Recording Audio Files ===
You can play an audio stream on a leg by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayStream '''PlayStream()'''] on it. To specify which audio stream you want to play, you have to specify it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html#CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath '''AddPlayFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html CTBCMC_PLAY_ATTRIBUTE] class. Toolpack will receive the request and play the stream. Once it is played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingDone '''OnStreamPlayingDone()'''] event.

You can also configure a leg to record an audio stream. First you must specify file paths to record by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html#CTBCMC_RECORD_ATTRIBUTE::AddRecFilePath '''AddRecFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html CTBCMC_RECORD_ATTRIBUTE] class. The you can call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RecordStream '''RecordStream()'''] on a leg. Once the stream is recorded, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamRecordingDone '''OnStreamRecordingDone()'''] event.

You can pause an active playing or recording stream by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PauseStream '''PauseStream()'''] and you can resume it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ResumeStream '''ResumeStream()''']. If you want to stop an active playing or recording stream, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopStream '''StopStream()'''] on the leg.

=== Modifying Media Profile ===
It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.

The media profile is stored in the leg attributes and can be modified like this :
TBX_SDP_INFO SdpInfo;
PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;

pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
pMediaLegAttribute->GetProfile().GetLocalSDP(SdpInfo);
Strncpy
(
SdpInfo.aConnections[0].szIp,
"",
sizeof( SdpInfo.aConnections[0].szIp )
);
SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
pMediaLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

pCallLeg->ChangeProfile();

Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotiation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.

Once the profile change has completed (or failed), event '''OnProfileChanged()''' will be received on the leg.

For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.

=== Controlling the Signaling ===
When a call leg receives the '''OnCallLegPresent()''' event, it indicates an incoming call. To confirm that the call contains sufficient valid information to process the call on the system, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AcceptCall '''AcceptCall()'''] on the leg. If a call leg receives the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAccepted '''OnCallAccepted()'''] event, it means that an outgoing call has been accepted by the remote peer. This event usually means that the calling number has been accepted and that the call is currently being processed.

After an incoming call has been accepted, a call leg can notify the remote peer that the incoming call has been put in the "ringing" state by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AlertCall '''AlertCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAlerting '''OnCallAlerting()'''] event when an outgoing call has been put in the "ringing" state by the remote peer.

When an incoming call is answered, a call leg can notify the remote peer of the incoming call answered by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AnswerCall '''AnswerCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAnswered '''OnCallAnswered()'''] event when an outgoing call has been answered by the remote peer.

SendCallSuppInfo/OnCallSuppInfo

== Leg Termination ==

Terminating a call leg is a 2 steps process:
# Call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::TerminateCall '''TerminateCall()''']
# Free leg object on [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminated '''OnCallTerminated()''']

When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resources freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Free '''Free()'''] on the leg's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::SetFreeListener '''SetFreeListener()'''] on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is deleted. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.

[[Image:TerminateCall from application.jpg|thumb|center|350px|Call flow for leg termination initiated by user application]]

In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other media resource or signaling error. In these cases, the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminatingIndication '''OnCallTerminatingIndication()'''] is sent to the leg. On reception of this event, the application should initiate call termination as shown below.

[[Image:TerminateCall from Toolpack.jpg|thumb|center|350px|Call flow for leg termination initiated by Toolpack]]

In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnLegTerminated '''OnLegTerminated()'''] event. This event indicates that the leg does not exist anymore on the Toolpack side and the user should free its object without trying any other interaction with Toolpack through it.

== Leg Synchronization on Failover ==
When a Toolpack application is restarted or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs through the '''OnCallLegSync()''' event of the [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_lib_user.html ITBCMCLibUser] interface (this interface must be implemented by all user applications). One event will be received for each leg being synchronized. The course of action to take when receiving a leg synchronization event depends on the ability of the application to resynchronize its states with theses legs.

* If the application can't resynchronize active legs or if it does not want to resychronize the leg for which it is receiving an '''OnCallLegSync()''' event, it must refuse the leg by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLeg '''RefuseLeg()'''].
*If the application wants the resynchronize the leg or if it does not yet have enough information to decide, it must create a CTBCMCLeg object using the leg attributes received in the event.

Once all '''OnCallLegSync()''' have been sent, Toolpack will start synchronization of the links between legs through '''OnLinkSync()'''. This event indicates that two legs are connected together. It can be used by the application to rebuild its internal states. As for the legs, unwanted links can be refused by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()'''].

When all links have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. At that moment, the application has all the information available on the Toolpack side to determine if the legs should be kept or release. Any leg that the application does not want to keep can be refused by calling '''RefuseLeg()''' on it. For all legs that have not been refused, an event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnSyncDone '''OnSyncDone()'''] will be sent on the leg. Once this event has been received on a leg, the leg is fully functional and the application can start calling any usual Toolpack function on it.

[[Image:CallFlow Sync After Application Restart.jpg|thumb|center|350px|Call flow for leg synchronization]]

===Loss of Communication with Toolpack Engine===
If communication is lost with the Toolpack Engine, event '''OnCmcLibNotReady()''' will be sent to the application. It indicates that the Toolpack framework is no more accessible. The legs are still valid at that time but no action can be executed on them as long the CmcLib is not ready. If the connection with the Toolpack Engine is not back up in less than 10 seconds, the CmcLib will declare a major communication loss and will call '''OnLegTerminated()''' on all the legs. In that case, when communication is regained with the Toolpack Engine, the synchronization sequence will start again from the beginning.

[[Image:CallFlow Sync After Comm Restart Passed 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart passed 10 seconds.]]

If the communication is regained before the 10 seconds timeout, event '''OnCmcLibReady()''' will be sent and the application can then continue working normally with its existing call legs. Note that you can also receive '''OnLegTerminated()''' on some legs before receiving the '''OnCmcLibReady()''' if those legs were in a transient state when disconnection occurred.

[[Image:CallFlow Sync After Comm Restart Within 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart within 10 seconds.]]

== Bridging the Media Path ==
=== Join ===

To bridge the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Join '''Join()'''] on one of the leg, giving the second leg as a parameter. This will connect the media path between the two legs according to the link properties set on the leg on which '''Join()''' is called. These link properties can be modified by overloading the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetJoinAttributes '''GetJoinAttributes()''']. The important attribute to set is '''IsFullDuplex()''' that indicates if the connection will be made full-duplex (A<-->B) or half-duplex (A-->B). Prior to release 2.5.2, the default connection mode is half-duplex. For all release version 2.5.2 or higher, the default connection mode is full-duplex.

'''Warning:''' If two legs are already connected in half-duplex and you want to connect them in full-duplex, you must first Unjoin() the legs, then Join() them in full-duplex. You can '''NOT''' only do another half-duplex in the opposite direction.

When legs are joined, it creates a link identified with a unique ''link id''. It is the responsibility of the application to provide this unique ''link id'' by implementing the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetLinkId '''GetLinkId()'''] function of the leg. It is planned to allow the user to provide a value of '0' to let the Toolpack system automatically choose a ''link id'', but as of this writing this feature is not yet available.

'''Warning:''' When two legs are joined, the application must ensure that '''GetLinkId()''' on both leg will return the right ''link id''. This will ensure that when the link needs to be removed, both A->Unjoin() and B->Unjoin() will work correctly.

==== Setting the link properties ====

In your leg class, add a member variable to store the join attributes for that leg.

CTBCMC_JOIN_ATTRIBUTE mJoinAttribute;

Then set the join properties you want in your leg class constructor (or at any other location that will run '''before''' the '''Join()''' is done:

mJoinAttribute.IsFullDuplex() = TBX_TRUE;

Last, implement the '''GetJoinAttributes()''' function.

CTBCMC_JOIN_ATTRIBUTE & CH248Termination::GetJoinAttributes()
{
return mJoinAttribute;
}

==== Broadcasting a media source ====
At the time of writing this, broadcast of a single media source to multiple destinations is not yet possible.

=== Unjoin ===
To disconnect the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Unjoin'''Unjoin()'''] on any of the legs. The '''GetLinkId()''' function of the leg on which '''Unjoin()''' is called must return the ''link id'' that was used when the legs were joined.

[[category:CAF]]
[[category:Needs revising]]

CAF: Working With Call Legs

2010-02-09T21:12:06Z

Alexandre Lussier: /* Playing and Collecting Tones */

== Call Leg Definition ==
The main mechanism through which the customer application controls the [[Toolpack]] system is via the management of call legs. The application creates a call leg (or more than one for conferencing and bridging) at the beginning of a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.

A call leg is represented by an instance of the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html CTBCMCLeg] class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 [[timeslot]]) or a [[SIP]] call with its associated [[VOIP]] [[Voice codecs|codec]] resource (attached to an IP/UDP endpoint). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (VOIP codec resource attached to an IP/UDP endpoint). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.

The CTBCMCLeg class allows a programmer to easily act upon the call leg to influence the signaling portion (e.g. accept, answer, terminate, etc) and to use the media portion as well (e.g play prompts, record voice, play or collect digits and tones).

Other member functions are available to retrieve (and change in some cases) the call leg attributes including the media profile (e.g. parameters to the media resource) or signaling information (e.g. protocol type, called and calling party numbers, etc). Joining/unjoining (connection/disconnection) of call legs is also a typical action handled by this class for ’gateway-type’ applications. It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse a ''call leg'' with a ''call''. A ''call leg'' represents one full-duplex link to a party while a ''call'' represents the agglomeration of multiple (two or more) call legs. For example, a ''bridge'' is a form of ''call'' that uses two ''call legs''.
* Do not confuse the base class CTBCMCLeg with the class [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_leg.html CTBCAFCallLeg]. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs. It is designed to represent a leg within a call. It cannot be instanciated as a standalone object without modifications to make it independent from the ITBCAFCallFlow interface.
* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

== Command Flow for Leg Actions in CAF ==
All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).

For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.

== Leg Creation ==
Creating a leg is always done through the definition of a ''call leg attribute''. The values entered in the ''call leg attribute'' will define the type of call leg created and its parameters. The following sections describe several scenarios in which you build a ''call leg''. Instruction will be given on how to fill the leg attributes and how to use them to create the ''call leg''.

=== Preparing Leg Attributes ===

==== Normal Call Leg Attributes ====
For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
* the called number,
* the calling number,
* the [[NAP | Network Access Point]].

Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|NAP Types]]).

The following code snippet shows how to build the attributes.
PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();

ptrOutgoingLegAttribute->GetCalledNumber() = "123-4567";
ptrOutgoingLegAttribute->GetCallingNumber() = "987-6543";
ptrOutgoingLegAttribute->GetNetworkAccessPoint() = "NAP_SS7_MONTREAL";

==== Media-only Leg Attributes ====
For media-only legs, no signaling information is needed but the user can specify which media channel to use and which media profile to use. The only required parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''MEDIA TDM'' or ''MEDIA VOIP'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;

ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();

ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;

When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. For ''MEDIA TDM'' NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For ''MEDIA VOIP'' NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and a timeslot number can be specified.

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc->Settings.TdmAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
pMediaDesc->Settings.TdmAudio.un8Timeslot = 5;
Strncpy
(
pMediaDesc->Settings.TdmAudio.szTrunkName,
"TRUNK_TORONTO_1",
sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
);

For VOIP legs, the user can control the media by providing local [[SDP]] and peer SDP. Setting the local SDP defines the codec and IP/port used to for the received media stream. Most of the time, the IP address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and IP/port used for the transmitted media stream. Note that Toolpack only allows for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in '''both''' SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].

TBX_RESULT Result;
TBX_SDP_INFO SdpInfo;
PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();
pMediaDesc->Settings.PacketAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;

// Set Local SDP
Result = BuildSdpInfo("", 0, SdpInfo); // No IP specified, Toolpack will choose one
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

// Set Peer SDP
Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo); // Using peer IP address and port
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetPeerSDP(SdpInfo);

=== Creating the Leg ===
Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CreateCall '''CreateCall()'''] on it. No action is taken when an instance of a CTBCMCLeg is created. Call resources are only allocated in the Toolpack system when '''CreateCall()''' is called on the object.

pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
pCallLeg->CreateCall();

For legs with signaling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).

[[Image:CallFlow SignalingMediaLeg Creation.JPG|thumb|center|350px|Call flow for creation of leg with signaling]]

For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.

[[Image:CallFlow MediaOnlyLeg Creation.JPG|thumb|center|350px|Call flow for media-only leg creation]]

Once a call is fully active (call answered and media allocated), event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnProfileChanged '''OnProfileChanged()'''] will be sent on the leg. In the cases where the user had not specified the IP/port to use, once this event is received, the media profile has been updated with the values chosen by Toolpack and the updated values can be retrieved using the functions '''GetLocalSDP()''' and '''GetPeerSDP()''' of the profile.
Note that the '''OnProfileChanged()''' event is also sent after the media profile has been modified with the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ChangeProfile '''ChangeProfile()'''] function (see [[#Modifying Media Profile|Modifying Media Profile]]) and when a connected peer has requested it (through a SIP re-INVITE for example).

See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.

=== Caveats ===
* The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).

== Interaction with Legs ==

=== Playing and Collecting Digits ===
You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play digits defined by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayDigit '''PlayDigit()'''] on a leg. Toolpack will receive the request and play the digits. Once digits are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitPlayingDone '''OnDigitPlayingDone()'''] event.

You can also configure a leg to collect digits played. To start the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartDigitCollection '''StartDigitCollection()'''] on the leg. Note that you will have to specify which digits you want to collect before starting the digit collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopDigitCollection '''StopDigitCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitCollected '''OnDigitCollected()'''] event on each digit received that correspond to a tone string specified with the previously call to '''AddToneString()'''.

=== Playing and Collecting Tones ===
You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in CTBCMC_EVENT_ATTRIBUTE class.
You can then play events by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayEvent '''PlayEvent()'''] on a leg. Toolpack will receive the request and play the events. Once events are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventPlayingDone '''OnEventPlayingDone()'''] event. Note that you can cancel an event to be played by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CancelEvent '''CancelEvent()'''] on the leg after a '''PlayEvent()''' has been called.

Two kinds of string can be passed to '''AddToneString()''' to play a tone. The first type is to play well known tones such as dtmf and fax tone. The syntax is really simple and is based on H248 package and signal ids. The first component of the string is the package id and the second is the signal id, both formated in string. So, to play dtmf 0, you have to format the following string: "dg/d0", where "dg" is for package "dtmf generation" and "d0" is for "dtmf 0".

The second type of string is to play custom tone such as ring tone. The syntax is much complicated than the first one, but it follows a well described syntax which can be found in [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.6-200011-I!!PDF-E&type=items/.pdf '''H248.6 Dynamic Tone Definition Package''']. This kind of string allows you to specify frequencies, duration, amplitude and repeating count of the tone. You can also specify well known tones and change their default duration, amplitude and repeating count. It is possible to describe a sequence of tones or frequencies that are played in one segment. Here are some examples of the syntax:

*;Frequencies 400Hz and 600Hz mixed together for 200ms, amplitude at -10dB and repeating 3 times (playing 4 times):
:*(((#400)+(#600)),200,-10)*3
:
*;Dtmf 5 repeated infinitly:
:*((0x0005,0x0015))*0
:
*;Multifrequency tone 8:
:*((mfg,mf8))
:
*;Frequency 440Hz played for 300ms at -10dB followed by frequency 600Hz played for 200ms at -5dB and then followed by dtmf 2, all this repeated infinitly:
:*((#440,300,-10),(#600,200,-5),(0x0005,0x0012))*0
:

You can also configure a leg to collect events played. To start the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartEventCollection '''StartEventCollection()'''] on the leg. Note that you will have to specify which events you want to collect before starting the event collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopEventCollection '''StopEventCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventCollected '''OnEventCollected()'''] event on each event received that correspond to a tone string specified with the previously call to '''AddToneString()'''.

Only one string is accepted to collect events. The string is the same as the first type to play event. Signal ids that are also event id are accepted. This means that you can ask to collect "dg/d0" (dtmf generation/dtmf 0) and the detection will be done anyway. But, when the event is detected, it's the event id that will be returned, which means that "dd/d0" (dtmf detection/dtmf 0) will be returned instead of "dg/d0". You can also detect all events from a package by putting a * as event id, so "dd/*" will detect all dtmf tones.

The most commonly used package are 5 and 6 [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.1-200509-I!!PDF-E&type=items/.pdf '''(H248.1 Annex E)''']: dtmf generation and dtmf detection. As H248 does not define events and signals for fax tone, we added a special package to do so. Package tbfax (0x0251) contains three events and two signals: cng (0x0080), g164 (0x0081) and only for detection g165 (0x0082).

=== Collecting digits and tones while call legs are joined ===
By default, when two call legs are joined together through function CTBCMCCallLeg::Join(), tone collection is automatically disabled.
One of the arguments of the Join() function ("in_fDisableToneWhileJoined") will allow to control if automatic tone collection feature is used or not on a call.

Why is Toolpack disabling tone collection on joined legs by default?
That's because tone collection introduces a 40ms delay in the audio connection (required to provide tone suppression), and most of the time it is no more require to collect digits while two call legs are joined, so it would be useless to leave 40ms delay while tone collection is no more required.

=== Playing and Recording Audio Files ===
You can play an audio stream on a leg by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayStream '''PlayStream()'''] on it. To specify which audio stream you want to play, you have to specify it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html#CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath '''AddPlayFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html CTBCMC_PLAY_ATTRIBUTE] class. Toolpack will receive the request and play the stream. Once it is played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingDone '''OnStreamPlayingDone()'''] event.

You can also configure a leg to record an audio stream. First you must specify file paths to record by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html#CTBCMC_RECORD_ATTRIBUTE::AddRecFilePath '''AddRecFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html CTBCMC_RECORD_ATTRIBUTE] class. The you can call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RecordStream '''RecordStream()'''] on a leg. Once the stream is recorded, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamRecordingDone '''OnStreamRecordingDone()'''] event.

You can pause an active playing or recording stream by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PauseStream '''PauseStream()'''] and you can resume it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ResumeStream '''ResumeStream()''']. If you want to stop an active playing or recording stream, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopStream '''StopStream()'''] on the leg.

=== Modifying Media Profile ===
It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.

The media profile is stored in the leg attributes and can be modified like this :
TBX_SDP_INFO SdpInfo;
PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;

pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
pMediaLegAttribute->GetProfile().GetLocalSDP(SdpInfo);
Strncpy
(
SdpInfo.aConnections[0].szIp,
"",
sizeof( SdpInfo.aConnections[0].szIp )
);
SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
pMediaLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

pCallLeg->ChangeProfile();

Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotiation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.

Once the profile change has completed (or failed), event '''OnProfileChanged()''' will be received on the leg.

For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.

=== Controlling the Signaling ===
When a call leg receives the '''OnCallLegPresent()''' event, it indicates an incoming call. To confirm that the call contains sufficient valid information to process the call on the system, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AcceptCall '''AcceptCall()'''] on the leg. If a call leg receives the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAccepted '''OnCallAccepted()'''] event, it means that an outgoing call has been accepted by the remote peer. This event usually means that the calling number has been accepted and that the call is currently being processed.

After an incoming call has been accepted, a call leg can notify the remote peer that the incoming call has been put in the "ringing" state by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AlertCall '''AlertCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAlerting '''OnCallAlerting()'''] event when an outgoing call has been put in the "ringing" state by the remote peer.

When an incoming call is answered, a call leg can notify the remote peer of the incoming call answered by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AnswerCall '''AnswerCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAnswered '''OnCallAnswered()'''] event when an outgoing call has been answered by the remote peer.

SendCallSuppInfo/OnCallSuppInfo

== Leg Termination ==

Terminating a call leg is a 2 steps process:
# Call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::TerminateCall '''TerminateCall()''']
# Free leg object on [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminated '''OnCallTerminated()''']

When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resources freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Free '''Free()'''] on the leg's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::SetFreeListener '''SetFreeListener()'''] on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is deleted. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.

[[Image:TerminateCall from application.jpg|thumb|center|350px|Call flow for leg termination initiated by user application]]

In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other media resource or signaling error. In these cases, the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminatingIndication '''OnCallTerminatingIndication()'''] is sent to the leg. On reception of this event, the application should initiate call termination as shown below.

[[Image:TerminateCall from Toolpack.jpg|thumb|center|350px|Call flow for leg termination initiated by Toolpack]]

In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnLegTerminated '''OnLegTerminated()'''] event. This event indicates that the leg does not exist anymore on the Toolpack side and the user should free its object without trying any other interaction with Toolpack through it.

== Leg Synchronization on Failover ==
When a Toolpack application is restarted or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs through the '''OnCallLegSync()''' event of the [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_lib_user.html ITBCMCLibUser] interface (this interface must be implemented by all user applications). One event will be received for each leg being synchronized. The course of action to take when receiving a leg synchronization event depends on the ability of the application to resynchronize its states with theses legs.

* If the application can't resynchronize active legs or if it does not want to resychronize the leg for which it is receiving an '''OnCallLegSync()''' event, it must refuse the leg by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLeg '''RefuseLeg()'''].
*If the application wants the resynchronize the leg or if it does not yet have enough information to decide, it must create a CTBCMCLeg object using the leg attributes received in the event.

Once all '''OnCallLegSync()''' have been sent, Toolpack will start synchronization of the links between legs through '''OnLinkSync()'''. This event indicates that two legs are connected together. It can be used by the application to rebuild its internal states. As for the legs, unwanted links can be refused by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()'''].

When all links have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. At that moment, the application has all the information available on the Toolpack side to determine if the legs should be kept or release. Any leg that the application does not want to keep can be refused by calling '''RefuseLeg()''' on it. For all legs that have not been refused, an event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnSyncDone '''OnSyncDone()'''] will be sent on the leg. Once this event has been received on a leg, the leg is fully functional and the application can start calling any usual Toolpack function on it.

[[Image:CallFlow Sync After Application Restart.jpg|thumb|center|350px|Call flow for leg synchronization]]

===Loss of Communication with Toolpack Engine===
If communication is lost with the Toolpack Engine, event '''OnCmcLibNotReady()''' will be sent to the application. It indicates that the Toolpack framework is no more accessible. The legs are still valid at that time but no action can be executed on them as long the CmcLib is not ready. If the connection with the Toolpack Engine is not back up in less than 10 seconds, the CmcLib will declare a major communication loss and will call '''OnLegTerminated()''' on all the legs. In that case, when communication is regained with the Toolpack Engine, the synchronization sequence will start again from the beginning.

[[Image:CallFlow Sync After Comm Restart Passed 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart passed 10 seconds.]]

If the communication is regained before the 10 seconds timeout, event '''OnCmcLibReady()''' will be sent and the application can then continue working normally with its existing call legs. Note that you can also receive '''OnLegTerminated()''' on some legs before receiving the '''OnCmcLibReady()''' if those legs were in a transient state when disconnection occurred.

[[Image:CallFlow Sync After Comm Restart Within 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart within 10 seconds.]]

== Bridging the Media Path ==
=== Join ===

To bridge the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Join '''Join()'''] on one of the leg, giving the second leg as a parameter. This will connect the media path between the two legs according to the link properties set on the leg on which '''Join()''' is called. These link properties can be modified by overloading the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetJoinAttributes '''GetJoinAttributes()''']. The important attribute to set is '''IsFullDuplex()''' that indicates if the connection will be made full-duplex (A<-->B) or half-duplex (A-->B). Prior to release 2.5.2, the default connection mode is half-duplex. For all release version 2.5.2 or higher, the default connection mode is full-duplex.

'''Warning:''' If two legs are already connected in half-duplex and you want to connect them in full-duplex, you must first Unjoin() the legs, then Join() them in full-duplex. You can '''NOT''' only do another half-duplex in the opposite direction.

When legs are joined, it creates a link identified with a unique ''link id''. It is the responsibility of the application to provide this unique ''link id'' by implementing the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetLinkId '''GetLinkId()'''] function of the leg. It is planned to allow the user to provide a value of '0' to let the Toolpack system automatically choose a ''link id'', but as of this writing this feature is not yet available.

'''Warning:''' When two legs are joined, the application must ensure that '''GetLinkId()''' on both leg will return the right ''link id''. This will ensure that when the link needs to be removed, both A->Unjoin() and B->Unjoin() will work correctly.

==== Setting the link properties ====

In your leg class, add a member variable to store the join attributes for that leg.

CTBCMC_JOIN_ATTRIBUTE mJoinAttribute;

Then set the join properties you want in your leg class constructor (or at any other location that will run '''before''' the '''Join()''' is done:

mJoinAttribute.IsFullDuplex() = TBX_TRUE;

Last, implement the '''GetJoinAttributes()''' function.

CTBCMC_JOIN_ATTRIBUTE & CH248Termination::GetJoinAttributes()
{
return mJoinAttribute;
}

==== Broadcasting a media source ====
At the time of writing this, broadcast of a single media source to multiple destinations is not yet possible.

=== Unjoin ===
To disconnect the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Unjoin'''Unjoin()'''] on any of the legs. The '''GetLinkId()''' function of the leg on which '''Unjoin()''' is called must return the ''link id'' that was used when the legs were joined.

[[category:CAF]]
[[category:Needs revising]]

CAF: Working With Call Legs

2010-02-09T20:54:59Z

Alexandre Lussier: /* Playing and Collecting Tones */

== Call Leg Definition ==
The main mechanism through which the customer application controls the [[Toolpack]] system is via the management of call legs. The application creates a call leg (or more than one for conferencing and bridging) at the beginning of a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.

A call leg is represented by an instance of the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html CTBCMCLeg] class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 [[timeslot]]) or a [[SIP]] call with its associated [[VOIP]] [[Voice codecs|codec]] resource (attached to an IP/UDP endpoint). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (VOIP codec resource attached to an IP/UDP endpoint). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.

The CTBCMCLeg class allows a programmer to easily act upon the call leg to influence the signaling portion (e.g. accept, answer, terminate, etc) and to use the media portion as well (e.g play prompts, record voice, play or collect digits and tones).

Other member functions are available to retrieve (and change in some cases) the call leg attributes including the media profile (e.g. parameters to the media resource) or signaling information (e.g. protocol type, called and calling party numbers, etc). Joining/unjoining (connection/disconnection) of call legs is also a typical action handled by this class for ’gateway-type’ applications. It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse a ''call leg'' with a ''call''. A ''call leg'' represents one full-duplex link to a party while a ''call'' represents the agglomeration of multiple (two or more) call legs. For example, a ''bridge'' is a form of ''call'' that uses two ''call legs''.
* Do not confuse the base class CTBCMCLeg with the class [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_leg.html CTBCAFCallLeg]. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs. It is designed to represent a leg within a call. It cannot be instanciated as a standalone object without modifications to make it independent from the ITBCAFCallFlow interface.
* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

== Command Flow for Leg Actions in CAF ==
All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).

For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.

== Leg Creation ==
Creating a leg is always done through the definition of a ''call leg attribute''. The values entered in the ''call leg attribute'' will define the type of call leg created and its parameters. The following sections describe several scenarios in which you build a ''call leg''. Instruction will be given on how to fill the leg attributes and how to use them to create the ''call leg''.

=== Preparing Leg Attributes ===

==== Normal Call Leg Attributes ====
For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
* the called number,
* the calling number,
* the [[NAP | Network Access Point]].

Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|NAP Types]]).

The following code snippet shows how to build the attributes.
PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();

ptrOutgoingLegAttribute->GetCalledNumber() = "123-4567";
ptrOutgoingLegAttribute->GetCallingNumber() = "987-6543";
ptrOutgoingLegAttribute->GetNetworkAccessPoint() = "NAP_SS7_MONTREAL";

==== Media-only Leg Attributes ====
For media-only legs, no signaling information is needed but the user can specify which media channel to use and which media profile to use. The only required parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''MEDIA TDM'' or ''MEDIA VOIP'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;

ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();

ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;

When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. For ''MEDIA TDM'' NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For ''MEDIA VOIP'' NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and a timeslot number can be specified.

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc->Settings.TdmAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
pMediaDesc->Settings.TdmAudio.un8Timeslot = 5;
Strncpy
(
pMediaDesc->Settings.TdmAudio.szTrunkName,
"TRUNK_TORONTO_1",
sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
);

For VOIP legs, the user can control the media by providing local [[SDP]] and peer SDP. Setting the local SDP defines the codec and IP/port used to for the received media stream. Most of the time, the IP address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and IP/port used for the transmitted media stream. Note that Toolpack only allows for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in '''both''' SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].

TBX_RESULT Result;
TBX_SDP_INFO SdpInfo;
PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();
pMediaDesc->Settings.PacketAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;

// Set Local SDP
Result = BuildSdpInfo("", 0, SdpInfo); // No IP specified, Toolpack will choose one
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

// Set Peer SDP
Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo); // Using peer IP address and port
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetPeerSDP(SdpInfo);

=== Creating the Leg ===
Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CreateCall '''CreateCall()'''] on it. No action is taken when an instance of a CTBCMCLeg is created. Call resources are only allocated in the Toolpack system when '''CreateCall()''' is called on the object.

pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
pCallLeg->CreateCall();

For legs with signaling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).

[[Image:CallFlow SignalingMediaLeg Creation.JPG|thumb|center|350px|Call flow for creation of leg with signaling]]

For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.

[[Image:CallFlow MediaOnlyLeg Creation.JPG|thumb|center|350px|Call flow for media-only leg creation]]

Once a call is fully active (call answered and media allocated), event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnProfileChanged '''OnProfileChanged()'''] will be sent on the leg. In the cases where the user had not specified the IP/port to use, once this event is received, the media profile has been updated with the values chosen by Toolpack and the updated values can be retrieved using the functions '''GetLocalSDP()''' and '''GetPeerSDP()''' of the profile.
Note that the '''OnProfileChanged()''' event is also sent after the media profile has been modified with the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ChangeProfile '''ChangeProfile()'''] function (see [[#Modifying Media Profile|Modifying Media Profile]]) and when a connected peer has requested it (through a SIP re-INVITE for example).

See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.

=== Caveats ===
* The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).

== Interaction with Legs ==

=== Playing and Collecting Digits ===
You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play digits defined by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayDigit '''PlayDigit()'''] on a leg. Toolpack will receive the request and play the digits. Once digits are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitPlayingDone '''OnDigitPlayingDone()'''] event.

You can also configure a leg to collect digits played. To start the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartDigitCollection '''StartDigitCollection()'''] on the leg. Note that you will have to specify which digits you want to collect before starting the digit collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopDigitCollection '''StopDigitCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitCollected '''OnDigitCollected()'''] event on each digit received that correspond to a tone string specified with the previously call to '''AddToneString()'''.

=== Playing and Collecting Tones ===
You can add tones you want to play by using '''AddToneString()''' available in CTBCMC_EVENT_ATTRIBUTE class.
You can then play events by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayEvent '''PlayEvent()'''] on a leg. Toolpack will receive the request and play the events. Once events are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventPlayingDone '''OnEventPlayingDone()'''] event. Note that you can cancel an event to be played by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CancelEvent '''CancelEvent()'''] on the leg after a '''PlayEvent()''' has been called.

Two kinds of string can be passed to '''AddToneString()''' to play a tone. The first type is to play well known tones such as dtmf and fax tone. The syntax is really simple and is based on H248 package and signal ids. The first component of the string is the package id and the second is the signal id, both formated in string. So, to play dtmf 0, you have to format the following string: "dg/d0", where "dg" is for package "dtmf generation" and "d0" is for "dtmf 0".

The second type of string is to play custom tone such as ring tone. The syntax is much complicated than the first one, but it follows a well described syntax which can be found in [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.6-200011-I!!PDF-E&type=items/.pdf '''H248.6 Dynamic Tone Definition Package''']. This kind of string allows you to specify frequencies, duration, amplitude and repeating count of the tone. You can also specify well known tones and change their default duration, amplitude and repeating count. It is possible to describe a sequence of tones or frequencies that are played in one segment. Here are some examples of the syntax:

*;Frequencies 400Hz and 600Hz mixed together for 200ms, amplitude at -10dB and repeating 3 times (playing 4 times):
:*(((#400)+(#600)),200,-10)*3
:
*;Dtmf 5 repeated infinitly:
:*((0x0005,0x0015))*0
:
*;Multifrequency tone 8:
:*((mfg,mf8))
:
*;Frequency 440Hz played for 300ms at -10dB followed by frequency 600Hz played for 200ms at -5dB and then followed by dtmf 2, all this repeated infinitly:
:*((#440,300,-10),(#600,200,-5),(0x0005,0x0012))*0
:

You can also configure a leg to collect events played. To start the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartEventCollection '''StartEventCollection()'''] on the leg. Note that you will have to specify which events you want to collect before starting the event collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopEventCollection '''StopEventCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventCollected '''OnEventCollected()'''] event on each event received that correspond to a tone string specified with the previously call to '''AddToneString()'''.

Only one string is accepted to collect events. The string is the same as the first type to play event. Signal ids that are also event id are accepted. This means that you can ask to collect "dg/d0" (dtmf generation/dtmf 0) and the detection will be done anyway. But, when the event is detected, it's the event id that will be returned, which means that "dd/d0" (dtmf detection/dtmf 0) will be returned instead of "dg/d0". You can also detect all events from a package by putting a * as event id, so "dd/*" will detect all dtmf tones.

The most commonly used package are 5 and 6 [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.1-200509-I!!PDF-E&type=items/.pdf '''(H248.1 Annex E)''']: dtmf generation and dtmf detection. As H248 does not define events and signals for fax tone, we added a special package to do so. Package tbfax (0x0251) contains three events and two signals: cng (0x0080), g164 (0x0081) and only for detection g165 (0x0082).

=== Collecting digits and tones while call legs are joined ===
By default, when two call legs are joined together through function CTBCMCCallLeg::Join(), tone collection is automatically disabled.
One of the arguments of the Join() function ("in_fDisableToneWhileJoined") will allow to control if automatic tone collection feature is used or not on a call.

Why is Toolpack disabling tone collection on joined legs by default?
That's because tone collection introduces a 40ms delay in the audio connection (required to provide tone suppression), and most of the time it is no more require to collect digits while two call legs are joined, so it would be useless to leave 40ms delay while tone collection is no more required.

=== Playing and Recording Audio Files ===
You can play an audio stream on a leg by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayStream '''PlayStream()'''] on it. To specify which audio stream you want to play, you have to specify it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html#CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath '''AddPlayFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html CTBCMC_PLAY_ATTRIBUTE] class. Toolpack will receive the request and play the stream. Once it is played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingDone '''OnStreamPlayingDone()'''] event.

You can also configure a leg to record an audio stream. First you must specify file paths to record by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html#CTBCMC_RECORD_ATTRIBUTE::AddRecFilePath '''AddRecFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html CTBCMC_RECORD_ATTRIBUTE] class. The you can call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RecordStream '''RecordStream()'''] on a leg. Once the stream is recorded, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamRecordingDone '''OnStreamRecordingDone()'''] event.

You can pause an active playing or recording stream by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PauseStream '''PauseStream()'''] and you can resume it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ResumeStream '''ResumeStream()''']. If you want to stop an active playing or recording stream, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopStream '''StopStream()'''] on the leg.

=== Modifying Media Profile ===
It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.

The media profile is stored in the leg attributes and can be modified like this :
TBX_SDP_INFO SdpInfo;
PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;

pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
pMediaLegAttribute->GetProfile().GetLocalSDP(SdpInfo);
Strncpy
(
SdpInfo.aConnections[0].szIp,
"",
sizeof( SdpInfo.aConnections[0].szIp )
);
SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
pMediaLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

pCallLeg->ChangeProfile();

Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotiation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.

Once the profile change has completed (or failed), event '''OnProfileChanged()''' will be received on the leg.

For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.

=== Controlling the Signaling ===
When a call leg receives the '''OnCallLegPresent()''' event, it indicates an incoming call. To confirm that the call contains sufficient valid information to process the call on the system, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AcceptCall '''AcceptCall()'''] on the leg. If a call leg receives the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAccepted '''OnCallAccepted()'''] event, it means that an outgoing call has been accepted by the remote peer. This event usually means that the calling number has been accepted and that the call is currently being processed.

After an incoming call has been accepted, a call leg can notify the remote peer that the incoming call has been put in the "ringing" state by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AlertCall '''AlertCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAlerting '''OnCallAlerting()'''] event when an outgoing call has been put in the "ringing" state by the remote peer.

When an incoming call is answered, a call leg can notify the remote peer of the incoming call answered by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AnswerCall '''AnswerCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAnswered '''OnCallAnswered()'''] event when an outgoing call has been answered by the remote peer.

SendCallSuppInfo/OnCallSuppInfo

== Leg Termination ==

Terminating a call leg is a 2 steps process:
# Call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::TerminateCall '''TerminateCall()''']
# Free leg object on [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminated '''OnCallTerminated()''']

When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resources freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Free '''Free()'''] on the leg's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::SetFreeListener '''SetFreeListener()'''] on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is deleted. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.

[[Image:TerminateCall from application.jpg|thumb|center|350px|Call flow for leg termination initiated by user application]]

In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other media resource or signaling error. In these cases, the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminatingIndication '''OnCallTerminatingIndication()'''] is sent to the leg. On reception of this event, the application should initiate call termination as shown below.

[[Image:TerminateCall from Toolpack.jpg|thumb|center|350px|Call flow for leg termination initiated by Toolpack]]

In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnLegTerminated '''OnLegTerminated()'''] event. This event indicates that the leg does not exist anymore on the Toolpack side and the user should free its object without trying any other interaction with Toolpack through it.

== Leg Synchronization on Failover ==
When a Toolpack application is restarted or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs through the '''OnCallLegSync()''' event of the [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_lib_user.html ITBCMCLibUser] interface (this interface must be implemented by all user applications). One event will be received for each leg being synchronized. The course of action to take when receiving a leg synchronization event depends on the ability of the application to resynchronize its states with theses legs.

* If the application can't resynchronize active legs or if it does not want to resychronize the leg for which it is receiving an '''OnCallLegSync()''' event, it must refuse the leg by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLeg '''RefuseLeg()'''].
*If the application wants the resynchronize the leg or if it does not yet have enough information to decide, it must create a CTBCMCLeg object using the leg attributes received in the event.

Once all '''OnCallLegSync()''' have been sent, Toolpack will start synchronization of the links between legs through '''OnLinkSync()'''. This event indicates that two legs are connected together. It can be used by the application to rebuild its internal states. As for the legs, unwanted links can be refused by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()'''].

When all links have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. At that moment, the application has all the information available on the Toolpack side to determine if the legs should be kept or release. Any leg that the application does not want to keep can be refused by calling '''RefuseLeg()''' on it. For all legs that have not been refused, an event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnSyncDone '''OnSyncDone()'''] will be sent on the leg. Once this event has been received on a leg, the leg is fully functional and the application can start calling any usual Toolpack function on it.

[[Image:CallFlow Sync After Application Restart.jpg|thumb|center|350px|Call flow for leg synchronization]]

===Loss of Communication with Toolpack Engine===
If communication is lost with the Toolpack Engine, event '''OnCmcLibNotReady()''' will be sent to the application. It indicates that the Toolpack framework is no more accessible. The legs are still valid at that time but no action can be executed on them as long the CmcLib is not ready. If the connection with the Toolpack Engine is not back up in less than 10 seconds, the CmcLib will declare a major communication loss and will call '''OnLegTerminated()''' on all the legs. In that case, when communication is regained with the Toolpack Engine, the synchronization sequence will start again from the beginning.

[[Image:CallFlow Sync After Comm Restart Passed 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart passed 10 seconds.]]

If the communication is regained before the 10 seconds timeout, event '''OnCmcLibReady()''' will be sent and the application can then continue working normally with its existing call legs. Note that you can also receive '''OnLegTerminated()''' on some legs before receiving the '''OnCmcLibReady()''' if those legs were in a transient state when disconnection occurred.

[[Image:CallFlow Sync After Comm Restart Within 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart within 10 seconds.]]

== Bridging the Media Path ==
=== Join ===

To bridge the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Join '''Join()'''] on one of the leg, giving the second leg as a parameter. This will connect the media path between the two legs according to the link properties set on the leg on which '''Join()''' is called. These link properties can be modified by overloading the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetJoinAttributes '''GetJoinAttributes()''']. The important attribute to set is '''IsFullDuplex()''' that indicates if the connection will be made full-duplex (A<-->B) or half-duplex (A-->B). Prior to release 2.5.2, the default connection mode is half-duplex. For all release version 2.5.2 or higher, the default connection mode is full-duplex.

'''Warning:''' If two legs are already connected in half-duplex and you want to connect them in full-duplex, you must first Unjoin() the legs, then Join() them in full-duplex. You can '''NOT''' only do another half-duplex in the opposite direction.

When legs are joined, it creates a link identified with a unique ''link id''. It is the responsibility of the application to provide this unique ''link id'' by implementing the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetLinkId '''GetLinkId()'''] function of the leg. It is planned to allow the user to provide a value of '0' to let the Toolpack system automatically choose a ''link id'', but as of this writing this feature is not yet available.

'''Warning:''' When two legs are joined, the application must ensure that '''GetLinkId()''' on both leg will return the right ''link id''. This will ensure that when the link needs to be removed, both A->Unjoin() and B->Unjoin() will work correctly.

==== Setting the link properties ====

In your leg class, add a member variable to store the join attributes for that leg.

CTBCMC_JOIN_ATTRIBUTE mJoinAttribute;

Then set the join properties you want in your leg class constructor (or at any other location that will run '''before''' the '''Join()''' is done:

mJoinAttribute.IsFullDuplex() = TBX_TRUE;

Last, implement the '''GetJoinAttributes()''' function.

CTBCMC_JOIN_ATTRIBUTE & CH248Termination::GetJoinAttributes()
{
return mJoinAttribute;
}

==== Broadcasting a media source ====
At the time of writing this, broadcast of a single media source to multiple destinations is not yet possible.

=== Unjoin ===
To disconnect the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Unjoin'''Unjoin()'''] on any of the legs. The '''GetLinkId()''' function of the leg on which '''Unjoin()''' is called must return the ''link id'' that was used when the legs were joined.

[[category:CAF]]
[[category:Needs revising]]

CAF: Working With Call Legs

2010-02-09T20:42:27Z

Alexandre Lussier: /* Playing and Collecting Tones */

== Call Leg Definition ==
The main mechanism through which the customer application controls the [[Toolpack]] system is via the management of call legs. The application creates a call leg (or more than one for conferencing and bridging) at the beginning of a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.

A call leg is represented by an instance of the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html CTBCMCLeg] class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 [[timeslot]]) or a [[SIP]] call with its associated [[VOIP]] [[Voice codecs|codec]] resource (attached to an IP/UDP endpoint). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (VOIP codec resource attached to an IP/UDP endpoint). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.

The CTBCMCLeg class allows a programmer to easily act upon the call leg to influence the signaling portion (e.g. accept, answer, terminate, etc) and to use the media portion as well (e.g play prompts, record voice, play or collect digits and tones).

Other member functions are available to retrieve (and change in some cases) the call leg attributes including the media profile (e.g. parameters to the media resource) or signaling information (e.g. protocol type, called and calling party numbers, etc). Joining/unjoining (connection/disconnection) of call legs is also a typical action handled by this class for ’gateway-type’ applications. It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, [[ISDN]], SS7, Media only, etc).

===== Caveats =====
* Do not confuse a ''call leg'' with a ''call''. A ''call leg'' represents one full-duplex link to a party while a ''call'' represents the agglomeration of multiple (two or more) call legs. For example, a ''bridge'' is a form of ''call'' that uses two ''call legs''.
* Do not confuse the base class CTBCMCLeg with the class [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_leg.html CTBCAFCallLeg]. The later is an implementation class specialized to be used by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs. It is designed to represent a leg within a call. It cannot be instanciated as a standalone object without modifications to make it independent from the ITBCAFCallFlow interface.
* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

== Command Flow for Leg Actions in CAF ==
All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).

For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.

== Leg Creation ==
Creating a leg is always done through the definition of a ''call leg attribute''. The values entered in the ''call leg attribute'' will define the type of call leg created and its parameters. The following sections describe several scenarios in which you build a ''call leg''. Instruction will be given on how to fill the leg attributes and how to use them to create the ''call leg''.

=== Preparing Leg Attributes ===

==== Normal Call Leg Attributes ====
For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
* the called number,
* the calling number,
* the [[NAP | Network Access Point]].

Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|NAP Types]]).

The following code snippet shows how to build the attributes.
PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();

ptrOutgoingLegAttribute->GetCalledNumber() = "123-4567";
ptrOutgoingLegAttribute->GetCallingNumber() = "987-6543";
ptrOutgoingLegAttribute->GetNetworkAccessPoint() = "NAP_SS7_MONTREAL";

==== Media-only Leg Attributes ====
For media-only legs, no signaling information is needed but the user can specify which media channel to use and which media profile to use. The only required parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''MEDIA TDM'' or ''MEDIA VOIP'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;

ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();

ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;

When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. For ''MEDIA TDM'' NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For ''MEDIA VOIP'' NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and a timeslot number can be specified.

PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc->Settings.TdmAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
pMediaDesc->Settings.TdmAudio.un8Timeslot = 5;
Strncpy
(
pMediaDesc->Settings.TdmAudio.szTrunkName,
"TRUNK_TORONTO_1",
sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
);

For VOIP legs, the user can control the media by providing local [[SDP]] and peer SDP. Setting the local SDP defines the codec and IP/port used to for the received media stream. Most of the time, the IP address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and IP/port used for the transmitted media stream. Note that Toolpack only allows for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in '''both''' SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].

TBX_RESULT Result;
TBX_SDP_INFO SdpInfo;
PTBCMC_MEDIA_DESCRIPTION pMediaDesc;

pMediaDesc = ptrLegAttribute->GetProfile().GetMediaDescription();
pMediaDesc->Settings.PacketAudio.Type = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;

// Set Local SDP
Result = BuildSdpInfo("", 0, SdpInfo); // No IP specified, Toolpack will choose one
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

// Set Peer SDP
Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo); // Using peer IP address and port
TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
ptrLegAttribute->GetProfile().SetPeerSDP(SdpInfo);

=== Creating the Leg ===
Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CreateCall '''CreateCall()'''] on it. No action is taken when an instance of a CTBCMCLeg is created. Call resources are only allocated in the Toolpack system when '''CreateCall()''' is called on the object.

pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
pCallLeg->CreateCall();

For legs with signaling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).

[[Image:CallFlow SignalingMediaLeg Creation.JPG|thumb|center|350px|Call flow for creation of leg with signaling]]

For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.

[[Image:CallFlow MediaOnlyLeg Creation.JPG|thumb|center|350px|Call flow for media-only leg creation]]

Once a call is fully active (call answered and media allocated), event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnProfileChanged '''OnProfileChanged()'''] will be sent on the leg. In the cases where the user had not specified the IP/port to use, once this event is received, the media profile has been updated with the values chosen by Toolpack and the updated values can be retrieved using the functions '''GetLocalSDP()''' and '''GetPeerSDP()''' of the profile.
Note that the '''OnProfileChanged()''' event is also sent after the media profile has been modified with the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ChangeProfile '''ChangeProfile()'''] function (see [[#Modifying Media Profile|Modifying Media Profile]]) and when a connected peer has requested it (through a SIP re-INVITE for example).

See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.

=== Caveats ===
* The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).

== Interaction with Legs ==

=== Playing and Collecting Digits ===
You can add tones you want to play by using [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html#CTBCMC_EVENT_ATTRIBUTE::AddToneString '''AddToneString()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___e_v_e_n_t___a_t_t_r_i_b_u_t_e.html CTBCMC_EVENT_ATTRIBUTE] class.
You can then play digits defined by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayDigit '''PlayDigit()'''] on a leg. Toolpack will receive the request and play the digits. Once digits are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitPlayingDone '''OnDigitPlayingDone()'''] event.

You can also configure a leg to collect digits played. To start the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartDigitCollection '''StartDigitCollection()'''] on the leg. Note that you will have to specify which digits you want to collect before starting the digit collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the digit collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopDigitCollection '''StopDigitCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnDigitCollected '''OnDigitCollected()'''] event on each digit received that correspond to a tone string specified with the previously call to '''AddToneString()'''.

=== Playing and Collecting Tones ===
You can add tones you want to play by using '''AddToneString()''' available in CTBCMC_EVENT_ATTRIBUTE class.
You can then play events by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayEvent '''PlayEvent()'''] on a leg. Toolpack will receive the request and play the events. Once events are played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventPlayingDone '''OnEventPlayingDone()'''] event. Note that you can cancel an event to be played by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::CancelEvent '''CancelEvent()'''] on the leg after a '''PlayEvent()''' has been called.

Two kinds of string can be passed to '''AddToneString()''' to play a tone. The first type is to play well known tones such as dtmf and fax tone. The syntax is really simple and is based on H248 package and signal ids. The first component of the string is the package id and the second is the signal id, both formated in string. So, to play dtmf 0, you have to format the following string: "dg/d0", where "dg" is for package "dtmf generation" and "d0" is for "dtmf 0".

The second type of string is to play custom tone such as ring tone. The syntax is much complicated than the first one, but it follows a well described syntax which can be found in [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.6-200011-I!!PDF-E&type=items/.pdf '''H248.6 Dynamic Tone Definition Package''']. This kind of string allows you to specify frequencies, duration, amplitude and repeating count of the tone. You can also specify well known tones and change their default duration, amplitude and repeating count. It is possible to describe a sequence of tones or frequencies that are played in one segment. Here are some examples of the syntax:

*;Frequencies 400Hz and 600Hz mixed together for 200ms, amplitude at -10dB and repeating 3 times (playing 4 times):
:*(((#400)+(#600)),200,-10)*3
:
*;Dtmf 5 repeated infinitly:
:*((0x0005,0x0015))*0
:
*;Multifrequency tone 8:
:*((mfg,mf8))
:
*;Frequency 440Hz played for 300ms at -10dB followed by frequency 600Hz played for 200ms at -5dB and then followed by dtmf 2, all this repeated infinitly:
:*((#440,300,-10),(#600,200,-5),(0x0005,0x0012))*0
:

You can also configure a leg to collect events played. To start the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StartEventCollection '''StartEventCollection()'''] on the leg. Note that you will have to specify which events you want to collect before starting the event collection by calling '''AddToneString()''' on a CTBCMC_EVENT_ATTRIBUTE object. To stop the event collection, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopEventCollection '''StopEventCollection()''']. A leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnEventCollected '''OnEventCollected()'''] event on each event received that correspond to a tone string specified with the previously call to '''AddToneString()'''.

Only one string is accepted to collect events. The string is the same as the first type to play event. Signal ids that are also event id are accepted. This means that you can ask to collect "dg/d0" (dtmf generation/dtmf 0) and the detection will be done anyway. But, when the event is detected, it's the event id that will be returned, which means that "dd/d0" (dtmf detection/dtmf 0) will be returned instead of "dg/d0".

The most commonly used package are 5 and 6 [http://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.248.1-200509-I!!PDF-E&type=items/.pdf '''(H248.1 Annex E)''']: dtmf generation and dtmf detection. As H248 does not define events and signals for fax tone, we added a special package to do so. Package tbfax (0x0251) contains three events and two signals: cng (0x0080), g164 (0x0081) and only for detection g165 (0x0082).

=== Collecting digits and tones while call legs are joined ===
By default, when two call legs are joined together through function CTBCMCCallLeg::Join(), tone collection is automatically disabled.
One of the arguments of the Join() function ("in_fDisableToneWhileJoined") will allow to control if automatic tone collection feature is used or not on a call.

Why is Toolpack disabling tone collection on joined legs by default?
That's because tone collection introduces a 40ms delay in the audio connection (required to provide tone suppression), and most of the time it is no more require to collect digits while two call legs are joined, so it would be useless to leave 40ms delay while tone collection is no more required.

=== Playing and Recording Audio Files ===
You can play an audio stream on a leg by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PlayStream '''PlayStream()'''] on it. To specify which audio stream you want to play, you have to specify it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html#CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath '''AddPlayFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___p_l_a_y___a_t_t_r_i_b_u_t_e.html CTBCMC_PLAY_ATTRIBUTE] class. Toolpack will receive the request and play the stream. Once it is played, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingDone '''OnStreamPlayingDone()'''] event.

You can also configure a leg to record an audio stream. First you must specify file paths to record by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html#CTBCMC_RECORD_ATTRIBUTE::AddRecFilePath '''AddRecFilePath()'''] available in [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c___r_e_c_o_r_d___a_t_t_r_i_b_u_t_e.html CTBCMC_RECORD_ATTRIBUTE] class. The you can call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RecordStream '''RecordStream()'''] on a leg. Once the stream is recorded, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamRecordingDone '''OnStreamRecordingDone()'''] event.

You can pause an active playing or recording stream by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::PauseStream '''PauseStream()'''] and you can resume it by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::ResumeStream '''ResumeStream()''']. If you want to stop an active playing or recording stream, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::StopStream '''StopStream()'''] on the leg.

=== Modifying Media Profile ===
It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.

The media profile is stored in the leg attributes and can be modified like this :
TBX_SDP_INFO SdpInfo;
PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;

pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
pMediaLegAttribute->GetProfile().GetLocalSDP(SdpInfo);
Strncpy
(
SdpInfo.aConnections[0].szIp,
"",
sizeof( SdpInfo.aConnections[0].szIp )
);
SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
pMediaLegAttribute->GetProfile().SetLocalSDP(SdpInfo);

pCallLeg->ChangeProfile();

Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotiation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.

Once the profile change has completed (or failed), event '''OnProfileChanged()''' will be received on the leg.

For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.

=== Controlling the Signaling ===
When a call leg receives the '''OnCallLegPresent()''' event, it indicates an incoming call. To confirm that the call contains sufficient valid information to process the call on the system, you have to call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AcceptCall '''AcceptCall()'''] on the leg. If a call leg receives the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAccepted '''OnCallAccepted()'''] event, it means that an outgoing call has been accepted by the remote peer. This event usually means that the calling number has been accepted and that the call is currently being processed.

After an incoming call has been accepted, a call leg can notify the remote peer that the incoming call has been put in the "ringing" state by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AlertCall '''AlertCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAlerting '''OnCallAlerting()'''] event when an outgoing call has been put in the "ringing" state by the remote peer.

When an incoming call is answered, a call leg can notify the remote peer of the incoming call answered by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::AnswerCall '''AnswerCall()''']. In the same way, a call leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallAnswered '''OnCallAnswered()'''] event when an outgoing call has been answered by the remote peer.

SendCallSuppInfo/OnCallSuppInfo

== Leg Termination ==

Terminating a call leg is a 2 steps process:
# Call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::TerminateCall '''TerminateCall()''']
# Free leg object on [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminated '''OnCallTerminated()''']

When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resources freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Free '''Free()'''] on the leg's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by calling [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::SetFreeListener '''SetFreeListener()'''] on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is deleted. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.

[[Image:TerminateCall from application.jpg|thumb|center|350px|Call flow for leg termination initiated by user application]]

In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other media resource or signaling error. In these cases, the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnCallTerminatingIndication '''OnCallTerminatingIndication()'''] is sent to the leg. On reception of this event, the application should initiate call termination as shown below.

[[Image:TerminateCall from Toolpack.jpg|thumb|center|350px|Call flow for leg termination initiated by Toolpack]]

In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnLegTerminated '''OnLegTerminated()'''] event. This event indicates that the leg does not exist anymore on the Toolpack side and the user should free its object without trying any other interaction with Toolpack through it.

== Leg Synchronization on Failover ==
When a Toolpack application is restarted or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs through the '''OnCallLegSync()''' event of the [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_lib_user.html ITBCMCLibUser] interface (this interface must be implemented by all user applications). One event will be received for each leg being synchronized. The course of action to take when receiving a leg synchronization event depends on the ability of the application to resynchronize its states with theses legs.

* If the application can't resynchronize active legs or if it does not want to resychronize the leg for which it is receiving an '''OnCallLegSync()''' event, it must refuse the leg by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLeg '''RefuseLeg()'''].
*If the application wants the resynchronize the leg or if it does not yet have enough information to decide, it must create a CTBCMCLeg object using the leg attributes received in the event.

Once all '''OnCallLegSync()''' have been sent, Toolpack will start synchronization of the links between legs through '''OnLinkSync()'''. This event indicates that two legs are connected together. It can be used by the application to rebuild its internal states. As for the legs, unwanted links can be refused by calling the static function [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::RefuseLink '''RefuseLink()'''].

When all links have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. At that moment, the application has all the information available on the Toolpack side to determine if the legs should be kept or release. Any leg that the application does not want to keep can be refused by calling '''RefuseLeg()''' on it. For all legs that have not been refused, an event [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnSyncDone '''OnSyncDone()'''] will be sent on the leg. Once this event has been received on a leg, the leg is fully functional and the application can start calling any usual Toolpack function on it.

[[Image:CallFlow Sync After Application Restart.jpg|thumb|center|350px|Call flow for leg synchronization]]

===Loss of Communication with Toolpack Engine===
If communication is lost with the Toolpack Engine, event '''OnCmcLibNotReady()''' will be sent to the application. It indicates that the Toolpack framework is no more accessible. The legs are still valid at that time but no action can be executed on them as long the CmcLib is not ready. If the connection with the Toolpack Engine is not back up in less than 10 seconds, the CmcLib will declare a major communication loss and will call '''OnLegTerminated()''' on all the legs. In that case, when communication is regained with the Toolpack Engine, the synchronization sequence will start again from the beginning.

[[Image:CallFlow Sync After Comm Restart Passed 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart passed 10 seconds.]]

If the communication is regained before the 10 seconds timeout, event '''OnCmcLibReady()''' will be sent and the application can then continue working normally with its existing call legs. Note that you can also receive '''OnLegTerminated()''' on some legs before receiving the '''OnCmcLibReady()''' if those legs were in a transient state when disconnection occurred.

[[Image:CallFlow Sync After Comm Restart Within 10sec.jpg|thumb|center|350px|Call flow for leg synchronization after a communication restart within 10 seconds.]]

== Bridging the Media Path ==
=== Join ===

To bridge the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Join '''Join()'''] on one of the leg, giving the second leg as a parameter. This will connect the media path between the two legs according to the link properties set on the leg on which '''Join()''' is called. These link properties can be modified by overloading the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetJoinAttributes '''GetJoinAttributes()''']. The important attribute to set is '''IsFullDuplex()''' that indicates if the connection will be made full-duplex (A<-->B) or half-duplex (A-->B). Prior to release 2.5.2, the default connection mode is half-duplex. For all release version 2.5.2 or higher, the default connection mode is full-duplex.

'''Warning:''' If two legs are already connected in half-duplex and you want to connect them in full-duplex, you must first Unjoin() the legs, then Join() them in full-duplex. You can '''NOT''' only do another half-duplex in the opposite direction.

When legs are joined, it creates a link identified with a unique ''link id''. It is the responsibility of the application to provide this unique ''link id'' by implementing the [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::GetLinkId '''GetLinkId()'''] function of the leg. It is planned to allow the user to provide a value of '0' to let the Toolpack system automatically choose a ''link id'', but as of this writing this feature is not yet available.

'''Warning:''' When two legs are joined, the application must ensure that '''GetLinkId()''' on both leg will return the right ''link id''. This will ensure that when the link needs to be removed, both A->Unjoin() and B->Unjoin() will work correctly.

==== Setting the link properties ====

In your leg class, add a member variable to store the join attributes for that leg.

CTBCMC_JOIN_ATTRIBUTE mJoinAttribute;

Then set the join properties you want in your leg class constructor (or at any other location that will run '''before''' the '''Join()''' is done:

mJoinAttribute.IsFullDuplex() = TBX_TRUE;

Last, implement the '''GetJoinAttributes()''' function.

CTBCMC_JOIN_ATTRIBUTE & CH248Termination::GetJoinAttributes()
{
return mJoinAttribute;
}

==== Broadcasting a media source ====
At the time of writing this, broadcast of a single media source to multiple destinations is not yet possible.

=== Unjoin ===
To disconnect the media path between two legs, one must call [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::Unjoin'''Unjoin()'''] on any of the legs. The '''GetLinkId()''' function of the leg on which '''Unjoin()''' is called must return the ''link id'' that was used when the legs were joined.

[[category:CAF]]
[[category:Needs revising]]