CAF: Working With Cmc Call Legs - Revision history

Allyntree at 14:59, 6 September 2022

2022-09-06T14:59:41Z

Allyntree: Revised language f article and removed the needs revising category since this article is old.

2018-02-22T20:22:08Z

Revised language f article and removed the needs revising category since this article is old.

← Older revision		Revision as of 16:22, 22 February 2018
Line 424:		Line 424:

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

	== Using timers ==		== Using timers ==

Allyntree: /* Playing and Recording Audio Files */ typo

2018-02-22T20:20:29Z

Playing and Recording Audio Files: typo

← Older revision		Revision as of 16:20, 22 February 2018
Line 271:		Line 271:

	=== Playing and Recording Audio Files ===		=== 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 ~~started~~ playing, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingStarted '''OnStreamPlayingStarted()'''] event. 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 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 starts playing, the leg will receive [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_leg.html#CTBCMCLeg::OnStreamPlayingStarted '''OnStreamPlayingStarted()'''] event. 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.
	It is possible to play multiple files simultaneously to the same call leg. Audio from all files will be mixed.		It is possible to play multiple files simultaneously to the same call leg. Audio from all files will be mixed.

Allyntree: /* Choosing a unique LegId */ typo

2018-02-22T20:15:28Z

Choosing a unique LegId: typo

← Older revision		Revision as of 16:15, 22 February 2018
Line 111:		Line 111:
	Each leg must be assigned a unique LegId.		Each leg must be assigned a unique LegId.

	* The LegId of incoming call legs is chosen by Toolpack system and provided to the application upon [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_lib_user.html#CTBCMCLibUser::OnCallLegPresent'''OnCallLegPresent()''']. This LegId must provided when creating the new CTBCMCLeg object.		* The LegId of incoming call legs is chosen by the Toolpack system and provided to the application upon [https://docs.telcobridges.com/mediawiki/autodoc/class_c_t_b_c_m_c_lib_user.html#CTBCMCLibUser::OnCallLegPresent'''OnCallLegPresent()''']. This LegId must be provided when creating the new CTBCMCLeg object.
	* For outgoing call legs (or media only legs), the LegId 0 should be passed to the constructor of CTBCMCLeg, which will assign an appropriate LegId to that call leg.		* For outgoing call legs (or media only legs), the LegId 0 should be passed to the constructor of CTBCMCLeg, which will assign an appropriate LegId to that call leg.
	* For re-synchronized call legs, the LegId is passed by Toolpack upon OnCallLegSync(), and must be used for re-creating the CTBCMCLeg object.		* For re-synchronized call legs, the LegId is passed by Toolpack upon OnCallLegSync(), and must be used for re-creating the CTBCMCLeg object.

Allyntree: /* Normal Call Leg Attributes */

2018-02-22T20:03:56Z

Normal Call Leg Attributes

← Older revision		Revision as of 16:03, 22 February 2018
Line 43:		Line 43:

	==== Normal Call 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:		For calls including both the signaling and the media path, there are very few parameters that one must enter. The required parameters are:
	* the called number,		* the called number,
	* the calling number,		* the calling number,
	* the [[NAP \| Network Access Point]].		* 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]]).		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 the call leg attribute (see [[NAP#NAP Types\|NAP Types]]).

	The following code snippet shows how to build the attributes.		The following code snippet shows how to build the attributes.

Allyntree: /* Command Flow for Leg Actions */ style

2018-02-22T20:02:48Z

Command Flow for Leg Actions: style

← Older revision		Revision as of 16:02, 22 February 2018
Line 34:		Line 34:

	== Command Flow for Leg Actions ==		== Command Flow for Leg Actions ==
	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).		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 a variable amount of time to complete. In this 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.


	~~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 ==		== Leg Creation ==

Allyntree: /* Audio Mixer Definition */ Style

2018-02-22T20:00:13Z

Audio Mixer Definition: Style

← Older revision		Revision as of 16:00, 22 February 2018
Line 22:		Line 22:

	== Audio Mixer Definition ==		== Audio Mixer Definition ==
	In addition of ~~joining~~ call legs ~~together~~ to ~~make~~ audio flow between them, another option is to join call legs to audio mixers.		In addition to the joining of call legs to have audio flow between them, another option is to join call legs to audio mixers.
	Audio mixers can be used, among other things, to:		Audio mixers can be used, among other things, to:
	* Build conferences		* Build conferences

Allyntree: /* Recommendation */ style

2018-02-22T19:58:23Z

Recommendation: style

← Older revision		Revision as of 15:58, 22 February 2018
Line 14:		Line 14:

	===== Recommendation =====		===== Recommendation =====
	We recommend developers to use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_flow.html CTBCAFCallFlow] model for managing call legs. This higher-level framework offers various advantages over managing call legs individually through CTBCMCLeg class.		We recommend that developers use the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_call_flow.html CTBCAFCallFlow] model for managing call legs. This higher-level framework offers various advantages over managing call legs individually through CTBCMCLeg class.

	An example of CTBCAFCallFlow usage is [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class. This class deals with a call bridge that includes two main call legs communicating with each other, and can be decorated with other behaviors that may provide play, record, lawful interception or other functionalities around the two main "bridged" call legs.		An example of CTBCAFCallFlow usage is [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_c_t_b_c_a_f_bridge.html CTBCAFBridge] class. This class deals with a call bridge that includes two main call legs communicating with each other, and can be decorated with other behaviors that may provide play, record, lawful interception or other functionalities around the two main "bridged" call legs.

Allyntree: /* Caveats */ typo

2018-02-22T19:57:03Z

Caveats: typo

← Older revision		Revision as of 15:57, 22 February 2018
Line 11:		Line 11:
	===== Caveats =====		===== 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 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.		* 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 latter 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.

	===== Recommendation =====		===== Recommendation =====

Lucas Trottier at 14:09, 11 July 2016

2016-07-11T14:09:52Z

← Older revision		Revision as of 10:09, 11 July 2016
Line 183:		Line 183:


	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". A comprehensive list of all the available well known tones is available in the [[Tone_definitions#Available_tones\|Tone definitions article]].		Two kinds of string can be passed to '''AddToneString()''' to play a tone.

	===== Play Tone with Signal Id String =====		===== Play Tone with Signal Id String =====
			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". A comprehensive list of all the available well known tones is available in the [[Tone_definitions#Available_tones\|Tone definitions article]].

	<code><pre>		<code><pre>
	/* this will play dtmf 7 */		/* this will play dtmf 7 */
Line 198:		Line 200:
	</pre></code>		</pre></code>

			===== Play Tone with Custom Tone String=====
	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:		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:

Line 214:		Line 216:
	:		:

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

			===== Collect Tone =====
			ou 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()'''.

	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.

	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>		<code><pre>
	/* this will collect all dtmf tones */		/* this will collect all dtmf tones */