CAF Bridge class
This class is an implementation of the CAF Call interface.
The CTBCAFBridge class represents the agglomeration of one incoming call leg and 1-to-n multiple outgoing call legs with the final purpose of joining (i.e. connecting) two of those legs together at the media level, thus creating a bridge between a calling and a called party. The class can handle one incoming call leg and multiple outgoing call legs in the signaling establishment phase although it will only try to connect two together. If the application programmer is looking for this behavior, then this class can be used in three different ways described below. If, on the other hand, the desired behavior is significantly different than this class’s implementation, it is advised to create a new class inheriting from CAF Call interface.
- The first approach is to use an instance of the class natively (i.e., no inheritance) to bridge one incoming leg to one outgoing leg. Each of these legs (actually information about these legs) are given to the object instance upon creation. From there, the object will automatically handle the call states for each leg and bridge them together once the outgoing legs has reached the ’answer’ state. It will handle failure/disconnection cases, will gracefully terminate the remaining leg and free itself at the end. It is important to note that because of the underlying CTBCMCCallLeg, this class is protocol-agnostic and can bridge any type of supported call legs (e.g. SIP/VoIP, ISDN, SS7, etc).
- The second approach is to modify the default behavior of this class by using ’behaviors’. This is explained in the Behaviors section. See the ’caveats’ about when to use (or not) this method.
- The third and last approach is to actually create a new class inheriting from CTBCAFBridge and to overload one or many member functions to create the desired behavior. The example below shows how to achieve this.
Usage
Although a typical application using this class would connect two call legs together (thus achieving a bridge), the following example shows an application where multiple outgoing call legs are created waiting for the first one to answer.
Follow-me application : In this example, we want to create multiple outgoing call leg, wait until the called party answers, disconnects all the other outgoing call legs and, finally, connect the incoming call leg with the remaining (answered) outgoing call leg. This application is really a ’follow-me’ behavior where one phone number is called to try to reach a person on its mobile phone, home phone and work phone. The first one to answers is actually connected to the calling party.
The application needs to create an instance of a CTBCAFBridge when it receives an incoming call from the network passing the incoming call attributes (calling/called numbers, input NAP, etc) using the AddIncoming() method. Before starting the processing, it also instructs the object to create the outgoing call legs by passing the outgoing call attributes (calling/called numbers, output NAP, etc) using the AddOutgoing() method. Once all the attributes are set, the code starts the processing by calling the InitCall() method of the object. From that point, all outgoing legs are being generated automatically.
*** Make sure that the call attributes and protocol attributes objects passed to AddIncoming() and AddOutgoing() remain valid until InitCall() function has returned.
Until this point, there is no need to have a specialized class derived from CTBCAFBridge to achieve this behavior. However, the application needs to make a decision when any of the outgoing call legs gets into the ’answered’ state. Thus, it is required for the class to overload the OnCallLegAnswered() method from CTBCAFBridge. Doing so, our code will be executed once one leg gets into the ’answered’ state. The only thing left to do is to instruct the object to terminate all other outgoing call legs and to let the base class do its regular job (being connect an outgoing and incoming leg together).
The CTBCAFBridge internal data flow offers an in-depth understanding of the flow of events leading to each member function calls.
Caveats
- Do not confuse a call with a call leg. A call leg represents one full-duplex link to a party while a call represents the agglomeration of multiple (two or more) call legs. In the previous example (follow-me), the call was actually handling up to 5 call legs (1 incoming and 4 outgoing legs).
- This base class is designed to free itself when the proper conditions are met. Thus, the ’freeListener’ interface will be called automatically when these conditions are reached (i.e. all internal call legs are terminated and all processing is done). Termination can occur in case of normal call legs termination (e.g. called/calling party hang-up) or during error processing (e.g. abnormal condition signaled by one of the internal call legs).
- Modifying the behavior of this class can be achieved through either inheritance (as shown in the above example) or using ’behaviors’ as described in Call behavior classes. In case where multiple different combinations of behaviors are optionally desired on a single instance of a call (e.g. follow-me, ring-back-tones, relay-to-voicemail), it is preferred to use the ’behavior’ approach rather than inheritance as the number of resulting classes using inheritance may be become very high (e.g. one class to support follow-me with ring-back-tone, one other class to support follow-me and relay-to-voice-mail, one other class to support all of them, etc).
- The CTBCAFBridge use the class CTBCAFCallLeg internally to handle legs. Although any custom code within a derived class will use the CTBCAFCallLeg, the application designer must be aware to never actually instantiate an object of the type CTBCAFCallLeg. This class was designed to be natively used in the context of a ITBCAFCall interface
Classes
- ITBCAFCall
- CTBCAFCall
Return to the Toolpack User Guide
