IP Media Server for Host Media Processing Demo Guide July 2005 05-2389-003
INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL® PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT.
Contents Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 About This Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1 Demo Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2 System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Figures 1 2 3 4 5 6 7 8 9 10 11 12 13 4 Demo Voice Menu Flowchart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 IP Media Server Demo Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 EventRouter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 IP Media Server Demo Threads . . . . . . . . . . . . . .
Contents Tables 1 2 3 4 5 6 7 8 9 Command Line Switches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Runtime Keyboard Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Files in IPMediaServer Folder Used by the IP Media Server Demo . . . . . . . . . . . . . . . . . . . . . Files in Modules Folder Used by the IP Media Server Demo . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents 6 IP Media Server for HMP Demo Guide – July 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-2389-003 July 2005 Added updated Linux information. 05-2389-002 April 2005 Globally changed file paths to use installation directory environment variable, and to reflect latest Windows directory hierarchy Globally removed Linux-specific information and references to pre-1.
Revision History 8 IP Media Server for HMP Demo Guide — July 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 • Intended Audience • How to Use This Publication • Related Information Purpose This guide provides information on the IP Media Server for HMP demo that is available with the Intel NetStructure® Host Media Processing Software product. The guide describes the demo, lists its requirements, and provides details on how it works.
About This Publication 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.
Demo Description 1. 1 This chapter describes the basic features of the IP Media Server for HMP demo. The IP Media Server for HMP 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.
Demo Description 12 IP Media Server for HMP Demo Guide — July 2005
System Requirements 2. 2 This chapter discusses the system requirements for running the IP Media Server for HMP demo. It contains the following topics: • Hardware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 • Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.
System Requirements 2.2 Software Requirements To run the IP Media Server for HMP demo as documented in this guide, you need one of the following software releases: • Intel NetStructure Host Media Processing Software 1.3 for Windows (or later) • Intel NetStructure Host Media Processing Software 1.5 for Linux (or later) For operating system requirements, see the release documentation (Release Guide or Release Notes) that accompanies your specific HMP release.
Preparing to Run the Demo 3. 3 This chapter discusses the preparations necessary to run the IP Media Server for HMP demo. It provides information about the following topics: • Editing Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 • Compiling and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 3.
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 Note: By default, the fax demo is turned off. This feature may be enabled when tested with T.38 capable IP endpoints.
Preparing to Run the Demo 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 V
Preparing to Run the Demo MediaAlarmLostPackets { Threshold = DebounceOn = DebounceOff = Interval = PercentSuccess = PercentFail = } MediaAlarmJitter { Threshold DebounceOn DebounceOff Interval PercentSuccess PercentFail } = = = = = = 20 10000 10000 1000 60 40 # # # # # # Threshold Threshold Threshold Threshold Threshold Threshold value debounce ON debounce OFF Time Interval (ms) Success Percent Fail Percent 60 20000 60000 5000 60 40 # # # # # # Threshold Threshold Threshold Threshold Threshold Thr
4 Running the Demo 4. This chapter discusses how to run the IP Media Server for HMP demo. It contains the following topics: • Starting the Demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 • Demo Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 • Using the Demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Running the Demo Table 1. Command Line Switches (Continued) -n Sets the number of channels The lesser of Voice Devices or IP devices -q Activates Quality of Service 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.
Running the Demo Main Menu [Main_Menu] 1 - Voice Mail 2 - Fax 3 - Conferencing (not supported in HMP 1.
Running the Demo Fax Menu [Fax_Menu] 1 - Send fax (to the IP Media Server demo) 2 - Receive fax (sent from the IP Media Server demo) * - Quit Send Fax Prompt [Send_Fax_Menu] Dial fax number - between 101 - 299 * - Quit Fax Sent Prompt [Fax_Sent_Menu] Announces that fax was sent and repeats Fax Menu: 1 - Send fax 2 - Receive fax * - Quit Receive Fax Menu [Receive_Fax_Menu] Dial fax number - between 101 - 299 * - Quit Fax Received Prompt [Fax_Received_Menu] Announces that fax was received and repeats Fax
Running the Demo Figure 1.
Running the Demo 4.4 Stopping the Demo The IP Media Server demo runs until it is terminated. Press “q” or “Q” to terminate the demo application.
5 Demo Details 5. This chapter discusses the IP Media Server for HMP demo in more detail. It contains the following topics: • Files Used by the Demo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 • Programming Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 • Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Demo Details Table 3. Files in IPMediaServer Folder Used by the IP Media Server Demo (Continued) Sub-Directory (if any) File Name Purpose Release 200.tif Sample fax file Release unavConf.vox Voice file Release cspPrompt.vox Voice file Release errorInput.vox Voice file Release faxMenu.vox Voice file Release faxReceived.vox Voice file Release faxSent.vox Voice file Release IPMediaServer.cfg Demo configuration file Release IPMediaServer.exe Demo executable Release listenMenu.
Demo Details Table 4. Files in Modules Folder Used by the IP Media Server Demo (Continued) Sub-Directory File Name Purpose FaxModule CFaxDevice.h Function prototype for cfaxdevice.cpp FaxModule CFaxModule.cpp Implements the operations of the CFaxModule class FaxModule CFaxModule.h Function prototype for cfaxmodule.cpp FaxModule CFaxStateMachine.cpp Implements the operations of the CFaxStateMachine class FaxModule CFaxStateMachine.h Function prototype for cfaxstatemachine.
Demo Details Table 4. Files in Modules Folder Used by the IP Media Server Demo (Continued) Sub-Directory 5.1.2 File Name Purpose VoiceModule CVoiceModule.cpp Implements the operations of the CVoiceModule class VoiceModule CVoiceModule.h Function prototype for cvoicemodule.cpp VoiceModule CVoiceStateMachine.cpp Implements the operations of the CVoiceStateMachine class VoiceModule CVoiceStateMachine.h Function prototype for cvoicestatemachine.cpp VoiceModule VoiceModule.
Demo Details 5.2.1 Module Structure The IP Media Server for HMP demo uses a modular architecture, in which each technology (IP, voice, fax, CSP)) is wrapped inside a module so that a particular technology can be easily added or removed.
Demo Details 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. Figure 3. EventRouter Retrieve event data from GC library Forward result to destination For which technology? IP Fax Voice Voice Module IP Module Fax Module Yes result result result No result.
Demo Details 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.
Demo Details Table 6. Application Classes (Continued) Class Name Interface CEventRouter Responsible for connecting all the modules.
Demo Details Table 7. IP Module Classes (Continued) Category Board Class Name Interface CIPTBoard • Interacts with the Global Call library to handle IP virtual boards Init( ) • 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.
Demo Details Table 7. IP Module Classes (Continued) Category Device Class Name Interface CIPDevice • Handles IP device operations, such as making/dropping calls, sending H.323 messages, making timeslot connections, etc. • Holds CIPStateMachine (or call control) Note: The public functions in this class should only be accessed by classes inside the IP module. Init( ) • Opens an IP device. If successful, creates an IP state machine. If QoS is enabled, creates a media alarm object.
Demo Details Table 8. Voice Module Classes Category Module Class Name CVoiceModule • Interacts with CVoiceBoard and CVoiceDevice. • Exports Voice module functions to CEventRouter. Note: The public functions in this class can be accessed by classes outside the Voice module. Board CVoiceBoard • Interacts with the voice library to handle voice boards Note: The public function in this class should only be accessed by classes inside the Voice module.
Demo Details Table 8. Voice Module Classes (Continued) Category Device Class Name Interface CVoiceDevice • Handles voice device operations, such as playing, recording, tone detection, and tone generation • Holds CVoiceStateMachine Note: The public functions in this class should only be accessed by classes inside the Voice module. Init( ) • Opens the voice device. If successful, creates voice state machine.
Demo Details Table 8. Voice Module Classes (Continued) Category State Machine Class Name CVoiceStateMachine • Handles voice events and maintains voice state machine(s) Note: The public functions in this class should only be accessed by the classes inside the voice module.
Demo Details Table 9. Fax Module Classes (Continued) Category Board Device Class Name Interface CFaxBoard • Interacts with the fax library to handle fax boards • The public function in this class should only be accessed by classes inside the Fax module Init( ) • Open fax board. CFaxDevice • Handles fax device operations, such as sending fax, receiving fax, etc. • Holds CFaxStateMachine Init( ) • Opens the fax device. If successful, creates fax state machine.
Demo Details Table 9. Fax Module Classes (Continued) Category State Machine Class Name Interface CFaxStateMachine • Handles fax events and maintains fax state machine Note: The public functions in this class should only be accessed by the classes inside the fax module. 5.3 Init( ) • Initializes fax state machine Exit( ) • Terminates fax state machine ProcessEvent( ) • Processes fax events Threads The IP Media Server for HMP demo operates with two threads, as shown in Figure 4. Figure 4.
Demo Details 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. Figure 5. System Initialization 1. Parse .
Demo Details 5.5 Event Handling This section describes how the IP Media Server for HMP demo handles events. It contains the following topics: • Event Mechanism • Handling Keyboard Input Events • Handling SRL Events • Handling Application Exit Events • TSUsrEvent Structure 5.5.1 Event Mechanism The IP Media Server demo uses the SRL mechanism to retrieve events. When an event occurs, SRL calls event handlers automatically.
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 neighborDevice; char 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, USR_SENDFAX, etc.
Demo Details Figure 6.
Demo Details Play Prompts After the call is connected, the Voice module is notified to play prompts and accept DTMF. Figure 7. Typical Scenario: Play Prompts CEventRouter CIPModule CIPDevice CIPState Machine CVoiceModule CVoiceDevice CVoiceState Machine USR_CONNECTED USR_CONNECTED USR_CONNECTED TDX_PLAY (finish playing main menu) TDX_PLAY 1. Call dx_listen( ) to listen to IP device 2.
Demo Details Fax Mailbox The user selects to send a fax to mailbox “101”. The Fax module is requested to send a fax. Figure 8. Typical Scenario: Fax Mailbox CEventRouter ...
Demo Details Establish Fax Session The Fax module requests the front end to get ready to send a fax. If the front end is IP, it should first move from an RTP port to a UDP port in order to send a fax. Figure 9. Typical Scenario: Establish Fax Session CEventRouter CIPModule CIPState Machine CIPDevice USR_ESTABLISHFAXSESSIONREQ USR_ESTABLISHFAXSESSIONREQ USR_ESTABLISHFAXSESSIONREQ GCEV_EXTENSION GCEV_EXTENSION 1. Call 2. Call 3. Call 4. Call gc_setConfigData( ) to set to manual (fax) mode.
Demo Details Fax Session Established The Fax module gets a reply from the front end that the fax session has been established. Figure 10. Typical Scenario: Fax Session Established CEventRouter ...
Demo Details Fax Sent The fax is sent. The front end is requested to close the fax session. Figure 11. Typical Scenario: Fax Sent CEventRouter CIPModule CIPDevice CIPState Machine USR_CLOSEFAXSESSIONREQ USR_CLOSEFAXSESSIONREQ USR_CLOSEFAXSESSIONREQ GCEV_EXTENSION GCEV_EXTENSION 1. Call gc_stop( ) to stop T.38 session 2. Call gc_extension ( ) to start audio session 3. Call gc_listen( ) listen to voice prompts GCEV_EXTENSION Format TSUserEvent to reply to fax module that T.
Demo Details Fax Session Closed The Fax module gets a reply from the front end that the fax session has been closed. Figure 12. Typical Scenario: Fax Session Closed CEventRouter ... CIPModule CFaxModule CFaxDevice CFaxState Machine USR_CLOSEFAXSESSIONCONF USR_CLOSEFAXSESSIONCONF USR_CLOSEFAXSESSIONCONF Format TSUserEvent to notify voice module fax is sent source=FAX destination=VOICE event= USR_FAXSENT Fax Complete The Voice module gets a reply from the Fax module that a fax has been sent.
Demo Details 50 IP Media Server for HMP Demo Guide — July 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.
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.
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.
IP Media Server for HMP Demo Guide — July 2005
Index A application classes 31 application exit events 41 C CallbackHdlr( ) 41 CConfig( ) 39 CEventRouter( ) 39 ChannelNumber( ) 31 CheckAndConvertDigits( ) 37 classes 31 application classes 31 Fax module classes 37 IP module classes 32 CloseFaxFile( ) 38 command-line switches 19 commands, keyboard 20 compiling and linking 18 configuration files, editing 15 Connect( ) 34, 36 CreateMailBoxFileName( ) 37 D Disconnect( ) 34, 36 E editing configuration files 15 event handling 41 application exit events 41 ke
M main( ) 41 module structure 29 O OnPlayComplete( ) 36 OpenFaxFile( ) 38 P ParseConfigFile( ) 31 PDL files 28 PDLSetApplicationExitPath( ) 41 PDLsr_enbhdlr( ) 41 PDLsr_enblhdlr( ) 39 Play( ) 36 ProcessEvent( ) 31 programming model 28 source code files 25 SRL events, handling 41 starting the demo 19 stopping the demo 24 switches, command line 19 system initialization 40 system requirements 13 T threads 39 ToLower_String( ) 38 TSUserEventProcessEvent( ) 37 TSUsrEvent structure 42 U using the media serve