(Page 1 of 1 in this chapter)

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 About the CT Access Programming Model
2.3 AG ISDN Application Overview
2.3.1 Initializing Your AG Boards
2.4 Receiving ISDN Events

2.1 Introduction

This chapter:

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

 Controlling Multi-Vendor Integration Protocol (MVIP) switch blocks on telephony boards.

Voice Message Service

 Playing, recording and editing voice messages in files or memory.

ADI Service

 · Call Control: Establishing and maintaining telephone network connections.

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

Digital Trunk Monitor Service

 Monitoring for T1/E1 trunk alarms, gathering performance statistics.

Parameter Management Service

 Loading and managing 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.

2.2.2 About the CT Access Programming Model

CT Access employs an asynchronous programming model to take advantage of concurrent processing between the host and the AG boards. When called, most functions return immediately indicating that the operation was initiated. The application may perform other functions while CT Access is processing the command.

There are two types of functions in CT Access, synchronous and asynchronous.

Synchronous functions are complete when the return value is received. The return value may be either SUCCESS or an error code.

For asynchronous functions, if the return value is SUCCESS, the function has been successfully initiated, and the result will arrive asynchronously via an event. If the return code is not SUCCESS, the function was never initiated, and no events associated with the function will be generated.

During execution, events are generated that indicate certain conditions or state changes. If an asynchronous function fails, CT Access delivers a DONE event to the application. The event value field contains an error code.

The table below summarizes the differences between asynchronous and synchronous functions. The AG ISDN Messaging API Developer's Reference Manual lists all AG ISDN functions and indicates if they are synchronous or asynchronous.

Asynchronous

 Synchronous

Operation complete when function returns

 NO

 YES

Returns a DONE event when function is complete

 YES

 NO

Function can fail after function returns

 YES

 NO

As shown in Figure 5, for asynchronous functions, CT Access sends a command to the service which sends a command to a telephony board. The board performs the functions and sends events to the service indicating its state (e.g., function was started, function is complete, etc.). The service sends events to CT Access, which makes them available to the application.

Figure 5. Asynchronous Programming Model



Your AG ISDN Messaging API Developers Reference Manual contains a complete list of AG ISDN events and errors.






2.3	 AG ISDN Application Overview





An AG ISDN application typically performs the following tasks:


 



Figure 6.	 AG ISDN Application Flowchart




The following is a summary of the tasks pictured in Figure 6: 





 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.


·	 Starts a Trunk Control Program (TCP) on each B channel context, loading country specific parameters if necessary.




 Initialize AG ISDN Protocol Stack



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




 Establish Call



·	 Uses ADI functions such as adiAcceptCall, adiAnswerCall, adiRejectCall or adiPlaceCall 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 ADI functions such as adiReleaseCall to release the call.




 Stop Protocol Stack



·	 Calls isdnStopProtocol to stop the ISDN protocol stack.



















2.3.1	 Initializing Your 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:


typedef struct CTA_EVENT
{
  DWORD     id;       /* event id (LIBEVN_xxx in `libdef.h')  */
  CTAHD     ctahd;    /* CTA context handle                   */
  DWORD     timestamp;/* timestamp                            */
  DWORD     userid;   /* user-supplied ID                     */
  DWORD     size;     /* size of buffer if buffer is not NULL */
  void     *buffer;   /* buffer pointer                       */
  DWORD     value;    /* Event status or reason or other data */
  DWORD     reserved; /* must be 0                            */
  } CTA_EVENT;




The CTA_EVENT structure fields are used as follows: 





 Field



 Description




 id



 Contains an event code defined in the library header file. The event's prefix relates the event to a specific Natural MicroSystems library of functions. For example, all AG ISDN events are prefixed with ISDNEVN_ (e.g., ISDNEVN_SOMETHING_ HAPPENED). All ADI service events are prefixed with ADIEVN_. All CT Access events are prefixed with CTAEVN_.




 ctahd



 Contains the CTA context handle returned from ctaCreateContext.




 timestamp



 Contains the time when the event was created in milliseconds since midnight, January 1, 1970, modulo 49 days. The resolution for AG board events is 10 milliseconds.




 userid



 Contains the user-supplied id. This field is unaltered by CT Access and facilitates asynchronous programming. Its purpose is to correlate a CTA context with an application object/context when events occur.




 size



 The size (bytes) of the area pointed to by buffer. If the buffer is NULL, this field may be used to hold an event-specific value.




 buffer



 This field points to data returned with the event. The field contains an application process address and the event's size field contains the actual size of the buffer.




 value



 This is an event-specific value. This field can hold a reason code or an error code.















 



To receive these events, a CT Access application can call 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.3.2, Unsolicited Events.



Note that the eventmask parameter in the ADI_CALLCTL_PARMS structure dictates whether certain informational call control events are generated. This structure is discussed in detail in the ADI Service Developer's Manual. 








 
    (Page 1 of 1 in this chapter)




 




tech_support@nmss.com



Copyright © 1998, Natural MicroSystems, Inc.   All rights
reserved.