CNF Conference Demo

The HMP CNF conference demo is a simple audio conferencing application that is implemented using CNF API from HMP Software. It is using GlobalCall API to handle call-control, Voice API to detect digits and play files and CNF API to maintain conferences. It is single threaded APP using SRL in polled mode.

1.2. Features

CNF demo demonstrates the following features:

Call control

Specify number of virtual boards, cc libraries and other parameters using gc_Start.
Waiting for call.
Answer to incoming call.
Detect disconnected state.
Drop and release the call.
Support for SIP and H323.
Using 3PCC mode
Handle errors.

Voice

Play file.
Detect digits.
Play tones.

Conference

Specify board parameters.
Detect maximal number of conferences and parties.
Specify conference parameters.
Specify party parameters.
Create conference.
Create conference party.
Add and remove from conference.
Play a tone to all parties in conference.
Record conference to a file.
Measure timeouts.

Device mapping

Detect configuration – voice, network and conference devices

2. Compilation

2.1. Windows

Use Microsoft C 6.0. Project name is CnfConferencingDemo.dsw.

2.2. Linux

Build debug version: make DEBUG=1 BUILD=_HMP31

Build release version: make

Build for Titusville: make BUILD=_HMP15

Build Debug version for Titusville: make BUILD=_HMP15 DEBUG=1

Add more compile flags, for example “-Wall”: make EXTRA_CXXFLAGS=”-Wall”

3. Configuration file conf_demo.cfg

You can configure the following parameters in file conf_demo.cfg:

3.1. Section [Common]

Contains common parameters:

CallControlMode. Operational mode. MODE_1PCC(default) or MODE_3PCC
ReserveResource: Specify how to reserve resources: via dev_ReserveResourceEx, dev_ReserveResource or not to reserve at all

For HMP releases, specify “Yes”(uses dev_ReserveResource) or “No”
For Titusville, specify “Ex” (uses dev_ReserveResourceEx)

LogFileName. Output log filename.
MaxLogSize. Maximum size in log messages (typically, one line per message). After reaching this number, cnf demo will create new log file.
PrintLevel. Each message is sent to output device with specific message type (level). The message is skipped, when its level is set to lower value than current Log object level (set via CGenLog::SetVerbosity). Otherwise message goes to output device. Different logs may have different verbosity levels. Possible levels ( in order lowest to highest level ) are:

DBG – Debug message.
API – Intel-Dialogic API.
EVT – Intel-Dialogic Event.
APP – Application flow.
WARNING – Intel-Dialogic API warning.
ERR1 – Intel-Dialogic API failure, will try to recover.
ERR2 – Intel-Dialogic API fatal error. Can’t recover, will exit.
ASSERT – Internal Cnf demo failure. Can’t recover, will exit.

Play file names

WelcomeFileName. Specify file name in quotes. Default is “welcome.pcm
BadPasscodeFileName. Specify file name in quotes. Default is “invalid.pcm
GoodByeFileName. Specify file name in quotes. Default is “bye.pcm”
CallLaterFileName. Specify file name in quotes. Default is “bye.pcm”

3.2. Section [Ipt]

Header Format: [Ipt <n>], where <n> is unique decimal number referred as ipt_id.

Contains IP front-end specific parameters:

NumberOfChannels. How many timeslots to open
IpProtocol. Use “SIP”, “H323” or “IP”
IpDigits. Digit type – use INBAND or RFC2833
IpCoder. You can use any name from enum eIPM_CODER_TYPE in file ipmlib.h such as CODER_TYPE_G711ALAW64K, CODER_TYPE_G711ULAW64K etc.
IpFrame. Specify frame size. See enum eIPM_CODER_FRAMESIZE in ipmlib.h.
IpVad. See enum eIPM_CODER_VAD in ipmlib.h.
PrivateLog. Log verbosity level for a separate log per timeslot. Set to “NONE” or skip this parameter to prevent creating this file.

3.3. Section [Dti]

This section contains PSTN front-end specific parameters.

NumberOfChannels. Use -1 to specify “all available”.
PrivateLog. Log verbosity level for a separate log per timeslot. Set to “NONE” or skip this parameter to prevent creating separate log file per dti timeslot.

3.4. Section [Board parameters]

ActiveTalker. Report Active talker. Specify “Yes” or “No” (without quotes...
ATInterval. Specify time interval to report active talkers (in seconds)
DTMFClamping. Specify Yes or No.
PrivateLog. Log verbosity level for a separate log per board. Set to “NONE” or skip this parameter to prevent creating separate log file per conference board.

3.5. Section [Conference]

Header Format: [Conference <n>], where <n> is unique decimal number referred as conf_id.

Parameters: PassCode, DetectDigits, DTMFClamping Tmo, VoiceParty, PrivateLog and BeepNotify. Each parameter except PassCode has default value and can be omitted. Passcode is mandatory, and must be unique across the file. Caller should enter this code followed by ‘#’ using DTMF digits in order to join conference. Parameters DetectDigits, DTMFClamping, BeepNotify and VoiceParty may have values Yes or No. DetectDigits specifies request to receive event GNFEV_DTMF_DETECTED. DetectDigits specifies request to clamp DTMF digits. VoiceParty is a request to include voice party into the conference in order to record it or play prompts. Currently, VoiceParty produces short beep when a party is added or removed to the conference. BeepNotify is request to notify automatically when party is added or removed to the conference (an alternative to the VoiceParty).

Tmo is maximum time that this conference is allowed to live with more than 0 parties (in seconds). Cnf demo will create separate conference for each section [conference] encountered in configuration file.

Example:

[Conference 12]

Passcode = 12345

DetectDigits = No

DTMFClamping = No

Tmo = 300 (max time in seconds)

BeepNotify=Yes

VoiceParty=No

PrivateLog=DBG

4. Execution

To start demo, execute program CnfConferencingDemo.

To end demo, press <Ctrl-C> or close console window. Be patient and wait until demo cleans up all resources correctly. Ungraceful stop may leave HMP software in improper state and cause failures next time when you run other HMP applications.

To join conference, call demo using SIP or H323 phone. Make sure demo parameters (coder, frame and protocol match your device). Example string to use: anything@146.152.10.10. Listen to the prompt and dial pass code for desired conference. You will hear short beep when somebody joins your conference if VoiceParty is enabled for this conference. Two short beeps indicate that a party has been removed and 3 short beeps indicate that conference timeout has expired and all conference parties will be closed immediately.

To bypass the prompt, use ‘c’ followed by conference code as party address when calling. For example, to join conference with pass code “1234”, call “c1234@146.152.10.10”.

You cannot start 2 instances of this demo on same host. You cannot use other SIP or H323 software (such as soft phone) on the same host unless other device can change default sip and H323 ports. In short, to use this demo you need at least 2 hosts or one host and one ip phone.

5. Call scenario

Cnf demo waits for incoming calls.
Cnf demo detects a call and answers.
If calling party matches ‘c’ and conference code, goto step 7. Example: to join immediately conference with pass code “12345”, call C12345@146.152.xx.yy (demo IP)
Cnf demo plays file WelcomeFileName. Play may be interrupted at any time by any DTMF digit. In this case, termination digit is considered as part of user response.
User enters a DTMF sequence terminated by ‘#’. ‘#” is not part of user response. Missing a digit for 10 sec is considered as end of input.
Cnf Demo searches for a conference by comparing as string conference PassCode to user specified digit sequence. If conference is not found, Cnf demo plays file BadPasscodeFileName and allows up to 3 attempts to recover. After 3^rd unsuccessful attempt, Cnf demo plays file GoodByeFileName, drops and releases the call and proceeds with (1).
Incoming call is joined to the specified conference.
At any time, caller may disconnect the call and cnf demo proceeds with (1).
A conference that has more than 0 parties for Tmo seconds is considered too long. Cnf demo plays file GoodByeFileName, disband the conference, drop and release all related calls and proceeds with (1). To disable this feature, set Tmo to 0.
At any time operator may terminate CNF demo by pressing Ctrl-C or closing console window. Cnf demo will gracefully release and close all resources, but will not send any indication to currently active callers.

6. Program flow (main.cpp)

Read configuration file. In case of errors: display message and exit.
Create log objects according to configuration file settings.
Issue gc_Start
Detect configuration. Cnf demo detects voice devices with play/record capabilities, ipt, ipm, cnf and dti devices.
Create object SrlThread. Note: this is single threaded app and SrlThread runs in App main thread in polled mode.
Create Conferences
Create Front-End objects (ipt and dti)
Run SrlThread event handler until all devices reach state SRLSTATE_INIT_COMPLETE following their state machines.
Indicate that initialization is complete (display message).
Run SrlThread event handler until any of the following:

all devices reach state NOT SRLSTATE_OPENED.
any device reach state SRLSTATE_FAILED_FATAL.
Global flag exit_now is set. This flag is set when operator press signals exit for the second time (when exit is already in progress). It indicates request for immediate exit and may leave some calls and conferences in undefined states.

Cleanup at exit.
At any time, if exit signal is detected Cnf demo sends message to all devices to shut down and close gracefully. This is implemented by sending SRL message USREV_EXIT_REQUEST to all devices.

7. Implementation

7.1. Log object

Class CGenLog is abstract class that implement generic Log interface. A pure virtual function doLog provides device specific output and should be implemented in every class inherited from CGenLog. Log object will send any particular message to the output device only its verbosity level is greater or equal to CGenLog::m_verbosity. Log objects can be “chained” via function CGenLog::DefineChainLog (CGenLog *). Each message sent to the log is also forwarded to the chained log.

Application is sending messages for logging using function CGenLog::Log (). Each log message contains:

Verbosity level (enum MSG_TYPE).
Object that sends the message (string identifier).
Message format and content – sprintf style.

There are 2 Log classes in this demo

· CFileLog uses disk file as output device.

· ConsoleLog uses logs to console window.

Application Log object is named glb_pAppLog. It chains File and Console logs. Macro GLBLOG is used to send messages to glb_pAppLog. Each device has its own private log. By default, it is set to glb_pAppLog, but can be set to private m_pPrivateLog based on configuration file settings. In this case, glb_pAppLog is also chained and each message goes to private log file, console and common log file. Private log file name is derived from device name, for example iptB1T1.log.

Example for using Log object:

pLog->Log (DBG, “CDetectCfg”, “%d = dx_close (%d)”, rc, handle);

Example line from log file:

15:26:11.998 DBG CDetectCfg 0 = dx_close (1)

This message contains timestamp, message type (DBG), object that sends this message (“CDetectCfg”) and message is “0 = dx_close (1)”.

7.2. Configuration file

Class ConfigFile implements generic configuration file processing methods and properties: Loading and tokenization. Class CnfDemoPrm implements specific configuration file reader for cnf demo.

7.3. Detect configuration

Class CDetectCfg is a configuration detector and resource keeper. It detects dx, dti, ipt, ipm, and cnf devices. Enum DEVICE_TYPE represents device types. Each device type has 2 lists implemented in object CDeviceList: “used” and “unused”. Other objects can request and reserve device of specific type via CDeviceList::Reserve (). They can either specify device name to be reserved or just ask for any available device of specific type. CDeviceList::UnReserve () will return back ownership of the device to object CDetectCfg. Configuration detector sets initial stage “unused” list. Then Reserve () and UnReserve () simply move devices between these lists. Each device should be in closed state when it is reserved or unreserved. Each device is represented by its name (“dxxxB1C1”, “dtiB1T1” etc.). Object glb_pDetectCnf is a singleton instance of class CDetectCfg.

Example for reserving any available device with play/record capabilities:

const char *dev_name;

if (glb_pDetectCnf->Reserve (DEV_DX, &dev_name)) {

//… dev_name points to the name of reserved device

}

const char *dev_name = “dxxxB1C1”;

if (glb_pDetectCnf->Reserve (DEV_DX, &dev_name)) {

//… Returns true if dxxxB1C1 was reserved.

}

Unreserved devices can be re-used from other clients:

glb_pDetectCnf->UnReserve (dev_name)

7.4. State machine

Each call scenario is driven by state machine. The only way to advance state machine is to handle SRL event in the following sequence:

Wait event -> Execute action -> Advance state -> Wait event.

If requested action fails, then Recover action is executed and state machine is then advanced. State machine loop terminates when all objects reach its final states (device closed). Each state machine maintains its current state and is driven by 2 tables: “Event table” and “Action table”.

Event table is array of structures EVENT_STRU and describes what action to execute upon receiving event in any particular state. EVENT_STRU description:

int current_state; // If this is current state

int event; // and this event is received

int action; // then attempt this action

Action table is array of ACTION_STRU and describes how to advance state and recover (if needed) after executing action in some particular state.

ACTION_STRU description:

int current_state; // If this is current state

int action; // and this action has been executed

int state_if_pass; // then advance to this state (if action passed)

int action_if_fail; // or execute this action to recover (action failed)

Notes:

For state following recover action, see same table.
State is changed after action and eventual recover action are executed.
There is no recover on recover regardless of the table values.

Example:

7.5. Object CSrlDevice and derived objects

CSrlDevice is an abstract class has one or more SRL handles obtained via gc_Open, dx_Open, cnf_Open etc. It implements following methods:

Handle events.

Virtual AreYouHandle (handle). Determine if specified handle belongs to this object.
Virtual HandleEvent (). Handle SRL events routed to this object.
PutEvent (). Post SRL event to this object.
Virtual ExitRequest. Post request for all state machines to reach gracefully and as soon as possible its final state.
DumpMissingEvents. Determine all events that can advance state machine from the current state. This function is used to display message in case of timeout – what this device is waiting for.

State machine,

SetStateMachine (). Construct state machine.
GetCurrentState (). Get current state.
AdvanceStateMachine (). Determine next action according to state machine.
Virtual Execute (). Execute next action.

Timer.

SetTimer() starts the timer
StopTimer () stops the timer.
CheckTmo () checks if timer has expired.

Logging

LOG – macro to log. Takes same parameters as function Log.
OpenPrivateLog () opens separate log for this device and routes LOG appropriately.
ClosePrivateLog () closes separate log and routes LOG back to global log object.

Generic handle for errors – separate function per technology

process_gc_error
process_cnf_error
process_dx_error
process_dev_error

Dump some structures – for logging purposes.

cnf_dump
gc_dump
dev_dump

CSrlDeviceContainer is inherited from CSrlDevice and represent collection of SRL devices and other SRL Device containers. It can be SRL device as well. For example, dtiB1 is collection of dtiB1T1, dtiB1T2 etc. and is SRL device at the same time. CSrlDeviceContainer implements AreYouHandle, ExitRequest and CheckTmo accordingly to affect all devices that it owns.

NtwkDevice is inherited from CSrlDevice and represent network front-end device routed to dx device. It implements GlobalCall and voice specific functions such as ClearDigits () or AnswerCall (), call scenario and appropriate state machine. Conference actions belong to this state machine as well, even if conference functions are implemented in other classes.

IptDevice is inherited from CSrlDevice and represent ipt front end. It contains media SRL handle as well and IP specific functions such as SetCoders () and SetDtmfTransfer ().

PstnDevice is inherited from CSrlDevice and represent PSTN front end.

CnfParty is inherited from CSrlDevice and represent Cnf party. This objects Implement Cnf party specific functions.

CnfConference is inherited from CSrlDeviceCintainer and represent Cnf conference. This objects Implement Cnf conference specific functions and state machine. It is collection of cnf parties as well.

CnfBoard is inherited from CSrlDeviceCintainer and represent Cnfboard. This objects Implement Cnf board specific functions and state machine. It is collection of cnf conferences as well.

glb_ConferencePool is collection of all conferences. It is used from Ntwk devices to search for appropriate conference based of caller input DTMF digits. The reason of having this object instead of using Cnfboard is that future releases may support multiple cnf boards.

7.6. Object CSrlThread

CSrlThread is CSrlDeviceContainer. The function CSrlThread::TheThreadBody () is consistently pulling events from SRL event queue, searching for appropriate CSrlDevice and executing its HandleEvent (). Finding appropriate device is based on:

If UserContect, retrieved from event is nonzero, it holds CSrlDevice address.
If User attribute, retrieved from event is nonzero, it holds CSrlDevice address.
Search entire collection passing event handle to function AreYouHandle()

WaitSrlState is convenient function that executes TheThreadBody until all devices reach specific state or until specified timer expire.

Function OnIdle is executed any time when SRL event queue is empty. It is used to calculate timeouts for all devices.

8. Multithreading considerations

This demo runs in single thread. Here are guidelines how to make it multithreading:

Each object (inherited from CSrlDevice) should run in one and the same thread. Accordingly, each instance of object CStateMachine is running in same thread and therefore it does not need protection.
One thread may serve multiple CSrlDevice(s) (state machines). In this example, one thread is serving all SRL devices.
Adding / removing front-end party to the conference is considered to belong to the state machine, attached to object CNtwkDevice (not CnfConference). Accordingly, CnfConference::AddParty and CnfConference::RemoveParty may be used simultaneously from different threads to arrange same conference and should be protected. More specifically, internally supported list of objects should be protected. An alternate method to request service from one CSrlDevice from another CSrlDevice that may run in different thread is demonstrated by using event USREV_REMOVE_PARTY. This event may trigger action (closing conference in this case) via object’s state machine and does not need any protection.

The following objects may need changes:

Log object, protect function Log.
CDetectCfg, protect Reserve and UnReserve.
CnfConference, protect internal list of objects CSrlDeviceContainer::m_DeviceList. Ignore requests to add/remove party when exit is requested.
CSrlThread::TheThreadBody – implement one of existing multithreading models.
Instantiate multiple CSrlThread objects. Each CSrlThread should be container of all CSrlDevice-s that it serves.

9. Exit gracefully

There are several reasons for conference demo to abandon current action and attempt to transit either to state S_RELAX (waiting for calls / conferences) or to state S_FINAL (closed): remote site disconnected; local operator request app to exit or alarm network condition was raised. Accordingly, conference demo can handle the following SRL events at any time:

USREV_EXIT_REQUEST. Generated from this app. Indicates a request for app to exit and is posted to all CSrlDevice objects. State machine goal is to transit to state S_FINAL gracefully.
GCEV_BLOCKED. Generated from HMP libraries. Indicates network failures and is posted to all CNtwkDevice objects. State machine goal is to transit to state S_WAIT_UNBLOCKED. Subsequent GCEV_UNBLOCKED will transit it back to S_RELAX and conference demo is ready to answer new calls.
GCEV_DISCONNECTED. Generated from HMP libraries. Indicates remote side dropped the call and is posted to affected CNtwkDevice object. State machine goal is to transit to state S_RELAX gracefully.
USREV_TIMEOUT. Generated from this app. Indicates that termination for the current action didn’t occur within specified timeout. It is posted to affected CSrlDevice object. Usually, this event indicates either Conference demo failure (incomplete state machine table) or a product failure. State machine goal is to transit to state S_RELAX or S_FINAL (depending of the importance of the action that timed out).

When any of exit signals is received, state machine initially performs all necessary steps to transit to S_RELAX state. Then, if exit is requested it transits to S_FINAL state and if Alarm condition is set it transits to state S_WAIT_UNBLOCKED.

If request to exit happens when conference demo is in its way to drop the call anyways, cleanup procedures proceed theirs normal path. Otherwise, _EXIT state is provided for each state and application is simply transited to appropriate _EXIT state while still continues to wait for termination event.

Example 1:

GCEV_DISCONNECTED is received when conference demo plays greeting file (state S_PLAYGREET). Dx_stopch () is invoked and state machine advances to S_STOP_DX (“exit” state for all voice functions). Application still waits for TDX_PLAY, then invokes DropCall () and proceeds its normal way to tear down the call.

Example 2:

USREV_EXIT_REQUEST is received when conference demo answers the call (state S_ANSWER). DropCall () is possible at this point, but there are hard to handle glair conditions:

a) GCEV_ANSWERED and/or GCEV_DISCONNECTED may be already posted from the firmware and in theirs way to the app. They could be received after DropCall. State machine should be able to handle this sequence.

b) If GCEV_TASKFAIL is posted, we cannot decide was it negative response to AnswerCall that was posted before DropCall, or it is negative response to DropCall. In the former case we should wait termination event for DropCall, in the later case we should not.

That’s why, better approach is to wait until AnswerCall completes and then initiate exit procedures. Accordingly conference demo transits to S_ANSWER_EXIT state. Subsequent GCEV_ANSWERCALL or GCEV_TASKFAIL will trigger DropCall () and application proceeds its normal way to tear down the call.

9.1. Releasing resources before exit

Application should release following resources to cleanup current call and get ready to the next call (or exit):

For each network device:

If voice function is active, issue dx_stopch()
Wait currently executed function (if any) to terminate
If ‘dev_connected’ , Dev_Disconnect
If joined to conference, RemoveParty
If party exist, CloseParty
If call is active, DropCall.
If call is exist, ReleaseCall.

For each conference device:

Wait currently executed function (if any) to terminate.
Wait all parties to be removed from the conference.
Close conference.

For each conference board:

Wait currently executed function (if any) to terminate
Wait all conferences to exit
Close board

9.2. Exit APP

There are 2 ways of exiting this demo: As a response to external signal, or as a result of internal error. They both call global function glb_exit_request (). Application performs all necessary steps to exit gracefully:

9.3. Call tear down

There are 3 ways of tear down the call: As a response to remote disconnect, as a result of conference timing out, or as part of exiting procedure initiated from operator. Application performs all necessary steps to exit gracefully:

10. Linux/Win32 compatibility

File win_unix.h is used to adjust all differences. All other files are identical for Linux and Window.

11. HMP and SR release versions compatibility

File product_versions.h is provided to adjust possible differences in feature releases and to make this demo backward and forward compatible (at source code level). Preprocessor constant _HMP30 is defined in project settings for this purpose. In feature GMP releases and for SR releases, it may be changed accordingly. _HMP3.1 is used HMP 3.1 release; _HMP15 – for Titusville.