CAF: Working With Call Legs: Difference between revisions

Latest revision as of 10:44, 6 September 2022

TelcoBridges Toolpack framework offers two API layers to manipulate call legs and audio mixers (conferences).

We recommend that developers use the CAF API layer, because it offers higher-level functionality, which accelerates application development.

CMC API layer

The lower-level API is based on classes CTBCMCLeg and CTBCMCMixer. These classes allow receiving leg or mixer events (answered, digit collected, terminating, etc.), and sending requests to perform actions (answer, play, terminate, etc.).

The following page explains how to work with CTBCMCLeg directly, for lower-level applications that don't want the convenience of the CAF Call framework

Working with CMC Call Legs

CAF API layer

A higher-level API uses the base classes CTBCMCLeg and CTBCMCMixer, but adds the following functionalities: - Simplification of call legs creations through single functions (AddIncoming, AddOutgoing, CreateMixer) - Centralizing reception of events from call legs and mixers in to a single "Call Flow" (CTBCAFCallFlow), which deals with inter-relations between legs and mixers. - Auto-destruction of call legs (CTBCMCLeg) and mixers (CTBCMCMixer) through usage of "smart" pointers. - Auto-destruction of the call flow (CTBCAFCallFlow) upon destruction of last leg/mixer.

The following page explains how to work with CAF Call leg framework (CTBCAFCallLeg, CTBCAFCallFlow, CTBCAFCallBehavior, etc...)

Working with CAF Call Legs and behaviors

The following page provides more details on call legs re-synchronization between toolpack_engine application and user "CAF" application:

Re-synchronizing CAF call legs

@@ Line 1: / Line 1: @@
-= Introduction =
+{{DISPLAYTITLE:CAF: Working With Call Legs}}
-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 call, then control it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.
+TelcoBridges Toolpack framework offers two API layers to manipulate call legs and audio mixers (conferences).
-An instance of the class CTBCMCCallLeg represents a combination of one full-duplex media resource and its associated
+We recommend that developers use the CAF API layer, because it offers higher-level functionality, which accelerates application development.
-signalling entity. Typical examples would be an SS7 ISUP call with its associated CIC (mapped to a TDM
-interface such as a T1 timeslot) or a SIP call with its associated Voip codec resource (attached to an IP/UDP endpoint).
-This 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).
+==  CMC API layer ==
-===== Caveats =====
+The lower-level API is based on classes ''CTBCMCLeg'' and ''CTBCMCMixer''. These classes allow receiving leg or mixer events (answered, digit collected, terminating, etc.), and sending requests to perform actions (answer, play, terminate, etc.).
-* 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 CTBCMCCallLeg with the class CTBCAFCallLeg. The later is a class used by
-the ITBCAFCall interface when dealing with multiple legs. It is designed to represent a leg within a call. It
-cannot be instanciated as a standalone object with modifications to make it independent from the ITBCAFCall interface.
-* If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the
-CTBCAFBridge class instead. This class already deals with the issues of handling multiple legs simulteanously.
-* The call leg attribute is an object containing the call leg information (called/calling numbers, etc) that needs
-to be allocated by the caller (in this example the ’main’) and given to the call leg object. It will be freed
-automatically when the leg is destroyed.
-* The base class does not automatically free itself. This is why the member function OnCallTerminated() was
-overloaded to actually instruct the base class to start the freeing operation once the signaling call is done. In
-CMC User’s Guide
-another type of application, some steps could be required before the actual leg free is desired (such as logging,
-DB access, etc).
-* The ’delete’ operation on the call leg is eventually done by the object exposing the ’freeListener’ interface. This
-allows the application to centralize (if required) the ownership of objects to a single entity. This means that
-an object could also self-delete if it is given its own ’freeListener’ interface pointer. This all depends on the
-hierarchy of object owership the application designer wants to do.
-== Creating Call Legs ==
+The following page explains how to work with CTBCMCLeg directly, for lower-level applications that don't want the convenience of the CAF Call framework
+[[CAF:_Working_With_Cmc_Call_Legs|Working with CMC Call Legs]]
+== CAF API layer ==
-=== When Should Call Legs be Created ===
+A higher-level API uses the base classes ''CTBCMCLeg'' and ''CTBCMCMixer'', but adds the following functionalities:
-==== When Doing a Standalone Outgoing Call ====
+- Simplification of call legs creations through single functions (''AddIncoming'', ''AddOutgoing'', ''CreateMixer'')
-==== When Bridging an Incoming Call ====
+- Centralizing reception of events from call legs and mixers in to a single "Call Flow" (''CTBCAFCallFlow''), which deals with inter-relations between legs and mixers.
-==== When Creating a Media-only Leg ====
+- Auto-destruction of call legs (''CTBCMCLeg'') and mixers (''CTBCMCMixer'') through usage of "smart" pointers.
+- Auto-destruction of the call flow (''CTBCAFCallFlow'') upon destruction of last leg/mixer.
+The following page explains how to work with CAF Call leg framework (CTBCAFCallLeg, CTBCAFCallFlow, CTBCAFCallBehavior, etc...)
+[[CAF:_Working_With_Caf_Call_Legs|Working with CAF Call Legs and behaviors]]
+The following page provides more details on call legs re-synchronization between toolpack_engine application and user "CAF" application:
+[[CAF:_Call_Legs_Resync|Re-synchronizing CAF call legs]]