2.1 Introduction

2.2 Natural Access Environment

2.2.1 Natural Access Components

2.2.2 Natural Access Programming Model

2.3 NMS ISDN Messaging API Application Overview

2.3.1 Initializing Your 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 NMS ISDN Protocol Stack

2.1 Introduction

This chapter:

• Provides an overview of a typical NMS ISDN Messaging API application.

• Explains how to initialize your boards.

• Summarizes application initialization steps.

• Explains how to send and receive ISDN ACU messages.

• Explains how to stop an ISDN protocol stack instance.

2.2 Natural Access Environment

NMS ISDN applications are built primarily on the Natural Access platform. This section provides background information about Natural Access and summarizes the main elements of the Natural Access environment. You must have Natural Access installed on your system to build applications using NMS ISDN.

For more detailed information about Natural Access, see the Natural Access Developer's Reference Manual.

2.2.1 Natural Access Components

Natural Access telephony functions are subdivided into groups of logically related functions, called services. Each service has a standard API.

A context organizes services and accompanying resources around a single processing context. A context usually represents an application instance controlling a single telephone call. A service may only be opened once on a 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 Natural Access Programming Model

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

There are two types of functions in Natural 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, Natural 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. Chapter 7 lists all NMS 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, Natural 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 (for example, function was started, function is complete, etc.). The service sends events to Natural Access, which makes them available to the application.

Figure 11. Asynchronous Programming Model

Appendix A contains a complete list of NMS ISDN events and errors.

2.3 NMS ISDN Messaging API Application Overview

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

Figure 12. NMS ISDN Messaging API Application Flowchart

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

In this phase...	The application...
Initialize Natural Access	· Makes CT bus switch connections to route D channel data to the HDLC controller, and to route B channel information to DSP resources (if necessary). · Initializes Natural 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 NMS 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 Channelized stack mode.
Establish connection	· Using isdnSendMessage, sends ACU or LAPD messages to the stack to establish a connection.
Perform tasks	· Uses functions from Natural 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 Boards

Before you can run an NMS ISDN application, you must initialize and load DSP files, Trunk Control Programs (TCPs) and protocol stack runfiles to your board(s). The items to load to the boards are specified in a configuration file. To load the components to your boards, run oamsys, the board initialization and monitoring utility. To learn how to create a configuration file for your setup, see the NMS ISDN Installation Manual, the installation manual for your board, and the NMS OAM System User's Manual.

For versions of Natural Access prior to 4.0, you must run agmon instead of oamsys to load the configuration file components to your boards. To learn how to create a configuration file for your setup, see the NMS ISDN Installation Manual, the installation manual for your board, and the AG Runtime Configuration and Developer's Manual.

2.4 Sending ISDN Messages to the Stack

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

• It builds two structures:

• ISDN_MESSAGE. In this structure, the application specifies the message to be sent, 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.

• A message structure (if needed). For messages that require additional data, a message structure (containing the data) is sent. The data differs for each message type. For details on each message type, see Chapter 8.

It calls isdnSendMessage in the NMS ISDN library. The ctahd argument in the function call specifies the context of the trunk on which the call is taking place. message is a pointer to ISDN_MESSAGE. pdata is a pointer to the associated message structure (if any). size is the size of the message structure (if any).

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 nfas_group;  /* NFAS group number                                 */
  DWORD userid;     /* User ID                                           */
} ISDN_MESSAGE;

2.4.1 Building ACU Message Structures

To send ACU messages, the NMS 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 specific sequence, so that 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 (for example ACU_CONN_RQ).
inf0, inf1, inf2, inf3, inf4	(Do not set.)
data_size	Size of message buffer containing data associated with message.
nfas_group	The NFAS group number for this NAI. (Used only if duplicate NAI values are defined.)
userid	(Not used.)

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

2.4.2 Sending LAPD Messages

To send LAPD messages, the NMS 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 (for example DL_EST_RQ).
inf0, inf1, inf2, inf3, inf4	(Do not set.)
data_size	Size of message buffer containing data associated with message (if any).
nfas_group	The NFAS group number for this NAI. (Used only if duplicate NAI values are defined.)
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 Natural Access event handling mechanism. The events returned can be standard Natural Access events, events sent by an ISDN protocol stack instance, or events specific to any Natural Access extensions. They arrive in the form of the standard event data structure:

typedef struct CTA_EVENT
{
    DWORD    id;              /* Event code (and source service ID)     */
    CTAHD    ctahd;           /* Context handle                         */
    DWORD    timestamp;       /* Timestamp                              */
    DWORD    userid;          /* User ID (defined by ctaCreateContext)  */
    DWORD    size;            /* Size of buffer if buffer != NULL       */
    void     *buffer;         /* Buffer pointer                         */
    DWORD    value;           /* Event status or event-specific data    */
    DWORD    objHd;           /* Service client side object handle      */
} CTA_EVENT;

The CTA_EVENT structure informs the application which event occurred on which context, and provides additional information specific to the event. The event's prefix relates the event to a specific Natural MicroSystems library of functions. The following table shows some of the available prefixes:

This prefix...	Indicates...
CTAEVN	A Natural Access event.
NCCEVN	An NCC service event.
ADIEVN	An ADI service event.
ISDNEVN	An NMS ISDN event.
OAMEVN	An OAM service event.
HSWEVN	An OAM Hot Swap event.
CLKEVN	An OAM clock management event.

The CTA_EVENT structure fields are used as follows:

Field	Description
id	Contains an event code defined in the library header file. All NMS ISDN events are prefixed with ISDNEVN_ (for example, ISDNEVN_SOMETHING_HAPPENED).
ctahd	Contains the 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 board events is 10 milliseconds.
userid	Contains the user-supplied ID. This field is unaltered by Natural Access and facilitates asynchronous programming. Its purpose is to correlate a context with an application object and 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. 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.
objHd	Contains the call handle, if the event concerns a particular call. If the event concerns the line and not a particular call, objHd is NULL.

To receive these events, the application can call ctaWaitEvent.

2.5.1 Receiving Messages From the NMS ISDN Protocol Stack

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

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

• An ISDN_MESSAGE structure which contains the message, and other data.

• A data area containing the message header.

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

This field in an incoming ISDN_MESSAGE...	Will contain...
	in ACU stack mode...	in 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	Contains the connection ID of the call that the message concerns. (See Section 4.1.1.)	1
code	Primitive of message (for example ACU_CONN_IN).	Primitive of message (for example DL_DA_IN).
inf0, inf1, inf2, inf3, inf4	(Reserved for internal data relay.)	(Reserved for internal data relay.)
data_size	Size of message buffer containing data associated with the event (if any).	Size of message buffer containing data associated with the event (if any).
nfas_group	The NFAS group number for this NAI. (Used only if duplicate NAI values are defined.)	The NFAS group number for this NAI. (Used only if duplicate NAI values are defined.)
userid	(Not used.)	(Not used.)