(Page 1 of 1 in this chapter) Version

Chapter 2

AG ISDN Programming Model

2.1 Introduction

2.2 About the CT Access Environment

: 2.2.1 About CT Access Components
: 2.2.2 Call Control Services under CT Access

2.3 AG ISDN Application Overview

: 2.3.1 Initializing the AG Boards

2.4 Receiving ISDN Events

2.1 Introduction

This chapter: Provides an overview of CT Access services. Summarizes typical AG ISDN application initialization steps. Explains AG ISDN event handling.

2.2 About the CT Access Environment

An AG ISDN for Natural Call Control application is built primarily on the CT Access platform. This section provides background information about CT Access and summarizes the main elements of the CT Access environment. You must have CT Access installed on your system to build applications using AG ISDN.
For more detailed information about CT Access, see the CT Access Developer's Reference Manual.

2.2.1 About CT Access Components

CT Access telephony functions are subdivided into groups of logically related functions, called services. Each service has a standard API. The following services are available: This service... Does the following.. Switching Service Controls switch blocks on telephony boards. Voice Message Service Plays, records and edits voice messages in files or memory. NCC Service Call Control: Establishes and maintains telephone network connections. ADI Service Provides these capabilities: · Playing/Recording: Playing and recording voice buffers. · Call Progress: Analyzing the progression of outbound calls. · Tone Detection: Detecting tones. · Tone Generation: Generating tones. · DTMF Detection: Detecting and generating DTMF and MF tones. · Auxiliary Functions: Signaling, low-level control, and timing. · Call Control: Establishing and maintaining telephone network connections. (Superseded by NCC Service.) Digital Trunk Monitor Service Monitors for T1/E1 trunk alarms, gathers performance statistics. Parameter Management Service Loads and manages user-supplied parameters.
A CTA context organizes services and accompanying resources around a single processing context. A CTA context usually represents an application instance controlling a single telephone call. A service may only be opened once on a CTA context.
An event queue is the communication path from a service to an application. A service generates events indicating certain conditions or state changes. An application retrieves the events from the event queue.

This service...	Does the following..
Switching Service	Controls switch blocks on telephony boards.
Voice Message Service	Plays, records and edits voice messages in files or memory.
NCC Service	Call Control: Establishes and maintains telephone network connections.
ADI Service	Provides these capabilities: · Playing/Recording: Playing and recording voice buffers. · Call Progress: Analyzing the progression of outbound calls. · Tone Detection: Detecting tones. · Tone Generation: Generating tones. · DTMF Detection: Detecting and generating DTMF and MF tones. · Auxiliary Functions: Signaling, low-level control, and timing. · Call Control: Establishing and maintaining telephone network connections. (Superseded by NCC Service.)
Digital Trunk Monitor Service	Monitors for T1/E1 trunk alarms, gathers performance statistics.
Parameter Management Service	Loads and manages user-supplied parameters.

2.2.2 Call Control Services under CT Access

Under CT Access, there are two services available which an application can use to perform call control: The Natural Call Control (NCC) service. This service features a protocol- independent API, separate call and line state machines, call hold/retrieve, and the ability to query a protocol's capabilities. If you are creating a new AG ISDN application, use this service to perform your call control operations. The ADI service. This service includes basic call control functions. These functions have been superseded by the NCC service. If your application currently uses the ADI service for call control, consider migrating to the NCC service for better performance, new features, and more control over your application's call control functionality. For more information, see the Natural Call Control Service Developer's Reference Manual. Note: With the release of CT Access 3.0, the call control functions within ADI will be considered deprecated functions. Eventually, the ADI call control API will be phased out entirely.
Chapter 4 and Chapter 5 of this manual describe how to perform call control using the two services. Note that you must use one or the other; CT Access will not allow you to use ADI service call control functions if the NCC service is used.

2.3 AG ISDN Application Overview

An AG ISDN application typically performs the following tasks: Figure 5. AG ISDN Application Flowchart
The following is a summary of the tasks pictured in Figure 5:

In this phase...

The application...

Initialize CT Access

· Makes MVIP switch connections to route D channel data to the HDLC controller, and to route B channel information to DSP resources (if necessary).
· Initializes CT Access services, and creates one context for each B channel. The application also creates a "dummy" context for each D channel.

Initialize AG ISDN Protocol Stack

· Invokes isdnStartProtocol to start up an ISDN protocol stack instance on each "dummy" CTA context.

Initialize TCP

· Uses nccStartProtocol or adiStartProtocol to start a Trunk Control Program (TCP) on each B channel context, loading country specific parameters if necessary.

Establish Call

· Uses NCC or ADI service call control functions to place outgoing calls and/or receive incoming calls.

Perform Tasks

· Uses functions from CT Access, Natural Media, or other APIs to play or record voice, generate or detect DTMF tones, send and receive faxes, and other tasks.

Disconnect Call

· Uses NCC or ADI service call control functions to disconnect and release the call. The application then establishes another call, or:

Stop Protocol Stack

· Invokes isdnStopProtocol to stop the ISDN protocol stack.

In this phase...	The application...
Initialize CT Access	· Makes MVIP switch connections to route D channel data to the HDLC controller, and to route B channel information to DSP resources (if necessary). · Initializes CT Access services, and creates one context for each B channel. The application also creates a "dummy" context for each D channel.
Initialize AG ISDN Protocol Stack	· Invokes isdnStartProtocol to start up an ISDN protocol stack instance on each "dummy" CTA context.
Initialize TCP	· Uses nccStartProtocol or adiStartProtocol to start a Trunk Control Program (TCP) on each B channel context, loading country specific parameters if necessary.
Establish Call	· Uses NCC or ADI service call control functions to place outgoing calls and/or receive incoming calls.
Perform Tasks	· Uses functions from CT Access, Natural Media, or other APIs to play or record voice, generate or detect DTMF tones, send and receive faxes, and other tasks.
Disconnect Call	· Uses NCC or ADI service call control functions to disconnect and release the call. The application then establishes another call, or:
Stop Protocol Stack	· Invokes isdnStopProtocol to stop the ISDN protocol stack.

2.3.1 Initializing the AG Boards

Before you can run an AG ISDN application, you must initialize and load DSP files, Trunk Control Programs (TCPs) and protocol stack runfiles to your AG board(s). The items to load to the AG boards are specified in an AG configuration file (ag.cfg). To learn how to create an AG configuration file for your setup, see the AG ISDN Installation Manual, the installation manual for your AG board, and the AG Runtime Configuration and Developer's Manual.
To load the components to your AG boards, run agmon, the AG board initialization and monitoring utility. agmon reads the AG configuration file and sets up your boards as described in the file.
Keep agmon running on the system to monitor the AG boards and report any errors.

2.4 Receiving ISDN Events

All messages and events from the AG ISDN protocol stack are presented to the application through the standard CT Access event handling mechanism, along with standard CT Access events and any events specific to CT Access extensions. They arrive in the form of the standard CTA_EVENT data structure. (For more information about CT Access events, refer to the CT Access Developer's Reference Manual.) All events from... are prefixed with... AG ISDN ISDNEVN_ (e.g., ISDNEVN_SOMETHING_HAPPENED) NCC service NCCEVN_ ADI service ADIEVN_ CT Access CTAEVN_.
To receive these events, a CT Access application can invokes ctaWaitEvent.
Some call-control-related CT Access events are unsolicited: they can occur at any time, regardless of the application's current activities. Usually, unsolicited events indicate that something has happened on the trunk. These events are summarized in Section 4.4.2, Unsolicited Events.
Note that the eventmask parameter dictates whether certain informational call control events are generated. This parameter is found in a different structure depending upon which call control service you are using: Service Structure containing eventmask parameter Documented in NCC NCC_START_PARMS Natural Call Control Service Developer's Reference Manual ADI ADI_CALLCTL_PARMS ADI Service Developer's Manual

All events from...	are prefixed with...
AG ISDN	`ISDNEVN_` (e.g., `ISDNEVN_SOMETHING_HAPPENED`)
NCC service	`NCCEVN_`
ADI service	`ADIEVN_`
CT Access	`CTAEVN_`.

Service	Structure containing eventmask parameter	Documented in
NCC	`NCC_START_PARMS`	Natural Call Control Service Developer's Reference Manual
ADI	`ADI_CALLCTL_PARMS`	ADI Service Developer's Manual

(Page 1 of 1 in this chapter) Version

tech_support@nmss.com