(Page 1 of 1 in this chapter) Version

Chapter 7

Demonstration Programs

7.1 Introduction

7.2 Demonstration Programs

7.3 ISDN Daemon: isdncta

: 7.3.1 isdncta Structure and Coding Features

7.4 ISDN Call Control Demonstration: isdnchan

: 7.4.1 isdnchan Structure and Coding Features

7.5 ISDN NCC Call Control Demonstration: isdnncc

: 7.5.1 isdnncc Structure and Coding Features

7.1 Introduction

This chapter describes the functionality and structure of the demonstration programs supplied with your AG ISDN software package.
Each demonstration program is shipped as an executable program, including 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.

7.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. isdnncc ISDN NCC call control demonstration program. isdnchan ISDN ADI call control demonstration program.

Program	Description
isdncta	A daemon which starts and stops the ISDN protocol stack.
isdnncc	ISDN NCC call control demonstration program.
isdnchan	ISDN ADI call control demonstration program.

7.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 `-B` if this option is specified.	`0`
`-B` board_#	AG board number (Network Terminator interface). Note: Do not use `-b` if this option is specified.	`0`
`-I` hex_bit	(Optional) Setting for in_calls_behavior, in hex. Use to make bit settings required for overlap receiving and/or channel ID setting (see Chapter 4): CC_TRANSPARENT_OVERLAP_RCV =0x0080 CC_SET_CHAN_ID=0x2000	0x0
`-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 `50` Taiwan	`23` (AT&T 5ESS10)
`-O` hex_bit	(Optional) Setting for out_calls_behavior, in hex. Use to make bit settings required for overlap sending and/or A-law/mu law coding (see Chapter 4): CC_USER_SENDING_COMPLETE =0x0002 CC_USE_MU_LAW=0x0010 CC_USE_A_LAW=0x0020	0x0
`-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 `866` Taiwan `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.)
`-T`	t309 option for D channel backup configurations (see Appendix C).	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: It parses command line arguments, and makes sure all arguments are valid and do not conflict. It initializes CT Access. 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. 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. 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: Set up your AG configuration file to describe your board and software. For more information, see the AG ISDN Installation Manual and AG Runtime Configuration and Developers Manual. Run agmon to initialize your hardware and to make your AG configuration file changes effective. To start the ISDN protocol stack, enter: isdncta [options] ... where options is one or more of the command line options described above. Now launch another demonstration program. When you have finished, 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 \nms\ctaccess\demos\isdncta nmake UNIX /opt/nms/ctaccess/demos/isdncta make
For more information, see the AG ISDN readme file.

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

7.3.1 isdncta Structure and Coding Features

isdncta is based on the CT Access asynchronous programming model. Most functions 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 functions 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 demonstration 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.
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.

7.4 ISDN Call Control Demonstration: isdnchan

Name

isdnchan

Purpose

Uses the ISDN TCP with the ADI service 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.

Note: isdnchan requires prior initialization of the ISDN protocol stack (via a call to isdnStartProtocol). To initialize the ISDN protocol stack, a program like isdncta can be used. For more information, see Section 7.3.

Featured Functions

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

Requirements

Any AG digital trunk interface board.
CT Access version 3.0 or later.
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:
Value Description
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 Appendix B 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 5.3.4, Digit Strings in Outbound Calls.

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.
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
unexpected 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: Value Description 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 Appendix B 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 5.3.4, Digit Strings in Outbound Calls.	`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. 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 unexpected 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: Start agmon and isdncta, as described in Section 7.3. 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: 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. It starts the AG ISDN TCP isd0.tcp, configuring it using the parameters loaded in step 1. It either places a call or waits for an inbound call, depending on the -i command line option. If it is commanded to dial out (outbound behavior), it dials either automatically or interactively, depending on the -i command line option. 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 the 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. 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 \nms\ctaccess\demos\isdnchan nmake UNIX /opt/nms/ctaccess/demos/isdnchan make
For more information, see the AG ISDN readme file.

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

7.4.1 isdnchan Structure and Coding Features

isdnchan is based on the CT Access asynchronous programming model. Most functions 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 functions 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 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.
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\ctaccess\cfg\

UNIX: /opt/nms/ctaccess/cfg/
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 later in this chapter.
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 later in this chapter.

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 5.5, 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 in 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 CustomRejectCall, which 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 to open a DSP resource to the application, so that custom audio can be played on the line. Then CustomRejectCall plays the defined SIT, and waits 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 does not match any of these digits, MyReceiveCall answers the call. To do so, it calls adiAnswerCall a first time with an argument to make 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 adiSetExtendedArgs, which prepares the ADI service 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 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 adiSetExtendedArgs, which prepares the ADI service 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.

7.5 ISDN NCC Call Control Demonstration: isdnncc

Name

isdnncc

Purpose

Uses the ISDN TCP with CT Access to receive and place calls.
Demonstrates:

Usage of NCC functions

Operation of the ISDN TCP on a live trunk

Operation of the ISDN TCP across the MVIP bus

Operation in Non-Exclusive Mode

Note: isdnncc requires prior initialization of the ISDN protocol stack (using isdnStartProtocol). To initialize the ISDN protocol stack, a program like isdncta can be used. For more information, see Section 7.3.

Featured Functions

adiCollectDigits, adiGetBoardInfo, adiStartCallProgress, adiStartDTMF, nccAnswerCall, nccDisconnectCall, nccGetCallStatus, nccGetExtendedCallStatus, nccPlaceCall, nccQueryCapability, nccRejectCall, nccReleaseCall, nccStartProtocol, swiMakeConnection, vcePlayList, vceRecordMessage

Requirements

Any AG digital trunk interface board.
CT Access version 3.0 or later.
AG ISDN software.
The isd0.tcp TCP file.
Country-specific parameter files (.pf files).
nccxisdn.par (optional).

Usage

isdnncc [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:
Value Description
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 the parameter file.
Refer to Appendix B for details on the default NCC parameters of the AG ISDN TCP.

Loads the parameter file.

-h or -?

Display a help screen, and terminate.

N/A

-i

Program behaves as inbound.

Outbound.

-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.
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 an 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
unexpected 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: Value Description 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 the parameter file. Refer to Appendix B for details on the default NCC parameters of the AG ISDN TCP.	Loads the parameter file.
`-h` or `-?`	Display a help screen, and terminate.	N/A
`-i`	Program behaves as inbound.	Outbound.
`-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. 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 an 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 unexpected high-level events 2 Display errors and all high- level events 3 Display errors and all events	2

Procedure

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

Functional Overview

When isdnncc is started, it does the following:

If the -d option is not specified, the program loads parameters that isd0.tcp will use.

To do so, it loads and parses one of the nccxisdn.par parameter files provided with the product.

It starts the AG ISDN TCP isd0.tcp, configuring it using the parameters loaded in step 1.

It either places a call or waits for an inbound call, depending on the -i command line option.

If it is commanded to dial out (outbound behavior), it dials automatically.

If the demonstration program is commanded to wait for a call (inbound behavior):

a. It waits for incoming calls.
b. When a call arrives, call status structures are accessed to retrieve the incoming call information such as the called number, calling number or UUI, if any.
c. 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.
d. If the -a option has been specified in the command line, the call is accepted using the mode supplied by the user.
e. 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 immediately rejects the call by calling nccDisconnectCall, starting the disconnect procedure.
f. If a reject digit was not found in the incoming number, the program waits until a specified number of rings have been played by the TCP. When the rings have been played, the TCP answers the call.
g. 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.
h. It then plays another prompt asking the user to choose an action by pressing a key on the telephone keypad. Available actions are: record a file ("1"), play a file ("2"), or hang up ("3").
i. The demonstration program starts the DTMF tone detector and waits for a tone. If the tone does not arrive, it hangs up.
j. If the tone arrives, the demonstration program performs the action that the tone specifies, then hangs up.

If the demonstration program seizes the line first (outbound behavior):

a. It dials the number specified by the user. The calling number is precoded as "987".
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 call progress.
d. If call progress detects the busy tone, the program hangs up, and ring tones are reported to the user. If call progress finishes with silence or detects voice, the program starts recording.
e. When silence is detected by the recording functions, the demonstration program stops recording and plays the DTMF tone "3" meaning "hang up" for its inbound counterpart.
f. When playing is completed, it hangs up.
The demonstration program hangs up if the caller hangs up at any time. If the program receives NCCEVN_CAPABILITY_UPDATE (meaning that the state of the ISDN stack has changed), it displays the new capability mask.
If the program receives NCCEVN_EXTENDED_CALL_STATUS_ UPDATE (sent by the TCP when a new UUI string or a progress descriptor is received from the network), a new field is displayed on the screen.
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 isdnncc 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. Hang up. Hang up.

Outbound		Inbound
Place call.		Wait for call.
Get connected.		Answer call.
Record.		Speak prompt and digits.
Send DTMF tone.		Detect DTMF tone.
Hang up.		Hang up.

Compilation

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

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

7.5.1 isdnncc Structure and Coding Features

isdnncc is based on the CT Access asynchronous programming model. Most function calls in the program are CT Access primitives, with names starting with ncc (for call control), adi (for media operations) or cta. An example is nccGetCallStatus, which retrieves a structure containing some information about the current call. Other function calls in isdnncc 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 DemoSetReportLevel, which sets a filter to tell which messages to report. Most CTADEMO functions are wrappers that enclose the corresponding NCC, ADI, or CTA 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.
The main Function
The main function of isdnncc 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 isdnncc, 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 ctaLoadParFile, a function from the CTA library. ctaLoadParFile loads the nccxisdn.par parameter file, containing parameters to configure the TCP. It looks for this file first in the current directory, and then in one of the following locations:

Windows NT: \nms\ctaccess\cfg\

UNIX: /opt/nms/ctaccess/cfg/
If the nccxisdn.par parameter file cannot be found, the demonstration program terminates.
Next, RunDemo starts the TCP on the opened CTA context. To do so, it calls nccStartProtocol with the following arguments:

startparms: a pointer to NCC_START_PARMS

mgrstartparms: a NULL pointer, to cause ADI to use the default ADI manager parameters just loaded from the country-specific parameter file (*.pf)

protstartparms: a pointer to NCC_ADI_ISDN_PARMS
Since RunDemo changes the parameter defaults for NCC startparms and ISDN protstartparms, it first calls ctaGetParms to obtain the default parameter values.
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: MyReceiveCall is called repeatedly. This function performs all the call interactions, and hangs up the line when the call is completed. If the -i option was not specified, the loop immediately calls MyPlaceCall to place a call.
The Call Receiving Function MyReceiveCall
The function MyReceiveCall waits for NCCEVN_INCOMING_CALL event and then immediately queries CT Access to get information about the incoming call by invoking nccGetCallStatus and nccGetExtendedCallStatus. The attributes are:

The called party information

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

The redirecting party information, if present

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 data structures, of type NCC_CALL_STATUS and NCC_ISDN_EXT_CALL_STATUS. (See Section 4.4, Retrieving Call Information for more information.)
If Non-Exclusive Mode has been selected, MyReceiveCall 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 NCCEVN_RECEIVED_DIGIT, indicating that a digit has arrived in the queue. MyReceiveCall displays a message on the screen which indicates the digit. An NCCEVN_RECEIVED_DIGIT event is possible if the ISDN variant supports overlapped receiving mode and the user sets the appropriate behavior bit while starting ISDN protocol. (See Section 4.8 for more information). MyReceiveCall may also receive NCCEVN_CALL_DISCONNECTED, indicating that the calling party has hung up. MyReceiveCall calls hangup_in to hang up the call.
If the state of the ISDN stack changes MyReceiveCall receives NCCEVN_CAPABILITY_UPDATE. It then invokes nccQueryCapability to retrieve the new capabilitymask. It prints this information on the screen. If the NCC_ISDN_EXT_CALL_STATUS structure is updated, NCCEVN_EXTENDED_CALL_STATUS_UPDATE is sent to the application. The value field of the event indicates the type of information that was changed. Currently, there are two fields which may be updated: uui and progressdescription. They are changed if the value of the event is equal to the value of NCC_X_STATUS_INFO_UUI and/or the NCC_X_STATUS_INFO_PROGRESS descriptor.
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 in isdnncc.c. They signify the following:

If the first digit equals REJECT_BUSY_DIGIT, MyReceiveCall rejects the call. To do so, it calls MyRejectCall, which calls nccRejectCall with the mode NCC_REJECT_PLAY_BUSY, directing it to signal that the line is busy. Then MyRejectCall waits for the event signifying that the caller has hung up (NCCEVN_CALL_DISCONNECTED).

If the first digit equals REJECT_REORDER_DIGIT, MyReceiveCall rejects the call using nccRejectCall with the mode NCC_REJECT_PLAY_REORDER, directing the TCP to play the reorder tone.

If the first digit equals REJECT_IMMEDIATE_DIGIT, MyReceiveCall immediately rejects the call by calling the MyHangUp function to initiate the disconnect procedure.

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 nccAnswerCall a first time with an argument that causes the TCP to play two rings before answering automatically. Then MyReceiveCall waits for a user's keystroke.
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 hang up, 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 fills in the PLACECALL_EXT structure using the corresponding macros and supplies the p_data pointer to the structure as an argument to nccPlaceCall. To place the call, MyPlaceCall invokes nccPlaceCall with the digits to call, and calling digits, 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.

MyPlaceCall may also receive NCCEVN_CALL_DISCONNECTED, indicating that the called party has hung up. MyPlaceCall calls MyHangUp function to hang up the call.
If the state of the ISDN stack changes, MyPlaceCall receives NCCEVN_CAPABILITY_UPDATE. It then invokes nccQueryCapability to retrieve the new capabilitymask. It prints this information on the screen. If the NCC_ISDN_EXT_CALL_STATUS structure is updated, NCCEVN_EXTENDED_CALL_STATUS_UPDATE is sent to the application. The value field of the event indicates the type of information that was changed. Currently, there are two fields, which may be updated: uui and progressdescription. They are changed if the value of the event is equal to the value of NCC_X_STATUS_INFO_UUI and/or the NCC_X_STATUS_INFO_PROGRESS descriptor.
The Disconnecting Function MyHangUp
MyHangUp is called whenever the program wants to hang up. The function first calls nccGetCallStatus to obtain the call's state. If the current call's state is NCC_CALLSTATE_DISCONNECTED (meaning that the NCCEVN_CALL_DISCONNECTED event has been received), nccReleaseCall is called to release the call handle. Receipt of the NCCEVN_CALL_RELEASED event indicates that the call handle has been cleared.
If the call state returned by nccGetCallStatus is different from NCC_CALLSTATE_DISCONNECTED, the function has been called to initiate the disconnect process. nccDisconnectCall is called in this case, and MyHangUp waits for the NCCEVN_CALL_DISCONNECTED event indicating that the other party accepted the disconnect. Then nccReleaseCall is called to clear the call handle.
The Switching Function ConnectBChannel
ConnectBChannel does the following:

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

It calls swiMakeConection to create a bi-directional connection between the physical B channel on the trunk and the appropriate DSP resource on the AG board.

(Page 1 of 1 in this chapter) Version

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

² In MVIP-95 terms, this is local streams 4:0, 5,0.

tech_support@nmss.com