Version
Chapter 1
Digital Trunk Monitor Service Overview
- 1.1 Introduction
- 1.2 Digital Trunk Monitor Service
- 1.2.1 Alarms and Digital Trunks
- 1.3 Natural Access Environment
- 1.3.1 Programming Model
- 1.3.2 Natural Access Components
- 1.3.3 Managing Parameters in Natural Access
1.1 Introduction
- This manual describes the Natural MicroSystems Digital Trunk Monitor (DTM) service API. This service allows Natural Access applications to monitor for alarms on digital trunks, and to gather performance statistics.
- This document is written for developers of telephony and voice applications who are using Natural Access 4.0 or higher. This document defines telephony terms where applicable, but assumes that the user is familiar with telephony concepts. It also assumes that the user is familiar with C programming.
1.2 Digital Trunk Monitor Service
- The Digital Trunk Monitor (DTM) service is a Natural Access service. Natural Access is a development environment for computer-based telephony applications that provides a standard, hardware-independent programming interface.
- A Natural Access service is a group of logically related telephony functions. Each service is contained in a service manager, which is a software wrapper surrounding one or more services. The service manager implements binding functions that enable a service to integrate with Natural Access.
- A trunk is a transmission channel between two switching stations. For the purpose of the DTM service, consider a T1 or E1 line (the aggregate of 24 or 30 channels) a single trunk. The DTM service operates directly on trunks, rather than on ports or contexts. A Natural Access service can be implemented on multiple boards.
- The DTM service enables an application to monitor for alarms on T1 and E1 trunks, to gather performance statistics, and to detect digital trunk failures easily.
- The DTM service can be used to collect statistics, report error counts, and report errored/failed seconds counts. A DTM event is generated when any count changes. The application can synchronously retrieve the current counter values from the DTM service's internal cache.
- A DTM service demonstration program called trunklog is included with Natural Access.
1.2.1 Alarms and Digital Trunks
- A T1 trunk enters an alarm state upon the presence of red, yellow, or blue alarms. An E1 trunk enters an alarm state upon receipt of local or remote Loss of Frame errors, or excessive bit errors. When the DTM service is used as an alarm monitor, an event is generated when a digital trunk goes into or out of an alarm state. Since failure monitoring is done in the same processing context as call processing, an application can terminate a call and mark its port as unavailable upon receipt of a trunk failure event.
- Multiple trunks can be monitored using a single context. The same trunk can be monitored by multiple contexts (and multiple processes).
1.3 Natural Access Environment
- This section provides background information about the Natural Access functions and summarizes the main elements of the Natural Access environment. For more detailed information about Natural Access and the ADI service, see the Natural Access Developer's Reference Manual, the ADI Service Developer's Manual, and the ADI Service Function Reference Manual.
1.3.1 Programming Model
- Natural Access employs an asynchronous programming model in order to take advantage of concurrent processing. Each function called will return immediately with either a return value of SUCCESS or an error code. Synchronous functions are complete when the return code is received.
- For asynchronous operations, if the return value is SUCCESS, the function has been successfully initiated, and the execution result will arrive asynchronously. If the return code is not SUCCESS, the operation is not initiated and no events associated with the particular function will be generated.
- The execution result is indicated by an event or a series of events. An event is a data structure which includes an event ID that indicates which operation it refers to, and operation-specific results. For more information about events in the Natural Access environment, refer to the Natural Access Developer's Reference Manual.
- Natural Access provides common system error codes that all the services use, which are defined in the header file ctaerr.h and are prefixed with CTAERR_. Refer to the Natural Access Developer's Reference Manual for detailed descriptions of Natural Access error codes, and to the ADI Service Function Reference Manual for detailed descriptions of ADI service error codes. Use ctaGetText to obtain the text description of an error code.
1.3.2 Natural Access Components
- A context organizes services and accompanying resources around a single processing context. A context usually represents an application instance controlling a single telephone call. Some contexts are not associated with a call. For example, an operation performing speech recognition on a buffer of data does not require a telephone line.
- Only one instance of a service may be opened on a single context.
- Each type of service has defined parameters. Each service instance has its own copy of these parameters maintained by the context. This allows each telephone call to have its own characteristics.
- To use the DTM service in the Natural Access environment, an application must obtain a context and open the DTM service on it.
- 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.
- When the event queue is created, you specify the service managers to be attached to it. Use the ADI service manager (ADIMGR) for the DTM service. When creating a context, you specify an associated event queue. All events from the services on the context are sent to the event queue attached to the context.
- One queue can be created for the entire application process or multiple queues may be used. The number of queues you create depends on the programming model used. Some models use one queue to handle all contexts, and handle multiple telephone calls through the same queue. Other models use one queue for each call.
1.3.3 Managing Parameters in Natural Access
- Natural Access service characteristics can be altered by modifying associated parameters. Each parameter structure has default values that are sufficient for most applications.
- Natural Access manages parameters for services on a context basis. The context maintains a copy of the parameters for all services opened on the context. This allows each operation to have its own characteristics.
- The following Natural Access functions allow you to obtain or change parameter information:
- ctaSetParmByName modifies a single field for a given parameter name.
- ctaGetParmInfo retrieves a parameter field definition.
- ctaGetParms returns parameter values for a given parameter structure.
- ctaRefreshParms resets the values of all context parameters on a context to
the global defaults.
- Refer to the Natural Access Developer's Reference Manual for details about Natural Access parameter management, and for details about Natural Access functions.
Version
Want to send us feedback on our documentation? Email: Tech_Pubs@nmss.com
Copyright © 2001, Natural MicroSystems, Inc. All rights
reserved.