AG ISDN Messaging API Developer s Reference Manual

Transcription

1 Developer s Reference Manual P/N Natural MicroSystems Corporation 100 Crossing Blvd. Framingham, MA 01702

2 No part of this document may be reproduced or transmitted in any form or by any means without prior written consent of Natural MicroSystems Corporation Natural MicroSystems Corporation. All Rights Reserved. Alliance Generation and PolicyPoint are registered trademarks of Natural MicroSystems Corporation. Natural MicroSystems, AG, CG, CX, QX, Convergence Generation, The Circuit Man Logo, Natural Access, CT Access, Natural Call Control, Natural Media, NaturalFax, NaturalRecognition, NaturalText, Fusion, NaturalEdge, Open Telecommunications, Natural Platforms and HMIC are trademarks of Natural MicroSystems Corporation. Multi-Vendor Integration Protocol (MVIP) is a registered trademark of GO-MVIP, Inc. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company, Ltd. Windows NT is a trademark, and MS-DOS, MS Word, and Windows are registered trademarks of Microsoft Corporation in the USA and other countries. All other trademarks referenced herein are trademarks of the respective owner(s) of such marks. Every effort has been made to ensure the accuracy of this manual. However, due to the ongoing improvements and revisions to our products, Natural MicroSystems cannot guarantee the accuracy of the printed material after the date of publication, or accept responsibility for errors or omissions. Revised manuals and update sheets may be published when deemed necessary by NMS. Revision History Revision Release Date Notes 1.0 November 15, 1996 MM, beta release 1.1 May, 1997 MM, CYF Product release 1.2B November, 1997 CYF add AG Quad, rewrite, combine with January, 1998 CYF index, final releaase 1.3B May, 1998 CYF NFAS, new primitives, functions, DL layer info, transparent IEs 1.4 August, 1998 CYF Supplementary services update 1.5 October, 1998 CYF index, Korea, final B3 release 1.6 November, 1998 CYF Final Release 1.7 February, 1999 CYF Changes for Natural Access 1.8 September, 1999 CYF, NBS CT Access 3.0 beta 1.9 December, 1999 CYF CT Access 3.0 GA 2.0 July, 2000 EPS / SJC, Support for Fusion September, 2000 SJC, CT Access 4.0 GA This manual printed: September 27, 2000 Refer to the NMS web site ( for product updates and for information about NMS support policies, warranty information, and service offerings.

3 Table of Contents 1 Introduction Introduction Integrated Services Digital Network (ISDN) ISDN Protocols and Protocol Layering Information Exchange Between Layers ISDN Carriers ISDN Functional Devices and Reference Points AG ISDN Software AG ISDN Product Configurations AG ISDN ACU Configuration The AG ISDN LAPD Configuration Reference Points Supported by AG ISDN AG ISDN Software Components The Readme File The AG ISDN Function Libraries ISDN Protocol Stack Downloadable Object Modules The Configuration File The Demonstration Programs and Utilities Other Components About CT Access Developing an AG ISDN Application Messaging API Programming Model Introduction The CT Access Environment CT Access Components The CT Access Programming Model Application Overview Initializing Your Boards Sending ISDN Messages to the Stack Building ACU Message Structures Sending LAPD Messages Receiving Events and ISDN Protocol Stack Messages Receiving Messages From the AG ISDN Protocol Stack Natural MicroSystems 3

4 Table of Contents 3 Initializing a Messaging API Application Introduction Overview Making Switch Connections for AG ISDN Initializing CT Access Specifying B Channel CTA Contexts Specifying D Channel CTA Contexts Accessing D Channels About Network Access Identifiers (NAIs) Initializing ISDN Protocol Stack Instances Starting the NOCC TCP Setting mediamask (AG Quad T/E only) Stopping an ISDN Protocol Stack Instance Call Control (ACU Configuration) Introduction About Connection IDs The ISDN Call Control State Machine Receiving Inbound Calls Accepting the Call Rejecting the Call Incoming Calls With Overlap Receiving Mode Enabled Placing Outbound Calls Call Collision Call Clearing Clear Collision Data Link Operations (LAPD) Introduction The AG ISDN State Machine (LAPD Configuration) Initiating a Data Link Responding to a Data Link Establishment Request Sending Messages Across an Established Link Messaging API Data Structures Introduction Messaging Structures ISDN_MESSAGE Structure Natural MicroSystems

5 Table of Contents ISDN_PACKET Structure Protocol Parameter Structures ISDN_PROTOCOL_PARMS_Q931CC Structure ISDN_PROTOCOL_PARMS_LAPD Structure ISDN_PROTOCOL_PARMS_CHANNELIZED Alphabetical Function Reference Introduction Function Summary Alphabetical Function Reference isdnreleasebuffer isdnsendmessage isdnsetmsgcapture isdnstartprotocol isdnstopprotocol Message Primitives Introduction ACU Primitives ACU Message Reference ACU_ALERT_IN ACU_ALERT_RQ ACU_CALL_PROC_IN ACU_CALL_PROC_RQ ACU_CLEAR_CO ACU_CLEAR_IN ACU_CLEAR_RQ ACU_CLEAR_RS ACU_CONN_CO ACU_CONN_IN ACU_CONN_RQ ACU_CONN_RS ACU_D_CHANNEL_STATUS_IN ACU_D_CHANNEL_STATUS_RQ ACU_DIGIT_CO ACU_DIGIT_IN ACU_DIGIT_RQ ACU_ERR_IN Natural MicroSystems 5

6 Table of Contents ACU_FACILITY_IN ACU_FACILITY_RQ ACU_INFORMATION_IN ACU_INFORMATION_RQ ACU_INIT_CO ACU_INIT_RQ ACU_NOTIFY_IN ACU_NOTIFY_RQ ACU_PROGRESS_IN ACU_PROGRESS_RQ ACU_RESTART_IN ACU_RESUME_CO ACU_RESUME_RQ ACU_SERVICE_CO ACU_SERVICE_IN ACU_SERVICE_RQ ACU_SET_MODE_CO ACU_SET_MODE_RQ ACU_SETPARM_RQ ACU_SETUP_ACK_IN ACU_SETUP_REPORT_IN ACU_SUSPEND_CO ACU_SUSPEND_RQ ACU_TEST_CO ACU_TEST_RQ ACU_USER_INFO_IN ACU_USER_INFO_RQ Data Types and Constants In Primitives User Rate Values Service Values Number Type Values Plan Values Screening Indicator Values Redirecting Reason Values Location Values UUI Protocol Discriminator Values Signal Values Network-Provided Clearing Cause Values Natural MicroSystems

7 Table of Contents Clear Code Values Facility Code Values Action Code Values Mode Code Values Error Cause Values Progress Description Values Charging Type Values Endpoint ID Values LAPD Primitives Demonstration Programs and Utilities Introduction Demonstration Programs and Utilities Layer 3 Call Control Demonstration: isdndemo Using NFAS With isdndemo Structure and Coding (Single-Threaded Version) Structure and Coding (Multi-Threaded Version) ISDN Call Control Identifying Trunks LAPD Demonstration Program: lapddemo The lapddemo Configuration File lapddemo Structure and Coding Features Stack Traffic Analysis Tool: dectrace Creating a Log File for dectrace Messages Decoded by dectrace Sample dectrace Output Stack Traffic Filtering Tool: itrace Appendix A Events, Reasons, and Errors Introduction AG ISDN Events AG ISDN Reasons AG ISDN Errors Appendix B Parameters Introduction ISDN_PROTOCOL_PARMS_Q931CC services_list Field Natural MicroSystems 7

8 Table of Contents in_calls_behaviour Field out_calls_behaviour Field acu_behaviour Field ns_behaviour Field qsig_source_party_nb_type Field qsig_source_type_of_nb Field ISDN_PROTOCOL_PARMS_LAPD Appendix C Sending and Receiving Raw Q.931 Data Introduction Creating Transparent IEs Transparent IE Formatting Rules Accessing and Reading a Q.931 Buffer Appendix D Sending and Receiving PCS-User Information Introduction Structure of User-PCS IEs Sending and Receiving PCS Information Elements Example Code Appendix E Timer Values Introduction Timer Functions Timer Values France VN6 Layer 3 Timer Defaults EuroISDN Layer 3 Timer Defaults AT&T E10 Layer 3 Timer Defaults Nortel DMS 100 Layer 3 Timer Defaults USA National ISDN-2 Layer 3 Timer Defaults Australian Telecom 1 Layer 3 Timer Defaults Hong Kong Telephone Layer 3 Timer Defaults INS-1500 NTT Layer 3 Timer Defaults AT&T 4ESS Layer 3 Timer Defaults Korean (and Taiwan) Layer 3 Timer Defaults QSIG Layer 3 Timer Defaults Appendix F NFAS and D Channel Backup Introduction Natural MicroSystems

9 Table of Contents Non-Facility Associated Signaling (NFAS) Setting Up NFAS Using NFAS D Channel Backup Setting up D Channel Backup Handling D Channel Failure Appendix G Modifying the NSF IE Introduction NSF IE Fields net_id_type action serv_feature Facility Coding param_fld Example Natural MicroSystems 9

10 Table of Contents 10 Natural MicroSystems

11 Chapter 1 Introduction 1.1 Introduction Integrated Services Digital Network (ISDN) ISDN Protocols and Protocol Layering Information Exchange Between Layers ISDN Carriers ISDN Functional Devices and Reference Points AG ISDN Software AG ISDN Product Configurations AG ISDN ACU Configuration The AG ISDN LAPD Configuration Reference Points Supported by AG ISDN AG ISDN Software Components The Readme File The AG ISDN Function Libraries ISDN Protocol Stack Downloadable Object Modules The Configuration File The Demonstration Programs and Utilities Other Components About CT Access Developing an AG ISDN Application 31 Natural MicroSystems 11

12 Chapter 1 Introduction 1.1 Introduction The Developer s Reference Manual provides the following: Æ Background information about ISDN. Æ A programming guide to applications. Æ A summary of API functions organized by task. Æ An extensive reference section for functions, data structures, parameters, and codes. The AG 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 CT 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 AG 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 CT Access, basic telephony concepts, and the C programming language. This chapter: Æ Briefly discusses ISDN carriers, protocols, and layers. Æ Explains how the AG ISDN product provides several interfaces to ISDN services. Æ Lists and describes the AG ISDN software components. Æ Lists and describes other hardware and software components required in an AG ISDN application. Æ Outlines the application development process. 12 Natural MicroSystems

13 Integrated Services Digital Network (ISDN) 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) 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-toprocess communication, and describe application-independent user services, user interfaces and applications, etc. Natural MicroSystems 13

14 Chapter 1 Introduction 4-7 End-to-end layers End-to-end layers 3 Network Q.931 Protocol Network 2 Data Link Q.921 (LAPD) Protocol Protocol Data Link Chained Layers 1 Physical I.431 & I.430 PRI Protocol Physical HOST HOST 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 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. 14 Natural MicroSystems

15 Information Exchange Between Layers (n+1) Layer entity (n+1) Layer entity Confirm Request Indication Response SAP SAP (n) Layer entity (n) Layer entity Figure 2. ISDN protocol stack making a request ISDN protocol stack responding to request Message Primitives Exchanged Between Layers Four types of primitives are exchanged between adjacent layers: Æ REQUEST (RQ), e.g., ACU_CONN_RQ A layer issues this type to request a service from the layer directly below it. Æ INDICATION (IN), e.g., 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), e.g., ACU_CONN_RS A layer issues this primitive type to acknowledge the receipt of an INDICATION from a lower layer. Æ CONFIRM (CO), e.g., ACU_CONN_CO A layer providing a requested service issues this primitive type to confirm that the activity has been completed. Natural MicroSystems 15

16 Chapter 1 Introduction 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 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. AG Quad T Board T1 Trunk (23 B Channels+D Channel with signaling for these channels) T1 Trunk (23 B Channels+D Channel with signaling for these channels) T1 Trunk (23 B Channels+D Channel with signaling for these channels) T1 Trunk (23 B Channels+D Channel with signaling for these channels) 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.) AG Quad T Board T1 Trunk (23 B Channels+D Channel with signaling for all four trunks) T1 Trunk (24 B Channels) T1 Trunk (24 B Channels) T1 Trunk (24 B Channels) Figure 4. Sample NFAS Configuration 16 Natural MicroSystems

17 ISDN Functional Devices and Reference Points NFAS configurations are not supported on E1 trunks. For more information about NFAS, see Appendix F ISDN Functional Devices and Reference Points ISDN equipment is classified into a number of categories by international and United States domestic standards 1. 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. 1 The International Telecommunications Union (ITU) document I.411 defines ISDN user-network interface reference configurations. In the USA, the definition is provided by a number of documents, including AT&T TR ISDN Primary Rate Interface Specification. Natural MicroSystems 17

18 Chapter 1 Introduction Figure 5 illustrates the component categories and associated reference points: ITU Network USA Network ISDN TE1 S T U CPE NT2 Local loop terminator NT1 ISDN switch LE End-user ISDN device ISDN Protocol Switching MUX Concentration Physical termination Performance monitoring Signaling conversion Power transfer B and D channel MUX Physical termination Switching Figure 5. ISDN Service Points and Equipment Classification 18 Natural MicroSystems

19 AG ISDN Software 1.3 AG ISDN Software Alliance Generation (AG) ISDN protocol software allows you to write CT Access applications that communicate with T1 or E1 trunks to perform voice processing functions and call control using ISDN Common Channel Signaling protocols. AG 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 AG ISDN Product Configurations You can use AG ISDN software to access ISDN services in three ways: Æ You can configure the AG ISDN software so an application can perform call control and other operations, using a standard CT Access call control API. This AG ISDN configuration is called the Channelized configuration. For more information about this access method, see the AG ISDN for Natural Call Control Developer s Manual. Æ You can access ISDN services at the ACU SAPI. Using the AG ISDN Messaging API, an application can then perform a wide range of Q.931 ISDN D channel functions. This AG 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, an application can then send and receive I-frame data in LAPD messages. This data typically consists of Q.931 messages. This AG 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 Natural MicroSystems 19

20 Chapter 1 Introduction AG ISDN ACU Configuration The AG ISDN ACU configuration allows access to Q.931 (layer 3) call control, using the. 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 AG 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 AG 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 CT 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 MVIP switch. The switch has certain default behavior, described in Section 3.3. Alternatively, the switch can be controlled using the CT Access Switching service. 20 Natural MicroSystems

21 AG ISDN ACU Configuration Application AG ISDN library CT Access Switching service context handle ACU messages sent using isdnsendmessage ISDN events Other commands Other events Layer 3 Layer 2 ISDN Protocol Stack ACU Network layer Data link layer DSP resources Layer 1 HDLC D Channel data MVIP switch T1/E1 Trunk T1/E1 Framer Data from B Channels Figure 6. Board AG ISDN Application Architecture (ACU Configuration) Natural MicroSystems 21

22 Chapter 1 Introduction The AG 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 AG 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 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 CT 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 MVIP switch. The switch has certain default behavior, described in Section 3.3. Alternatively, the switch can be controlled using the CT Access Switching service. 22 Natural MicroSystems

23 The AG ISDN LAPD Configuration Application AG ISDN library CT Access Switching service context handle LAPD frames sent using isdnsendmessage ISDN events Other commands Other events Layer 3 Layer 2 ISDN Protocol Stack Data link layer DSP resources Layer 1 HDLC D Channel data MVIP switch T1/E1 Trunk T1/E1 Framer Data from B Channels Figure 7. Board AG ISDN Application Architecture (LAPD Configuration) Natural MicroSystems 23

24 Chapter 1 Introduction Reference Points Supported by AG ISDN The AG 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. EQUIPMENT_TE ITU network USA network EQUIPMENT_NT ISDN TE1 S T U CPE NT2 Local loop terminator NT1 ISDN switch LE End-user ISDN device ISDN Protocol Switching MUX Concentration Physical termination Performance monitoring Signaling conversion Power transfer B and D channel MUX Physical termination Switching Figure 8. Reference Points Supported by AG ISDN 24 Natural MicroSystems

25 AG ISDN Software Components 1.4 AG ISDN Software Components ISDN is implemented differently around the world. For this reason, NMS provides versions of its AG 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. Æ AG ISDN function libraries for CT Access. Æ Header files. Æ Downloadable object modules containing the AG ISDN protocol stack software and the AG 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 AG ISDN protocol stack is running in Channelized stack mode. For more information about this mode, see the AG 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 AG 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 AG 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 AG 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. Natural MicroSystems 25

26 Chapter 1 Introduction The 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 AG ISDN software components are located after installation The AG 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 board and to communicate with NCC and ADI services. These are dynamic-link libraries (DLL) under Windows NT, and are shared objects under UNIX. The libraries have different names under different operating systems: Operating System Windows NT UNIX CT Access Library Name(s) isdnapi.lib, isdnapi.dll, nccisdn.lib*, nccisdn.dll*, imgtapi.lib*, imgtapi.dll* libisdnapi.so, libnccisdn.so*, libimgtapi.so* *These files are not in use for Layer 3. Standard AG ISDN header files, required by your applications to communicate with the ISDN protocol stack on the board, are also supplied. 26 Natural MicroSystems

27 The AG ISDN Function Libraries The following figure describes the include file structure used by an application using AG ISDN in the ACU configuration: isdndef.h Event code definitions. ISDN API function prototypes. Included by application interfacing at ACU SAP. isdnparm.h Parameter structure definitions. Manifest constants for parameter structure fields. isdntype.h NMS types definition. Basic and derived types. Entity identifiers. isdnacu.h isdnval.h ACU SAP message structure definitions. ACU macros to build ACU messages. Note that most defines appearing in this file apply to ACU configuration only. Contains defines to be used both in ACU configuration and in Channelized configuration. Figure 9. Header File Usage (ACU Configuration) Natural MicroSystems 27

28 Chapter 1 Introduction The following figure describes the include file structure used by an application using AG ISDN in the LAPD configuration: isdndef.h Event code definitions. ISDN API function prototypes. Included by application interfacing at SAPI SIG for raw LAPD access isdnparm.h Parameter structure definitions. Manifest constants for parameter structure fields. isdntype.h NMS types definition. Basic and derived types. Entity identifiers. isdndl.h SAPI SIG Configuration for raw LAPD. Macros to build LAPD messages. Figure 10. Header File Usage (LAPD Configuration) 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 onboard 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 AG ISDN Installation Manual The 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. 28 Natural MicroSystems

29 The Demonstration Programs and Utilities 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 OAM System User s Manual. For versions prior to CT Access 4.0, see the AG ISDN Installation Manual and AG Runtime Configuration and Developer s Manual The Demonstration Programs and Utilities The following demonstration programs and utilities are included, with their source code files and makefiles: Program isdndemo lapddemo dectrace itrace Description Simple call control application that communicates with the ISDN stack in the ACU configuration. Illustrates establishing a LAPD data link on an ISDN trunk. Decodes and displays messages sent or received by the AG ISDN protocol stack which were previously captured in a log file by the oammon or agmon utility. Runtime filter for AG ISDN messages from the stack being captured by the oammon or agmon utility. For details on these programs, see Chapter 9. Natural MicroSystems 29

30 Chapter 1 Introduction 1.5 Other Components In addition to the AG ISDN software, you will need the following components to build an ISDN protocol application: Æ One or more NMS T1 or E1 trunk interface boards 1. Æ CT 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 About CT Access CT 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. CT Access provides functions for telephony-related tasks such as call control, tone and DTMF tone generation and detection, and voice playing and recording. CT Access includes a service which controls switching on MVIP-compliant devices. You can use this service to make or break connections, send patterns, sample data, etc. This service supports both MVIP-95 and MVIP-90 specifications. Alternatively, you can use the swish standalone utility to control switching interactively or in a batch mode. For general information about installing and using CT Access, see the CT Access documentation. 1 AG-T1 and AG-E1 boards only support AG 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 CT Access 4.0 and later. 30 Natural MicroSystems

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

32 Chapter 1 Introduction 32 Natural MicroSystems

33 Chapter 2 Messaging API Programming Model 2.1 Introduction The CT Access Environment CT Access Components The CT Access Programming Model Application Overview Initializing Your Boards Sending ISDN Messages to the Stack Building ACU Message Structures Sending LAPD Messages Receiving Events and ISDN Protocol Stack Messages Receiving Messages From the AG ISDN Protocol Stack 45 Natural MicroSystems 33

34 Chapter 2 Messaging API Programming Model 2.1 Introduction This chapter: Æ Provides an overview of a typical 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 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 CT Access Components CT Access telephony functions are subdivided into groups of logically related functions, called services. Each service has a standard API. 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. 34 Natural MicroSystems

35 The CT Access Programming Model The CT Access Programming Model CT 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 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. Chapter 7 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 Natural MicroSystems 35

36 Chapter 2 Messaging API Programming Model 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. When this happens... This happens... And one or the other of these... Application Application Application Application command CT Access Service return value CT Access Service CT Access Service event: results of command OR event: done CT Access Service command return value event: results of command event: done Board Board Board Board Figure 11. Asynchronous Programming Model Appendix A contains a complete list of AG ISDN events and errors. 36 Natural MicroSystems

37 Application Overview 2.3 Application Overview An application typically performs the following tasks: Initialize CT Access using... CT Access functions Initialize AG ISDN protocol stack AG ISDN functions Establish connection AG ISDN functions Perform tasks CT Access functions Disconnect AG ISDN functions Stop protocol stack AG ISDN functions Figure 12. Application Flowchart Natural MicroSystems 37

38 Chapter 2 Messaging API Programming Model The following is a summary of the tasks pictured in Figure 12: In this phase... Initialize CT Access Initialize AG ISDN protocol stack Establish connection Perform tasks Disconnect Stop protocol stack The application... Æ 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. Æ 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. Æ Using isdnsendmessage, sends ACU or LAPD messages to the stack to establish a connection. Æ 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. Æ Using isdnsendmessage, sends ACU or LAPD messages to the stack to terminate the connection. Æ Calls isdnstopprotocol to stop the ISDN protocol stack Initializing Your 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 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 AG ISDN Installation Manual, the installation manual for your board, and the OAM System User s Manual. For versions of CT 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 AG ISDN Installation Manual, the installation manual for your board, and the AG Runtime Configuration and Developer s Manual. 38 Natural MicroSystems

39 Sending ISDN Messages to the Stack 2.4 Sending ISDN Messages to the Stack To send a message to the AG 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 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 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: isdnsendmessage(ctahd, *message, *p_data, size); size (bytes) ISDN_MESSAGE structure Contains: o primitive (e.g. ACU_CONN_IN) o data_size=size o other data ACU message structure Contains data for message Figure 13. isdnsendmessage Data Structures Natural MicroSystems 39