CAF: Working With Caf Call Legs

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();
// 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.