1.1 Introduction

1.2 NaturalConference Overview

1.2.1 NaturalConference Objects

1.2.2 Conferencing Capabilities

1.3 NaturalConference and CT Access

1.3.1 CT Access Services

1.3.2 CTA Contexts and Event Queues

1.3.3 CT Access Programming Model

1.3.4 Managing Parameters in CT Access

1.3.5 Operations, Administration, and Maintenance Service

1.4 NaturalConference Development Environment

1.4.1 NaturalConference System Architecture

1.4.2 NaturalConference Data Flow

1.4.3 Resource Handles, and Conference and Member Identifiers

1.4.4 Regulatory Constraints

1.1 Introduction

This manual describes how to use NaturalConference to write applications that create and manage conferences, and provides detailed descriptions of the NaturalConference capabilities and functions. This reference manual should be used with the CT Access Developer's Reference Manual.

This manual is targeted to developers of telephony and voice applications who are using CT Access. This document defines telephony terms where applicable, but assumes that you are familiar with telephony concepts and switching. It also assumes that you are familiar with the C programming language.

1.2 NaturalConference Overview

NaturalConference allows you to create a virtual meeting room, in which several participants can converse with one another simultaneously. NaturalConference contains many features that allow these virtual meeting rooms to act much like their real world counterparts.

NaturalConference functions fall into three distinct categories:

• A set of functions used to open conferencing resources, create conferences, and add members to conferences.

• Functions for retrieving information about:

• Conferencing resources

• Conferences

• Members

More advanced functions that enable dynamic changes to conference features and the behavior of members added to a conference.

NaturalConference is designed to be used with AG 2000, AG 4000, and AG 4000C boards.

1.2.1 NaturalConference Objects

A conference is created and managed through three interdependent entities:

Object	Description
Conferencing resource	A single digital signal processor (DSP) or a set of DSPs working together. When a conferencing resource (associating one or more DSPs) is created, a set is declared, providing uniform capabilities and features. As an analogy, a conferencing resource can be seen as a building, and the number of DSPs assigned to the resource represent the scale of the building.
Conference	A space created by the application on a specified conferencing resource. In our building analogy, the conference would be a meeting room within the building. At creation time, the room would be empty, and the number of participants it would expect would be determined by the application creating it. An application can also add seats to the meeting after it has begun.
Member	An object created by the application on a specified conference. Adding a member to a conference would be like a participant sitting in a seat in our meeting room/building analogy.

Figure 1. Visualization of the Building Analogy

1.2.2 Conferencing Capabilities

The building analogy can also illustrate the different capabilities that can be given to each resource, conference, and member. A capability is a NaturalConference feature that can be enabled for a given conferencing object. NaturalConference offers these features:

• Automatic gain control on input and output

• Dual-tone-multi-frequency (DTMF) clamping

• Tone clamping

• Echo cancellation

• Talker privilege (can be activated to ensure that a member can be heard)

• Active talkers (used to recognize which participants are presently talking)

The capabilities that are available to an application depend on the board itself. The application can choose which capabilities to use to regulate system resources. Additionally, NaturalConference allows an application to query a conferencing object about its capabilities.

In the building analogy, capabilities translate into seat types. The full set of capabilities would correspond to an armchair, whereas the minimal set would be a simple stool. Just as an armchair would take up more space in a room than a stool, the more capabilities that are added to an object, the more system resources are used.

1.3 NaturalConference and CT Access

CT Access is a development environment that provides standard programming interfaces for hardware independent telephony functions. You must have CT Access installed on your system to build applications using NaturalConference. This section provides background information about CT Access and describes how NaturalConference fits into the CT Access environment. For detailed information about CT Access, see the CT Access Developer's Reference Manual.

1.3.1 CT Access Services

A CT Access service is a group of logically related telephony functions. NaturalConference uses a specific CT Access service called the CNF service. Other services address other aspects of a telephony application. For example, the Switching service controls circuit switching; the NCC service performs call control. For a complete list of CT Access services, see the CT Access Developer's Reference Manual.

1.3.2 CTA Contexts and Event Queues

CT Access organizes services and accompanying resources around a single processing context. A CTA context usually represents an application instance controlling a single telephone call. However, the application using NaturalConference uses one CT Access context to control each telephone call, and another to control one or more NaturalConference resources.

CT Access provides multi-processing support. Multiple CT Access application processes can perform tasks on behalf of the same CT Access context (referred to as context sharing). CT Access applications can transfer control of CT Access contexts (for example, contexts associated with individual telephone calls) to other CT Access applications (referred to as context hand-off).

An event queue is the communication path from a CT Access service to an application. The CT Access service generates events indicating certain conditions or state changes and sends them to applications via the event queue.

Figure 2. CT Access and NaturalConference

1.3.3 CT Access Programming Model

The CT Access programming model employs two types of functions: synchronous and asynchronous.

• Synchronous functions indicate completion by sending a return value. The return value may be either SUCCESS or an error code.

• Asynchronous functions allow applications to take advantage of concurrent processing by calling additional functions after receiving an indication that a function has initiated successfully.

Chapter 5 lists the NaturalConference functions and whether they are synchronous or asynchronous. The application may receive conference events that are not directly related to a function invocation. Refer to
Appendix A for a complete list of NaturalConference errors and events.

Note: NaturalConference requires CT Access 3.0 (or later).

1.3.4 Managing Parameters in CT Access

The characteristics of CT Access services can be altered by modifying associated parameters. Each NaturalConference parameter structure has default values that are compatible with most configurations. CT Access manages parameters for services on a CTA context basis. The CTA context maintains a copy of the parameters for all services opened on the context.

The following CT Access functions allow you to obtain or change parameter information:

Function	Description
ctaGetParmByName	Retrieves a single field for a given parameter name.
ctaSetParmByName	Modifies a single field for a given parameter name.
ctaGetParmID	Retrieves the parameter ID for a given parameter descriptor 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 CTA context to the global defaults.

Refer to the CT Access Developer's Reference Manual for detailed information about the parameter functions.

1.3.5 Operations, Administration, and Maintenance Service

The Operations, Administration, and Maintenance (OAM) service is the API for the NMS OAM software. OAM is an extension to CT Access that performs operations on, administration of, and maintenance of telephony resources in a system. Use OAM to configure and initialize the NMS hardware in your chassis. OAM can manage

• Hardware components, such as NMS boards, or

• Software components, such as the NMS Hot Swap process.

Since these components are being managed by OAM, they are called managed components.

Using NMS OAM, you can

• Create, delete, and query the configuration of a board managed component.

• Start (boot), stop (shut down), and test a managed component.

• Receive notifications from managed components.

Software processes supported by OAM include

• Hot Swap: the ability to insert and extract CompactPCI boards without powering down the system.

• Basic H.110 clock management operations: configuring and setting the bus clock across all boards in a system.

OAM is available with versions of CT Access 4.0 and later. For general information about OAM, refer to the OAM System User's Manual. For more information about the OAM service, refer to the OAM Service Developer's Reference Manual.

Note: OAM operates only when the CT Access Server (ctdaemon) is running.

1.4 NaturalConference Development Environment

This section explains the NaturalConference system architecture and processing chain.

1.4.1 NaturalConference System Architecture

NaturalConference is an API allowing communication with enhanced voice processing modules running on Digital Signal Processors (DSPs) embedded on NMS boards. This relationship is shown in Figure 3:

Figure 3. NMS Basic NaturalConference System

DSPs or DSP pools located on AG 2000, AG 4000, and AG 4000C boards can be programmed to support IVR, Fax, IP Telephony, or NaturalConference. NaturalConference requires dedicated DSPs. DSPs programmed for NaturalConference cannot be used for any other feature.

For more detail about AG 2000, AG 4000, and AG 4000C configurations, see your board-specific installation and developer's manual and Chapter 2 of this manual.

Although the voice channel associated with a particular member joining a conference and the conference being joined do not have to be located on the same board, the application must perform the appropriate switching to connect the new member's line to the conference. If the member comes from the same board, establish a local stream to local stream connection; otherwise, establish a bus stream to a local stream connection.

For more detail about the Switching API, see the Switching Service Developer's Reference Manual and the Point-to-Point Switching Service Developer's Reference Manual.

1.4.2 NaturalConference Data Flow

NaturalConference performs processing individually for each member's voice input, mixes according to the conference's attrributes, and generates the output signal for each member. Figure 4 summarizes the processing chain performed by the conferencing DSP code:

Figure 4. Processing Chain in a Conference

NaturalConference features such as DTMF clamping or echo cancellation can be specified when declaring the conferencing resource or creating the conference. Other settings, such as selecting the number of loudest speakers, can be changed dynamically. Settings (or attributes) such as talking and listening activity and gain control can be specified for each member.

1.4.3 Resource Handles, and Conference and Member Identifiers

Any call to NaturalConference requires a conferencing resource handle (cnfresourcehd). A conferencing resource handle links a CTA context and a conferencing resource. An application can create as many of these paths as necessary among CTA contexts. A conferencing resource handle is obtained by opening a conferencing resource with cnfOpenResource and specifying the resource number to open. Once you have a cnfresourcehd, you can create conferences and add members to them.

When you create a new conference, a unique conference identifier is generated and is returned to an application. Similarly, when adding a new member to a conference, a unique member identifier is generated and returned. NaturalConference also provides enumeration functions allowing the retrieval of existing conference identifiers on a given resource and existing members on a given conference.

By opening a resource and creating a resource handle on a given CT Access context, the application implicitly designates which queue returns the events for the conferences created by that resource handle. Figure 5 shows the respective links among CT Access objects, resource handles, and conferencing identifiers.

Figure 5. CT Access Objects, Resource Handles, and Conferencing Identifiers

The actual link between CT Access and a NaturalConference object is performed at the resource handle level. Resource handles can be created using ctahd in the same way that instances of ctahd can be created on a queue.

See Chapter 4 for further details about queue/context threading models for use with NaturalConference within the CT Access environment.

See Chapter 6 for a complete description of NaturalConference functions.

1.4.4 Regulatory Constraints

The Telecom Regulatory Authorities regulate NaturalConference in some countries. These regulations address two aspects of conferencing:

• The number of outside lines involved in a conference

• The transmission plan

Since these aspects are dependent on the applications that our customers develop and the countries where the product is installed, Natural MicroSystems does not obtain Type Approval for NaturalConference. Contact the Regulatory Authorities in each country in which you plan to install this product to learn the regulations applicable to applications developed with NaturalConference.