AG ISDN Messaging API Developer s Reference Manual

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

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. 2000 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 6330 1.2 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 4.0 2.1 September, 2000 SJC, CT Access 4.0 GA This manual printed: September 27, 2000 Refer to the NMS web site (www.nmss.com) for product updates and for information about NMS support policies, warranty information, and service offerings.

Table of Contents 1 Introduction..................................................... 11 1.1 Introduction................................................. 12 1.2 Integrated Services Digital Network (ISDN)........................ 13 1.2.1 ISDN Protocols and Protocol Layering...................... 13 1.2.2 Information Exchange Between Layers...................... 14 1.2.3 ISDN Carriers.......................................... 16 1.2.4 ISDN Functional Devices and Reference Points............... 17 1.3 AG ISDN Software............................................ 19 1.3.1 AG ISDN Product Configurations.......................... 19 1.3.2 AG ISDN ACU Configuration............................. 20 1.3.3 The AG ISDN LAPD Configuration........................ 22 1.3.4 Reference Points Supported by AG ISDN.................... 24 1.4 AG ISDN Software Components................................. 25 1.4.1 The Readme File........................................ 26 1.4.2 The AG ISDN Function Libraries.......................... 26 1.4.3 ISDN Protocol Stack Downloadable Object Modules........... 28 1.4.4 The Configuration File................................... 28 1.4.5 The Demonstration Programs and Utilities................... 29 1.5 Other Components............................................ 30 1.5.1 About CT Access....................................... 30 1.6 Developing an AG ISDN Application............................. 31 2 Messaging API Programming Model................................ 33 2.1 Introduction................................................. 34 2.2 The CT Access Environment.................................... 34 2.2.1 CT Access Components.................................. 34 2.2.2 The CT Access Programming Model........................ 35 2.3 Application Overview.................... 37 2.3.1 Initializing Your Boards.................................. 38 2.4 Sending ISDN Messages to the Stack............................. 39 2.4.1 Building ACU Message Structures.......................... 40 2.4.2 Sending LAPD Messages................................. 43 2.5 Receiving Events and ISDN Protocol Stack Messages................ 44 2.5.1 Receiving Messages From the AG ISDN Protocol Stack........ 45 Natural MicroSystems 3

Table of Contents 3 Initializing a Messaging API Application............................. 49 3.1 Introduction.................................................. 50 3.2 Overview.................................................... 51 3.3 Making Switch Connections for AG ISDN.......................... 55 3.4 Initializing CT Access.......................................... 59 3.4.1 Specifying B Channel CTA Contexts........................ 59 3.4.2 Specifying D Channel CTA Contexts........................ 60 3.5 Accessing D Channels.......................................... 60 3.5.1 About Network Access Identifiers (NAIs).................... 60 3.5.2 Initializing ISDN Protocol Stack Instances.................... 61 3.6 Starting the NOCC TCP........................................ 62 3.6.1 Setting mediamask (AG Quad T/E only)...................... 63 3.7 Stopping an ISDN Protocol Stack Instance.......................... 63 4 Call Control (ACU Configuration)................................... 65 4.1 Introduction.................................................. 66 4.1.1 About Connection IDs.................................... 66 4.2 The ISDN Call Control State Machine............................. 67 4.3 Receiving Inbound Calls........................................ 67 4.3.1 Accepting the Call....................................... 68 4.3.2 Rejecting the Call....................................... 69 4.3.3 Incoming Calls With Overlap Receiving Mode Enabled......... 69 4.4 Placing Outbound Calls......................................... 70 4.5 Call Collision................................................. 71 4.6 Call Clearing................................................. 73 4.6.1 Clear Collision.......................................... 76 5 Data Link Operations (LAPD)...................................... 79 5.1 Introduction.................................................. 80 5.2 The AG ISDN State Machine (LAPD Configuration)................. 80 5.3 Initiating a Data Link........................................... 81 5.4 Responding to a Data Link Establishment Request.................... 82 5.5 Sending Messages Across an Established Link....................... 83 6 Messaging API Data Structures..................................... 85 6.1 Introduction.................................................. 86 6.2 Messaging Structures........................................... 86 6.2.1 ISDN_MESSAGE Structure............................... 87 4 Natural MicroSystems

Table of Contents 6.2.2 ISDN_PACKET Structure................................ 88 6.3 Protocol Parameter Structures................................... 88 6.3.1 ISDN_PROTOCOL_PARMS_Q931CC Structure............. 89 6.3.2 ISDN_PROTOCOL_PARMS_LAPD Structure............... 91 6.3.3 ISDN_PROTOCOL_PARMS_CHANNELIZED.............. 92 7 Alphabetical Function Reference.................................... 93 7.1 Introduction................................................. 94 7.2 Function Summary...................... 94 7.3 Alphabetical Function Reference................................. 95 isdnreleasebuffer....................................... 96 isdnsendmessage....................................... 99 isdnsetmsgcapture..................................... 103 isdnstartprotocol...................................... 106 isdnstopprotocol....................................... 114 8 Message Primitives.............................................. 117 8.1 Introduction................................................ 118 8.2 ACU Primitives............................................. 118 8.2.1 ACU Message Reference................................ 121 ACU_ALERT_IN...................................... 122 ACU_ALERT_RQ..................................... 127 ACU_CALL_PROC_IN................................. 130 ACU_CALL_PROC_RQ................................ 132 ACU_CLEAR_CO..................................... 134 ACU_CLEAR_IN..................................... 136 ACU_CLEAR_RQ..................................... 139 ACU_CLEAR_RS..................................... 142 ACU_CONN_CO...................................... 144 ACU_CONN_IN...................................... 149 ACU_CONN_RQ...................................... 156 ACU_CONN_RS...................................... 164 ACU_D_CHANNEL_STATUS_IN........................ 169 ACU_D_CHANNEL_STATUS_RQ....................... 170 ACU_DIGIT_CO...................................... 171 ACU_DIGIT_IN....................................... 172 ACU_DIGIT_RQ...................................... 173 ACU_ERR_IN........................................ 174 Natural MicroSystems 5

Table of Contents ACU_FACILITY_IN................................... 175 ACU_FACILITY_RQ................................... 177 ACU_INFORMATION_IN............................... 179 ACU_INFORMATION_RQ.............................. 181 ACU_INIT_CO........................................ 183 ACU_INIT_RQ........................................ 184 ACU_NOTIFY_IN..................................... 185 ACU_NOTIFY_RQ..................................... 186 ACU_PROGRESS_IN.................................. 187 ACU_PROGRESS_RQ.................................. 189 ACU_RESTART_IN.................................... 190 ACU_RESUME_CO.................................... 191 ACU_RESUME_RQ.................................... 192 ACU_SERVICE_CO.................................... 193 ACU_SERVICE_IN.................................... 194 ACU_SERVICE_RQ.................................... 195 ACU_SET_MODE_CO................................. 196 ACU_SET_MODE_RQ................................. 197 ACU_SETPARM_RQ................................... 198 ACU_SETUP_ACK_IN................................. 199 ACU_SETUP_REPORT_IN.............................. 201 ACU_SUSPEND_CO................................... 208 ACU_SUSPEND_RQ................................... 209 ACU_TEST_CO....................................... 210 ACU_TEST_RQ....................................... 211 ACU_USER_INFO_IN.................................. 212 ACU_USER_INFO_RQ................................. 213 8.3 Data Types and Constants In Primitives........................... 214 8.3.1 User Rate Values....................................... 214 8.3.2 Service Values......................................... 215 8.3.3 Number Type Values.................................... 218 8.3.4 Plan Values........................................... 219 8.3.5 Screening Indicator Values............................... 219 8.3.6 Redirecting Reason Values............................... 220 8.3.7 Location Values........................................ 220 8.3.8 UUI Protocol Discriminator Values........................ 221 8.3.9 Signal Values.......................................... 222 8.3.10 Network-Provided Clearing Cause Values................... 223 6 Natural MicroSystems

Table of Contents 8.3.11 Clear Code Values..................................... 227 8.3.12 Facility Code Values................................... 228 8.3.13 Action Code Values.................................... 229 8.3.14 Mode Code Values..................................... 229 8.3.15 Error Cause Values..................................... 230 8.3.16 Progress Description Values.............................. 231 8.3.17 Charging Type Values.................................. 231 8.3.18 Endpoint ID Values.................................... 232 8.4 LAPD Primitives............................................ 232 9 Demonstration Programs and Utilities.............................. 235 9.1 Introduction................................................ 236 9.2 Demonstration Programs and Utilities............................ 236 9.3 Layer 3 Call Control Demonstration: isdndemo.................... 237 9.3.1 Using NFAS With isdndemo............................. 243 9.3.2 Structure and Coding (Single-Threaded Version)............. 246 9.3.3 Structure and Coding (Multi-Threaded Version).............. 251 9.3.4 ISDN Call Control..................................... 253 9.3.5 Identifying Trunks..................................... 257 9.4 LAPD Demonstration Program: lapddemo........................ 258 9.4.1 The lapddemo Configuration File.......................... 262 9.4.2 lapddemo Structure and Coding Features.................... 267 9.5 Stack Traffic Analysis Tool: dectrace............................ 268 9.5.1 Creating a Log File for dectrace........................... 270 9.5.2 Messages Decoded by dectrace........................... 272 9.5.3 Sample dectrace Output................................. 278 9.6 Stack Traffic Filtering Tool: itrace............................... 280 Appendix A Events, Reasons, and Errors.............................. 283 Introduction..................................................... 284 AG ISDN Events................................................. 284 AG ISDN Reasons................................................ 285 AG ISDN Errors.................................................. 286 Appendix B Parameters............................................. 287 Introduction..................................................... 288 ISDN_PROTOCOL_PARMS_Q931CC............................... 288 services_list Field........................................... 291 Natural MicroSystems 7

Table of Contents in_calls_behaviour Field...................................... 294 out_calls_behaviour Field..................................... 297 acu_behaviour Field......................................... 299 ns_behaviour Field.......................................... 300 qsig_source_party_nb_type Field............................... 302 qsig_source_type_of_nb Field.................................. 303 ISDN_PROTOCOL_PARMS_LAPD.................................. 304 Appendix C Sending and Receiving Raw Q.931 Data..................... 307 Introduction...................................................... 308 Creating Transparent IEs............................................ 308 Transparent IE Formatting Rules............................... 309 Accessing and Reading a Q.931 Buffer................................ 311 Appendix D Sending and Receiving PCS-User Information................ 313 Introduction...................................................... 314 Structure of User-PCS IEs........................................... 314 Sending and Receiving PCS Information Elements....................... 315 Example Code.................................................... 316 Appendix E Timer Values........................................... 317 Introduction...................................................... 318 Timer Functions.................................................. 318 Timer Values..................................................... 321 France VN6 Layer 3 Timer Defaults............................. 321 EuroISDN Layer 3 Timer Defaults.............................. 323 AT&T E10 Layer 3 Timer Defaults............................. 324 Nortel DMS 100 Layer 3 Timer Defaults......................... 325 USA National ISDN-2 Layer 3 Timer Defaults.................... 326 Australian Telecom 1 Layer 3 Timer Defaults..................... 327 Hong Kong Telephone Layer 3 Timer Defaults.................... 328 INS-1500 NTT Layer 3 Timer Defaults.......................... 329 AT&T 4ESS Layer 3 Timer Defaults............................ 330 Korean (and Taiwan) Layer 3 Timer Defaults..................... 331 QSIG Layer 3 Timer Defaults.................................. 332 Appendix F NFAS and D Channel Backup............................. 333 Introduction...................................................... 334 8 Natural MicroSystems

Table of Contents Non-Facility Associated Signaling (NFAS)............................. 334 Setting Up NFAS........................................... 335 Using NFAS............................................... 336 D Channel Backup................................................ 336 Setting up D Channel Backup................................. 337 Handling D Channel Failure................................... 337 Appendix G Modifying the NSF IE.................................... 339 Introduction..................................................... 340 NSF IE Fields.................................................... 341 net_id_type............................................... 341 action.................................................... 341 serv_feature............................................... 341 Facility Coding............................................. 342 param_fld................................................. 343 Example........................................................ 343 Natural MicroSystems 9

Table of Contents 10 Natural MicroSystems

Chapter 1 Introduction 1.1 Introduction 12 1.2 Integrated Services Digital Network (ISDN) 13 1.2.1 ISDN Protocols and Protocol Layering 13 1.2.2 Information Exchange Between Layers 14 1.2.3 ISDN Carriers 16 1.2.4 ISDN Functional Devices and Reference Points 17 1.3 AG ISDN Software 19 1.3.1 AG ISDN Product Configurations 19 1.3.2 AG ISDN ACU Configuration 20 1.3.3 The AG ISDN LAPD Configuration 22 1.3.4 Reference Points Supported by AG ISDN 24 1.4 AG ISDN Software Components 25 1.4.1 The Readme File 26 1.4.2 The AG ISDN Function Libraries 26 1.4.3 ISDN Protocol Stack Downloadable Object Modules 28 1.4.4 The Configuration File 28 1.4.5 The Demonstration Programs and Utilities 29 1.5 Other Components 30 1.5.1 About CT Access 30 1.6 Developing an AG ISDN Application 31 Natural MicroSystems 11

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

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

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. 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. 14 Natural MicroSystems

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

Chapter 1 Introduction 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. 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

ISDN Functional Devices and Reference Points 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 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-41449 ISDN Primary Rate Interface Specification. Natural MicroSystems 17

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

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. 1.3.1 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 4.4.1. Natural MicroSystems 19

Chapter 1 Introduction 1.3.2 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

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

Chapter 1 Introduction 1.3.3 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

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

Chapter 1 Introduction 1.3.4 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

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

Chapter 1 Introduction 1.4.1 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. 1.4.2 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

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

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

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

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

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

Chapter 1 Introduction 32 Natural MicroSystems

Chapter 2 Messaging API Programming Model 2.1 Introduction 34 2.2 The CT Access Environment 34 2.2.1 CT Access Components 34 2.2.2 The CT Access Programming Model 35 2.3 Application Overview 37 2.3.1 Initializing Your Boards 38 2.4 Sending ISDN Messages to the Stack 39 2.4.1 Building ACU Message Structures 40 2.4.2 Sending LAPD Messages 43 2.5 Receiving Events and ISDN Protocol Stack Messages 44 2.5.1 Receiving Messages From the AG ISDN Protocol Stack 45 Natural MicroSystems 33

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

The CT Access Programming Model 2.2.2 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

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

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

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

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