CMC Call Leg class
(New page: include this link in the description Call Leg) |
(added core text and image ; need to format) |
||
| Line 1: | Line 1: | ||
| + | include this link in the description | ||
| + | A [[Call Leg|call leg]] is .... | ||
| − | + | [[Image:CTBCMCCallLeg Hierarchy.jpg]] | |
| + | |||
| + | An instance of the class CTBCMCCallLeg represents a combination of one full-duplex media resource and its associated | ||
| + | signalling entity. Typical examples 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). | ||
| + | This 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, etc). | ||
| + | |||
| + | |||
| + | == Usage == | ||
| + | |||
| + | Although a typical application connects call legs together to achieve a bridge, the following example show an application | ||
| + | where outgoing call leg is created to handle the signaling, play a prompt and disconnect. | ||
| + | Pager application : In this example, we want to create an outgoing call leg, wait until the called party answers, play | ||
| + | a message (prompt) and disconnect the call leg. This can be achieved by creating a custom class for our application | ||
| + | inheriting from the CTBCMCCallLeg class. Since we only want to act when the called party answers the phone, | ||
| + | we only need to overload the base class member function OnCallAnswered() and insert the piece of code to play the | ||
| + | prompt there. As the prompt playing is asynchronous, we want to terminate the call leg only once the complete prompt | ||
| + | is played. To do so, overloading the OnStreamPlayDone() base class member function. When it is called, we act on | ||
| + | the call leg by calling the base class Terminate() member function. The call will then terminate itself. | ||
| + | |||
| + | |||
| + | |||
| + | == 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 CTBCMCCallLeg with the class CTBCAFCallLeg. The later is a class 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. Therefore, the above example used the CTBCMCCallLeg. | ||
| + | *If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the | ||
| + | CTBCAFBridge class instead. This class already deals with the issues of handling multiple legs simulteanously. | ||
| + | *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 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. | ||
| + | |||
| + | |||
| + | == Classes == | ||
| − | [[ | + | *[[CTBCMCLeg]] |
| + | *[[ITBCMCCallLeg]] | ||
Revision as of 14:00, 6 July 2009
include this link in the description
A call leg is ....
An instance of the class CTBCMCCallLeg represents a combination of one full-duplex media resource and its associated signalling entity. Typical examples 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). This 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, etc).
Usage
Although a typical application connects call legs together to achieve a bridge, the following example show an application where outgoing call leg is created to handle the signaling, play a prompt and disconnect. Pager application : In this example, we want to create an outgoing call leg, wait until the called party answers, play a message (prompt) and disconnect the call leg. This can be achieved by creating a custom class for our application inheriting from the CTBCMCCallLeg class. Since we only want to act when the called party answers the phone, we only need to overload the base class member function OnCallAnswered() and insert the piece of code to play the prompt there. As the prompt playing is asynchronous, we want to terminate the call leg only once the complete prompt is played. To do so, overloading the OnStreamPlayDone() base class member function. When it is called, we act on the call leg by calling the base class Terminate() member function. The call will then terminate itself.
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 CTBCMCCallLeg with the class CTBCAFCallLeg. The later is a class 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. Therefore, the above example used the CTBCMCCallLeg.
- If the overall goal is to bridge two or more call legs together, then the programmer would be advised to use the
CTBCAFBridge class instead. This class already deals with the issues of handling multiple legs simulteanously.
- 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 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.
