(Page 1 of 1 in this chapter)

Chapter 6

Demonstration Programs

6.1 Introduction

6.2 Demonstration Programs

6.3 ISDN Daemon: isdncta

: 6.3.1 isdncta Structure and Coding Features

6.4 ISDN Call Control Demonstration: isdnchan

: 6.4.1 isdnchan Structure and Coding Features

6.1 Introduction

This chapter describes the functionality and structure of the demonstration programs supplied with your AG ISDN software package.
AG ISDN is shipped with source code for the demonstration programs. Each demonstration program is shipped as an executable program and with its source and makefiles.
Before you start the demonstration programs, ensure that: CT Access is properly installed. The AG board is executing. MVIP switching is correctly configured.
Refer to the appropriate installation manual for your operating system for details on installation.

6.2 Demonstration Programs

The following demonstration programs are provided with AG ISDN: Program Description isdncta A daemon which starts and stops the ISDN protocol stack. isdnchan Call control demonstration program.

Program	Description
isdncta	A daemon which starts and stops the ISDN protocol stack.
isdnchan	Call control demonstration program.

6.3 ISDN Daemon: isdncta

Option	Description	Default
`-a` nai	Network access identifier of trunk to use.	`0`
`-b` board_#	AG board number (Terminal Equipment interface). Note: do not use the `-B` option if this option is specified.	`0`
`-B` board_#	AG board number (Network Terminator interface). Note: do not use the `-b` option if this option is specified.	`0`
`-o` operator	Network operator variant. Allowed values: Value Protocol `3` France Telecom VN6 `8` Northern Telecom DMS 100 `9` INS-1500 NTT `11` EuroISDN ¹ `15` Australian Telecom 1 `16` QSIG `17` Hong Kong Telephone `20` US National ISDN 2 `23` AT&T 5ESS10 `24` AT&T 4ESS `25` Korea	`23` (AT&T 5ESS10)
`-c` country	Country. The behavior of a network operator may change depending on the country specified. The default country depends on the operator. Allowed values: Value Country `1` USA `32` Belgium `33` France `44` Great Britain `46` Sweden `49` Germany `61` Australia `81` Japan `82` Korea `86` China `92` Singapore `852` Hong Kong `1000` Europe*	`1` (USA)
`-s`	Creates the MVIP default connections needed to support AG ISDN call control. Only necessary if MVIP switching is enabled in your AG configuration file (i.e. `EnableMvip=YES`). If `EnableMvip=NO`, these connections are made automatically when the AG board boots. For more information, Section 3.3, Making Switch Connections for AG ISDN.	No connections are made. (Assumes MVIP switching is disabled.)
`-h` or `-?`	Display a help screen, and terminate the program.	N/A

Functional Overview

To enable other CT Access programs to place or receive calls on an ISDN trunk, the user starts the ISDN protocol stack by running isdncta. This program allows the user to choose from several ISDN operator variants based on command-line options.
When isdncta is launched, it does the following: 1. It parses command-line arguments, and makes sure all arguments are valid and do not conflict. 2. It initializes CT Access. 3. If the -s option is specified, isdncta makes MVIP connections needed to support AG ISDN call control. (If EnableMvip=NO in the AG configuration file, these connections are made automatically when the AG board boots.) For more information, see Section 3.3, Making Switch Connections for AG ISDN. 4. It starts the ISDN protocol stack on the AG board specified on the command-line, either as Terminal Equipment (TE) or as Network Equipment (NT), with the specified network operator variant and country variant. 5. It waits for the q key to be pressed. When the q key is pressed, the daemon program stops the ISDN protocol stack and terminates.

Procedure

To launch isdncta: 1. Set up your AG configuration file to describe your board and software configuration. For more information, see the AG ISDN Installation Manual and your AG Runtime Configuration and Developers Manual. 2. Run agmon to initialize your hardware and to make your AG configuration file changes effective. 3. To start the ISDN protocol stack, enter: isdncta [options] ... where options is one or more of the command line options described above. 4. Now launch another demonstration program. 5. When you have finished with the demonstration, press Q to terminate isdncta.

Compilation

isdncta is supplied in executable form and as source code.
If you need to recompile isdncta, do one of the following: Under this OS... Go to this directory... Enter... Windows NT c:\nms\ctaccess\demos\isdncta nmake UNIX /opt/nms/ctaccess/demos/isdncta make
For more information, see the readme file that came with the AG ISDN software package.

Under this OS...	Go to this directory...	Enter...
Windows NT	`c:\nms\ctaccess\demos\isdncta`	`nmake`
UNIX	`/opt/nms/ctaccess/demos/isdncta`	`make`

6.3.1 isdncta Structure and Coding Features

isdncta is based on the CT Access asynchronous programming model. Most function calls in the program are CT Access primitives, with names starting with adi or cta. An example is adiStartProtocol, which starts a TCP instance on a context. Other function calls in isdncta are found in CTADEMO, a library distributed with CT Access containing examples of how to use the API. CTADEMO functions have names starting with Demo. One example is DemoOpenPort, which opens the CT Access application queue, and then calls another demo function to create a context and open services on the new queue. Most CTADEMO functions are wrappers that enclose the corresponding ADI function and wait for an event to terminate the function, signaling whether the function was successful or not. In this way, they transform an asynchronous wait for an event into a synchronous function call.
The main function of isdncta first defines the list of CT Access service managers that the application will need. Then it calls ParseArguments, which parses command-line arguments, and assigns the corresponding values to variables. ParseArguments also checks that none of the user options are inconsistent with each other, and warns the user if it finds a problem.
Then main registers an error handler with CT Access, calls ctaInitialize to initialize CT Access, and calls MyOpenPort, which uses the demonstration library function DemoOpenPort to open a CTA context.
If the -s option was specified, main then calls MyMakeConnection, which uses the CT Access switching service to make the MVIP connections necessary to support Natural Call Control. For more information, see Section 3.3, Making Switch Connections for AG ISDN.
main then calls IsdnStart to start the ISDN protocol stack. IsdnStart calls isdnStartProtocol on the open CTA context with the operator and country variant specified on the command-line. isdnStartProtocol is started with ISDN_PROTOCOL_CHANNELIZED specified, so it runs in Natural Call Control mode.
main then calls WaitForKeyboardEvent. WaitForKeyboardEvent waits for the q key to be pressed. When the key is pressed, main calls IsdnStop, which calls isdnStopProtocol to stop the ISDN protocol stack. Then the daemon program terminates.

6.4 ISDN Call Control Demonstration: isdnchan

Name

isdnchan

Purpose

Uses the ISDN TCP with CT Access to receive and place calls. Demonstrates: Operation of the ISDN TCP, on a live trunk. Operation of the ISDN TCP across the MVIP bus. Operation in Non-Exclusive Mode.

Featured Functions

adiAnswerCall, adiGetCallStatus, adiPlaceCall, adiRejectCall, adiSetExtendedArgs, adiStartDTMF, adiStartProtocol, adiStartDTMF, swiMakeConnection, vcePlayList, vceRecordMessage

Requirements

Any AG board with DSPs (AG Quad T, AG Quad E, AG Dual T, AG Dual E, AG-T1, AG-E1, AG-24, AG-8, etc.).
CT Access version 2.0 or later.
If you are using CT Access 2.0, you also need AG Access 1.4, and the CT Access 2.0 Service Pack 2.
AG ISDN software.
The isd0.tcp TCP file.
Country-specific parameter files (.pf files).

adiisd.par (optional).

Note: Parameter files are optional for United States implementations.

Usage

isdnchan [options]
... where options is one or more of the following:

Option

Description

Default

-a mode

Accept call, without answering. mode specifies the call acceptance method:
1 Accept and play ring back tone.
2 Accept and remain silent until next
command.
3 Accept with user audio and play a voice file.
4 Accept with user audio and detect DTMFs.

Answer call.

-b board_#

AG board number.

0

-d

Use the TCP's default parameters, without loading a country-specific parameter file. Refer to for details on the default parameters of the AG ISDN TCP.

Loads a country-specific parameter file.

-h or -?

Display a help screen, and terminate.

N/A

-i

Enable interactive dialing.

Disabled.

-n num_to_dial

Number to dial. num_to_dial must be formatted appropriately, as described in Section 4.5.1, Initiating an Outbound Call.

123

-P

This option allows the user to place a call on an ISDN PRI trunk in Non-Exclusive Mode. This allows the equipment on the other side of the trunk to accept a call on any B channel.
Note that some ISDN Network Terminators do not accept "exclusive" calls. In these cases, you must use the -P option.

Exclusive Mode (Preferred Mode)

-r rings

Number of ring tones to play before answering inbound call.

2

-s n:m

MVIP stream and timeslot.

MVIP-95: 0:0
MVIP-90: 18:0
(depends upon board type)

-t threads

Number of threads to launch.

0

-u

Send a string of user-to-user information.

Disabled.

-v level

Verbosity level of messages printed on screen. level can be any of the following:
Value Description
0 Display error messages only
1 Display errors and unex-
pected high-level events
2 Display errors and all high-
level events
3 Display errors and all events

2

Option	Description	Default
`-a` mode	Accept call, without answering. mode specifies the call acceptance method: 1 Accept and play ring back tone. 2 Accept and remain silent until next command. 3 Accept with user audio and play a voice file. 4 Accept with user audio and detect DTMFs.	Answer call.
`-b` board_#	AG board number.	`0`
`-d`	Use the TCP's default parameters, without loading a country-specific parameter file. Refer to for details on the default parameters of the AG ISDN TCP.	Loads a country-specific parameter file.
`-h` or `-?`	Display a help screen, and terminate.	N/A
`-i`	Enable interactive dialing.	Disabled.
`-n` num_to_dial	Number to dial. num_to_dial must be formatted appropriately, as described in Section 4.5.1, Initiating an Outbound Call.	`123`
`-P`	This option allows the user to place a call on an ISDN PRI trunk in Non-Exclusive Mode. This allows the equipment on the other side of the trunk to accept a call on any B channel. Note that some ISDN Network Terminators do not accept "exclusive" calls. In these cases, you must use the `-P` option.	Exclusive Mode (Preferred Mode)
`-r` rings	Number of ring tones to play before answering inbound call.	`2`
`-s` n`:`m	MVIP stream and timeslot.	MVIP-95: `0:0` MVIP-90: `18:0` (depends upon board type)
`-t` threads	Number of threads to launch.	`0`
`-u`	Send a string of user-to-user information.	Disabled.
`-v` level	Verbosity level of messages printed on screen. level can be any of the following: Value Description 0 Display error messages only 1 Display errors and unex- pected high-level events 2 Display errors and all high- level events 3 Display errors and all events	`2`

Procedure

To start isdnchan for an ISDN demonstration: 1. Start agmon and isdncta, as described in Section 6.3. 2. Enter the following at the command line:
isdnchan [options] ... where options is one or more of the command line options described above.

Functional Overview

When isdnchan is started, it does the following: 1. If the -d option is not specified, the program loads the country-specific parameters that isd0.tcp will use. To do so, it loads and parses one of the country-specific parameter files provided with the product. 2. It starts the AG ISDN TCP isd0.tcp, configuring it using the parameters loaded in step 1. 3. It either places a call or waits for an inbound call, depending on the -i command-line option. 4. If it is commanded to dial out (outbound behavior), it dials either automatically or interactively, depending on the -i command-line option. 5. If the demonstration program is commanded to wait for a call (inbound behavior): a. It waits for incoming calls. b. When a call arrives, if the user has selected the -P command-line option (Non-Exclusive Mode), the program performs the switching to connect the B channel on which the call has been received to the appropriate DSP resource on the AG board. c. The user can answer immediately by pressing a key on the computer keyboard, or wait until a specified number of rings has been played by the TCP. When that number of rings have been played, the TCP answers without the user's intervention. d. At this point, the program checks the first digit of the incoming number. If the digit is an 8, it rejects the call and plays a busy tone. If the digit is a 9, it rejects the call, plays a reorder tone and goes back to waiting for calls. If the digit is a 0, it rejects the call and plays a Special Information Tone (SIT). Note: These digits are assigned in the code with a preprocessor directive. You can change them; for example, for tests in a switch-room environment where the demonstration program is connected to a line with an address starting with 8, 9, or 0. e. If the first digit is not an 8, 9, or 0, the demonstration program plays a welcome message and speaks back the digits it received. f. It then plays another prompt asking the user to choose an action by pressing a key on the telephone keypad. Available actions are: play a file, record a file, or hang up. g. It starts the DTMF tone detector and waits for a tone. If the tone does not arrive, it hangs up. h. If the tone arrives, the demonstration program performs the action that the tone specifies, then hangs up. 6. If the demonstration program seizes the line first (outbound behavior): a. It dials the number specified by the user. b. If the user has selected the -P command-line option (Non-Exclusive Mode), the program performs the switching to connect the B channel on which the call has been placed to the appropriate DSP resource on the AG board. c. When the call is answered, the demonstration program starts recording. d. When silence is detected, the demonstration program stops recording and plays the DTMF tone meaning "hang up" for its inbound counterpart. e. Then the program starts playing back the newly recorded voice file. f. When playing is completed, it hangs up.
The demonstration program hangs up if the caller hangs up at any time. If -v is specified on the command-line, the demonstration program displays on screen the CT Access messages it receives, according to the specified verbosity level.
The following table lists the interactions between two isdnchan applications connected back-to-back, in which one acts as an inbound application, and the other as an outbound application: outbound inbound Place call. Wait for call. Get connected. Answer call. Record. Speak prompt and digits. Send DTMF tone. Detect DTMF tone. Play back recorded file. Record voice. Wait for hang up, or hang up. Wait for hang up, or hang up.

outbound		inbound
Place call.		Wait for call.
Get connected.		Answer call.
Record.		Speak prompt and digits.
Send DTMF tone.		Detect DTMF tone.
Play back recorded file.		Record voice.
Wait for hang up, or hang up.		Wait for hang up, or hang up.

Compilation

isdnchan is supplied as executable as well as source code.
If you need to recompile isdnchan, do one of the following: Under this OS... Go to this directory... Enter... Windows NT c:\nms\ctaccess\demos\isdnchan nmake UNIX /opt/nms/ctaccess/demos/isdnchan make
For more information, see the readme file that came with the AG ISDN software package.

Under this OS...	Go to this directory...	Enter...
Windows NT	`c:\nms\ctaccess\demos\isdnchan`	`nmake`
UNIX	`/opt/nms/ctaccess/demos/isdnchan`	`make`

6.4.1 isdnchan Structure and Coding Features

isdnchan is based on the CT Access asynchronous programming model. Most function calls in the program are CT Access primitives, with names starting with adi or cta. An example is adiGetCallStatus, which retrieves a structure containing information about the current call. Other function calls in isdnchan are found in CTADEMO, a library distributed with CT Access containing examples of how to use the API. CTADEMO functions have names starting with Demo. One example is DemoRejectCall, which uses adiRejectCall and then waits for the result of the call before returning. Most CTADEMO functions are wrappers that enclose the corresponding adi function and wait for an event to terminate the function, signaling whether the function was successful or not. In this way, they transform an asynchronous wait for an event into a synchronous function call.

The main Function

The main function of isdnchan first defines the list of CT Access service managers that the application will need. Then it parses its command-line arguments, and assigns the corresponding values to its variables. The function also checks that none of the user options are inconsistent with each other, and warns the user if it finds a problem. Then it registers an error handler with CT Access and starts CT Access.
Then main launches the demonstration loop.

Opening the AG Driver, CTA Context and Protocol

In isdnchan, RunDemo defines the list of CT Access services needed by the application. Then it calls the DemoOpenPort function, a function from the CTADEMO library. DemoOpenPort opens the CT Access application queue, attaching all defined service managers. It then creates a CTA context and opens the defined services on the context specified by the user on the specified board. If the user did not specify these parameters in the command-line, the default CTA context opened is 18:0 ¹ on board 0. If this CTA context is already in use, the call to CT Access fails and the demonstration program terminates.
Next, RunDemo calls DemoLoadParameters, a function from the CTADEMO library. DemoLoadParameters loads a country-specific parameter file, containing parameters to configure the TCP for the particular implementation of ISDN used in the country. If the -c option was specified on the command-line with a three-letter country code cty, DemoLoadParameters looks for the file prtcty.par, where prt is the value given with the -p option on the command-line, minus the trailing digit. Otherwise, DemoLoadParameters searches for the file adiisd.par. It looks first in the current directory, and then in one of the following locations:

Windows NT: \nms\agaccess\cfg\country

UNIX: /opt/nms/agaccess/cfg/country
If the country-specific parameter file cannot be found, the demonstration program terminates.
Next, RunDemo starts the TCP on the opened CTA context. To do so, it calls adiStartProtocol with a NULL pointer for protoparms, so that the TCP uses the parameters just loaded from the country-specific parameter file.

Calling MyReceiveCall Or MyPlaceCall

At this point, RunDemo is ready to accept incoming calls or place outgoing calls. The incoming call loop is very simple: the function MyReceiveCall is called repeatedly. This function performs all of the call interaction, and hangs up the line when the call is completed. This function is discussed in detail below.
The loop does the following:

If the -i option (for interactive dialing) was specified on the command-line, the loop prompts the user to hit a key, and starts waiting for the keyboard event. When the user hits a key, the loop calls the function MyPlaceCall to place a call. This function is described in detail below.

If a call comes in while the loop is waiting for the user to press a key, the function MyReceiveCall is called. This function is described in detail below.

If the -i option was not specified, the loop immediately calls the function MyPlaceCall to place a call.

The Call Receiving Function MyReceiveCall

The function MyReceiveCall first determines why it has been called.

If MyReceiveCall was called because an incoming call was detected while the program was waiting to place an outgoing call, there is no need to wait further for a call. MyReceiveCall immediately queries CT Access to get information about the incoming call by invoking adiGetCallStatus. For AG ISDN, these attributes are:

The called number;

The calling party's number (ANI - Automatic Number Identification digits);

User-to-user (UUI) information, if present;

If Non-Exclusive Mode was selected, the stream and timeslot to be connected with the DSP resource managed by the application.

All these attributes are stored in a data structure, of type ADI_CALL_STATUS (See Section 4.4.1, Retrieving Call Information for more information.)
If the TCP signals to the application that the line has been seized and that call setup has begun, then the application must wait for the incoming call setup to be completed. The function does so by waiting for the appropriate CT Access event (ADIEVN_INCOMING_CALL). Once this event is detected, the function calls adiGetCallStatus to get the digit information as described above.
If Non-Exclusive Mode has been selected, the function calls ConnectBChannel to connect the appropriate DSP resource on the AG board to the B channel on the trunk.
While waiting for ADIEVN_INCOMING_CALL, MyReceiveCall may receive ADIEVN_INCOMING_DIGIT, indicating that a digit has arrived in the queue. MyReceiveCall displays a message on the screen which indicates the digit.
MyReceiveCall may also receive ADIEVN_CALL_DISCONNECTED, indicating that the calling party has hung up. MyReceiveCall calls hangup_in to hang up the call.

MyReceiveCall decides to answer or reject a call based on the first digit in the called number. Depending upon the digit, MyReceiveCall answers the call or rejects it in different ways. The digits MyReceiveCall looks for are defined at the top of isdnchan.c. They signify the following:

If the first digit equals BUSY_DIGIT, MyReceiveCall rejects the call. To do so, it calls CTADEMO function DemoRejectCall, which calls adiRejectCall, directing it to signal that the line is busy. Then DemoRejectCall waits for the event signifying that the caller has hung up (ADIEVN_CALL_DISCONNECTED).

If the first digit equals REJECT_DIGIT, MyReceiveCall rejects the call using DemoRejectCall, directing the TCP to signal that the number called is not allocated.

If the first digit equals USER_AUDIO_DIGIT, MyReceiveCall rejects the call using the function CustomRejectCall, that plays a Special Information Tone (SIT). CustomRejectCall defines the SIT, and then calls adiRejectCall with the argument ADI_REJ_USER_AUDIO. This tells the TCP to reject the call, and open a DSP resource to the application, so that custom audio can be played on the line. Then CustomRejectCall plays the defined SIT, and monitors the event queue for ADIEVN_TONES_DONE with reason ADI_REASON_RELEASED, and an ADIEVN_CALL_DISCONNECTED event. When both have been received, the function terminates.

If the first digit of the called number does not correspond to any of these digits, MyReceiveCall answers the call. To do so, it calls adiAnswerCall a first time with an argument that makes the TCP play four rings before answering automatically. Then MyReceiveCall waits for a user's keystroke. If this is detected, MyReceiveCall calls the function adiAnswerCall again. This makes the TCP answer the call immediately.

If MyReceiveCall answers the call, it then implements the following user interaction. This allows the demonstration program to talk either with a human being on a telephone, or with a corresponding outbound application:

First, it plays a voice message welcoming the user. To play voice files, it calls MyPlayMessage, which opens a voice file and calls VcePlayList to play it.

Next, MyReceiveCall plays voice files announcing the called number and the calling number, if available.

It plays another voice file with a menu, prompting the user to enter a DTMF tone from the telephone keypad to do one of the following: record a voice file, play a previously recorded voice file, or hang up.

It waits for a DTMF tone to be detected. To do so, it calls adiCollectDigits twice in an attempt to get the digits. If a DTMF tone is not detected, MyReceiveCall hangs up.

If a DTMF tone is detected, MyReceiveCall performs the task corresponding to the tone, and then hangs up. (If the command was to hangup, it hangs up immediately.) If the voice file to be played does not exist, MyReceiveCall plays a default voice file (i.e., "There is nothing to play.").

The Call Placement Function MyPlaceCall

The function MyPlaceCall does the following:

It tries to place a call to the number that the user specified in the command- line.

If -u was specified on the command line, MyPlaceCall invokes the function adiSetExtendedArgs, that prepares ADI to attach the extended arguments to adiPlaceCall.

To place the call, MyPlaceCall invokes adiPlaceCall with the digits to call, and waits for events.

When the event ADIEVN_PLACING_CALL occurs, if Non-Exclusive Mode was selected, the function calls ConnectBChannel to connect the appropriate DSP resource on the AG board to the B channel on the trunk.

When the call is answered, MyPlaceCall starts recording whatever input is on the line, waiting for a period of silence to stop recording. This operation is designed both to interact with a human being ("Hello") and to interact with the MyReceiveCall function, which speaks a little longer.

To record the voice data, MyPlaceCall opens a voice file to receive the recording and then invokes vceRecordMessage.

When silence is detected, MyPlaceCall first sends a DTMF tone on the line, by invoking adiStartDTMF. This is strictly to interact with MyReceiveCall: the DTMF tone is the one that tells it to hang up; however, it is not overwhelmingly disturbing for a human ear.

The Switching Function ConnectBChannel

The function ConnectBChannel does the following:

It parses the ADI_CALL_STATUS structure to find out the stream and timeslot on which the call has been placed (or received).

It calls the function swiMakeConection to create the bidirectional connection between the physical B channel on the trunk and the appropriate DSP resource on the AG board.

The SendIdleCode Function

The function SendIdleCode sends the idle code to the DSP resource handling a call, when the call is released. This avoids the situation in which a new call is connected to a DSP resource that is still performing a task related to the previous call.

(Page 1 of 1 in this chapter)

¹ In MVIP-95 terms, this is 4:0, 5,0.

tech_support@nmss.com