CAF: Working With Call Legs

Call Leg Definition

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.

A call leg is respresented by an instance of the class CTBCMCLeg. It represents a full-duplex media resource and/or its associated signalling entity. Typical examples of call leg with signaling 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). A media-only call leg would represent a standalone TDM endpoint (such as a T1 timeslot) or a VOIP endpoint (Voip codec resource attached to an IP/UDP endpoint). Section Creating Call Legs will show how different types of leg can be created.

The CTBCMCLeg 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).

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 CTBCAFCallLeg. The later is an implementation class specialized to be 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 without 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 for leg creation instead of creating call legs manually. This class already deals with the issues of handling multiple legs simultaneously.

Creating Call Legs

Creating a leg is always done through the definition of a call leg attribute. The values entered in the call leg attribute will define the type of call leg created and it's parameters. The following sections describe several scenarios in which you build a call leg. Instruction will be given on how to fill the leg attributes and how to use them to create the call leg.

TODO Present call flow for leg creation.

Preparing Leg Attributes

Normal Call Leg Attributes

For calls including both the signalling and the media path, there is very few parameters that one must enter. The required parameters are:

• the called number,
• the calling number,
• the Network Access Point.

Toolpack will automatically select an available channel in the specified NAP to make the call. Only NAPs of type SS7, ISDN or SIP can be specified for call leg attribute (see NAP Types).

The following code snippet shows how to build the attributes.

   PTRCTBCMC_CALL_LEG_ATTRIBUTE ptrOutgoingLegAttribute;
 
   ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();
 
   ptrOutgoingLegAttribute->GetCalledNumber()            = "123-4567";
   ptrOutgoingLegAttribute->GetCallingNumber()           = "987-6543";
   ptrOutgoingLegAttribute->GetNetworkAccessPoint()      = "NAP_SS7_MONTREAL";

Media-only Leg Attributes

For media-only legs, no signaling information is needed, but the user can specify which media channel to use and which media profile to use. The only required parameter is the Network Access Point. Only NAPs of type TDM Media or VOIP Media can be specified for media-only leg attribute (see NAP Types).

   PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;
 
   ptrLegAttribute= tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
   ptrLegAttribute->GetNetworkAccessPoint()      = "NAP_SS7_MONTREAL";

When only the NAP is specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media channel. For TDM Media NAPs, a trunk/timeslot from the specified NAP will be chosen by Toolpack. For VOIP Media NAPs, an IP interface and port from the specified NAP will be chosen.

If the user wants to specify which media channel to use, it can do so by adding extra information in the leg attribute. For TDM legs, a trunk name and timeslot number can be specified.

   PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
 
   pMediaDesc = ptrLegAttribute->GetProfile()->MediaDescription;
   pMediaDesc->Type                                    = TBCMC_MEDIA_TYPE_AUDIO;
   pMediaDesc->Options                                 = TBCMC_MEDIA_OPTIONS_NONE;
   pMediaDesc->Transport                               = TBCMC_MEDIA_TRANSPORT_TDM;
   pMediaDesc->Settings.TdmAudio.Type                  = TBCMC_MEDIA_SETTINGS_TYPE_TDM_AUDIO;
   pMediaDesc->Settings.TdmAudio.un8Timeslot           = 5;
   Strncpy
   (
       pMediaDesc->Settings.TdmAudio.szTrunkName, 
       "TRUNK_TORONTO_1", 
       sizeof(pMediaDesc->Settings.TdmAudio.szTrunkName)
   );

For VOIP legs, the user can control the media by providing local SDP and peer SDP. Setting the local SDP defines the codec and ip/port used to for the received media stream. Most of the time, the ip address and port should be left empty to let Toolpack choose an available port. Setting the peer SDP defines the codec and ip/port used for the transmitted media stream. Note that Toolpack only allow for the same codec to be used in RX and TX. If both local SDP and peer SDP are specified, codecs that are not in both SDP will be filtered out.

For details on how to fill the TBX_SDP_INFO structure needeed for SetLocalSDP and SetPeerSDP, see [Customer_Application_Framework_:_Filling_SDP_Structure|Filling an SDP Structure]].

   TBX_RESULT               Result;
   TBX_SDP_INFO             SdpInfo;
   PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
 
   pMediaDesc = ptrLegAttribute->GetProfile()->MediaDescription;
   pMediaDesc->Type                                    = TBCMC_MEDIA_TYPE_AUDIO;
   pMediaDesc->Options                                 = TBCMC_MEDIA_OPTIONS_NONE;
   pMediaDesc->Transport                               = TBCMC_MEDIA_TRANSPORT_IP;
   pMediaDesc->Settings.PacketAudio.Type               = TBCMC_MEDIA_SETTINGS_TYPE_PACKET_AUDIO;
 
   // Set Local SDP
   Result = BuildSdpInfo("", 0, SdpInfo);                 // No IP specified, Toolpack will choose one
   TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
   ptrLegAttribute->SetLocalSDP(&SdpInfo);
 
   // Set Peer SDP
   Result = BuildSdpInfo("10.0.0.15", 5000, SdpInfo);     // Using peer IP address and port
   TBCAF_EXIT_ON_ERROR( Result, "BuildSdpInfo failed." );
   ptrLegAttribute->SetPeerSDP(&SdpInfo);

Creating the Leg

Once the leg attributes have been filled, creating the leg in Toolpack is only a matter of creating a CTBCMCLeg object and calling CreateCall() on it. No action is taken when an instance of a CTBCMCLeg is creating. Call resources are only allocated in the Toolapck system when CreateCall() is called on the object.

 pCallLeg = new CTBCMCLeg( mun32LegId++, ptrOutgoingMediaOnlyLegAttribute, this, 0, &mLegMutex );
 pCallLeg->CreateCall();

See Leg creation example

Caveats

• 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.