(Page 1 of 1 in this chapter)

Chapter 2

Messaging API 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 Messaging API Application Overview
2.3.1 Initializing Your AG Boards
2.4 Sending ISDN Messages to the Stack
2.4.1 Building ACU Message Structures
2.4.2 Sending LAPD Messages
2.5 Receiving Events and ISDN Protocol Stack Messages
2.5.1 Receiving Messages From the AG ISDN Protocol Stack

2.1 Introduction

This chapter:

2.2 About the CT Access Environment

AG ISDN applications are 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 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 following table 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 11, 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 11. 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 Messaging API Application Overview





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






Figure 12.	 AG ISDN Messaging API Application Flowchart




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





 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 and D-channel.


·	 Starts the nocc ("no call control") Trunk Control Program (TCP) on each B-channel context.




 Initialize AG ISDN Protocol Stack



·	 Calls isdnStartProtocol to start up an ISDN protocol stack instance on each D-channel context. This function also determines whether the stack runs in LAPD, ACU or NCC stack mode.




 Establish Connection



·	 Using isdnSendMessage, sends ACU or LAPD messages to the stack to establish a connection.




 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



·	 Using isdnSendMessage, sends ACU or LAPD messages to the stack to terminate the connection.




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






2.4	 Sending ISDN Messages to the Stack





To send a message to the AG ISDN protocol stack, the application does the following:




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






Figure 13.	 isdnSendMessage Data Structures




ISDN_MESSAGE is defined as follows:


typedef struct ISDN_MESSAGE
{
  nai_t nai;         /* Network access interface index */
  ent_id_t from_ent; /* Message source */
  ent_id_t to_ent;   /* Message destination */
  sapi_t to_sapi;    / * Destination Service Access Point */ 
union {
  add_t conn_id;     /* Connection identifier for the ACU layer */
  add_t crv;         /* Call Reference value for the NS layer. Not used. */
  add_t ces;         /* Connection Endpoint suffix (DL later upper half) */
  add_t tei;     /* Terminal Endpoint id (DL layer lower half). Not used. */
  add_t chani;       /* Physical layer channel identifier. Not used. */
} add;
   code_t code;      /* Primitive code unique only between two entities */
  WORD inf0;         /* Information location 0 */
  WORD inf1;         /* Information location 1 */
  WORD inf2;         /* Information location 2 */
  WORD inf3;         /* Information location 3 */
  WORD inf4;         /* Information location 4 */
  WORD data_size;    /* Size of data to follow   */
  WORD pad;          /* Pad */
  DWORD userid;      /* User ID */
} ISDN_MESSAGE;





2.4.1	 Building ACU Message Structures





To send ACU messages, the AG ISDN protocol stack must be in ACU stack mode. To learn how to place the stack in this mode, see Section 3.5.2.



To send an ACU message, the application first creates a message structure containing the ACU message data. When this structure (and its substructures) reaches the ISDN protocol stack, the stack rearranges the data into several Q.931 information elements (IEs), builds a complete Q.931 message with the IEs, and sends it to the network.



The application assigns values to the fields in the message structure using macros.  Each macro corresponds to a field in the structure.  The application should use these macros instead of accessing fields directly, because the fields do not correspond to actual C language structure fields, and need some simple addressing computation to be reached. These macros are defined in isdnacu.h. See Chapter 8 for more information about message primitives and macros.



The following code fragment shows how to use macros to assign values to fields in an ACU message structure:


void build_cc_conn_rs(char *buffer, int *len, char ts)
{
    struct acu_conn_rs_args *p_data;
    p_data = (struct acu_conn_rs_args *)buffer;
    memset(p_data, OFF, ISDN_BUFFER_DATA_LGTH);
    /* Fill in two fields using macros*/
    Acu_conn_rs_data_chani = ts;              /* T1/E1 time-slot */
    Acu_conn_rs_data_chani_nb = 1;            /* only one B channel */
    /* User to user information could go here */
    *len = sizeof( struct acu_conn_rs_args );
    return;
}




Note that certain pointer and size macros must be called in a certain sequence, so the corresponding IEs are filled out in order. For details, see Chapter 8.



The application also builds an ISDN_MESSAGE structure specifying the message primitive and other data, as follows: 





 In this field in an outgoing ISDN_MESSAGE (ACU stack mode)...



 Place this value...




 nai



 The NAI of the destination trunk.




 from_ent



 ENT_APPLI. 


 Indicates that message is sent from the application to the stack.




 to_ent



 ENT_CC. 


 Indicates that the message is sent to the call control layer (ACU).




 to_sapi



 ACU_SAPI


 This value indicates the ACU SAP.




 conn_id



 The connection ID of the call that the message concerns (see Section 4.1.1).




 code



 Primitive of ACU message (e.g. ACU_CONN_RQ).




 inf0, inf1, inf2, inf3, inf4



 (Do not set.)




 data_size



 Size of message buffer containing data associated with message.




 userid



 (Not used.)
















Note that an application can specify custom information elements containing raw Q.931 data, using transparent IEs. For details, see Appendix D.






2.4.2	 Sending LAPD Messages





To send LAPD messages, the AG ISDN stack must be in LAPD stack mode.



To send a LAPD message, the application builds an ISDN_MESSAGE structure specifying the message primitive and other data, as follows: 





 In this field in an outgoing ISDN_MESSAGE (LAPD stack mode)...



 Place this value...




 nai



 The NAI of the destination trunk.




 from_ent



 ENT_APPLI. 


 This value indicates that the message is sent from the application to the stack.




 to_ent



 ENT_DL_D. 


 This value indicates that the message is sent to the data link layer.




 to_sapi



 DL_SAPI_SIG.




 conn_id



 1




 code



 Primitive of LAPD message (e.g. DL_EST_RQ).




 inf0, inf1, inf2, inf3, inf4



 (Do not set.)




 data_size



 Size of message buffer containing data associated with message (if any).




 userid



 (Not used.)



















If necessary, the application also builds a message buffer containing data to send.






2.5	 Receiving Events and ISDN Protocol Stack Messages





All messages and events are presented to the application through the standard CT Access event handling mechanism. The events returned can be standard CT Access events, events sent by an ISDN protocol stack instance, or events specific to any 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 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 ADI service event.




 ISDNEVN



 An AG ISDN event.
















The CTA_EVENT structure fields are used as follows: 





 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.




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



















To receive these events, the application can call ctaWaitEvent.






2.5.1	 Receiving Messages From the AG ISDN Protocol Stack





When an AG ISDN protocol stack message is received, an ISDNEVN_RCV_MESSAGE event occurs.



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




Figure 14 illustrates the structure of this message packet:






Figure 14.	 Receiving Protocol Stack 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 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;






The fields in the ISDN_MESSAGE structure will contain the following: 





 In this field in an incoming  ISDN_ MESSAGE...



 This value will appear...




 ACU stack mode



  LAPD stack mode




 nai



 The NAI of the trunk that the message concerns..



 The NAI of the trunk that the message concerns.




 from_ent



 ENT_CC. Indicates that message was sent from call control layer (ACU)



 ENT_DL_D. Indicates that message was sent from data link layer. 




 to_ent



 ENT_APPLI. Indicates that message was sent to application.



 ENT_APPLI. Indicates that message was sent to application.




 to_sapi



 ACU_SAPI



 DL_SAPI_SIG




 conn_id


 ces



 Contains the connection ID of the call that the message concerns. (See Section 4.1.1.)



 1




 code



 Primitive of message (e.g. ACU_CONN_IN).



 Primitive of message (e.g.  DL_DA_IN).




 inf0, inf1, inf2, inf3, inf4



 (Reserved for internal data relay.)



 (Reserved for internal data relay.)




 data_size



 Size of buffer containing data associated with message.



 Size of buffer containing data associated with message (if any).




 userid



 (Not used. )



 (Not used.)





















 
    (Page 1 of 1 in this chapter)




 




tech_support@nmss.com



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