IP Gateway (Global Call) Demo Guide for Linux and Windows Copyright © 2002-2005 Intel Corporation 05-1662-005
COPYRIGHT NOTICE 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.
Table of Contents 1. About This Guide ............................................................................................ 1 1.1. Purpose........................................................................................................... 1 1.2. Intended Audience ......................................................................................... 1 1.3. Related Documents ........................................................................................ 1 2. Demo Description ........
IP Gateway (Global Call) Demo Guide for Linux and Windows 6.5.1. Handling Keyboard Input Events ........................................................ 29 6.5.2. Handling SRL Events.......................................................................... 29 6.5.3. Handling Application Exit Events....................................................... 30 6.6. Demo State Machine .................................................................................... 30 6.6.1. Call Establishment from IP .......
List of Tables Table 2. Command Line Switches ...................................................................... 18 Table 3. Runtime Keyboard Commands ............................................................. 20 Table 4. Source Files Used by the IP Gateway (Global Call) Demo ..................
IP Gateway (Global Call) Demo Guide for Linux and Windows vi
List of Figures Figure 1. Hardware Configuration with Onboard NIC and PSTN Front End....... 7 Figure 2. Hardware Configuration with Onboard NIC and separate PSTN board.............................................................................................................. 8 Figure 3. Typical Topology .................................................................................. 9 Figure 4. Programming Model............................................................................ 26 Figure 5.
IP Gateway (Global Call) Demo Guide for Linux and Windows viii
1. About This Guide This section describes the purpose of this guide, the intended audience, and references to other documents that may be useful to the user. 1.1. Purpose This guide describes the operation of the IP Gateway (Global Call) demo. 1.2. Intended Audience This guide is intended for application developers who will be developing a PSTN-IP gateway application using the Global Call API.
IP Gateway (Global Call) Demo Guide for Linux and Windows 2
2. Demo Description 2.1. About the Demo The IP Gateway (Global Call) demo is a host-based application that demonstrates using the Global Call API to build a PSTN−IP gateway. The demo source code can be used as sample code for those who want to begin developing an application from a working application. The demo is not designed to implement a complete gateway, lacking features such as least-cost routing, etc.
IP Gateway (Global Call) Demo Guide for Linux and Windows 4
3. System Requirements This chapter discusses the system requirement for running the IP Gateway (Global Call) demo. It contains the following topics: • Hardware Requirements • Software Requirements 3.1.
IP Gateway (Global Call) Demo Guide for Linux and Windows 6
4. Preparing to Run the Demo This chapter discusses how to prepare to run the IP Gateway (Global Call) demo. It provides information about the following topics: • Connecting to External Equipment • Editing Configuration Files 4.1.
IP Gateway (Global Call) Demo Guide for Linux and Windows Intel NetStructure® DM/V-A series board CTbus cable PSTN line Intel NetStructure® IPT board Internet/ Intranet line Figure 2. Hardware Configuration with Onboard NIC and separate PSTN board The IP Gateway (Global Call) demo allows you to connect to gateways on an IP network and establish voice calls via the IP network. It also allows you to connect to H.
4. Preparing to Run the Demo Fax Fax IP Network IP Gateway IP Gateway PBX PBX Telephone Telephone H.323 Terminal Figure 3. Typical Topology 4.2. Editing Configuration Files This section discusses how to configure the demo for your system. It contains the following topics: • Configuration file location • Editing the gateway_r4.cfg File 4.2.1. Configuration File Location Before running the IP Gateway (Global Call) demo, modify the gateway_r4.cfg file to reflect your system environment.
IP Gateway (Global Call) Demo Guide for Linux and Windows 4.2.2. Editing the gateway_r4.cfg File Below is an example of the gateway_r4.cfg file. Update the following information: ipProtocol The IP Protocol used for opening the IP Line devices, values: H323, SIP, both Channel Channels defined by this section of the file - may be individual channel or a range of channels Source Source address Destination Destination address RemotePhoneNumber Destination phone number to call.
4. Preparing to Run the Demo • • CoderFramesPerPkt - frames per packet for the selected coder CoderVAD - Voice Activity Detection on/off AudioTxCodecs Capability for transmit audio codecs. See AudioRxCodecs for a complete description. DataCodecs Capability for fax codecs. The demo currently support T38 only. MediaAlarmLostPackets Indicates that the percentage of packets lost during a call exceeded its threshold value • Threshold - defines when a Quality of Service (QoS) parameter is in a fault condition.
IP Gateway (Global Call) Demo Guide for Linux and Windows UII User Input Indication string to send NonStdParm Non-standard parameter data to send NonStdCmd Non-standard command string to send ObjId Object ID Q931Facility Facility data to send on the Q.931 channel DTMF DTMF mode. Possible options: OutOfBand, inband, rfc2833 enableRegestration Register with gatekeeper TTL Time-to-live parameter (in seconds) Protocol Call control protocol.
4. Preparing to Run the Demo The following is an example of a configuration file. ######################################################################################## # Telephony Protocol : # For ANAPI(Analog Front End) use the root file name of the analog protocol file for your country or telephone network) # For ICAPI (Digital Front End) use the root file name of the country dependent parameter <.
IP Gateway (Global Call) Demo Guide for Linux and Windows DTMFmode = OutOfBand AudioRxCodecs { CoderType = g711Mulaw CoderFramesPerPkt = 30 CoderVAD = 0 } AudioTxCodecs { CoderType = g711Mulaw CoderFramesPerPkt = 30 CoderVAD = 0 } DataCodecs { CoderType = t38 } MediaAlarmLostPackets { Threshold = 20 DebounceOn = 10000 DebounceOff = 10000 Interval = 1000 PercentSuccess = 60 PercentFail = 40 } MediaAlarmJitter { Threshold DebounceOn DebounceOff Interval PercentSuccess PercentFail } = = = = = = # MediaAlarm
4. Preparing to Run the Demo # use 0.0.0.0 as the default address for descovering the GK regServerAddress = 10.242.214.
5. Running the Demo This chapter discusses how to run the IP Gateway (Global Call) demo. It contains the following topics: • Starting the Demo • Demo Options • Using the Demo • Stopping the Demo 5.1. Starting the Demo Windows From a command prompt, change directories to: $(INTEL_DIALOGIC_DIR)\samples\\ipt_demos\gateway_r4\Release Type gateway_r4 at the command prompt to run the IP Gateway (Global Call) demo using the default settings.
IP Gateway (Global Call) Demo Guide for Linux and Windows Table 1. Command Line Switches Switch Action Default -c Configuration file name gateway_r4.cfg -d Sets Debug Level (0-4): 0 - FATAL 0-FATAL: used when one or more channels are deadlocked. 1-ERROR: used when the application receives a failure which doesn’t cause the channel to be deadlocked. 2-WARNING used when some problem or failure occurred without affecting the channel’s usual action.
5. Running the Demo Switch Action Default -l Printouts will be printed into channel log files. Disabled If ‘all’ follows the –l, log files will be created for all available channels. If a list of channels in the following format: C1-C2, C3-C4, C5 (e.g., 110,112-150,314) follows the –l, log files are created for the channel ranges or specific channels specified in the list.
IP Gateway (Global Call) Demo Guide for Linux and Windows 5.3. Using the Demo The demo always waits for input from the keyboard. While the demo is running, you can enter any of the following commands: Table 2. Runtime Keyboard Commands Command Function c or C Print channel information d or D Change debug level during runtime f or F Send Q.
6. Demo Details This chapter discusses the IP Gateway (Global Call) demo in more detail. It contains the following topics: • Files Used by the Demo • Handling an Incoming Call • Programming Model • Initializations • Event Handling • Demo State Machine 6.1. Files Used by the Demo 6.1.1. Demo Source Files In Windows the following files are located in $(INTEL_DIALOGIC_DIR)\samples\ipt_demos\gateway_r4. In Linux the following files are located in $(INTEL_DIALOGIC_DIR)/ipt_demos/gateway_r4. Table 3.
IP Gateway (Global Call) Demo Guide for Linux and Windows Filename Description OS gatepars.c The demo configuration file parsing functions Both gatepars.h Function prototype for gatepars.c Both gatepstn.c PSTN-specific functions Both gatepstn.h Function prototype for gatepstn.c Both gatestate.c State machine functions Both gatestate.h Function prototype for gatestat.c Both gatestrc.h Demo structure (including Main Structure Session) Both gatevars.
6. Demo Details Filename Description OS register.h Function prototype for register.c Both Release\ gateway_r4.cfg Demo configuration file Windows Release/ gateway_r4.cfg Demo configuration file Linux Release\ gateway_r4.exe Executable Windows Release/ gateway_r4.exe Executable Linux 6.1.2. Utility Files In Windows the following files are located $(INTEL_DIALOGIC_DIR)\samples\ipt_demos\Shared In Linux the following files are located in $(INTEL_DIALOGIC_DIR)/ipt_demosShared.
IP Gateway (Global Call) Demo Guide for Linux and Windows Filename Description OS Release\util.lib Compiled Utility library Windows 6.1.3. PDL Files In Windows the following files are located in $(INTEL_DIALOGIC_DIR)\samples\ipt_demosShared In Linux the following files are located in $(INTEL_DIALOGIC_DIR)/ipt_demos/Shared Filename Description OS pdl_win\iptransport.cpp PDL IP transport functions Windows pdl_win\iptransport.h Function prototype for iptransport.cpp Windows pdl_win\pdl.
6. Demo Details Filename Description OS /pdl_linux/pdl.c Platform dependency functions Linux /pdl_linux/pdl.h Function prototype for pdl.c Linux /pdl_linux/ pdl_linux_version.c PDL version information Linux 6.2. Handling an Incoming Call This section discusses how the demo application handles incoming calls. It contains the following topics: • Receiving a Call • Handling a PSTN Call • Handling an IP Call 6.2.1.
IP Gateway (Global Call) Demo Guide for Linux and Windows Once the destination gateway has answered the H.323 call, the IP Gateway (Global Call) demo connects the PSTN call to the IP call. An audio path is now established between the PSTN call and the destination IP station. For more details see section 6.5. Event Mechanism . 6.2.3. Handling an IP Call A call that arrives from the IP network needs to be routed to a PSTN number.
6. Demo Details The threads are created as follows: • The first (main) thread is created by the demo application to get the keyboard input. • The second thread is an SRL thread, created as a result of the demo application calling sr_enblhdlr( ) in Windows. In Linux, the thread must be explicitly created. All Global Call events are received through the SRL. 6.4. Initializations The application main() function calls gateInitialize(), which does the following: 1.
IP Gateway (Global Call) Demo Guide for Linux and Windows • • 9. Calculates the logical board and channel and saves them into Session.pstnParams Closes the board, by calling dx_Close( ) or dt_Close( ). Call ipGetChannels( ) which checks how many available IP channels there are by doing the following: • Gets number of IP boards from #define MAX_IP_BOARDS in gatedefs.
6. Demo Details • Calls gc_OpenEx( ) which opens all IP devices, returns the IP LineDevH, and saves it in Session.ipParams • Saves the channel number in the global array HandleToChannel[ ] according to the LineDevH handle 13. The application main() function calls waitForKey( ), to receive keyboard input. 6.5. Event Mechanism The IP Gateway (Global Call) demo uses the SRL mechanism to retrieve events. When an event occurs, SRL calls event handlers automatically.
IP Gateway (Global Call) Demo Guide for Linux and Windows 3. Otherwise, the application calls gc_GetUsrAttr( ) and then calls either ipGetEvent( ) to process the IP event, or pstnGetEvent( ) to process the PSTN event. 6.5.3. Handling Application Exit Events Normal application exit events 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.
6.
IP Gateway (Global Call) Demo Guide for Linux and Windows 3. In IP_CONNECTED, when the application receives GCEV_CONNECTED from the PSTN side, the application calls pstnListen( ), which in turn calls ag_Listen( ) or dt_Listen( ) (ag for analog; dt for digital) to tell the PSTN line device to listen to the IP time slot The state transitions to GATE_CONNECTED 6.6.2. Call Establishment from PSTN This section describes what happens when a call is initiated from the PSTN network.
6. Demo Details 2. In PSTN_OFFERED the application waits for GCEV_CONNECTED from the IP side.
IP Gateway (Global Call) Demo Guide for Linux and Windows 2. When the application receives GCEV_DROPCALL from the IP side, it calls gc_Extension( ) to get the RTCP information. When the application receives GCEV_EXTENSION the application calls gc_ReleaseCall( )and the state transitions to GATE_NULL. 6.6.4. Glare Conditions Glare conditions occur when a call is being initiated from both sides at the same time.
Appendix A Log File of IP Call Establishment DATE: 08/16/01 TIME: 10:49:20 TRACE: File: gatepstn.c Line: 189 End of pstnOpenFrontEnd function on channel 14 DATE: 08/16/01 TIME: 10:49:21 TRACE: File: gateip.c Line: 99 Start ipOpenDevices function on channel 14 DATE: 08/16/01 TIME: 10:49:21 TRACE: File: gateip.c Line: 116 End of ipOpenDevices function on channel 14 DATE: 08/16/01 TIME: 10:49:21 TRACE: File: gatepstn.
IP Gateway (Global Call) Demo Guide for Linux and Windows TRACE: File: gateip.c Line: 466 End of ipGetEvent function on channel 14 DATE: 08/16/01 TIME: 10:53:00 TRACE: File: gateip.c Line: 385 In ipGetEvent function on channel 14 DATE: 08/16/01 TIME: 10:53:00 TRACE: File: gateip.c Line: 227 Start OnExtension function on channel 14 DATE: 08/16/01 TIME: 10:53:00 INFO: File: gateip.c Line: 250 Got extension data display: DATE: 08/16/01 TIME: 10:53:00 INFO: File: gateip.
Appendix A TRACE: File: gateip.c Line: 466 End of ipGetEvent function on channel 14 DATE: 08/16/01 TIME: 10:53:01 TRACE: File: gateip.c Line: 385 In ipGetEvent function on channel 14 DATE: 08/16/01 TIME: 10:53:01 TRACE: File: gatestate.c Line: 357 In IP_OFFERED State on channel (0xe) got event GCEV_ANSWERED (0x802) from IP DATE: 08/16/01 TIME: 10:53:01 TRACE: File: gatepstn.c Line: 369 In pstnGetEvent function on channel 14 DATE: 08/16/01 TIME: 10:53:01 TRACE: File: gatestate.
IP Gateway (Global Call) Demo Guide for Linux and Windows TRACE: File: gatestate.c Line: 841 Drop call on channel 14 DATE: 08/16/01 TIME: 10:54:24 TRACE: File: gateip.c Line: 466 End of ipGetEvent function on channel 14 DATE: 08/16/01 TIME: 10:54:24 TRACE: File: gatepstn.c Line: 369 In pstnGetEvent function on channel 14 DATE: 08/16/01 TIME: 10:54:24 TRACE: File: gatestate.
Appendix B Log File of PSTN Call Establishment DATE: 08/16/01 TIME: 10:57:55 TRACE: File: gatepstn.c Line: 189 End of pstnOpenFrontEnd function on channel 10 DATE: 08/16/01 TIME: 10:57:56 TRACE: File: gateip.c Line: 99 Start ipOpenDevices function on channel 10 DATE: 08/16/01 TIME: 10:57:56 TRACE: File: gateip.c Line: 116 End of ipOpenDevices function on channel 10 DATE: 08/16/01 TIME: 10:57:57 TRACE: File: gatepstn.
IP Gateway (Global Call) Demo Guide for Linux and Windows TRACE: File: gateip.c Line: 140 Start ipMakeCall function on channel 10 DATE: 08/16/01 TIME: 10:58:37 TRACE: File: gateip.c Line: 205 End of ipMakeCall function on channel 10 DATE: 08/16/01 TIME: 10:58:37 TRACE: File: gatepstn.c Line: 369 In pstnGetEvent function on channel 10 DATE: 08/16/01 TIME: 10:58:37 TRACE: File: gatestate.
Appendix B DATE: 08/16/01 TIME: 10:58:38 TRACE: File: gateip.c Line: 385 In ipGetEvent function on channel 10 DATE: 08/16/01 TIME: 10:58:38 TRACE: File: gateip.c Line: 227 Start OnExtension function on channel 10 DATE: 08/16/01 TIME: 10:58:38 INFO: File: gateip.c Line: 250 Got extension data display: target DATE: 08/16/01 TIME: 10:58:38 TRACE: File: gateip.c Line: 362 End of OnExtension function on channel 10 DATE: 08/16/01 TIME: 10:58:38 TRACE: File: gatestate.
IP Gateway (Global Call) Demo Guide for Linux and Windows DATE: 08/16/01 TIME: 11:00:03 TRACE: File: gatepstn.c Line: 348 End of pstnUnListen function on channel 10 DATE: 08/16/01 TIME: 11:00:03 TRACE: File: gatestate.c Line: 841 Drop call on channel 10 DATE: 08/16/01 TIME: 11:00:03 TRACE: File: gatepstn.c Line: 369 In pstnGetEvent function on channel 10 DATE: 08/16/01 TIME: 11:00:03 TRACE: File: gatestate.
Appendix B DATE: 08/16/01 TIME: 11:00:05 TRACE: File: gateip.
IP Gateway (Global Call) Demo Guide for Linux and Windows 44
Index A G ag_Listen( ), 32, 33 GATE_CONNECTED, 32, 33 ag_Unlisten( ), 33 GATE_DROP, 33 APPMAIN.C, 29 GATE_NULL, 30 ATDV_SUBDEVS( ), 27 gatedefs.h, 21 C gateip.c, 21 Call connection, 3 gateip.h, 21 Call establishment, 25 gatemain.c, 21 Call progress tones, 26 gatepars.c, 22 Call state GATE_CONNECTED, 32, 33 GATE_DROP, 33 GATE_NULL, 30 IP_CONNECTED, 31, 33 IP_DROP, 33 IP_OFFERED, 31, 33 PSTN_OFFERED, 32 gatepars.h, 22 Call Teardown, 33 checkArg( ), 27 gatepstn.c, 22 gatepstn.
IP Gateway (Global Call) Demo Guide for Linux and Windows gc_DropCall( ), 33 IP address, 25 gc_Extension( ), 31, 33 IP, Log File, 35 gc_GetNetworkH( ), 28 IP_CONNECTED, 31, 33 gc_GetVoiceH( ), 28 IP_DROP, 33 gc_GetXmitSlot(), 30 IP_OFFERED, 31, 33 gc_Listen( ), 31, 33 ipGetChannels( ), 27 gc_MakeCall( ), 31, 32 ipOpenDevices( ), 28 gc_Open( ), 27 IPTMail_R4.
Index N T NetwH, 28 Teardown, 33 P U PDL, 3 util.dsp, 23 pdl.c, 24 util.dsw, 23 PDLsr_enbhdlr( ), 27 util.lib, 23 PDLsr_getboardcnt( ), 27 util.ver, 23 Platform Dependency Library, 3 V PSTN State Diagram, 32 VoiceH, 28 PSTN channel, 3 PSTN, Log File, 39 PSTN_OFFERED, 32 pstnGetVOXChannels( ), 27 pstnOpenFrontEnd( ), 28 R remote phone number, 25 Routing, 25 S Session.ipParams, 28 Session.
48
