1.1 Introduction

1.2 Integrated Services Digital Network (ISDN)

1.2.1 ISDN Protocols and Protocol Layering

1.2.2 Information Exchange Between Layers

1.2.3 ISDN Carriers

1.2.4 ISDN Functional Devices and Reference Points

1.3 NMS ISDN Software

1.3.1 NMS ISDN Product Configurations

1.3.2 NMS ISDN ACU Configuration

1.3.3 NMS ISDN LAPD Configuration

1.3.4 Reference Points Supported by NMS ISDN

1.4 NMS ISDN Software Components

1.4.1 Readme File

1.4.2 NMS ISDN Function Libraries

1.4.3 ISDN Protocol Stack Downloadable Object Modules

1.4.4 Configuration File

1.4.5 Demonstration Programs and Utilities

1.5 Other Components

1.5.1 Natural Access

1.6 Developing an NMS ISDN Application

1.1 Introduction

The NMS ISDN Messaging API Developer's Reference Manual provides the following:

• Background information about ISDN.

• A programming guide to NMS ISDN Messaging API applications.

• A summary of API functions organized by task.

• An extensive reference section for functions, data structures, parameters, and codes.

The NMS ISDN product exposes the ISDN primary rate protocol at three levels:

• The LAPD Service Access Point (SAP) for layer 2 protocols, providing direct access to the D channel;

• The ACU SAP for access to a simplified abstraction of the Q.931 ISDN D channel layer 3 message protocols; and

• An ISDN primary rate trunk interface, which is channelized and integrated with the standard Natural Access call control API.

This manual concentrates on building applications that interface with the ISDN protocol stack at layers 2 and 3. For information on building applications that are integrated at higher layers, see the NMS ISDN for Natural Call Control Developer's Manual.

This document is for developers of ISDN applications in C who want to program at the messaging level. The developer should be experienced with ITU Q.931 ISDN call control messages and call states. The developer should also be familiar with Natural Access, basic telephony concepts, and the C programming language.

This chapter:

• Briefly discusses ISDN carriers, protocols, and layers.

• Explains how the NMS ISDN product provides several interfaces to ISDN services.

• Lists and describes the NMS ISDN software components.

• Lists and describes other hardware and software components required in an NMS ISDN application.

• Outlines the application development process.

1.2 Integrated Services Digital Network (ISDN)

Integrated Services Digital Network (ISDN) is a continually evolving international standard for networking a wide range of services, including voice and non-voice services. The network is completely digital, from one end to the other: voice information is digitized and sent in digital form. Signaling information is sent separately from voice information, using a method called common channel signaling (CCS).

1.2.1 ISDN Protocols and Protocol Layering

ISDN communications can be described at many levels, from the way bits are transferred from machine to machine to the sets of messages computers pass to one another. A scheme for communication at a certain level is called a protocol.

In the late 1970's, the International Standards Organization (ISO) established the Open Systems Interconnect (OSI) model for communication. ISDN is based on this model. In OSI, seven separate levels, or layers, of communication are defined. The first three layers, called the chained layers, are the lowest levels. The chained layers are:

• The physical layer (layer 1). This is the electrical and mechanical layer. Protocols for this layer describe, on an electrical and mechanical basis, the methods used to transfer bits from one device to another. One protocol used at this layer is CCITT recommendation I.430/I.431.

• The data link layer (layer 2). This is the layer above the physical layer. Protocols for this layer describe methods for error-free communication between devices across the physical link. One protocol used at this layer is CCITT recommendation Q.921, also known as Link Access Procedures on the D Channel (LAPD).

• The network layer (layer 3). This is the layer above the data link layer. Protocols for this layer describe methods for transferring information between computers. They also describe how data is routed within and between networks. One protocol used at this layer is CCITT recommendation Q.931.

Layers higher than these three are end-to-end layers. They describe how information is exchanged and delivered end-to-end. They also define process-to-process communication, and describe application-independent user services, user interfaces and applications.

Figure 1 illustrates the hierarchy of layers:

Figure 1. OSI Protocol Layering Model

The functionality provided by a layer includes the services and functions of all of the layers below it. A Service Access Point (SAP) is the point at which a layer provides services to the layer directly above it. A unique Service Access Point Identifier (SAPI) is associated with each SAP.

1.2.2 Information Exchange Between Layers

Cooperation between entities on the same layer is governed by a peer-to-peer protocol specific to the layer and the entity. To exchange information between two or more layer entities, a connection must be established between the layer entities using the protocol of the layer directly below. Connections are provided by a layer between two or more SAPs.

Data message units are conveyed between peer-to-peer entities at the lowest layer by means of a physical connection. Layer (n+1) requests services from layer n via primitives. These primitives allow the logical exchange of information and control between two adjacent layers.

Figure 2. Message Primitives Exchanged Between Layers

Four types of primitives are exchanged between adjacent layers:

• REQUEST (RQ), for example, ACU_CONN_RQ
  A layer issues this type to request a service from the layer directly below it.

• INDICATION (IN), for example, ACU_CONN_IN
  A layer providing a service issues this primitive type to notify the layer above it of any specific activity that is related to the service. An INDICATION that a layer receives may be the result of an activity performed by the layer directly below it that is related to a REQUEST given by a peer entity.

• RESPONSE (RS), for example, ACU_CONN_RS
  A layer issues this primitive type to acknowledge the receipt of an INDICATION from a lower layer.

• CONFIRM (CO), for example, ACU_CONN_CO
  A layer providing a requested service issues this primitive type to confirm that the activity has been completed.

1.2.3 ISDN Carriers

ISDN is transmitted over standard T1 and E1 carriers. T1 and E1 are typically four-wire digital transmission links. T1 is used mainly in the United States, Canada, Hong Kong, and Japan. E1 is used in most of the rest of the world.

Data on a T1 or E1 trunk is transmitted in channels. Each channel carries information digitized at 64000 bits per second (bps). For primary rate ISDN, T1 carries 24 channels. E1 carries 32 channels.

With primary rate ISDN, the channels are usually used as follows:

• On a T1 trunk, 23 of the 24 channels carry data: voice, audio, data and/or video signals. These channels are called bearer channels (B channels).

• On an E1 trunk, 30 of the 32 channels are bearer channels.

• On a T1 or E1 trunk, one channel carries signaling information for all B channels. This is called the D channel.

Figure 3. T1 Trunk (Standard Configuration)

In setups with multiple T1 ISDN trunks, a Non-Facility Associated Signaling (NFAS) configuration is often used. In this configuration, the D channel on one of the ISDN trunks carries signaling for all channels on several other trunks. This leaves channel 24 free on each of the other trunks to be used as another B channel. (See Figure 4.)

Figure 4. Sample NFAS Configuration

NFAS configurations are not supported on E1 trunks. For more information about NFAS, see Appendix F.

1.2.4 ISDN Functional Devices and Reference Points

ISDN equipment is classified into a number of categories by international and United States domestic standards¹. Among those categories are the following:

• TE1 - ISDN end-user terminating equipment, class 1, which terminates a single ISDN trunk.

• NT2 - Network terminating equipment, class 2. NT2 equipment can support more than one primary rate trunk, switch channels between different trunks, and take primary synchronization from the T1 or E1 network.

• NT1 - Physically terminates the local loop. In Europe, the NT1 equipment is the network in I.411-compliant installations. In the USA, NT1 is often referred to as the CSU, a separate box on the customer premises.

• LE - Local Exchange equipment.

The interface between each category is called a point:

• The interface between TE1 and NT2 equipment is the S point.

• The interface between NT2 and NT1 equipment is the T point.

• The interface between NT1 and LE equipment is the U point.

Figure 5 illustrates the component categories and associated reference points:

Figure 5. ISDN Service Points and Equipment Classification

1.3 NMS ISDN Software

NMS ISDN protocol software allows you to write Natural Access applications that communicate with T1 or E1 trunks to perform voice processing functions and call control using ISDN Common Channel Signaling protocols.

NMS ISDN software is designed to use one or more NMS digital boards (such as the CG 6000C, AG Quad, AG 4000, AG-T1, or AG-E1 boards) as the physical interface to trunk lines. In addition to line interfaces, these boards also feature powerful on-board digital signal processing (DSP) resources that can handle much of the call control and voice processing overhead.

1.3.1 NMS ISDN Product Configurations

You can use NMS ISDN software to access ISDN services in three ways:

• You can configure the NMS ISDN software so an application can perform call control and other operations, using a standard Natural Access call control API.
  This NMS ISDN configuration is called the Channelized configuration. For more information about this access method, see the NMS ISDN for Natural Call Control Developer's Manual.

• You can access ISDN services at the ACU SAPI. Using the NMS ISDN Messaging API, an application can then perform a wide range of Q.931 ISDN D channel functions.
  This NMS ISDN configuration is called the ACU configuration. This access method is discussed in this manual.

• You can access ISDN services at the data link layer (Layer 2). Using the NMS ISDN Messaging API, an application can then send and receive I- frame data in LAPD messages. This data typically consists of Q.931 messages.
  This NMS ISDN configuration is called the LAPD configuration. This access method is discussed in this manual.

Specify the configuration to use when initializing the ISDN protocol stack, as described in Section 3.5.2.

1.3.2 NMS ISDN ACU Configuration

The NMS ISDN ACU configuration allows access to Q.931 (layer 3) call control, using the NMS ISDN Messaging API. Your application can send and receive switch- and country-invariant D channel messages using this interface. Access at this level allows you direct control over D channel messages and greater control over the contents of these messages.

In this configuration (shown in Figure 6), one or more instances of the NMS ISDN protocol stack run on the board, one for each D channel. The stack runs in ACU stack mode. In this mode, the protocol stack implements all ISDN layer 2 and layer 3 functionality. The application uses the NMS ISDN messaging API to command an entity in the stack called the ACU, which in turn commands the D channel through the lower ISDN layers. Events received by the stack from the D channel are placed in the same event queue as other Natural Access events, allowing the application to access ISDN events in the same way that other events are accessed.

B channel information is routed to the DSP resources through the board's H.100, H.110, or MVIP switch. The switch has certain default behavior, described in Section 3.3. Alternatively, the switch can be controlled using the Natural Access Switching service.

Figure 6. NMS ISDN Application Architecture (ACU Configuration)

1.3.3 NMS ISDN LAPD Configuration

Access at the data link layer is useful if an application must support a private data link protocol, or if the user wishes to create a complete Q.931 protocol at the application level. At this level, the messages sent and received by the application constitute LAPD frames.

The NMS ISDN protocol stack runs in LAPD stack mode, as shown in Figure 7. In this mode, the protocol stack implements ISDN layer 2 functionality. No ACU is present. Instead, the application uses the NMS ISDN Messaging API to send LAPD frames directly to the data link layer (layer 2).

Events coming from the data link layer are placed in the same event queue as other Natural Access events, allowing the user to access ISDN events in the same way that other events are accessed.

As in other configurations, B channel information is routed to the DSP resources through the board's H.100, H.110, or MVIP switch. The switch has certain default behavior, described in Section 3.3. Alternatively, the switch can be controlled using the Natural Access Switching service.

Figure 7. NMS ISDN Application Architecture (LAPD Configuration)

1.3.4 Reference Points Supported by NMS ISDN

The NMS ISDN product supports access across the S and the T reference points (as depicted with the solid arrows on the upper left of Figure 8). At the ACU SAP, access to S/T is transparent.

In addition, you can configure an ISDN protocol stack to emulate the network, using the partner_equip field passed to isdnStartProtocol. See Chapter 7 for more details on the parameters available to configure the ISDN protocol stack.

Figure 8. Reference Points Supported by NMS ISDN

1.4 NMS ISDN Software Components

ISDN is implemented differently around the world. For this reason, NMS provides versions of its ISDN software for different regions. The package for a variant contains the software modules you need to allow a board to communicate on a T1 or E1 trunk in one or more countries using that variant.

The ISDN software package for a given region contains the following:

• A readme file.

• NMS ISDN function libraries for Natural Access.

• Header files.

• Downloadable object modules containing the NMS ISDN protocol stack software and the NMS ISDN Management software.

• Sample configuration files.

• Demonstration programs, with their source code files and makefiles.

The sections that follow briefly describe each of these components.

Other components, also included, are only used when the NMS ISDN protocol stack is running in Channelized stack mode. For more information about this mode, see the NMS ISDN for Natural Call Control Developer's Manual.

The Channelized stack mode-specific components are:

• A Trunk Control Program (TCP).

• Parameter files (.pf files) containing the complete set of NMS ISDN parameters. Certain parameters in these files are set to values specific to a certain country or region.

• An nccxisdn.par file, containing the subset of NMS ISDN parameters which can be changed, if desired. Two country-specific parameter files, nccxadicty.par and nccstartcty.par, contain parameters that should not be changed. These files are used when the protocol stack is in Channelized configuration, using the NCC service.

• An adiisd.par file, containing the subset of NMS ISDN parameters that can be changed without risking violation of approvals. This file is used when the protocol stack is in channelized configuration, using the ADI service.

1.4.1 Readme File

The ASCII text file readme_isdn.txt contains release information that does not appear in other documentation. Consult this file to learn where the NMS ISDN software components are located after installation.

1.4.2 NMS ISDN Function Libraries

These components run on the host computer. They are used by the application program to interact with ISDN protocol stacks running on a board and to communicate with NCC and ADI services. These are dynamic-link libraries (DLL) under Windows NT and Windows 2000, and are shared objects under UNIX. The libraries have different names under different operating systems:

Operating System	Natural Access Library Name(s)
Windows NT and Windows 2000	isdnapi.lib, isdnapi.dll, nccisdn.lib*, nccisdn.dll*, imgtapi.lib*, imgtapi.dll*
UNIX	libisdnapi.so, libnccisdn.so*, libimgtapi.so*

*These files are not in use for Layer 3.

Standard NMS ISDN header files, required by your applications to communicate with the ISDN protocol stack on the board, are also supplied.

The following figure describes the include file structure used by an application using NMS ISDN in the ACU configuration:

Figure 9. Header File Usage (ACU Configuration)

The following figure describes the include file structure used by an application using NMS ISDN in the LAPD configuration:

Figure 10. Header File Usage (LAPD Configuration)

1.4.3 ISDN Protocol Stack Downloadable Object Modules

A downloadable object module file contains the basic low-level software which a board requires to support ISDN. The module is transferred from the host into on-board memory when the board boots.

Different module files are supplied for different configurations. The file you use depends upon what board type you are using. For more information about downloadable object modules, see the NMS ISDN Installation Manual.

1.4.4 Configuration File

The configuration file contains information that determines how to set up your boards for use. This file also contains country-specific information, and defines what trunks are assigned to which D-channels.

Several example files are included, describing ISDN configurations for different boards. You can use these files to create a file describing your hardware and software setup. For details, see the NMS OAM System User's Manual. For versions prior to Natural Access 4.0, see the NMS ISDN Installation Manual and AG Runtime Configuration and Developer's Manual.

1.4.5 Demonstration Programs and Utilities

The following demonstration programs and utilities are included, with their source code files and makefiles:

Program	Description
isdndemo	Simple call control application that communicates with the ISDN stack in the ACU configuration.
lapddemo	Illustrates establishing a LAPD data link on an ISDN trunk.
dectrace	Decodes and displays messages sent or received by the NMS ISDN protocol stack which were previously captured in a log file by the oammon or agmon utility.
itrace	Runtime filter for NMS ISDN messages from the stack being captured by the oammon or agmon utility.

For details on these programs, see Chapter 9.

1.5 Other Components

In addition to the NMS ISDN software, you will need the following components to build an ISDN protocol application:

• One or more NMS T1 or E1 trunk interface boards.

• Natural Access version 3.0 or later.

  WARNING:

  Natural MicroSystems obtains board-level approvals certificates for supported countries. Some countries require that you obtain system-level approvals before connecting a system to the public network. To learn what approvals you require, contact the appropriate regulatory authority in the target country.

  Note: AG-T1 and AG-E1 boards only support NMS ISDN if they are revision D-1 and later. If your AG-T1 or AG-E1 board was purchased prior to June 1996, you may need a hardware upgrade. These board models are not supported by Natural Access 4.0 and later.

1.5.1 Natural Access

Natural Access is a complete development environment for telephony applications. It provides a standard set of telephony functions grouped into logical services, each of which has a standard API. Natural Access provides functions for telephony-related tasks such as call control, tone and DTMF tone generation and detection, and voice playing and recording.

Natural Access includes a service which controls switching on H.100, H.110, or MVIP-compliant devices. You can use this service to make or break connections, send patterns, sample data, etc. Alternatively, you can use the swish standalone utility to control switching interactively or in a batch mode.

For general information about installing and using Natural Access, see the Natural Access documentation.

1.6 Developing an NMS ISDN Application

To create an NMS ISDN application:

Step	Where Step Is Documented
1. Install digital trunk interface boards in a system, and any other boards you will need in your application.	The installation manuals for the boards
2. Install Natural Access.	Natural Access installation booklet
3. Install the NMS ISDN software for each country or region that your application will be used in.	NMS ISDN Installation Manual
4. Edit your configuration file so it describes all boards in your system.	The NMS ISDN Installation Manual, the installation manuals for your boards, and the NMS OAM System User's Manual (or the AG Runtime Configuration and Developer's Manual for versions of Natural Access prior to 4.0)
5. Test your hardware installation.	The installation manuals for your boards
6. Write your application.	This manual, and the Natural Access documentation set