CAF: Working With Caf Call Legs

Revision as of 13:10, 7 April 2011

Overview

CAF Call leg (CTBCAFCallLeg):

The CTBCAFCallLeg is the representation of communication with one peer, through one protocol (SS7, ISDN, SIP, CAS).

They can be created either after the toolpack_engine has notified the CAF application that a new call has been received, or else when the CAF application asks toolpack_engine to create a new outgoing call. When creating a new outgoing call, attributes are provided to indicate toolpack_engine which NAP to make the call to (which also defines the signaling protocol), which calling/called numbers to use, etc.

From the C++ point of view, the CTBCAFCallLeg class is a wrapper around the CTBCMCLeg object. It's enhancing the CTBCMCLeg object so multiple call legs can be grouped and managed together from a parent Call object (CTBCAFCallFlow).

CAF Call Flow (CTBCAFCallFlow):

The CTBCAFCallFlow base class contains one or multiple CTBCAFCallLeg objects. The role of the CTBCAFCallFlow object is to implement a call flow that involves actions on legs that have a relation with each other.

CAF Call Bridge (CTBCAFBridge, based on CTBCAFCallFlow):

A typical implementation of a call flow is the CTBCAFBridge class (based on the CTBCAFCallFlow base class). This class is designed to - Receive an incoming call - Make a corresponding outgoing call - Join them together - Terminate both of them when one leg hangups.

CAF Call Behavior (CTBCAFCallBehavior):

Behaviors CTBCAFCallBehavior can be attached to a call flow (CTBCAFCallFlow). Their role is to modify the basic call flow, decorating it with optional functionality (CDR logging, FAX detection, Ring tone playback, etc.)

Actions on call legs

The call flow can perform various actions on each of it's call legs. Here is a list of the actions available on the CTBCAFCallLeg objects (please refer to the header files CTBCMCLeg.hpp for more information on each of these functions).

Controlling call flow:

- AcceptCall()
- AlertCall()
- AnswerCall()
- ProgressCall()
- SendCallSuppInfo()
- Join()
- Unjoin()
- TerminateCall()
- CallTransferRequest()
- CallTransferProgress()
- CallTransferResponse()

Playing/recording audio

- PlayStream()
- RecordStream()
- PauseStream()
- ResumeStream()
- StopStream()

Digits (tone) and events:

- PlayDigit()
- StartDigitCollection()
- StopDigitCollection()
- PlayEvent()
- CancelEvent()
- StartEventCollection()
- StopEventCollection()

Controlling profile or stats:

- SetProfile()
- ChangeProfile()
- GetStats()

States can be queried instantly:

IsTerminating()
IsAccepted()
IsAlerted()
IsAnswered()
IsSynchronized()
IsJoined()

Call information can be queried instantly:

GetLegId()
GetLinkId()
GetAttributes()
GetProfile()
GetJoinAttributes()

Events received from call legs by the CTBCAFCallFlow object

Initialization and termination of call leg objects:

- OnInitIncomingCallLeg()
- OnInitOutgoingCallLeg()
- OnLegFreed()

Controlling call flow:

- OnCallLegAccepted()
- OnCallLegAlerting()
- OnCallLegAnswered()
- OnCallLegSuppInfo()
- OnLegJoinDone()
- OnLegUnjoinDone()
- OnCallLegTerminatingIndication()
- OnCallLegTerminated()
- OnLegTerminated()
- OnCallLegTransferRequest()
- OnCallLegTransferProgress()
- OnCallLegTransferResponse()

Re-synchronization with toolpack_engine:

- OnSyncDone()
- OnSyncLost()

Timers or custom events:

- OnLegEvent()

Errors detected by toolpack_engine:

- OnLegError()

Playing/recording audio

- OnStreamPlayingDone()
- OnStreamRecordingDone()

Digits (tone) and events:

- OnDigitPlayingDone()
- OnDigitCollected()
- OnEventPlayingDone()
- OnEventCollected()

Controlling profile or stats:

- OnLegProfileChanged()
- OnLegStatsUpdated()

Events behavior chain

All the events describe above are called consecutively on each behavior attached to the call flow, and ultimately, called on the call flow itself.

Each behavior in the chain can

• Pass the event to the next behavior in the chain
• Consume the event so other behaviors in the chain and the call flow are unaware that this event occurred

The CTBCAFCallBehavior default implementation is to forward the event to the next event in the chain.

When you implement your own behaviors, you can override only a couple of events (like OnCallLegAnswered() for example) to perform specific tasks, and leave all other events to the base class, so you don't have to write a lot of code to create a new behavior.

Creating the CTBCAFCallFlow object and it's legs

Steps to create a new call flow are:

• Create a new object (using a class derived from CTBCAFCallFlow class)
• Attach behaviors to the call flow
• Add attributes of incoming and outgoing legs to create
• Tell the call flow object to initialize itself, and create the call legs as requested

Here is an example:

ITBCAFCallFlow* pCallFlow;
ITBCAFCallFlow* pParentCallOrBehavior;

// Create the call flow object (here using the CTBCAFBridge class, based on CTBCAFCallFlow)
pCallFlow = tbnew CTBCAFBridge( 0, this);

// Optionally, attach behaviors
pParentCallOrBehavior = pCallFlow;
pParentCallOrBehavior = tbnew CTBCAFCallBehaviorBusyTone( pParentCallOrBehavior, ... );
pParentCallOrBehavior = tbnew CTBCAFCallBehaviorBridgeCdr( pParentCallOrBehavior, ... );

// Add an incoming call leg to that call flow (CTBCAFCallLeg object will get created based on provided attributes)
pCallFlow->AddIncoming( in_LegId, ptrIncomingLegAttribute, ptrIncomingLegProtocolAttributes, ptrAcceptCallProtAttribute );

// Add an outgoing call leg
pCallFlow->AddOutgoing( ptrOutgoingLegAttribute, ptrOutgoingLegProtocolAttributes );

// Initialize the call (this actually creates the call legs)
pCallFlow->InitCall( &pCallFlow );

For a more complete code example, please refer to the simple_call application, in file CTBS2GWSimpleCall.cpp file, or here:

[CTBCAFBridge creation]

Constructing leg attributes

Incoming call leg attributes

To create the incoming call leg, the following information is required:

• Smart pointer to incoming call leg attributes, received from toolpack_engine through OnCallLegPresent().

ptrIncomingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE( *(in_CallLegAttribute.GetCallLegAttribute()) );

• Smart pointer to incoming call leg attributes, received from toolpack_engine through OnCallLegPresent().

ptrIncomingLegProtocolAttributes = tbnew CTBCMC_PROTOCOL_ATTRIBUTE( in_ProtocolAttribute, TBX_TRUE );

• Smart pointer to empty protocol attributes that Behaviors can fill, and that will be used when accepting the call

Outgoing call leg attributes

To create the outgoing call leg, the following information is required:

• Smart pointer to outgoing call leg attributes to use to create the call, generally derived from the incoming call attributes

ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();
ptrOutgoingLegAttribute->CopyLegAttributeFrom( *(ptrIncomingLegAttribute.Get()) );

• Smart pointer to empty protocol attributes that Behaviors can fill, and that will be used when creating the outgoing call (SIP invite, ISUP IAM, ISDN Setup, etc.)

Destruction the CTBCAFCallFlow object and it's legs

The CTBCAFCallFlow object contains smart pointers to it's call legs. Destruction of these call legs will thus occur when removing the last smart pointer reference to the pointed call leg object.

The CAF framework is responsible to determine when a call leg needs to be destroyed, and will call the function OnLegFreed() of all behaviors and of the CTBCAFCallFlow object itself. When CTBCAFCallFlow::OnLegFreed is called, the smart pointer to that leg is removed (eventually causing leg destruction).

Also upon destruction of the last call leg, object based on CTBCAFCallFlow or CTBCAFCallBehavior will delete themselves automatically, by calling the attached "free listener" (that was provided in the constructor of the call flow object).