Intel 05-2505-001 User Manual

Conferencing API

Programming Guide

August 2006

05-2505-001

INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL® PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, INTEL ASSUMES NO LIABILITY WHATSOEVER, AND INTEL DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT. Intel products are not intended for use in medical, life saving, life sustaining, critical control or safety systems, or nuclear facility applications.

Intel may make changes to specifications and product descriptions at any time, without notice.

This Conferencing API Programming Guide as well as the software described in it is furnished under license and may only be used or copied in accordance with the terms of the license. The information in this manual is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Intel Corporation. Intel Corporation assumes no responsibility or liability for any errors or inaccuracies that may appear in this document or any software that may be provided in association with this document.

Except as permitted by such license, no part of this document may be reproduced, stored in a retrieval system, or transmitted in any form or by any means without the express written consent of Intel Corporation.

Dialogic, Intel, Intel logo, and Intel NetStructure are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

* Other names and brands may be claimed as the property of others.

Publication Date: August 2006

Document Number: 05-2505-001

Intel 1515 Route 10 Parsippany, NJ 07054

For Technical Support, visit the Intel Telecom Support Resources website at:

http://developer.intel.com/design/telecom/support

For Products and Services Information, visit the Intel Telecom and Compute Products website at:

http://www.intel.com/design/network/products/telecom

For Sales Offices and other contact information, visit the Buy Telecom Products page at:

http://www.intel.com/buy/networking/telecom.htm

Conferencing API Programming Guide – August 2006

Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

About This Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Applicability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

How to Use This Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1 Product Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

1.2 Key Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

1.3 Understanding How Conferences are Formed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

1.4 Relationship with Other Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

1.4.1 Standard Runtime Library (SRL). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

1.4.2 Device Management API Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

1.4.3 Voice API Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

1.4.4 IP Media Library API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

1.4.5 Global Call API Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

1.4.6 Digital Network Interface API Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

2 Programming Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2.1 Programming Models Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2.2 Asynchronous Programming Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

3 Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

3.1 SRL Event Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

3.2 SRL Standard Attribute Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

5 Application Development Guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

5.1 Using Symbolic Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

5.2 Using Conferencing Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

5.3 Creating a Conference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

5.4 Conference Bridging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

5.5 Terminating an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

5.6 Data Structure Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

5.7 Multiprocessing Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

5.8 Multithreading Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

6 Using Active Talker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

7 Using Volume Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

8 Building Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

8.1 Compiling and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Conferencing API Programming Guide – August 2006 3

Contents

8.1.1 Include Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

8.1.2 Required Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

8.2 Variables for Compiling and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

4 Conferencing API Programming Guide – August 2006

Revision History

This revision history summarizes the changes made in each published version of this document.

Document No. Publication Date Description of Revisions

05-2505-001 August 2006 Initial version of document.

Conferencing API Programming Guide — August 2006 5

Revision History

6 Conferencing API Programming Guide — August 2006

About This Publication

The following topics provide more information about this publication:

• Purpose

• Applicability

• Intended Audience

• How to Use This Publication

• Related Information

Purpose

This publication provides programming guidelines for the conferencing API, supported in Intel NetStructure a companion document to the Conferencing API Library Reference, which provides details on all functions, parameters, and data structures in the conferencing API.

Host Media Processing Software for Linux* and Windows* operating systems. It is

Applicability

This document (05-2505-001) is originally published for Intel NetStructure® Host Media Processing Software Release 3.0 for Windows* operating system.

This document may also be applicable to later software releases (including service updates) on Linux or Windows. Check the Release Guide for your software release to determine whether this document is supported.

Intended Audience

This publication is intended for the following audience:

• Distributors

• System Integrators

• Toolkit Developers

• Independent Software Vendors (ISVs)

• Value Added Resellers (VARs)

• Original Equipment Manufacturers (OEMs)

• End Users

Conferencing API Programming Guide — August 2006 7

About This Publication

How to Use This Publication

This document assumes that you are familiar with the Linux* or Windows* operating systems and the C programming language.

The information in this document is organized as follows:

• Chapter 1, “Product Description” introduces the key features of the conferencing software.

• Chapter 2, “Programming Models” provides a brief overview of supported programming

models.

• Chapter 3, “Event Handling” provides information on functions used to handle events.

• Chapter 4, “Error Handling” provides information on handling errors in your application.

• Chapter 5, “Application Development Guidelines” provides programming guidelines for

developing conferencing applications.

• Chapter 6, “Using Active Talker” provides details on using the active talker feature.

• Chapter 7, “Using Volume Control” provides details on using the volume control feature.

• Chapter 8, “Building Applications” discusses compiling and linking requirements such as

includes files and library files.

Related Information

Refer to the following sources for more information:

• For information about Standard Runtime Library features and guidelines for building all

applications, see the Standard Runtime Library API Programming Guide.

• For details on all functions and data structures in the Standard Runtime Library, see the

Standard Runtime Library API Library Reference.

• For details on all functions and data structures in the device management API, see the Device

Management API Library Reference.

• For information on the software release, system requirements, release features, and release

documentation, see the Release Guide for the software release you are using.

• For details on compatibility issues, restrictions and limitations, known problems, and late-

breaking updates or corrections to the release documentation, see the Release Update.

Be sure to check the Release Update for the system release you are using for any updates or corrections to this publication. Release Updates are available on the Telecom Support Resources website at http://resource.intel.com/telecom/support/releases/index.html.

8 Conferencing API Programming Guide — August 2006

1.Product Description

This chapter provides an overview of the conferencing library. Topics include:

• Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

• Key Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

• Understanding How Conferences are Formed. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

• Relationship with Other Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

1.1 Overview

The conferencing (CNF) software supports development of conferencing applications on Intel NetStructure and/or over traditional PSTN lines.

Intel NetStructure general-purpose servers based on Intel architecture without the need for specialized hardware. When installed on a system, HMP performs like a virtual DM3 board to the customer application, but all media processing takes place on the host processor. In this document, the term “board” represents the virtual DM3 board.

Note: This conferencing (CNF) API is distinct from and incompatible with the conferencing (CNF) API

that was previously released in Intel® Dialogic® System Release 6.0 on PCI for Windows.

Host Media Processing software. The conference can take place over an IP network

Host Media Processing (HMP) software performs media processing tasks on

1.2 Key Features

Key features of the conferencing (CNF) software include the following:

Asynchronous programming model support

This model enables multiple channels to be handled in a single process and supports higher density conferencing solutions.

Support for conferees from multiple sources

Participants in a conference may come from a variety of sources, such as a voice device and an IP media device. The software is designed for flexibility to grow and support additional sources.

Conference bridging

Multiple conferences can be bridged together so that all parties (also called conferees) in two or more established conferences can communicate with one another.

Coach/pupil feature

Two selected parties can establish a private communication link within the overall conference. The coach is a private member of the conference and is only heard by the pupil. However, the pupil cannot speak privately with the coach.

Conferencing API Programming Guide — August 2006 9

Product Description

DTMF digit detection

The application can determine whether a party has generated a DTMF digit.

Vo l u m e c o n t r o l

A party can adjust the listening volume of the conference using pre-programmed DTMF digits.

DTMF tone clamping

This feature mutes dual tone multi-frequency (DTMF) tones heard during a conference. Tone clamping applies to the transmitted audio going into the conference and does not affect DTMF function. It can be enabled on a board, conference, or party basis.

Automatic gain control (AGC)

AGC is an algorithm for normalizing an input signal to a target level. The AGC algorithm discriminates between voiced and unvoiced signals within a conference.

Active talker

The active talker feature sums the three most active talkers in a conference, so that the conversation doesn’t get drowned out when too many people talk at once.

Conference monitoring

Participants have listen-only access to a conference.

Echo cancellation

This feature reduces echo from the incoming signal, improving the quality of a conference for all participants.

Tariff t o n e

A party can receive a periodic tone for the duration of the conference call.

1.3 Understanding How Conferences are Formed

Developing a conferencing application requires the use of the conferencing API library as well as other Intel management API library. Other libraries include the IP media and voice libraries.

A conference consists of conferees (also known as parties). The maximum number of conferences and parties supported varies with the Intel NetStructure in use and, if applicable, the media load in use on the board.

A conference is identified by a unique conference device handle, which is registered with the Standard Runtime Library (SRL). A party is identified by a unique SRL party device handle. The virtual board device is the parent device for the conference device and party device; it has a unique SRL device handle. For more information on the types of conferencing devices, see Section 5.3,

“Creating a Conference”, on page 20.

The conferencing API is used to open a conference, and to add parties to a conference. However, these parties cannot participate in a conference until they are connected to a technology device handle through the dev_Connect( ) device management API function. Technology device handles are obtained through the respective technology API library functions. For example, the dxxxB1C1 voice channel device handle is obtained from dx_open( ).

Dialogic® API libraries, such as the Standard Runtime Library (SRL) and the device

Host Media Processing software license

10 Conferencing API Programming Guide — August 2006

A conference may be formed from parties that are connected to any one of the following technology device handles:

• voice (dx) device handle

• IP media (ipm) device handle

• digital network interface (dti) device handle

Note: A device handle obtained from gc_OpenEx( ) in the Global Call API library cannot be used by

dev_Connect( ) to connect a party to a conference. Rather, you can use the device handle returned by gc_GetResourceH( ) to connect a party to a conference.

1.4 Relationship with Other Libraries

Product Description

A conferencing application is developed using the conferencing API library as well as other Intel® Dialogic

API libraries, including the following:

• Standard Runtime Library (SRL)

• Device Management API Library

• Voice API Library

• IP Media Library API

• Global Call API Library

• Digital Network Interface API Library

1.4.1 Standard Runtime Library (SRL)

The Standard Runtime Library (SRL) provides a common interface for event handling and other functionality common to all devices.

The conferencing API uses three types of devices: virtual board device, conference device, and party device. The conferencing API registers the virtual board device with the Standard Runtime Library (SRL) when cnf_Open( ) is called. In addition, the conference device and the party device are registered when cnf_OpenConference( ) and cnf_OpenParty( ), respectively, are called. Conferencing events are posted to the SRL, which then delivers these events to the application. For more information about SRL functions, see the Standard Runtime Library API Library Reference.

1.4.2 Device Management API Library

The device management API library provides run-time control and management of configurable system devices. It includes functions to reserve resources and to manage the connections between devices. It performs all necessary connection-related operations, including time slot management.

The device connection functions enable connection between conferencing devices and other devices on HMP software, providing the ability for conferencing communication. Before a party can participate in a conference, it must be connected to a supported technology device (such as voice and IP media) using the dev_Connect( ) function. Conference bridging is also accomplished

Conferencing API Programming Guide — August 2006 11

Product Description

through the device management library. For more information about device management functions, see the Device Management API Library Reference.

1.4.3 Voice API Library

The voice API provides a collection of functions supporting call processing such as dual tone multifrequency (DTMF) detection, tone signaling, playing and recording. You may add a party to a conference using a device handle obtained from dx_open( ). You must then connect the voice device to a conference using dev_Connect( ). For more information about voice functions, see the Voice API Library Reference.

1.4.4 IP Media Library API

The IP media library (IPML) API provides a collection of functions for media control on IP devices. You may add a party to a conference using a device handle obtained from ipm_Open( ). You must then connect the IP media device to a conference using dev_Connect( ). For more information about IP media functions, see the IP Media Library API Library Reference.

1.4.5 Global Call API Library

The Global Call API provides a collection of functions supporting call control operations. You may add a party to a conference using a device handle obtained from gc_GetResourceH( ). You must then connect the device to a conference using dev_Connect( ). For more information about Global Call functions, see the Global Call API Library Reference.

1.4.6 Digital Network Interface API Library

The digital network interface API is used to manage digital network interface devices. You may add a party to a conference using a device handle obtained from dt_open( ). You must then connect the device to a conference using dev_Connect( ). For more information about digital network interface functions, see the Digital Network Interface Software Reference.

12 Conferencing API Programming Guide — August 2006

+ 26 hidden pages