3.6.1 Receiving Messages From the ACU

3.7 Stopping an ISDN Protocol Stack Instance

3 Messaging API Programming Model

3.1 Introduction

This chapter:

Provides an overview of a typical AG ISDN Messaging API application.

Explains how to initialize your AG boards.

Summarizes application initialization steps.

Explains how to send and receive ISDN ACU messages.

Explains how to stop an ISDN protocol stack instance.

3.2 AG ISDN Messaging API Application Overview

An AG ISDN Messaging API application typically performs the following tasks:

Undisplayed Graphic

Figure 9: AG ISDN Messaging API Application Flowchart

3.3 Initializing Your AG Boards

You must initialize and load DSP files, Trunk Control Programs (TCPs) and protocol stack runfiles to your AG board(s) before you can run an AG ISDN application. The items to load to the boards are specified in an AG configuration file (ag.cfg). 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. 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.

Keep agmon running on the system to monitor your AG boards and report errors.

3.4 Initializing the Application

To initialize, an AG ISDN Messaging API application does the following:

If necessary, it makes MVIP switch connections to route D channel data to the HDLC controller, and to route B channel information to DSP resources. Note that certain default connections are automatically made if MVIP switching is not enabled. For more information, see Section 4.2, Making Switch Connections for AG ISDN.

It initializes CT Access or AG Access, and creates a separate CTA context for each D channel and B channel it will interact with. For more information, see Section 4.3.

It initializes ISDN protocol stack instances on each D channel CTA context, using isdnStartProtocol from the AG ISDN library. This function:

Binds the D channel of a specified physical trunk to the CTA context. The trunk is referred to by a network access identifier (NAI). For more information, see Section 4.4, Accessing D Channels.

Starts up an ISDN protocol stack instance on the CTA context, in one of the configurations described in Chapter 1: NCC, ACU or LAPD.

It starts a special "no call control" Trunk Control Program (TCP) on each B channel CTA context. This TCP puts the CTA context in a state where voice or media functions can be used without call control. For more information, see Section 4.5, Starting the "No Call Control" TCP.

3.4.1 About Network Access Identifiers (NAIs)

A trunk is referred to by its network access identifier (NAI). When you initialize an ISDN protocol stack instance for a CTA context (using isdnStartProtocol), you specify the NAI of the trunk to associate with the CTA context. From then on, the application can communicate with the D channel on that trunk via the CTA context handle. For example, when an event is received, the CTA context handle indicates the trunk on which the event occurred.

Different board types support differing numbers of D channels, with different NAI numbers.

The table below shows what each AG board type supports:

Board Type	Number of D Channels	NAIs
AG Quad T, AG Quad E	Up to 4	0 through 3
AG Quad Connect T, AG Quad Connect E	Up to 4	0 through 3
AG Dual T, AG Dual E	Up to 2	0 through 1
AG-T1, AG-E1	1	0

For more information, see Section 4.4, Accessing D Channels.

3.4.2 About Connection Ids

The connection id is a handle to a call on a B channel. It is used to identify the call in all communications between the ACU and the application. The id is a number between 0 and 39.

When an incoming call arrives, the protocol stack assigns it a connection id. The connection id assigned is the highest unused value starting with 39. For example, if connection ids 39 and 38 are already allocated to calls, the protocol stack assigns id 37 to the next call.

When the application places a call, it assigns a connection id to the call. To avoid any chance of collision, the application should use connection ids beginning with 0. The application must keep track of which connection ids are in use and which are available. (The demonstration program documented in Chapter 9 illustrates this.)

When a call is disconnected, the connection id is freed. The id can then be assigned to a new call by the protocol stack or the application.

A different set of connection ids (numbered 0 through 39) is available for each D channel. Thus a call is identified both by its D channel context and by its connection id.

3.5 Sending ISDN Messages to the ACU

To send a message to the ACU, the application does the following:

It builds two structures:

ISDN_MESSAGE. In this structure, the application specifies the NAI and the connection id of the call that the message is associated with. The message to be sent is also specified here, using one of the message primitives documented in Chapter 8. (The message primitive appears in the code field in this structure.) For details about ISDN_MESSAGE, see Chapter 6.

An ACU message structure, which contains the associated message data. The data differs for each message type. For details on each message type, see Chapter 8.

It calls isdnSendMessage in the AG ISDN library. The ctahd argument in the function call specifies the CTA context of the trunk on which the call is taking place. message is a pointer to ISDN_MESSAGE. pdata is a pointer to the ACU message structure. size is the size of the ACU message structure.

Figure 10 illustrates the content and meaning of each of the arguments sent in an isdnSendMessage function call:

Undisplayed Graphic

Figure 10: isdnSendMessage Data Structures

3.6 Receiving Events and ISDN ACU Messages

All messages and events are presented to the application through the standard CT Access/AG Access event handling mechanism. The events returned can be standard CT access or AG Access events, events sent by an ISDN protocol stack instance, or events specific to any AG Access or CT Access extensions. They arrive in the form of the standard CTA (or ADI) 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 or ADI_EVENT structure informs the application which event occurred on which CTA context, and provides additional information specific to the event. The event's prefix relates the event to a specific Natural MicroSystems library of functions, as shown in the following table:

This prefix...	Indicates...
CTAEVN	A CT Access event.
ADIEVN	An AG Access or ADI service event.
ISDNEVN	An AG ISDN event.

The CTA_EVENT or ADI_EVENT structure contains the following fields:

Field	Description
id	Contains an event code defined in the library header file. All AG ISDN events are prefixed with ISDNEVN_ (e.g., ISDNEVN_SOMETHING_HAPPENED).
ctahd	Contains the CTA context handle returned from ctaCreateContext or adiOpenPort.
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/AG Access and facilitates asynchronous programming. Its purpose is to correlate a CTA context with an application object/CTA 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.

CT Access and AG Access applications receive these events in different ways, as follows:

A CT Access application can call ctaWaitEvent.

An AG Access application can block on the semaphore or file handle, muxhandle, returned from the original call to adiOpenDriver. When the application is unblocked, a call must be made to adiFetchAndProcess.

3.6.1 Receiving Messages From the ACU

When an ISDN ACU message is received, an ISDNEVN_RCV_MESSAGE event occurs.

buffer in the CT Access or AG Access structure is a pointer to an ISDN_PACKET structure. This structure contains:

An ISDN_MESSAGE structure which contains the message, the NAI, and the connection id of the call that the message concerns.

A data area containing the ACU message header.

Figure 11 illustrates the structure of this message packet:

Undisplayed Graphic

Figure 11: Receiving ACU Messages

After receiving and processing the data within the CTA_EVENT event buffer, the application must use isdnReleaseBuffer to free the buffer as quickly as possible. Otherwise, the ISDN interface will time out and stop passing events to the application. For more information about isdnReleaseBuffer, see Chapter 7.

The following code fragment illustrates how the application should process an incoming ISDN ACU event from the on-board protocol stack via the CT Access event mechanism:

cta_ret = ctaWaitEvent(ctaqueuehd, &cta_event, CTA_WAIT_FOREVER);    
if (cta_ret != SUCCESS)    
   {    
   printf("isdnproc: ctaWaitEvent failure %d %x\n",    
          cta_ret, cta_ret);    
   continue;    
   }    
/* we have an event -- switch on the type */    
switch (cta_event.id)    
   {    
	.    
	.    
	.    
   case ISDNEVN_RCV_MESSAGE:    
/*      pick up the ISDN_PACKET structure */
    
        isdnpkt = (ISDN_PACKET *)adi_event.buffer;    
        isdnmsg = (ISDN_MESSAGE *)&isdnpkt->message;
    
/*      extract information from the ISDN incoming packet */
    
        message = isdnmsg->code;    
        sender = isdnmsg->from_ent;    
        recipient = isdnmsg->to_ent;    
        CRN = isdnmsg->add.conn_id;

3.7 Stopping an ISDN Protocol Stack Instance

To stop an ISDN protocol stack instance, call isdnStopProtocol from within the application. This shuts down the ISDN protocol stack instance, and releases all on-board resources and buffers formerly used by the protocol stack instance.

The ISDNEVN_STOP_PROTOCOL event contains the completion status of the stop request. If the stack instance stopped successfully, the value field in this event contains SUCCESS. Otherwise, another reason code appears here.

For more information about isdnStopProtocol, see Chapter 7.

Natural MicroSystems, Inc.
100 Crossing Boulevard
Framingham, MA 01702

Contact Developer Support