isdnncc (ISDN NCC call control demonstration)

Uses the ISDN TCP with NaturalAccess to receive and place calls.

Demonstrates:

isdnncc requires prior initialization of the ISDN protocol stack with isdnStartProtocol. To initialize the ISDN protocol stack, a program similar to isdncta can be used.

Featured functions

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

Requirements

Usage

isdnncc [options]

where options is one or more of the following:

Option

Description

Default

-a mode

Accepts a call, without answering. mode specifies the call acceptance method:

1 - Accepts and plays ring back tone.

2 - Accepts and remains silent until next command.

3 - Accepts with user audio and plays a voice file.

4 - Accepts with user audio and detects DTMFs.

Answers the call.

-A string

Specifies data for the ie_list field in nccAcceptCall.

Disabled

-b board_#

Specifies a board number.

0

-C string

Specifies data for the ie_list field in nccAnswerCall.

Disabled

-d

Uses the TCP's default parameters, without loading the parameter file. Refer to ISDN TCP parameters overview for details on the default NCC parameters of the ISDN Software TCP.

Loads the parameter file.

-D number

Sets the calling party number for outbound calls.

987

-F

Sends the calling party name

Disabled

-h or -?

Displays a Help screen and terminates.

N/A

-i

Awaits incoming calls.

Awaits outbound calls.

-I string

Specifies data for the ie_list field in an INFORMATION message to be sent after callconnect.

Disabled

-n num_to_dial

Sets the number to dial. num_to_dial must be formatted appropriately.

123

-N string

Specifies data for the ie_list field in a NOTIFY message to be sent after callconnect.

Disabled

-p

Determines by the first digit of the called number if the inbound call should be rejected.

Disabled

-P

Allows the user to place a call on an ISDN PRI trunk in Non-exclusive mode.

This mode 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

Specifies the number of ring tones to play before answering an inbound call.

2

-R

Sends a redirecting number in an outbound call setup.

Disabled

-s n:m

Specifies the stream and timeslot.

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

-S string

Specifies data for the ie_list field in nccPlaceCall.

Disabled

-t threads

Specifies the number of threads to launch.

0

-u

Sends a string of user-to-user information.

Disabled

-v level

Specifies the verbosity level of messages printed on screen. level can be any of the following:

0 - Displays error messages only.

1 - Displays errors and unexpected high-level events.

2 - Displays errors and all high-level events.

3 - Displays errors and all events.

2

Procedure

Complete the following steps to start isdnncc for an ISDN demonstration:

Step

Action

1

Start isdncta, as described in isdncta (ISDN daemon).

2

Enter the following command at the command line:

isdnncc [options]

where options is one or more of the command line options described in the previous table.

Functional overview

When isdnncc is started, it performs the following actions:

Step

Action

1

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.

2

It starts the ISDN Software TCP isd0.tcp, configuring it using the specified parameters.

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 automatically.

5

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

  • It waits for incoming calls.

  • 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.

  • 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 board.

  • If the -a option is specified in the command line, the call is accepted using the mode supplied by the user.

  • If the -p option is specified on the command line, the program checks the first digit of the incoming number. If the digit is a 7, it rejects the call and plays a special information tone (SIT). 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.

  • 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.

  • If the first digit is not a 7, 8, 9, or 0, the demonstration program plays a welcome message and speaks back the digits it received.

  • 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).

  • The demonstration program starts the DTMF tone detector and waits for a tone. If the tone does not arrive, it hangs up.

  • 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):

  • It dials the number specified by the user. The calling number is precoded as 987.

  • 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 board.

  • When the call is answered, the demonstration program starts call progress.

  • 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.

  • When silence is detected by the recording functions, the demonstration program stops recording and plays DTMF tone 3 (hang up) for its inbound counterpart.

  • 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 (the state of the ISDN stack has changed), it displays the new capability mask.

If the program receives NCCEVN_EXTENDED_CALL_STATUS_ UPDATE that is sent by the TCP when a new UUI string or a progress descriptor is received from the network, a new field displays on the screen.

If -v is specified on the command line, the demonstration program displays the NaturalAccess 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.

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

\nms\ctaccess\demos\isdnncc

nmake

UNIX

/opt/nms/ctaccess/demos/isdnncc

make

For more information, see the ISDN Software readme file.

isdnncc structure and coding features

isdnncc is based on an asynchronous programming model. The NaturalAccess function names start 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 NaturalAccess 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.

main function

The main function of isdnncc defines the list of NaturalAccess service managers that the application needs. 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 sends a warning if it finds a problem. Then it registers an error handler with NaturalAccess and starts NaturalAccess.

Then main launches the demonstration loop.

Opening the AG driver, context, and protocol

In isdnncc, RunDemo defines the list of NaturalAccess APIs needed by the application. It calls the DemoOpenPort function, from the CTADEMO library. DemoOpenPort opens the NaturalAccess application queue, attaching all defined service managers. It creates a 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 context opened is 4:0, 5 on board 0. If this context is already in use, the call to NaturalAccess fails and the demonstration program terminates. In MVIP-90 terms, this is local streams 18:0,0.

Next, RunDemo calls ctaLoadParFile, which 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:

Operating system

Directory

Windows

\nms\ctaccess\cfg\

UNIX

/opt/nms/ctaccess/cfg/

If the nccxisdn.par parameter file cannot be found, the demonstration program terminates.

RunDemo starts the TCP on the opened context. To do so, it calls nccStartProtocol with the following arguments:

Argument

Description

startparms

A pointer to NCC_START_PARMS.

mgrstartparms

A NULL pointer, to use the default manager parameters just loaded from the country-specific parameter file (*.pf).

protstartparms

A pointer to NCC_ADI_ISDN_PARMS.isdn_start.

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

RunDemo is ready to accept incoming calls or place outgoing calls. 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.

Call receiving function MyReceiveCall

MyReceiveCall waits for an NCCEVN_INCOMING_CALL event and immediately queries NaturalAccess for information about the incoming call by invoking nccGetCallStatus and nccGetExtendedCallStatus. The attributes are:

These attributes are stored in data structures, of type NCC_CALL_STATUS and NCC_ISDN_EXT_CALL_STATUS. See Retrieving call information for more information.

If non-exclusive mode was selected, MyReceiveCall calls ConnectBChannel to connect the appropriate DSP resource on the board to the B channel on the trunk.

While waiting for NCCEVN_INCOMING_CALL, MyReceiveCall can receive NCCEVN_RECEIVED_DIGIT, indicating that a digit has arrived in the queue. MyReceiveCall displays a message on the screen that 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 Overlapped sending and receiving for more information. MyReceiveCall can 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 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. There are two fields supported by the demonstration program that can 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 MyReceiveCall answers the call, it 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:

Call placement function MyPlaceCall

The function MyPlaceCall does the following:

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. There are two fields supported by the demonstration program that can 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.

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 (was the NCCEVN_CALL_DISCONNECTED event received), nccReleaseCall is called to release the call handle. Receipt of the NCCEVN_CALL_RELEASED event indicates that the call handle was cleared.

If the call state returned by nccGetCallStatus is different from NCC_CALLSTATE_DISCONNECTED, the function was 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. nccReleaseCall is called to clear the call handle.

Switching function ConnectBChannel

ConnectBChannel does the following: