1.1 Introduction

1.2 What is Natural Access?

1.2.1 Types of Services

1.3 Natural Access Operation

1.3.1 Context

1.3.2 Event Queue

1.4 Natural Access Application Setup and Initialization

1.4.1 Initializing Natural Access

1.4.2 Creating Queues

1.4.3 Creating Contexts

1.4.4 Opening Services

1.1 Introduction

The Natural Access Service Writer's Manual provides the information necessary to write a service that fits into the Natural Access framework.

This manual requires that the reader be familiar with Natural Access concepts and terminology. Previous experience with writing an application with Natural Access is helpful.

The Natural Access Service Writer's Manual is part of the Service Writer's Kit. Full sample code including a sample Natural Access service and test application can be found in the Service Writer's Kit associated with this manual.

1.2 What is Natural Access?

Natural Access is a programming environment for telephony applications providing:

• A standard set of telephony functions grouped into logical services.

• An application programming interface (API) to these services that is independent of the underlying hardware.

• Support for multiple programming models.

• A consistent interface for event handling, error handling, and parameter management.

As shown in Figure 1, a service manager is a software wrapper that surrounds a service. It implements the required Natural Access functions that enable a service to seamlessly integrate into Natural Access.

The dispatcher handles all routing of commands and responses between the services and the application. When an application invokes a function by using a service API, the dispatcher routes the commands to the appropriate service. When the response is received from the service, the dispatcher returns it to the application.

Figure 1. Natural Access Overview

Natural Access includes the following standard services:

This service...	Provides the functionality for..
Switching service	Controlling Multi-Vendor Integration Protocol (MVIP) switch blocks on telephony boards.
Voice Message service	Playing, recording, and editing voice messages in files or memory.
ADI service	Call control, tone detection and generation, and DTMF detection using AG boards.
Point-to-Point Switching service	Making switch connections between boards without specifying intervening bus timeslots.
DTM service	Monitoring for alarms on T1 and E1 trunks, and gathering performance statistics.

In addition, Natural Access supports extended services. These services are not included in the standard Natural Access package:

This service...	Provides...
NaturalFax	Fax functionality.
NaturalText	Text-to-speech functionality.
NaturalRecognition	Functions for accurate, automatic speech recognition.

Services are provided by NMS, but they can also be provided by third party vendors. The purpose of this manual is to describe how to define and implement a service which can be seamlessly integrated into the Natural Access environment.

The remainder of this chapter provides an overview of the Natural Access programming environment from an application developer's perspective. For further details on developing a Natural Access application, refer to the Natural Access Developer's Reference Manual.

1.2.1 Types of Services

There are two types of Natural Access services:

• Device services

• Integration services

Device services interface directly with the hardware providing some kind of functionality (e.g., a telephony board). Device services deal with the low-level details of interoperating with the hardware and present an easy-to-use, abstracted API to an application. For example, the ADI service is a device service. It uses the resources on AG boards to provide functionality such as call control, tone generation, and DTMF detection via the ADI service API.

In a Natural Access application, you specify a device service with a board number and an MVIP address. This defines the channel (port) on the telephony board to use.

Integration services combine one or more device services with additional functionality to provide more convenient application programming.

For example, the Switching service is a device service providing functions for controlling switch blocks. The Point-to-Point Switching service is an integration service providing functions for making switch connections without specifying intervening bus timeslots. The Point-to-Point Switching service manages the bus timeslots in use and how connections can be made.

A device service provides the hardware interface for an integration service. When the Point-to-Point Switching service makes a switch connection, it calls the appropriate Switching service function.

Figure 2. Device Service and Integration Service

1.3 Natural Access Operation

Natural Access employs an asynchronous programming model in order to take advantage of concurrent processing.

When called, most API functions return immediately indicating that the function was initiated. The application may then perform other functions while Natural Access is processing the requested function.

As shown in Figure 3, Natural Access converts the function call to a command, sends the command to the service which then sends a command to a telephony board. The board performs the requested functions and sends events to the service indicating its state (e.g., function was started, function is complete, etc.). The service sends events to Natural Access which then makes the events available to the application.

Figure 3. Natural Access Commands & Events

1.3.1 Context

A context organizes services and accompanying resources around a single processing context. Typically, a context represents an application instance controlling a single telephone call. Other contexts may not be associated with a call. For example, an application performing voice conversions does not require a telephone line.

Service functionality is attached to a context by opening a service on a context, creating a service instance. A service instance defines a service (i.e., a logical group of functions) and its associated resource (e.g., MVIP board, stream, and timeslot). A context is a bound collection of service instances. This binding groups functions and resources with a state, creates service dependencies, and manages parameters.

Figure 4. Contexts

1.3.2 Event Queue

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 you create a context, you also specify an event queue. All events from the services on the context are sent to the event queue attached to the context.

One event queue can be created for the entire application process or multiple event queues can be used. The number of event queues depends on the application programming model. Some models use one event queue to handle all contexts; multiple telephone calls are handled with the same event queue. Other models use one event queue for each call.

Figure 5. Event Queue

1.4 Natural Access Application Setup and Initialization

Application setup for Natural Access consists of the following steps:

1. Initialize Natural Access for the process.

2. Create event queues.

3. Create contexts and attach them to an event queue.

4. Open services on contexts.

1.4.1 Initializing Natural Access

You register services in the call to ctaInitialize by specifying the service and service manager names. Only the services specified in the call to ctaInitialize may be used by the application.

1.4.2 Creating Queues

The next step is to create one or more event queues by calling ctaCreateQueue. You specify which service managers will be attached to each queue. When you attach a service manager to a queue, you are informing Natural Access that this queue will be receiving events from the listed service managers once the service managers have been opened.

An event queue handle (ctaqueuehd), returned from ctaCreateQueue, references the event queue. You supply the handle to retrieve events from the queue when calling ctaWaitEvent.

ctaCreateQueue may be invoked multiple times within a single process. Each invocation returns a unique queue handle.

1.4.3 Creating Contexts

A context is created by calling ctaCreateContext. You provide the queue handle (ctaqueuehd) that was returned from ctaCreateQueue. All events for services on the context will be received in the specified event queue.

ctaCreateContext returns a context handle (ctahd). The context handle is supplied by the application when invoking Natural Access functions. Events communicated back to the application are also associated with the context.

1.4.4 Opening Services

Services are opened on a context by calling ctaOpenServices, passing a context handle and a list of service descriptors. The service descriptor specifies the name of the service, service manager, and service-specific arguments (e.g., MVIP address).

Services are referenced by the context handle (ctahd). Applications access a service via the service API. Each service API function typically takes, as one of its arguments, the associated context handle. For example vceOpenFile (ctahd...), implies the ctahd instance of the Voice Message service.