|
|
| (212 intermediate revisions by 8 users not shown) |
| Line 1: |
Line 1: |
| − | == Call Leg Definition ==
| + | TelcoBridges Toolpack framework offers two API layers to manipulate call legs and audio mixers (conferences). |
| − | 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 a call, then controls it through a simple, protocol-agnostic API. When a call is terminated, the call leg can be destroyed.
| + | |
| | | | |
| − | A call leg is represented by an instance of the CTBCMCLeg class. It represents a full-duplex media resource and/or its associated signaling entity. Typical examples of call legs with signaling would be an [[SS7]] [[ISUP]] call with its associated [[Circuit identification code|CIC]] (mapped to a [[TDM]] interface such as a T1 timeslot) or a SIP call with its associated [[VOIP]] [[Voice codecs|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). The section titled [[CAF:_Working_With_Call_Legs#Leg Creation| Leg Creation ]] will show how different types of call legs can be created.
| + | We recommend that developers use the CAF API layer, as it offers higher-level functionality which accelerate application development. |
| | | | |
| − | 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).
| + | == 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 send requests to perform actions (answer, play, terminate, etc.). |
| | | | |
| − | ===== Caveats =====
| + | 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 |
| − | * 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.
| + | [[CAF:_Working_With_Cmc_Call_Legs|Working with CMC Call Legs]] |
| − | * 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.
| + | |
| | + | == CAF API layer == |
| | | | |
| − | | + | A higher-level API uses the base classes ''CTBCMCLeg'' and ''CTBCMCMixer'', but adds the following functionalities: |
| − | == Command Flow for Leg Actions in CAF ==
| + | - Simplification of call legs creations through single functions (''AddIncoming'', ''AddOutgoing'', ''CreateMixer'') |
| − | All actions requested on a leg are executed asynchronously. For each action '''DoSomething()''' on a leg, a corresponding '''OnDoSomethingResponse()''' event will be received on the leg once Toolpack starts processing the command. If the '''OnXXXResponse()''' function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function '''OnLegError()''' will be called. Most of the actions executed on a leg can take variable time to complete. In these case, an extra event will be received on the leg once the action is complete ('''OnXXXResponse()''' is always called when Toolpack '''starts''' executing the action).
| + | - 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. |
| − | For example, to play a digit sequence, one would call '''PlayDigit()'''. It would then almost immediately receive the '''OnPlayDigitResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the leg. Once the digits play is completed, the user will receive an '''OnDigitPlayingDone()''' event.
| + | |
| − | | + | |
| − | | + | |
| − | == Leg Creation ==
| + | |
| − | 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 its 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''.
| + | |
| − | | + | |
| − | '''TO-DO Present call flow for leg creation'''
| + | |
| − | | + | |
| − | | + | |
| − | === Preparing Leg Attributes ===
| + | |
| − | | + | |
| − | ==== Normal Call Leg Attributes ====
| + | |
| − | For calls including both the signaling and the media path, there is very few parameters that one must enter. The required parameters are:
| + | |
| − | * the called number,
| + | |
| − | * the calling number,
| + | |
| − | * the [[NAP | Network Access Point]].
| + | |
| − | | + | |
| − | Toolpack will automatically select an available channel in the specified NAP to make the call leg. Only NAPs of type ''SS7'', ''ISDN'' or ''SIP'' can be specified for call leg attribute (see [[NAP#NAP Types|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 parameters are the [[NAP | Network Access Point]] and the leg type. Only NAPs of type ''TDM Media'' or ''VOIP Media'' can be specified for media-only leg attribute (see [[NAP#NAP Types|NAP Types]]).
| + | |
| − | | + | |
| − | PTRCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE ptrLegAttribute;
| + | |
| − |
| + | |
| − | ptrLegAttribute = tbnew CTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE();
| + | |
| − | ptrLegAttribute->GetNetworkAccessPoint() = "NAP_MEDIA_1";
| + | |
| − |
| + | |
| − | pMediaDesc = ptrLegAttribute->GetProfile()->MediaDescription;
| + | |
| − | pMediaDesc->Type = TBCMC_MEDIA_TYPE_AUDIO;
| + | |
| − | pMediaDesc->Transport = TBCMC_MEDIA_TRANSPORT_TDM or TBCMC_MEDIA_TRANSPORT_IP;
| + | |
| − | | + | |
| − | When only the NAP and type are specified, Toolpack will automatically select an available channel in the specified NAP to allocate the media path. 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 a timeslot number can be specified.
| + | |
| − | | + | |
| − | PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
| + | |
| − |
| + | |
| − | 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 allows 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 needed for SetLocalSDP and SetPeerSDP, see [[CAF:_Filling_SDP_Structures|Filling an SDP Structures]].
| + | |
| − | | + | |
| − | TBX_RESULT Result;
| + | |
| − | TBX_SDP_INFO SdpInfo;
| + | |
| − | PTBCMC_MEDIA_DESCRIPTION pMediaDesc;
| + | |
| − |
| + | |
| − | pMediaDesc = ptrLegAttribute->GetProfile()->MediaDescription;
| + | |
| − | 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 Toolpack system when '''CreateCall()''' is called on the object.
| + | |
| − | | + | |
| − | pCallLeg = new CTBCMCLeg( mun32LegId++, ptrLegAttribute, this, 0, &mLegMutex );
| + | |
| − | pCallLeg->CreateCall();
| + | |
| − | | + | |
| − | For legs with signalling, the '''CreateCall()''' will trigger the sending of the call setup message (SIP Invite, SS7 IAM, etc.). In that case, the media resources are not allocated immediately. They will be allocated only when the signaling part of the call setup is complete. If the application requests a media action (PlayFile, StartDigitCollection, etc.) on the leg, this will immediately trigger the allocation of the media resources even if the call is not yet answered (used for early media for example).
| + | |
| − | | + | |
| − | For media-only legs, the media ressources will always be allocated as soon as '''CreateCall()''' is called.
| + | |
| − | | + | |
| − | Once a call is fully active (call answered and media allocated), event '''OnProfileChangeComplete()''' will be sent on the leg. Note that this event is also sent after the media profile has been modified with the '''ChangeProfile()''' function (see [[#Modifying Media Profile|Modifying Media Profile]]).
| + | |
| − | | + | |
| − | | + | |
| − | See [[CAF:_Leg_Creation_Samples|Leg creation example]] for sample code of leg creation in different scenarios.
| + | |
| − | | + | |
| − | === Caveats ===
| + | |
| − | * The call leg attribute is an object containing the call leg information (called/calling numbers, media profile, etc) that needs to be allocated by the caller and used when creating the leg object. It will be freed automatically when the leg is destroyed (it uses a shared-pointer so it is in fact destroyed when there are no more reference to it).
| + | |
| − | | + | |
| − | | + | |
| − | == Interaction with Legs ==
| + | |
| − | | + | |
| − | === Playing and Collecting Digits ===
| + | |
| − | PlayDigit
| + | |
| − | OnDigitPlayingDone
| + | |
| − | StartDigitCollection
| + | |
| − | StopDigitCollection
| + | |
| − | OnDigitCollected
| + | |
| − | | + | |
| − | | + | |
| − | === Playing and Collecting Tones ===
| + | |
| − | PlayEvent
| + | |
| − | CancelEvent
| + | |
| − | OnEventPlayingDone
| + | |
| − | StartEventCollection
| + | |
| − | StopEventCollection
| + | |
| − | OnEventCollected
| + | |
| − | === Playing and Recording Audio Files ===
| + | |
| − | PlayStream/OnStreamPlayingDone
| + | |
| − | RecordStream/OnStreamRecordingDone
| + | |
| − | PauseStream/ResumeStream
| + | |
| − | StopStream
| + | |
| − | | + | |
| − | | + | |
| − | === Modifying Media Profile ===
| + | |
| − | It is always possible to modify the media profile of a leg after it was created. This can be used for example to change to a more compressed codec if bandwidth resources become sparse or to switch to T.38 Fax after a fax tone was detected.
| + | |
| − | | + | |
| − | The media profile is stored in the leg attributes and can be modified either by:
| + | |
| − | * using helper functions directly on the attribute:
| + | |
| − | TBX_SDP_INFO SdpInfo;
| + | |
| − | PCTBCMC_MEDIA_ONLY_LEG_ATTRIBUTE pMediaLegAttribute;
| + | |
| | | | |
| − | pMediaLegAttribute = pCallLeg->GetAttributes().GetMediaOnlyLegAttribute();
| + | The following page explains how to work with CAF Call leg framework (CTBCAFCallLeg, CTBCAFCallFlow, CTBCAFCallBehavior, etc...) |
| − | pMediaLegAttribute->GetLocalSDP(SdpInfo);
| + | |
| − | Strncpy
| + | |
| − | (
| + | |
| − | SdpInfo.aConnections[0].szIp,
| + | |
| − | "",
| + | |
| − | sizeof( SdpInfo.aConnections[0].szIp )
| + | |
| − | );
| + | |
| − | SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 0;
| + | |
| − | pMediaLegAttribute->AlterBySDP( &SdpInfo, TBCMC_MEDIA_PROFILE_ALTERATION_TYPE_SDP_SET );
| + | |
| | | | |
| − | pCallLeg->ChangeProfile();
| + | [[CAF:_Working_With_Caf_Call_Legs|Working with CAF Call Legs and behaviors]] |
| − | * getting the profile from the attribute, then modifying it:
| + | |
| − | CTBCMC_MEDIA_PROFILE MediaProfile;
| + | |
| − | MediaProfile.GetMediaDescription() = in_ptrMediaLegAttr->GetProfile()->MediaDescription;
| + | |
| − | in_ptrMediaLegAttr->GetLocalSDP(SdpInfo);
| + | |
| − | Strncpy
| + | |
| − | (
| + | |
| − | SdpInfo.aConnections[0].szIp,
| + | |
| − | "",
| + | |
| − | sizeof( SdpInfo.aConnections[0].szIp )
| + | |
| − | );
| + | |
| − | SdpInfo.Capabilities.aCapGroups[0].aSimultaneousCap[0].un16UdpPort = 10500;
| + | |
| − | MediaProfile.AlterBySDP( &SdpInfo, TBCMC_MEDIA_PROFILE_ALTERATION_TYPE_SDP_SET );
| + | |
| − |
| + | |
| − | pCallLeg->SetProfile( MediaProfile );
| + | |
| − | | + | |
| − | Once the attributes have been modified, '''ChangeProfile()''' must be called to activate the new profile. In the case of media-only legs, activating a modified profile will immediately reallocate the media resources. In the case of a SIP call leg, activating the new profile will trigger a new negotitation with the peer (INVITE-RESPONSE) after which the media resources will be allocated using the newly negotiated codecs.
| + | |
| − | | + | |
| − | Once the profile change has completed (or failed), event '''OnProfileChangeComplete()''' will be received on the leg.
| + | |
| − | | + | |
| − | For SIP call leg, if the peer entity sends us re-INVITE with a new SDP during a call, the media resource will be automatically updated and event '''OnProfileChanged()''' will be received on the leg.
| + | |
| − | | + | |
| − | === Controlling the Signalling ===
| + | |
| − | AcceptCall/OnCallAccepted
| + | |
| − | AlertCall/OnCallAlerting
| + | |
| − | AnswerCall/OnCallAnswered
| + | |
| − | SendCallSuppInfo/OnCallSuppInfo
| + | |
| − | | + | |
| − | | + | |
| − | == Leg Termination ==
| + | |
| − | | + | |
| − | Terminating a call leg is a 2 step process:
| + | |
| − | # Call '''TerminateCall()'''
| + | |
| − | # Free leg object on '''OnCallTerminated()'''
| + | |
| − | | + | |
| − | When '''TerminateCall()''' is called, the Toolpack framework will start leg termination. This includes media resource freeing and, for leg with signaling, sending of the appropriate signaling message to terminate the call. Once the media resources have been deallocated and call termination signaling is done, Toolpack will call '''OnCallTerminated()''' on the leg. When this event is received on the leg, this leg no more exists in Toolpack and the object can thus be freed. At the end of the '''OnCallTerminated()''' handler, the default implementation of class CTBCMCLeg will call method '''Free()''' on the leg's ITBCMCFreeListener interface. The ITBCMCFreeListener to use can be specified either in the CTBCMCLeg constructor and by call '''SetFreeListener''' on the leg. The leg can be it's own ''FreeListener'', in which it just 'delete' itself when its '''Free()''' method is called. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the leg is delete. An example could be the case where the leg object was allocated from a pool and it should be returned to that pool instead of being deleted.
| + | |
| − | | + | |
| − | | + | |
| − | '''TO-DO Call flow for leg termination initiated by user application'''
| + | |
| − | | + | |
| − | In some situation, it is possible that leg termination be initiated by Toolpack. This can happen for leg with signaling, when a call termination request is received on the signaling channel. It can also happen on any type of leg in the event of sudden media resource unavailability and other internal error. In these cases, the '''OnCallTerminatingIndication()''' is sent to the leg. On reception of this event, the application should initiate call termination as shown above.
| + | |
| − | | + | |
| − | '''TO-DO Call flow for leg termination initiated by Toolpack'''
| + | |
| − | | + | |
| − | == Leg Synchronization on Failover ==
| + | |
| − | RefuseLeg
| + | |
| − | OnLegSync
| + | |
| − | OnLinkSync
| + | |
| − | OnSyncDone
| + | |
| − | | + | |
| | | | |
| | + | The following page provides more details on call legs re-synchronization between toolpack_engine application and user "CAF" application: |
| | | | |
| − | [[category:CAF]] | + | [[CAF:_Call_Legs_Resync|Re-synchronizing CAF call legs]] |
| − | [[category:Needs revising]]
| + | |
TelcoBridges Toolpack framework offers two API layers to manipulate call legs and audio mixers (conferences).
We recommend that developers use the CAF API layer, as it offers higher-level functionality which accelerate application development.
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
The following page explains how to work with CAF Call leg framework (CTBCAFCallLeg, CTBCAFCallFlow, CTBCAFCallBehavior, etc...)
The following page provides more details on call legs re-synchronization between toolpack_engine application and user "CAF" application:
