2.1 Introduction

2.2 NMS ISDN Management API Application Overview

2.3 Setting up the Natural Access Environment

2.4 Setting Up the IMGT Service

2.4.1 Initializing the IMGT Service

2.4.2 Opening the IMGT Service

2.5 Starting a Management Session

2.5.1 Network Access Identifiers (NAIs)

2.6 Sending IMGT Messages to the Stack

2.7 Receiving Events and IMGT Messages

2.7.1 Receiving IMGT Messages

2.8 Stopping a Management Session

2.1 Introduction

The NMS ISDN Management API is a C function library component of Natural Access. It is implemented as the NMS ISDN Management (IMGT) service, managed by the ADI service manager. The IMGT service is a dynamic link library (DLL) under Windows NT and Windows 2000 and a shared library under UNIX.

You must have Natural Access installed on your system to build and run applications using the IMGT service. This chapter presents a programming model for using the IMGT service within the Natural Access environment.

2.2 NMS ISDN Management API Application Overview

An NMS ISDN Management API application typically performs these tasks:

Figure 3. NMS ISDN Management API Application Flowchart

The following table summarizes the tasks shown in Figure 3:

In this phase...	The application...
Initialize Natural Access	· Initializes Natural Access services and creates one context for each B channel and D channel.
Start IMGT Session	· Calls imgtStart to start an IMGT session on each D channel context.
Perform Tasks	· Uses the standard Natural Access event structure to send IMGT messages and receive IMGT events.
Stop Protocol Stack	· Calls imgtStop to end the IMGT session.

Note: Start the NMS ISDN protocol stack before starting the IMGT service.

2.3 Setting up the Natural Access Environment

Application setup for Natural Access consists of the following steps:

1. Initialize Natural Access for the process.

2. Create event queues.

3. Create CTA contexts for each event queue.

4. Open services on each context.

Services are opened on a context by calling ctaOpenServices, passing a context handle and a list of service descriptors. Each service descriptor specifies the name of the service, service manager, and service-specific arguments.

The call to ctaOpenServices is asynchronous and returns immediately. When all services have been opened, the CTAEVN_OPENSERVICES_DONE event is returned to the application. Natural Access supports opening and closing services on an as-needed basis to share scarce resources.

There can be only one open instance of each service per context. Once the IMGT service is opened, the application can make function calls from the Management API.

For details on setting up the Natural Access environment, see the Natural Access Developer's Reference Manual.

2.4 Setting Up the IMGT Service

Before you can call functions from the IMGT service, the application must initialize and open the IMGT service on an open context.

Note: Start the NMS ISDN protocol stack before starting the IMGT service.

2.4.1 Initializing the IMGT Service

To open the IMGT service, include the IMGT service and the ADI Service Manager in the call to ctaInitialize.

The following code excerpt demonstrates initializing the IMGT service together with the ADI service:

void MyServiceInit()

{

DWORD ret;

CTA_INIT_PARMS initparms = { 0 };

CTA_ERROR_HANDLER hdlr;

CTA_SERVICE_NAME InitServices[] = /* for ctaInitialize */

{ { "ADI", "ADIMGR" },

{ "IMGT", "ADIMGR" },

};

/* Initialize size of init parms structure */

initparms.size = sizeof(CTA_INIT_PARMS);

if ( ( ret = ctaInitialize(

InitServices,

sizeof(InitServices)/sizeof(InitServices[0]),

&initparms)) != SUCCESS)

{

/* ... handle error conditions here.... */

}

}

After the call to ctaInitialize:

1. Create an event queue attached to the ADI Service Manager by calling ctaCreateQueue. ADIMGR can be explicitly specified in the call. If NULL is passed, all service managers specified in ctaInitialize are attached.

2. Create a context by calling ctaCreateContext.

2.4.2 Opening the IMGT Service

The IMGT service must be opened on a context in order to use the IMGT service's library of C functions. Opening the IMGT service starts the trunk monitor software on the board, and enables it to make status information accessible to the application at specific intervals.

Note: Only one instance of the IMGT service can be opened on each context.

When the application opens a service, it specifies a board. When the application opens the trunk monitor, it binds it to a context.

To open the IMGT service on a context, call ctaOpenServices. This function takes an array of CTA_SERVICE_DESC structures as an input argument. Each CTA_SERVICE_DESC structure defines a service (in this case, the IMGT service). If the service(s) is opened successfully, a CTAEVN_OPEN_SERVICES_DONE event with the reason CTA_REASON_FINISHED is delivered to the application. The CTA_SERVICE_DESC structure is defined as follows:

typedef struct CTA_SERVICE_DESC

{

CTA_SERVICE_NAME name; /* service name */

CTA_SERVICE_ADDR svcaddr; /* reserved */

CTA_SERVICE_ARGS svcargs; /* passes service-specific arguments */

CTA_MVIP_ADDR mvipaddr; /* board #, stream, timeslot, mode */

}CTA_SERVICE_DESC;

The following code sample demonstrates opening the IMGT service :

DWORD ret ;

CTA_EVENT event ;

CTA_SERVICE_DESC services[] =

{

{ {"IMGT", "ADIMGR"}, { 0 }, { 0 }, { 0 } } ,

} ;

/* open the IMGT service */

ret = ctaOpenServices( ctahd, /* a CTA context handle */

services,

sizeof(InitServices)/sizeof(InitServices[0]),);

if(ret != SUCCESS)

{

/* opening IMGT service failed */

printf ( "OpenServices failed\n" );

}

else

{

/* wait for the CTAEVN_OPEN_SERVICES_DONE event */

while (1)

{

ctaWaitEvent( ctaqueuehd, &event, CTA_WAIT_FOREVER);

if (event.id == CTAEVN_OPEN_SERVICES_DONE)

{

/* check the reason of completion */

if (event.value != CTA_REASON_FINISHED)

{

printf ( "Open services failed\n" );

}

break;

}

else

{

/* Process other (unrelated) messages. */

...

}

}

}

2.5 Starting a Management Session

To start an IMGT session, call the API function imgtStart. The function takes as arguments the NAI (Network Access Identifier), described in Section 2.5.1, and the pointer to a configuration structure, described in Section 4.2.3. The configuration structure allows the user to filter the IMGT events that the application will receive.

After calling imgtStart, the application is ready to use imgtSendMessage to send messages to the IMGT service.

See Chapter 3 for details of the specific IMGT functions.

2.5.1 Network Access Identifiers (NAIs)

A trunk is referred to by its network access identifier (NAI). To initialize an ISDN protocol stack instance for a context (using isdnStartProtocol), specify the NAI of the trunk to associate with the context. From then on, the application can communicate with the D channel on that trunk through the context handle. For example, when an event is received, the context handle indicates the trunk on which the event occurred. For more information about using isdnStartProtocol, see the NMS ISDN Messaging API Developer's Reference Manual.

Different board types support different numbers of D channels, with different NAI numbers. The following table shows what each board type supports:

Digital Trunk Interface Board Type	Number of D Channels	Default NAI Values	Number of NFAS groups
Four-trunk boards	1 - 4	0 - 3	1 - 4
Two-trunk boards	1 - 2	0 - 1	1 - 2
One-trunk boards	1	0	0

Note: One-trunk boards are not supported by Natural Access 4.0 and later.

If your configuration involves NFAS groups, the NAI for each group is specified in your configuration file. For more information, see the NMS ISDN Installation Manual.

2.6 Sending IMGT Messages to the Stack

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

• It builds two structures:

  
  -	 IMGT_MESSAGE. In this structure, the application specifies the message to be sent, using one of the message primitives documented in Chapter 4. (The message primitive appears in the code field in this structure.) For details about IMGT_MESSAGE, see Chapter 4.
  
  
  -	 A primitive-specific data structure (if needed). For messages that require additional data, a message structure is sent containing the data. The data differs for each message type. For details on each message type, see Chapter 4.
  
  

• It calls imgtSendMessage in the IMGT library. The ctahd argument in the function call specifies the context of the trunk on which the call is taking place. pmessage is a pointer to IMGT_MESSAGE. pbuff is a pointer to the primitive-specific data structure. size is the size of the message structure.

Figure 4 illustrates the content and meaning of each of the arguments sent in an imgtSendMessage function call:

Figure 4. imgtSendMessage Data Structures

IMGT_MESSAGE is defined as follows:

typedef struct IMGT_MESSAGE
{
BYTE nai; /* Network access interface index */
BYTE code; /* Primitive code */
WORD nfas_group; /* NFAS group number, only required for */
/* Configurations with duplicate NAI values */
} IMGT_MESSAGE;

2.7 Receiving Events and IMGT Messages

The IMGT service sends messages up to the application using a standard Natural Access event structure. The information arrives as a buffer attached to the IMGTEVN_RCV_MESSAGE event. See Chapter 4 for details about what goes into this buffer.

The events returned can be standard Natural Access events, events sent by an ISDN protocol stack instance or IMGT session, or events specific to any Natural Access extensions. They arrive in the form of the standard CTA event data structure:

typedef struct CTA_EVENT

{

DWORD id; /* Event code (and source service id) */
CTAHD ctahd; /* CT Access 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 Library of NMS functions. A partial list of these prefixes is shown in the following table:

This prefix...	Indicates...
CTAEVN	A Natural Access event
NCCEVN	An NCC service event
ADIEVN	An ADI service event
ISDNEVN	An NMS ISDN event
IMGTEVN	An IMGT event

Appendix A contains a table that describes the CTA_EVENT structure fields.

To receive these events, the application can call ctaWaitEvent.

2.7.1 Receiving IMGT Messages

When an IMGT message is received, an IMGTEVN_RCV_MESSAGE event occurs.

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

• An IMGT_MESSAGE structure that contains the message and other data.

• A data area containing the message header.

Figure 5 illustrates the structure of this message packet:

Figure 5. Receiving IMGT Messages

Most IMGT events have a buffer associated with them. When the buffer and size fields of the Natural Access event indicate that a buffer is associated with the event, the application processes the buffer and must release it as soon as possible by calling imgtReleaseBuffer. Otherwise, the IMGT service interface runs out of buffers and stops passing events to the application. For more information about imgtReleaseBuffer, see Chapter 3.

If the configuration includes NAIs whose values are not unique on a given board, the nfas_group field of the IMGT_MESSAGE structure contains the NFAS group number for the NAI.

2.8 Stopping a Management Session

Use imgtStop to end an IMGT session. See Chapter 3 for more information about imgtStop.