CAF: Working With Cmc Call Legs - Revision history

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.

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

2018-02-22T20:20:29Z

Playing and Recording Audio Files: typo

Allyntree: /* Choosing a unique LegId */ typo

2018-02-22T20:15:28Z

Choosing a unique LegId: typo

Allyntree: /* Normal Call Leg Attributes */

2018-02-22T20:03:56Z

Normal Call Leg Attributes

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

2018-02-22T20:02:48Z

Command Flow for Leg Actions: style

Allyntree: /* Audio Mixer Definition */ Style

2018-02-22T20:00:13Z

Audio Mixer Definition: Style

Allyntree: /* Recommendation */ style

2018-02-22T19:58:23Z

Recommendation: style

Allyntree: /* Caveats */ typo

2018-02-22T19:57:03Z

Caveats: typo

Lucas Trottier at 14:09, 11 July 2016

2016-07-11T14:09:52Z

Abrassard: Added section about monitoring

2016-04-21T12:54:36Z

Added section about monitoring

@@ Line 424: / Line 424: @@
 [[category:CAF]]
-[[category:Needs revising]]
 == Using timers ==

@@ Line 271: / Line 271: @@
 === 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.

@@ Line 111: / Line 111: @@
 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 re-synchronized call legs, the LegId is passed by Toolpack upon OnCallLegSync(), and must be used for re-creating the CTBCMCLeg object.

@@ Line 43: / Line 43: @@
 ==== 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 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]]).
+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.

@@ Line 34: / Line 34: @@
 == 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 ==

@@ Line 22: / Line 22: @@
 == 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:
 * Build conferences

@@ Line 14: / Line 14: @@
 ===== 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.

@@ Line 11: / Line 11: @@
 ===== 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.
+* 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 =====

@@ 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 =====
 <code><pre>
 /* this will play dtmf 7 */
@@ Line 198: / Line 200: @@
 </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:
@@ Line 214: / Line 216: @@
+:
 <code><pre>
 /* this will play frequencies 1000Hz and 2100Hz mixed together */
@@ Line 227: / Line 228: @@
 </pre></code>
+===== Collect Tone =====
-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()'''.
+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()'''.
 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 */

← Older revision		Revision as of 12:54, 21 April 2016
Line 321:		Line 321:

	SendCallSuppInfo/OnCallSuppInfo		SendCallSuppInfo/OnCallSuppInfo
		+
		+
		+	=== Capturing (monitoring) HDLC ===
		+	Using the [[Toolpack_monitoring\|Monitoring]] capabilities, you can ask a media-only TDM call leg to capture HDLC (or other) data on the timeslot.
		+
		+	You can start monitoring by calling '''StartMonitoring()''', and providing monitoring parameters.
		+
		+	Monitoring allows to
		+	* Capture HDLC (or SS7-HDLC) packets from the timeslot
		+	* Capture RAW data (capture every byte from the timeslot)
		+	* Capture CAS bit changes from a Trunk (by using a Media-only Leg on timeslot 0)
		+
		+	Among the parameters:
		+	* Monitoring rate (64Kbps, 56Kbps, 48Kbps, 32Kbps, 16Kbps or 8Kbps)
		+	* Timeslot sub-index (for 32Kbps or less)
		+
		+	Once monitoring is ready on the hardware, the CTBCMCLeg object will be notified through '''OnMonitoringStarted()'''.
		+
		+	Upon capture of monitored data, the CTBCMCLeg object will be notified through '''OnMonitoringDataReceived()'''.

	== Leg Termination ==		== Leg Termination ==