IP Media Server (Global Call)
Demo Guide
August 2005
05-2065-003
Contents
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
About This Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Demo Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Preparing to Run the Demo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Editing Configuration Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.1.1 Configuration File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.1.2 Editing the IPMediaServer.cfg Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . 15
Running the Demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Using the Demo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.3.1 Keyboard Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.3.2 Using the Media Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Demo Details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Files Used by the Demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.1.1 Demo Source Code Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.1.2 PDL Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Programming Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.2.1 Module Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.2.2 EventRouter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.2.3 Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
5.2.4 Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
5.5.1 Event Mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
5.5.2 Handling Keyboard Input Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
5.5.3 Handling SRL Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
5.5.4 Handling Application Exit Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
5.5.5 TSUsrEvent Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
IP Media Server (Global Call) Demo Guide – August 2005
3
Contents
Figures
IP Media Server (Global Call) Demo Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
EventRouter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
IP Media Server (Global Call) Demo Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39
System Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
4
IP Media Server (Global Call) Demo Guide – August 2005
Contents
Tables
Command Line Switches. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Files in IPMediaServer Folder Used by the IP Media Server (Global Call) Demo. . . . . . . . . . . 27
Files in Modules Folder Used by the IP Media Server (Global Call) Demo. . . . . . . . . . . . . . . . 28
10 Voice Module Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
IP Media Server (Global Call) Demo Guide – August 2005
5
Contents
6
IP Media Server (Global Call) Demo Guide – August 2005
Revision History
This revision history summarizes the changes made in each published version of this document.
Document No.
Publication Date
Description of Revisions
05-2065-003
August 2005
Globally added Linux-specific filenames, paths, and commands.
Globally updated paths to use environment variables for installation base directory.
restrictions
Editing the IPMediaServer.cfg Configuration File section: Updated descriptions of
QoS attributes to match IPML API Reference. Updated sample config file.
Using the Media Server section: Added CSP Barge-in to Main Menu listing.
Corrected description of CSP Prompt.
Demo Voice Menu Flowchart figure: Corrected description of CSP Prompt.
05-2065-002
05-2065-001
November 2003
September 2003
Removed all references to fax, which is not supported in System Release version of
demo.
Initial version of document.
IP Media Server (Global Call) Demo Guide — August 2005
7
Revision History
8
IP Media Server (Global Call) Demo Guide — August 2005
About This Publication
This section describes the purpose of the guide, the intended audience, and provides references to
other documents that may be useful to the user.
• Purpose
Purpose
This guide provides information on the IP Media Server (Global Call) demo that is provided with
®
®
Intel Dialogic System Release 6.1. The guide describes the demo, its requirements, and provides
details on how it works.
Intended Audience
This guide is intended for application developers who will be developing a media server
application using the Global Call API. Developers should be familiar with the C++ programming
language and either the Windows* or Linux* programming environment.
This information is intended for:
• Distributors
• Toolkit Developers
• Independent Software Vendors (ISVs)
• Value Added Resellers (VARs)
• Original Equipment Manufacturers (OEMs)
How to Use This Publication
Refer to this publication after you have installed the hardware and the system software.
This publication assumes that you are familiar with the Windows or Linux operating system and
the C++ programming language.
The information in this guide is organized as follows:
IP Media Server (Global Call) Demo Guide — August 2005
9
About This Publication
demo
the demo
Related Information
See the following for more information:
• the Release Guide for your Intel Dialogic System Release
®
• the Configuration Guide for your Intel NetStructure DM/IP series or IPT series board
• Global Call IP Technology Guide
• Voice API Programming Guide
• Voice API Library Reference
• Standard Runtime Library API Programming Guide
• Standard Runtime Library API Library Reference
10
IP Media Server (Global Call) Demo Guide — August 2005
1
1
Demo Description
.
This chapter describes the basic features of the IP Media Server (Global Call) demo.
The IP Media Server (Global Call) demo is an object-oriented host-based application that
demonstrates using the Global Call API to build an IP media server, providing voice and fax
services via IP technology. The demo source code can be used as sample code for those who want
to begin developing an application from a working application.
Note: The IP Media Server (Global Call) demo is limited to a maximum of four simultaneous channels.
Additionally, the channel numbers used must be below 120; the demo will fail to run if you attempt
to use a channel number higher than 120.
The IP Media Server (Global Call) demo supports the following features:
• Voice service
• CSP barge in
• Configuration file
• Command line options
Note: The IP Media Server (Global Call) demo does not function as a gateway. Therefore, it can only
answer calls from the IP network. Gateway functionality can be added by writing additional
software code within the IP module that will allow it to make outgoing calls to the IP network, and
connecting a gateway to interface with the PSTN.
The IP Media Server (Global Call) demo is a cross-OS demo, designed to run under both the
Windows and Linux environments. Most of the differences in the environments are handled
directly by the programming interface and are transparent to the user. Other differences, due to
inherent differences in the operating systems, are handled by the Platform Dependency Library
(PDL). For more information about the PDL refer to the source code in the pdl_win or pdl_linux
directories directory.
IP Media Server (Global Call) Demo Guide — August 2005
11
Demo Description
12
IP Media Server (Global Call) Demo Guide — August 2005
2
2
S
.
ystem Requirements
This chapter discusses the system requirements for running the IP Media Server (Global Call)
demo. It contains the following topics:
• Hardware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.1
Hardware Requirements
To run the IP Media Server (Global Call) demo, you need:
• One of the following:
®
– Intel NetStructure DM/IP Series board
®
– Intel NetStructure IPT Series board
®
• also requires an Intel NetStructure DM/V-A series board for PSTN connection
• IP network cable
For other hardware requirements, such as memory requirements, see the Release Guide for the
system release you are using.
2.2
Software Requirements
®
To run the IP Media Server (Global Call) demo as documented in this guide, you need the Intel
®
Dialogic System Software 6.1 or later. For a list of operating system requirements see the Release
Guide for the system release you are using.
this demo. Using a non-supported compiler may cause unforeseen problems in running the demo.
IP Media Server (Global Call) Demo Guide — August 2005
13
System Requirements
14
IP Media Server (Global Call) Demo Guide — August 2005
3
3
Preparing to Run the Demo
.
This chapter discusses the preparations necessary to run the IP Media Server (Global Call) demo. It
provides information about the following topics:
3.1
Editing Configuration Files
This section discusses how to configure the demo for your system. It contains the following topics:
3.1.1
Configuration File Location
Before running the IP Media Server (Global Call) demo, modify the IPMediaServer.cfg file to
reflect your system environment. Use a text editor and open the file from the following location:
Windows
$(INTEL_DIALOGIC_DIR)\Demos\IPMediaServer\Release
Linux
$(INTEL_DIALOGIC_DIR)/demos/IPMediaServer/Release
where $(INTEL_DIALOGIC_DIR) identifies the base installation directory for the software.
3.1.2
Editing the IPMediaServer.cfg Configuration File
Below is an example of the IPMediaServer.cfg file. Update the following information:
ipProtocolName
The IP protocol for opening IP line devices. Possible vlues are:
• H323
• SIP
• both
DTMFmode
Specifies how DTMF tones are transmitted. Possible values are:
• OutofBand – usually used with low bandwith coders, such as GSM
Note: OutofBand is used for H.323 only.
IP Media Server (Global Call) Demo Guide — August 2005
15
Preparing to Run the Demo
• InBand – usually used with G.711 coders
• RFC2833
Capability
Describes the transmit and receive coders. See the Global Call IP Technology Guide for
specific information about coder support. The parameters are as follows:
• TxType – the transmit voice coder
• TxFramesPerPkt – the number of frames per packet for the selected Tx coder
• TxVAD – specifies if VAD is active for the selected Tx coder
• RxType – the receive voice coder
• RxFramesPerPkt – the number of frames per packet for the selected Rx coder
Note: The G.711 coder defines frames per packet using the packet size in milliseconds, i.e.
correct syntax for all the parameters.
• RxVAD – specifies if VAD is active for the selected Rx coder
Quality of Service
The application can set threshold values to monitor the quality of service during calls. A fault
occurs when the result of a measurement of a QoS parameter crosses a predefined threshold. A
success occurs when the result of a measurement of a QoS parameter dis not cross a predefined
threshold. The QoS parameters are measured during time intervals, starting when a call is
established. The following parameters are supported:
• MediaAlarmLostPackets – monitors the number of lost IP packets during a call
(supported for IPT series boards only)
• MediaAlarmJitter – monitors the jitter (as defined in RFC 1889) during IP transmission
QoS Attributes
The threshold for each QoS parameter is measured with the following six attributes:
• Threshold – defines when a QoS parameter is in a fault condition. A fault occurs when the
result of a measurement of a QoS parameter crossed the Threshold value.
• DebounceOn – the time during which faults are measured (in msec., must be multiple of
Interval)
• DebounceOff – the time during which successes are measured (in msec., must be multiple
of Interval)
• Interval – the amount of time between two QoS parameter measurements (in multiples of
100 msec)
• Percent_Fail – used to detect failure condition, together with DebounceOn (expressed as
a percentage of failures)
• Percent_Success – used to detect failure recovery, together with DebounceOff (expressed
as a percentage of successes)
The default values are as follows:
Table 1. Quality of Service Parameter Defaults for DM/IP Series Boards
Time
Interval (ms)
Debounce Debounce %Success
% Fail
Threshold
QoS Type
Jitter
Fault Threshold
On (ms)
Off (ms)
Threshold
60 (ms)
5000
20000
60000
40
40
16
IP Media Server (Global Call) Demo Guide — August 2005
Preparing to Run the Demo
Table 2. Quality of Service Parameter Defaults for IPT Series Boards
Fault
Time
Interval (ms)
Debounce Debounce %Success
% Fail
Threshold
QoS Type
Jitter
Threshold 1
On (ms)
Off (ms)
Threshold
30 (ms)
100 (%)
0 (n/a)
0 (n/a)
0 (n/a)
0 (n/a)
0 (n/a)
0 (n/a)
0 (n/a)
Lost Packets
0 (n/a)
0 (n/a)
0 (n/a)
Notes:
1. Units for Fault Threshold are different for different QoS Types. See unit indications in table cells.
Sample Configuration File
################################################################################################
# IP Protocol :
#
#
The IP Protocol used for opening the IP Line devices, values: H323, SIP, both
# DTMFmode
#
#
#
possible options:
OutOfBand, inband, rfc2833
# Capability posiblities:
#
#
#
#
#
#
#
#
#
#
#
#
#
#
g711Alaw
g711Mulaw
gsm
gsmEFR
g723_5_3k
g723_6_3k
g729a
g729ab
t38UDPFax
Note: if you want to run the demo with coder g729 use:
g729a for running with VAD disable
and 729ab for running with VAD enable
# Caution:
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
If capability is g711Alaw /Mulaw ==> FramesPerPkt = 10,20,30.
G711 frame per packet defines the packet size in
milliseconds
If capability is g723_5_3k / 6_3k ==> FramesPerPkt = 1, 2, 3 .
FrameSize isn't needed, default= 30ms.
==> FramesPerPkt = 1, 2, 3 .
FrameSize isn't needed, default= 20ms.
==> FramesPerPkt = 1, 2, 3 .
FrameSize isn't needed, default= 20ms.
==> FramesPerPkt = 3, 4 .
If capability is gsm
If capability is gsmEFR
If capability is g729a
FrameSize isn't needed, default= 10ms.
VAD disable, the VAD parameter is ignored
==>FramesPerPkt = 3, 4 .
If capability is g729ab
FrameSize isn't needed, default= 10ms.
VAD enable, the VAD parameter is ignored
################################################################################################
ipProtocolName = H323
DTMFmode = inBand
Channel = 1-120
{
Capability
{
#
#
TxType = g711Alaw
TxFramesPerPkt = 30
IP Media Server (Global Call) Demo Guide — August 2005
17
Preparing to Run the Demo
#
#
#
#
TxVAD = 0
RxType = g711Alaw
RxFramesPerPkt = 30
RxVAD = 0
TxType = g711Mulaw
TxFramesPerPkt = 20
TxVAD = 0
RxType = g711Mulaw
RxFramesPerPkt = 20
RxVAD = 0
#
TxType = t38UDPFax
}
MediaAlarmLostPackets
{
Threshold
DebounceOn
DebounceOff
Interval
= 20
# Threshold value
= 10000 # Threshold debounce ON
= 10000 # Threshold debounce OFF
= 1000 # Threshold Time Interval (ms)
PercentSuccess = 60
# Threshold Success Percent
# Threshold Fail Percent
PercentFail
= 40
}
MediaAlarmJitter
{
Threshold
DebounceOn
DebounceOff
Interval
= 60
# Threshold value
= 20000 # Threshold debounce ON
= 60000 # Threshold debounce OFF
= 5000 # Threshold Time Interval (ms)
PercentSuccess = 60
# Threshold Success Percent
# Threshold Fail Percent
PercentFail
}
= 40
# MediaAlarmResetAlarmState
}
= 0
3.2
Compiling and Linking
Compile the IP Media Server (Global Call) demo project within one of the following environments:
Windows
To compile the IP Media Server (Global Call) demo on a Windows system, use Microsoft* Visual
Studio* 6.0 with Service Pack 5.
Set IPMediaServer as the active project and build.
18
IP Media Server (Global Call) Demo Guide — August 2005
Preparing to Run the Demo
Linux
To compile the IP Media Server (Global Call) demo on a Linux system, use gcc version 3.2.3.
To compile the entire project, go to the directory
$(INTEL_DIALOGIC_DIR)/demos/IPMediaServer and issue the commands:
make clean
make
To compile an individual module, go to the specific module directory (for example,
$(INTEL_DIALOGIC_DIR)/demos/IPMediaServer/Modules/FaxModule for the fax module), and
issue the commands:
make clean
make
IP Media Server (Global Call) Demo Guide — August 2005
19
Preparing to Run the Demo
20
IP Media Server (Global Call) Demo Guide — August 2005
4
4
R
.
unning the Demo
This chapter discusses how to run the IP Media Server (Global Call) demo. It contains the
following topics:
• Using the Demo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
• Stopping the Demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.1
Starting the Demo
The demo executable file for the IP Media Server (Global Call) demo can be started as follows:
Windows
From a command prompt window, change to the directory:
$(INTEL_DIALOGIC_DIR)\Demos\IPMediaServer\Release
Type IPMediaServerto run the IP Media Server (Global Call) demo using the default settings.
Linux
Change to the directory:
$(INTEL_DIALOGIC_DIR)/demos/IPMediaServer/Release
Type IPMediaServerto run the IP Media Server (Global Call) demo using the default settings.
4.2
Demo Options
To specify certain options at run-time, launch the demo from a command line, using any of the
Table 3. Command Line Switches
Switch
-c<filename>
-e<encoding type> Sets the encoding type:
Action
Default
-cIPMediaServer.cfg
-em
Configuration file name
•
•
m – mu-law
a – A-law
-h or ?
Prints the command syntax to the screen
Off
IP Media Server (Global Call) Demo Guide — August 2005
21
Running the Demo
Table 3. Command Line Switches (Continued)
-n<n>
Sets the number of channels
Activates Quality of Service
The lesser of Voice Devices
or IP devices
-q
Disabled
Example
The following example shows how to launch the demo from a command line with options:
IPMediaServer -n64 -cmyconfig.cfg -ea
This command launches the demo with 64 channels, using the myconfig.cfg configuration file and
A-law encoding.
4.3
Using the Demo
This section describes how to use the IP Media Server (Global Call) demo and contains the
following topics:
4.3.1
Keyboard Commands
The demo always waits for input from the keyboard. While the demo is running, you may enter any
Table 4. Runtime Keyboard Commands
Command
Function
q or Q or Ctrl+c
Terminates the application
4.3.2
Using the Media Server
The IP Media Server (Global Call) demo allows the caller to interact with a series of voice menus,
using the telephone keypad to enter an option. Basic operations include playing a pre-recorded
message, recording a new message, and barge-in for CSP. Each menu prompts the caller to select
an action by pushing a key. The call state within which the menu is called is indicated by the square
Main Menu [Main_Menu]
1 - Voice Mail
3 - Conferencing (not supported in HMP 1.x)
4 - CSP Barge-in
* - Quit
22
IP Media Server (Global Call) Demo Guide — August 2005
Running the Demo
Voice Mail Menu [Voicemail_Menu]
1 - Record Message
2 - Listen to message from a mailbox
* - Quit
Send Message Prompt [SendMsg_Menu]
Enter Mailbox Number - between 101 - 299
* - Quit
Start Record Prompt [Record_Menu]
2 - Start Record
Press 2 at end of message to stop recording (at end, Stop Record Prompt is played)
* - Quit
Stop Record Prompt [StopRec_Menu]
2 - Discard Message and re-record message to same mailbox
3 - Confirm Message [Save_Confirm]
4 - Listen to Message (and replay Stop Record Prompt)
* - Quit without saving
Confirm Message Saved [StopRec_Menu]
1 - Record a message
2 - Listen to a message from a mailbox
* - Quit
Listen to Message Prompt [ListenMsg_Menu]
Enter Mailbox Number - between 101 - 299 (Recorded message is played)
* - Quit
Stop Listen Prompt [Listening]
2 - Discard message and quit
* - Save message and quit
CSP Prompt [CSP_Menu]
Say something to barge in (new file will be created with barged-in message) or press any DTMF.
IP Media Server (Global Call) Demo Guide — August 2005
23
Running the Demo
Figure 1. Demo Voice Menu Flowchart
Main Menu
Select one of the following:
1 - Voice Mail
4 - CSP
* - Quit
4
1
2
-
Fax
Voice Mail Prompt
1 - Record Message
2 - Listen to message
from a mailbox
CSP Prompt
Say something to barge in
* - Quit
* - Quit
2
1
Listen Message
Prompt
Enter Mailbox
Number (Message
is played)
Send Message
Prompt
Enter Mailbox
Number
* - Quit
* - Quit
Mailbox
number
Mailbox
number
Stop Listen Prompt
2 - Discard message
and quit
* - Save message and
quit
Start Record Prompt
2 - Start/Stop Record
* - Quit
2
2
Stop Record Prompt
2 - Discard message and
re-record message to
same mailbox
3 - Confirm message
4 - Replay message
* - Quit
3
4
Confirm Message Saved
Prompt
Confirm message
Replay Message
Replay Stop Record
Prompt
Return to Voice Mail prompt
24
IP Media Server (Global Call) Demo Guide — August 2005
Running the Demo
26
IP Media Server (Global Call) Demo Guide — August 2005
5
5
Demo Details
.
This chapter discusses the IP Media Server (Global Call) demo in more detail. It contains the
following topics:
• Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
• Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
5.1
Files Used by the Demo
This section lists the files used by the IP Media Server (Global Call) demo. It contains the
following information
5.1.1
Demo Source Code Files
$(INTEL_DIALOGIC_DIR)\Demos\IPMediaServer
$(INTEL_DIALOGIC_DIR)/demos/IPMediaServer
Table 5. Files in IPMediaServer Folder Used by the IP Media Server (Global Call) Demo
Sub-Directory (if any)
File Name
CConfig.cpp
Purpose
Implements the operations of the Configuration
class
CConfig.h
Function prototype for config.cpp
CEventRouter.cpp
CEventRouter.h
IPMediaServer.dsp
IPMediaServer.dsw
main.cpp
Implements the operations of the EventRouter class
Function prototype for ceventrouter.cpp
Visual C++ project file
Visual C++ project workspace
Contains the main function and the WaitForKey
Function prototype for main.cpp
main.h
makefile
Top-level make file (Linux only)
IP Media Server (Global Call) Demo Guide — August 2005
27
Demo Details
Table 5. Files in IPMediaServer Folder Used by the IP Media Server (Global Call) Demo
Sub-Directory (if any)
Release
File Name
unavConf.vox
Purpose
Voice file
Voice file
Voice file
Release
cspPrompt.vox
errorInput.vox
IPMediaServer.cfg
IPMediaServer.exe
listenMenu.vox
mainMenu.vox
savecCnfirm.vox
sendfaxMenu.vox
sendMsg.vox
Release
Release
Demo configuration file
Demo executable
Voice file
Release
Release
Release
Voice file
Release
Voice file
Release
Voice file
Release
Voice file
Release
startRec.vox
Voice file
Release
stopListen.vox
stopRec.vox
Voice file
Release
Voice file
Release
thankYou.vox
Voice file
Release
unavCsp.vox
Voice file
Release
unavFax.vox
Voice file
Release
unavMenu.vox
voicemailMenu.vox
Voice file
Release
Voice file
$(INTEL_DIALOGIC_DIR)\Demos\IPMediaServer\Modules
$(INTEL_DIALOGIC_DIR)/demos/IPMediaServer/Modules
Table 6. Files in Modules Folder Used by the IP Media Server (Global Call) Demo
Sub-Directory
common
File Name
Defines.h
Purpose
Definitions and structures for the demo
Interfaces used in the demo
common
common
common
IPModule
IPModule
IPModule
IPModule
IPModule
IPModule
Interfaces.h
Parameters.h
makefile
Parameters used in the demo
Module make file (Linux only)
CIPDevice.cpp
CIPDevice.h
CIPMBoard.cpp
CIPMBoard.h
CIPModule.cpp
CIPModule.h
Implements the operations of the CIPDevice class
Function prototype for cipdevice.cpp
Implements the operations of the CIPMBoard class
Function prototype for cipmboard.cpp
Implements the operations of the CIPModule class
Function prototype for cipmodule.cpp
28
IP Media Server (Global Call) Demo Guide — August 2005
Demo Details
Table 6. Files in Modules Folder Used by the IP Media Server (Global Call) Demo (Continued)
Sub-Directory
IPModule
File Name
Purpose
CIPStateMachine.cpp
Implements the operations of the CIPStateMachine
class
IPModule
IPModule
IPModule
IPModule
CIPStateMachine.h
CIPTBoard.cpp
CIPTBoard.h
Function prototype for cipstatemachine.cpp
Implements the operations of the CIPTBoard class
Function prototype for ciptboard.cpp
CMediaAlarms.cpp
Implements the operations of the CMediaAlarms
class
IPModule
IPModule
IPModule
CMediaAlarms.h
IPModule.dsp
makefile
Function prototype for cmediaalarms.cpp
Visual C++ project file
Module-level make file (Linux only)
Compiled IP Module library
IPModule\Release or
IPModule/Release
IPModule.lib
VoiceModule
VoiceModule
VoiceModule
VoiceModule
VoiceModule
VoiceModule
VoiceModule
CCSPDevice.cpp
CCSPDevice.h
CMailBoxBtil.cpp
CMailBoxUtil.h
Implements the operations of the CCSPDevice class
Function prototype for ccdspdevice.cpp
Implements the operations of the CMailBoxUtil class
Function prototype for cmailboxutil.cpp
CVoiceBoard.cpp
CVoiceBoard.h
CVoiceDevice.cpp
Implements the operations of the voiceBoard class
Function prototype for cvoiceboard.cpp
Implements the operations of the CVoiceDevice
class
VoiceModule
VoiceModule
CVoiceDevice.h
Function prototype for cvoicedevice.cpp
CVoiceModule.cpp
Implements the operations of the CVoiceModule
class
VoiceModule
VoiceModule
CVoiceModule.h
Function prototype for cvoicemodule.cpp
CVoiceStateMachine.cpp Implements the operations of the
CVoiceStateMachine class
VoiceModule
VoiceModule
VoiceModule
CVoiceStateMachine.h
VoiceModule.dsp
makefile
Function prototype for cvoicestatemachine.cpp
Visual C++ project file
Module-level make file (Linux only)
Compiled Voice Module library
VoiceModule\Release or
VoiceModule/Release
VoiceModule.lib
5.1.2
PDL Files
$(INTEL_DIALOGIC_DIR)\Demos\Shared\pdl_win
$(INTEL_DIALOGIC_DIR)/demos/Shared/pdl_Linux
IP Media Server (Global Call) Demo Guide — August 2005
29
Demo Details
Table 7. PDL Files Used by the IP Media Server (Global Call) Demo
Sub-Directory (if any)
File Name
iptransport.cpp
iptransport.h
pdl.c
Purpose
PDL IP transport functions
Function prototype for iptransport.cpp
Platform dependency functions
Function prototype for pdl.c
PDL version information
pdl.h
pdl.ver
pdl_win.dsp
pdl_win.dsw
makefile
PDL Visual C project file
PDL Visual C project workspace
PDL make file (Linux only)
Compiled PDL library
release
psl_win.lib
5.2
Programming Model
This section describes the IP Media Server (Global Call) demo architecture in the following topics:
• Classes
5.2.1
Module Structure
The IP Media Server (Global Call) demo uses a modular architecture, in which each technology
(IP, voice, CSP) is wrapped inside a module so that a particular technology can be easily added or
removed.
The system contains two modules:
• IP module that serves as the front end to communicate with the IP network
• Voice module to provide voice service
The system also contains a software component, the EventRouter, to connect the modules. The
basic architecture of the system is illustrated in Figure 2.
30
IP Media Server (Global Call) Demo Guide — August 2005
Demo Details
Figure 2. IP Media Server (Global Call) Demo Architecture
Voice Module
Board
Device
State Machine
IP Module
Board
Device
EventRouter
State Machine
User Module
Board
Device
State Machine
Each module is composed of four elements:
• Board
• Device
• State Machine (call control)
• Wrapper
The Wrapper acts like a manager, receiving requests from the EventRouter and distributing the
request to the boards or devices. A device can have one or multiple state machines attached to it.
Each state machine represents one call.
5.2.2
EventRouter
The EventRouter is responsible for communicating with the modules. It does the following:
• Maintains routing tables
• Retrieves event data from the SRL and routes it to a module for processing
• Forwards event process result to another module if so requested.
IP Media Server (Global Call) Demo Guide — August 2005
31
Demo Details
Figure 3. EventRouter
Retrieve event
data from GC
library
Forward result to destination
For which
technology?
I P
Voice
Voice Module
IP Module
Yes
result
result
No
result.destination
= NONE ?
5.2.3
Interfaces
The modular architecture implements a unified interface that allows replacement of modules by
including new header files and adjusting routing statements.
A module is treated by the EventRouter as a block box. It has three types of APIs:
Initialization
• Init( ) – for initializing a module
32
IP Media Server (Global Call) Demo Guide — August 2005
Demo Details
• GetNumOfDevices( ) – returns the number of devices available to the application
• GetDeviceHandle( ) – returns a device handle
• GetDeviceXmitSlot( ) – returns a device transmit timeslot
• SetDeviceReceiveSlot( ) – sets a device receive timeslot
Runtime
• ProcessEvent( ) – processes event data
Termination
• Exit( ) – exits a module
5.2.4
Classes
This section describes the classes contained in the demo and within each module. Each module
contains three classes: board, device, and state machine.
Table 8. Application Classes
Class Name
Interface
CConfig
ParseConfigFile( )
• Responsible for parsing configuration file and
populating configuration variables in the program.
• Parses configuration file
ChannelNumber( )
• Gets the number of channels that are the
minimum of the number of voice lines and the
number of IP lines
IPParms( )
• Returns configured IP parameters
VoiceParms( )
• Returns configured voice parameters
CEventRouter
Init( )
• Initializes the IP module and voice module
• Builds event routing tables
Responsible for connecting all the modules. It does
the following:
• Maintains routing tables
• Retrieves event data from the SRL and routes
them to modules
Exit( )
• Terminates the voice module and IP module
• Gets event process results from the modules and
routes them to other modules if the destination is
not NONE
ProcessEvent( )
• Retrieves event data from Global Call and routes
them to a module for processing
• Routes processing result to other module(s) for
further processing.
IP Media Server (Global Call) Demo Guide — August 2005
33
Demo Details
Table 9. IP Module Classes
Category
Module
Class Name
Interface
CIPModule
Init( )
• Interacts with CIPBoard and CIPDevice.
• Exports IP module functions to
CEventRouter.
• Starts host based IP protocol
• Creates and initializes IPT (virtual) board
objects
• Creates and initializes IPM (media)
board objects
• Creates and initializes IP device objects
Note: The public functions in this class can
be accessed by classes outside the
IP module.
Exit( )
• Terminates and closes IPT boards
• Terminates and closes IPM boards
• Terminates and closes IP devices
ProcessEvent( )
• Receives event data from the event
router and distributes them, based on
handles, to IPT boards, IPM boards or IP
devices
GetNumOfDevices( )
• Returns number of IP devices engaging
in the communication
GetDeviceHandle( )
• Returns an IP device handle
GetDeviceXmitSlot( )
• Returns the transmit timeslot of an IP
device
SetDeviceReceiveSlot( )
• Sets the receiving timeslot of an IP
device
34
IP Media Server (Global Call) Demo Guide — August 2005
Demo Details
Table 9. IP Module Classes (Continued)
Category
Board
Class Name
Interface
CIPTBoard
Init( )
• Interacts with the Global Call library to
handle IP virtual boards
• Opens IPT (virtual) board and sets board
parameters
Note: The public function in this class
should only be accessed by classes
inside the IP module.
Exit( )
• Closes IPT (virtual) board
ProcessEvent( )
• Processes IPT (virtual) board events
GetNumOfDevicesOnBoard( )
• Returns the number of IPT devices
(signaling devices) on the board
CIPMBoard
Init( )
• Interacts with the Global Call library to
handle IP media boards
• Opens IP media boards
Exit( )
Note: The public functions in this class
should only be accessed by classes
inside the IP module.
• Closes IP media boards
ProcessEvent( )
• Processes IP media board events
GetNumOfDevices( )
• Returns number of IPM devices on the
board
IP Media Server (Global Call) Demo Guide — August 2005
35
Demo Details
Table 9. IP Module Classes (Continued)
Category
Device
Class Name
Interface
CIPDevice
Init( )
• Handles IP device operations, such as
making/dropping calls, sending H.323
messages, making timeslot connections,
etc.
• Opens an IP device. If successful,
creates an IP state machine. If QoS is
enabled, creates a media alarm object.
Exit( )
• Holds CIPStateMachine (or call control)
• Deletes IP state machine
• Deletes media alarm object
• Closes IP devices
Note: The public functions in this class
should only be accessed by classes
inside the IP module.
ProcessEvent( )
• Processes IP device events
Connect( )
• Allows IP device to listen to its receiving
timeslot
Disconnect( )
• Allows IP device to unlisten to its
receiving timeslot
GetDeviceHandle( )
• Returns IP device handle
GetXmitSlot( )
• Returns IP device transmit timeslot
SetDeviceReceiveSlot( )
• Sets IP device receiving timeslot
SetFaxHandle( )
• Sets fax device handle associated with
the device
GetFaxHandle( )
• Returns fax device handle associated
with the device
State
CIPStateMachine
Init( )
Machine
• Handles IP events and maintains IP
state machine(s)
• Initializes the IP state machine
Exit( )
Note: The public functions in this class
should only be accessed by the
classes inside the IP module.
• Terminates the IP state machine
ProcessEvent( )
• Processes IP call events
36
IP Media Server (Global Call) Demo Guide — August 2005
Demo Details
Table 10. Voice Module Classes
Category
Class Name
Interface
Module
CVoiceModule
Init( )
• Interacts with CVoiceBoard and
CVoiceDevice.
• Opens and initializes voice board objects
• Opens and initializes voice device objects
• Exports Voice module functions to
CEventRouter.
Exit( )
• Terminates and closes voice boards
• Terminates and closes voice devices
Note: The public functions in this class can
be accessed by classes outside the
Voice module.
ProcessEvent( )
• Receives event data from the event router
and distributes them, based on
devicehandles, to voice boards or voice
devices for processing
Board
CVoiceBoard
Init( )
• Interacts with the voice library to handle
voice boards
• Opens voice board
Exit( )
• Closes voice board
Note: The public function in this class
should only be accessed by classes
inside the Voice module.
ProcessEvent( )
• Processes voice board events
IP Media Server (Global Call) Demo Guide — August 2005
37
Demo Details
Table 10. Voice Module Classes (Continued)
Category
Device
Class Name
Interface
CVoiceDevice
Init( )
• Handles voice device operations, such
as playing, recording, tone detection,
and tone generation
• Opens the voice device. If successful,
creates voice state machine.
Exit( )
• Holds CVoiceStateMachine
• Deletes the voice state machine from the
voice device
• Closes voice device
Note: The public functions in this class
should only be accessed by classes
inside the Voice module.
ProcessEvent( )
• Processes voice device events
Connect( )
• Allows IP device to listen to its receiving
timeslot
Play( )
• Plays a vox file
OnPlayComplete( )
• Replays a vox file when it has finished
playing
Record( )
• Records voice to a vox file
GetDigits( )
• Retrieves DTMF digits
GetDigitCount( )
• Returns the number of retrieved DTMF
digits
GetDigitString( )
• Returns retrieved DTMF string
Connect( )
• Allows the voice device to listen to its
receiving timeslot
Disconnect( )
• Allows voice device to unlisten to its
receiving timeslot
GetStoppedReason( )
• Tells why a played voice file stops
GetDeviceHandle( )
• Returns voice device handle
GetXmitSlot( )
• Returns voice device transmit timeslot
SetReceiveSlot( )
• Sets voice device receiving timeslot
38
IP Media Server (Global Call) Demo Guide — August 2005
Demo Details
Table 10. Voice Module Classes (Continued)
Category
State
Class Name
CVoiceStateMachine
• Handles voice events and maintains
voice state machine(s)
Interface
Init( )
• Opens vox files
• Creates mailbox utility object that
manages mailboxes
Machine
Note: The public functions in this class
should only be accessed by the
classes inside the voice module.
Exit( )
• Closes vox files
• Deletes mailbox utility object that
manages mailboxes
ProcessEvent( )
• Processes voice events
Misc
CMailBoxUtil
InitMailBoxes( )
• Provides utility function to manage
mailboxes
• Initializes mailboxes
CheckAndConvertDigits( )
• Checks if the extension number is in
allowed range. If it is, converts it into an
integer.
Note: The public functions in this class
should only be accessed by the
classes inside the voice module
GetMailBox( )
• Checks if the mailbox is ready to be used.
If it is, gets the mailbox.
CreateMailBoxFileName( )
• Creates a filename for the mailbox
FreeMailBox( )
• Frees the mailbox for future use
5.3
Threads
The IP Media Server (Global Call) demo operates with two threads, as shown in Figure 4.
Figure 4. IP Media Server (Global Call) Demo Threads
IP
R4/GC
Keyboard
SRL
Main Thread
Sub-Thread
IP Media Server (Global Call) Demo Guide — August 2005
39
Demo Details
The threads are created as follows:
1. The first (main) thread is created by the demo application to get the keyboard input.
2. The second thread is an SRL thread, created as a result of the demo application calling
PDLsr_enblhdlr( ). All Global Call events are received through the SRL.
5.4
Initialization
This section describes the IP Media Server (Global Call) demo initialization as shown in Figure 5.
A system is started in the following sequence:
1. The application creates CConfig( ) to parse the configuration file.
2. The application creates CEventRouter( ) to start the Event Router, which, in turn, starts the IP
module and the Voice module. When a module is started, it initializes its boards, devices and
state machines.
After all the modules are started, the EventRouter starts to build a static routing table that maps
voice devices to IP devices. It is important that each IP device has a dedicated voice resource, so
that when an IP channel is connected (an incoming call is answered) the user can get a voice
prompt immediately.
If the initialization should fails, the application shuts down. The shutdown sequence is the reverse
of the initialization sequence.
40
IP Media Server (Global Call) Demo Guide — August 2005
Demo Details
Figure 5. System Initialization
1. Parse .cfg file
Application
Configuration
Event Router
2. Start router
3. Start IP Module
4. Start IP Board
5. Start IP Device
IP Module
IP Board
IP Device
6. Start IP State Machine
IP State Machine
7. Start Voice Module
8. Start Voice Board
Voice Module
Voice Board
9. Start VoiceDevice
Voice Device
10. Start Voice State
Machine
Voice State
Machine
IP Media Server (Global Call) Demo Guide — August 2005
41
Demo Details
5.5
Event Handling
This section describes how the IP Media Server (Global Call) demo handles events. It contains the
following topics:
5.5.1
Event Mechanism
The IP Media Server (Global Call) demo uses the SRL mechanism to retrieve events. When an
event occurs, SRL calls event handlers automatically. All events are received by the SRL and then
passed to the CallbackHdlr( ) function for handling.
In the initialization phase of the demo, the main( ) function sets up the call-back handler, by calling
PDLsr_enbhdlr( ).
5.5.2
5.5.3
Handling Keyboard Input Events
There is an endless loop {while(0)} in the main( ) function in the Main.cpp file. In that loop, the
application waits forever for a keyboard event by calling the waitForKey( ) function. The event
must be handled immediately and event-specific information should be retrieved before the next
call to waitForKey( ).
Handling SRL Events
When the R4/Global Call event is received, the application performs the following:
1. Get METAEVENT by calling gc_GetMetaEvent( ).
2. Get channel ID through device handle to channel mapping.
3. Get device type through device handle to type mapping.
4. Route meta event to the module specified by device type.
5.5.4
Handling Application Exit Events
Normal application exit events, such as pressing either q or Q, don’t enter the SRL. The main( )
function calls PDLSetApplicationExitPath( ) before initialization. In Linux, this function sets the
signals (SIGINT, SIGTERM, SIGABRT) for making the appropriate exit from the application. In
Windows, this function enables the detection of CTRL_CLOSE_EVENT (closing the window).
42
IP Media Server (Global Call) Demo Guide — August 2005
Demo Details
5.5.5
TSUsrEvent Structure
The TSUsrEvent structure is used by the demo modules to return event processing results to the
event router.
The TSUserEvt structure is defined as follows:
typedef struct
{
int
event;
TDeviceType destination;
int
lineDevice;
long
xmitSlot;
long
char
neighborDevice;
dialString[MAX_STRING_LENGTH]}
TSUserEvent;
The fields of the TSUserEvt structure are described as follows:
event
the name of a user-defined event, such as USR_CONNECTED, etc.
destination
the name of the module that this event is destined for. Possible vavues are IP, VOICE, or
NONE.
lineDevice
the device handle in this module. It will be later used by the Event Router as an index to find its
counterpart in the destination module.
xmitSlot
an integer that normally indicates a time slot number
neighborDevice
the neighbor device handle
dialString
a char string that is normally filled with a DTMF dialing string
IP Media Server (Global Call) Demo Guide — August 2005
43
Demo Details
44
IP Media Server (Global Call) Demo Guide — August 2005
Glossary
Codec: see COder/DECoder
COder/DECoder: A circuit used to convert analog voice data to digital and digital voice data to analog audio.
Computer Telephony (CT): Adding computer intelligence to the making, receiving, and managing of
telephone calls.
DTMF: Dual-Tone Multi-Frequency
Dual-Tone Multi-Frequency: A way of signaling consisting of a push-button or touch-tone dial that sends out a
sound consisting of two discrete tones that are picked up and interpreted by telephone switches (either PBXs or
central offices).
Emitting Gateway: called by a G3FE. It initiates IFT service for the calling G3FE and connects to a Receiving
Gateway.
E1: The 2.048 Mbps digital carrier system common in Europe.
FCD file: An ASCII file that lists any non-default parameter settings that are necessary to configure a DM3
hardware/firmware product for a particular feature set. The downloader utility reads this file, and for each
parameter listed generates and sends the DM3 message necessary to set that parameter value.
Frame: A set of SCbus/CT Bus timeslots which are grouped together for synchronization purposes. The period of
a frame is fixed (at 125 µsec) so that the number of time slots per frame depends on the SCbus/CT Bus data rate.
G3FE: Group 3 Fax Equipment. A traditional fax machine with analog PSTN interface.
Gatekeeper: An H.323 entity on the Internet that provides address translation and control access to the network
for H.323 Terminals and Gateways. The Gatekeeper may also provide other services to the H.323 terminals and
Gateways, such as bandwidth management and locating Gateways.
Gateway: A device that converts data into the IP protocol. It often refers to a voice-to-IP device that converts an
analog voice stream, or a digitized version of the voice, into IP packets.
H.323: A set of International Telecommunication Union (ITU) standards that define a framework for the
transmission of real-time voice communications through Internet protocol (IP)-based packet-switched networks.
The H.323 standards define a gateway and a gatekeeper for customers who need their existing IP networks to
support voice communications.
IAF: Internet Aware Fax. The combination of a G3FE and a T.38 gateway.
IFP: Internet Facsimile Protocol
IFT: Internet Facsimile Transfer
IP Media Server (Global Call) Demo Guide — August 2005
45
International Telecommunications Union (ITU): An organization established by the United Nations to set
telecommunications standards, allocate frequencies to various uses, and hold trade shows every four years.
Internet: An inter-network of networks interconnected by bridges or routers. LANs described in H.323 may be
considered part of such inter-networks.
Internet Protocol (IP): The network layer protocol of the transmission control protocol/Internet protocol
(TCP/IP) suite. Defined in STD 5, Request for Comments (RFC) 791. It is a connectionless, best-effort packet
switching protocol.
Internet Service Provider (ISP): A vendor who provides direct access to the Internet.
Internet Telephony: The transmission of voice over an Internet Protocol (IP) network. Also called Voice over IP
(VoIP), IP telephony enables users to make telephone calls over the Internet, intranets, or private Local Area
Networks (LANs) and Wide Area Networks (WANs) that use the Transmission Control Protocol/Internet Protocol
(TCP/IP).
ITU: See International Telecommunications Union.
Jitter: The deviation of a transmission signal in time or phase. It can introduce errors and loss of synchronization
in high-speed synchronous communications.
NIC (Network Interface Card): Adapter card inserted into computer that contains necessary software and
electronics to enable a station to communicate over network.
PCD file: An ASCII text file that contains product or platform configuration description information that is used
by the DM3 downloader utility program. Each of these files identifies the hardware configuration and firmware
modules that make up a specific hardware/firmware product. Each type of DM3-based product used in a system
requires a product-specific PCD file.
PSTN: see Public Switched Telephone Network
Public Switched Telephone Network: The telecommunications network commonly accessed by standard
telephones, key systems, Private Branch Exchange (PBX) trunks and data equipment.
Reliable Channel: A transport connection used for reliable transmission of an information stream from its
source to one or more destinations.
Reliable Transmission: Transmission of messages from a sender to a receiver using connection-mode data
transmission. The transmission service guarantees sequenced, error-free, flow-controlled transmission of messages
to the receiver for the duration of the transport connection.
RTCP: Real Time Control Protocol
RTP: Real Time Protocol
SIP: Session Initiation Protocol: an Internet standard specified by the Internet Engineering Task Force (IETF) in
RFC 3261. SIP is used to initiate, manage, and terminate interactive sessions between one or more users on the
Internet.
46
IP Media Server (Global Call) Demo Guide — August 2005
T1: A digital transmission link with a capacity of 1.544 Mbps used in North America. Typically channeled into 24
digital subscriber level zeros (DS0s), each capable of carrying a single voice conversation or data stream. T1 uses
two pairs of twisted pair wires.
TCP: see Transmission Control Protocol
Terminal: An H.323 Terminal is an endpoint on the local area network which provides for real-time, two-way
communications with another H.323 terminal, Gateway, or Multipoint Control Unit. This communication consists
of control, indications, audio, moving color video pictures, and/or data between the two terminals. A terminal may
provide speech only, speech and data, speech and video, or speech, data, and video.
Transmission Control Protocol: The TCP/IP standard transport level protocol that provides the reliable, full
duplex, stream service on which many application protocols depend. TCP allows a process on one machine to send
a stream of data to a process on another. It is connection-oriented in the sense that before transmitting data,
participants must establish a connection.
UDP: see User Datagram Protocol
UDPTL: Facsimile UDP Transport Layer protocol
User Datagram Protocol: The TCP/IP standard protocol that allows an application program on one machine to
send a datagram to an application program on another machine. Conceptually, the important difference between
UDP datagrams and IP datagrams is that UDP includes a protocol port number, allowing the sender to distinguish
among multiple destinations on the remote machine.
VAD: Voice Activity Detection
IP Media Server (Global Call) Demo Guide — August 2005
47
48
IP Media Server (Global Call) Demo Guide — August 2005
|