CMC library

Latest revision as of 10:21, 30 May 2011

CMC Library – CMC stands for Call & Media Control – is a C-based message-driven API that was designed to enable object-oriented, asynchronous event handling of call legs. It removes the complexity of media resource management while easing the bridging of call legs that employ different protocols (SS7, ISDN, CAS, SIP, etc.). Through the use of a signaling-agnostic message API, CMC Library simplifies the requirement for the customer’s application to control signaling along with the associated media.

CMC Library sits between Toolpack Engine and the customer application. It provides the customer application with a message-based API to communicate with Toolpack Engine. CMC Library forwards requests from the customer application to Toolpack Engine and returns response/event messages from Toolpack Engine to the customer application and is responsible for thread management.

CMC Library is an asynchronous framework used by the Customer Application Framework (CAF) and is not normally accessed by developers who would usually interact with the CAFClass library. The CAFClass library provides C++ wrapper classes that ease the handling of call leg state machines and remove the burden of creating an asynchronous framework while allowing synchronous operations within a call flow (e.g., access to a database) to work without affecting other legs. However, if an existing application already has its own asynchronous framework for handling call states, the software developer might choose to use CMC Library API directly.

Although it is still possible to ‘tweak’ parameters (i.e., information elements, SDPs, etc.) with CMC Library, doing so is optional. Therefore, applications requiring special control over signaling will still be able to do their things as long as they do not affect the system state. A typical example is for an application to send proprietary information into a SS7 primitive using the user-to-user information elements (IE) or to fill a specific IE with network-specific information. The CMC Library API also removes the responsibility of the customer’s application for creating and managing resources (e.g., resource allocation for IVR functions, resource allocation for VoIP functions, TB StreamServer access). These high-level functions enable the user to focus on value-added features and services instead of creating adaptation layer software. (e.g., an API ’CMD_PLAY’ that automatically allocated the IVR resources and tells the stream server to play an audio or video file onto a call leg). Although the protocols and resources handling are simplified, event driven handling of call legs is still required.

Initialization

This module should be initialized through the GlobalSetParams function. Parameters for this module are contained in class CTBCMCLibParams. Please refer to documentation in the C++ header files for class CTBCMCLibParams to know more about available parameters.

Key features

Key features of CMC Library include:

• Automatic CMC Server detection
• Automatic resynchronization of already created call legs and associated media.
• Providing automatic High Availability (HA) resynchronization capabilities in case of application failure/restart
• Automatic load sharing among running instances of CMC Server
• Thread pooling and call context serialization
• Enables more efficient use of CPU resources (thread, semaphores, etc).
• Synchronous operations on one call leg without affecting other legs.

High availability applications

CMC Library supports the high availability capabilities of Toolpack. This includes:

• Application can register as a backup application
• Automatic takeover of the service in the event an application goes down

Message types

CMC Library handles both request messages and event messages sent by the application to Toolpack engine through the CMC library.

• Request messages
  • Make call
  • Alert/Accept/Answer call
  • Join / unjoin legs
  • Play Stream, Record Stream, Stop Stream
  • Start/stop digit collection
  • Play digits

• Event messages
  • Incoming call present
  • Leg resync
  • Call terminating indication
  • Call alerting/accepted/answered
  • Stream play done, record stream done
  • Digit collected
  • Error report

Example usage

Documentation on how to use CMC Library can be found here:

CAF:_Working_With_Caf_Call_Legs

and here

CAF:_Leg_Creation_Samples

Below is an example that show how to initialize and terminate the CTBCMCLib module:

class MyApplication : public CTBCMCLibUser
{
	// your class definition

	// Functions inherited from CTBCMCLibUser
 	TBX_VOID OnCallLegPresent( TBCMC_LEG_ID in_LegId, CTBCMC_CALL_LEG_ATTRIBUTE_COMMON & in_CallLegAttribute, CTBCMC_PROTOCOL_ATTRIBUTE & in_ProtocolAttribute );
	// ... and many more...
};

TBX_RESULT MyApplication::Init()
{
	TBX_RESULT			Result = TBX_RESULT_OK;
	CTBCAFGlobalsParams	CafGlobalParams;
	CTBCMCLibParams		CmcLibParams;

	CafGlobalParams.mpCmcLibParams		= &CmcLibParams;
	// CafGlobalParams.mpLogParams		= [your paramters...]
	// CafGlobalParams.mpCliParams		= [your paramters...]
	// etc...

	Result = TBCAF::GlobalSetParam( &CafGlobalParams );

	if( TBX_RESULT_SUCCESS( Result ) )
	{
		// Attach this class to CMC library as receiver for callbacks such as OnCallLegPresent()
		Result = CTBCMCLib::Attach( this );
	}

	return Result;
}

TBX_RESULT MyApplication::UnInit()
{
	TBX_RESULT			Result = TBX_RESULT_OK;
	CTBCAFGlobalsParams	EmptyGlobalParams;

	// Terminate all CAF modules
	Result = TBCAF::GlobalSetParam( &EmptyGlobalParams );

	return Result;
}


TBX_VOID MyApplication::OnCallLegPresent
(
  IN	TBCMC_LEG_ID						in_LegId, 
  IN	CTBCMC_CALL_LEG_ATTRIBUTE_COMMON &	in_CallLegAttribute, 
  IN	CTBCMC_PROTOCOL_ATTRIBUTE &			in_ProtocolAttribute
)
{
	// Handle new incoming call...
}