# isdnncc (ISDN NCC call control demonstration)

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

Demonstrates:

- Using NCC functions

- Operating the ISDN TCP on a live trunk

- Operating of the ISDN TCP across the CT bus

- Operating in non-exclusive mode

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

- A digital trunk interface board.

- NaturalAccess installed.

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

- 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

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 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. 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_SIT_DIGIT, MyReceiveCall rejects the call. To do so, it calls MyRejectCall, which calls nccRejectCall with the mode NCC_REJECT_USER_AUDIO. It calls adiStartTones to play the special information tone.

- If the first digit equals REJECT_IMMEDIATE_DIGIT, MyReceiveCall immediately rejects the call by calling MyHangUp 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. MyReceiveCall waits for a user's keystroke.

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:

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

- 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 ("There is nothing to play.").

### Call placement function MyPlaceCall

The function MyPlaceCall does the following:

- It tries to place a call to the number that the user specified on 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. It then waits for events.

- When the event NCCEVN_PLACING_CALL occurs, if non-exclusive mode was selected, the function calls ConnectBChannel to connect the appropriate DSP resource on the board to the B channel on the trunk.

- When the call is answered, MyPlaceCall starts recording the input that 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 MyReceiveCall, that 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 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. It is not disturbing for a human ear.
  MyPlaceCall can 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. 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:

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