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.
Contents Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 About This Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Applicability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents 8.2 8.1.1 Include Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 8.1.2 Required Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Variables for Compiling and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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.
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® Host Media Processing Software for Linux* and Windows* operating systems.
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.
Product Description 1. 1 This chapter provides an overview of the conferencing library. Topics include: • Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 • Key Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 • Understanding How Conferences are Formed. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Product Description DTMF digit detection The application can determine whether a party has generated a DTMF digit. Volume control 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.
Product Description 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: 1.4 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.
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( ).
Programming Models 2. 2 This chapter describes the programming models supported by the conferencing software. The following topics are covered: • Programming Models Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 • Asynchronous Programming Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.1 Programming Models Overview The conferencing software supports application development using asynchronous programming models.
Programming Models 14 Conferencing API Programming Guide — August 2006
Event Handling 3. 3 All conferencing events are retrieved using Standard Runtime Library (SRL) event retrieval mechanisms, including event handlers. The SRL is a device-independent library containing event management functions and Standard Attribute functions. This chapter lists SRL functions that are typically used by conferencing applications. • SRL Event Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 • SRL Standard Attribute Functions. . . . . .
Event Handling ATDV_NAMEP( ) pointer to device name ATDV_SUBDEVS( ) number of subdevices Note: 16 See the Standard Runtime Library API Library Reference for function details.
Error Handling 4. 4 This chapter describes error handling for the conferencing software. All conferencing functions return a value that indicates the success or failure of the function call. Success is indicated by a return value of CNF_SUCCESS. Failure is indicated by a value of CNF_ERROR. If a function fails, call the Standard Attribute functions ATDV_LASTERR( ) and ATDV_ERRMSGP( ) for the reason for failure. These functions are described in the Standard Runtime Library API Library Reference.
Error Handling 18 Conferencing API Programming Guide — August 2006
Application Development Guidelines 5. 5 This chapter contains guidelines for developing conferencing applications. The following topics are covered: • Using Symbolic Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 • Using Conferencing Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 • Creating a Conference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application Development Guidelines devices at once. A conference device and a party device are independent; that is, you can open a party device without first opening a conference device. 5.3 Creating a Conference The following steps describe how to create a conference. See the Glossary for information on the terms used here. See the Conferencing API Library Reference for details on conferencing functions and data structures. Note: These steps provide general guidelines.
Application Development Guidelines 11. If desired, you can specify attributes for a party using cnf_SetAttributes( ). Attributes are contained in the CNF_ATTR data structure. Use cnf_GetAttributes( ) to return the current attributes for the party. 12. Before a party can participate in a conference, you must connect this party to a supported technology device using dev_Connect( ). Examples of supported technology devices include a voice device (dxxxB1C1) and an IP device (ipmB1C1). See Section 1.
Application Development Guidelines • Even though two (or more) conferences can be bridged together, the attributes and settings of each conference remain unchanged. The application is responsible for managing each conference and conference related events separately. • The coach/pupil feature does not span conference bridges. Coach and pupil must be in the same conference. 5.5 Terminating an Application Party resources and conference resources are not released when an application terminates.
Application Development Guidelines 5.7 Multiprocessing Considerations Having multiple processes acting on the same board is undesirable. It is recommended to use a single process per board, or a single process for all boards, rather than more than one process acting on the same board. Consider the scenario where there are multiple boards in the system and each board is being controlled by a different process.
Application Development Guidelines 24 Conferencing API Programming Guide — August 2006
Using Active Talker 6. 6 This chapter provides information about the active talker feature. An active talker refers to a party in a conference who is providing “non-silence” energy. Active talkers are determined by the loudness or strength of their “non-silence” energy. 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.
Using Active Talker 26 Conferencing API Programming Guide — August 2006
Using Volume Control 7. 7 This chapter provides information about controlling the volume level in a conference. A party in a conference may wish to change the volume level of the received signal. This is accomplished using the volume control feature. The cnf_SetDTMFControl( ) function allows the application to define the DTMF digits that cause the volume level to be adjusted up, down, or back to the default.
Using Volume Control 28 Conferencing API Programming Guide — August 2006
Building Applications 8. 8 This chapter provides information on building applications using the conferencing API library. The following topics are discussed: • Compiling and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 • Variables for Compiling and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 8.
Building Applications If you use other library functions such as voice or IP media, you will have to include the header files for that library: dxxxlib.h Contains function prototypes and symbolic defines for the voice library. dtilib.h Contains function prototypes and symbolic defines for the digital network interface library. gclib.h The primary header file for the Global Call library; contains function prototypes and symbolic defines for this library. ipmerror.
Building Applications Linux In Linux, you must link the following library files in the order shown when compiling your conferencing application: libsrl.so Standard Runtime Library file. Required in all applications. Specify -lsrl in makefile. libdxxx.so the primary voice library file. Required only if the application uses voice library functions directly; for example, dx_open( ). Specify -ldxxx in makefile. libdti.so digital network interface library file.
Building Applications 32 Conferencing API Programming Guide — August 2006
Glossary active talker: A participant in a conference who is providing “non-silence” energy. automatic gain control (AGC): An electronic circuit used to maintain the audio signal volume at a constant level. AGC maintains nearly constant gain during voice signals, thereby avoiding distortion, and optimizes the perceptual quality of voice signals by using a new method to process silence intervals (background noise).
configuration file: An unformatted ASCII file that stores device initialization information for an application. configuration manager: A utility with a graphical user interface (GUI) that enables you to add new boards to your system, start and stop system service, and work with board configuration data. Also known as DCM. CT Bus: Computer Telephony bus. A time division multiplexing communications bus that provides 4096 time slots for transmission of digital information between CT Bus products. See TDM bus.
pupil: A participant in a conference that has a mentoring relationship with a coach. resource: Functionality (for example, conferencing) that can be assigned to a call. Resources are shared when functionality is selectively assigned to a call and may be shared among multiple calls. Resources are dedicated when functionality is fixed to the one call. RFU: Reserved for future use. route: Assign a resource to a time slot. SRL: See Standard Runtime Library.
tone clamping: (DTMF tone clamping) Mutes DTMF tones heard in a conference. If a confereee’s phone generates a tone, the DTMF signal will not interfere with the conference. Applies to transmitted audio into the conference and does not affect DTMF function. time division multiplexing (TDM): See TDM (Time Division Multiplexing). time slot: The smallest, switchable data unit on a TDM bus. A time slot consists of 8 consecutive bits of data. One time slot is equivalent to a data path with a bandwidth of 64 kbps.
Index A active talker enabling 25 feature description 10 asynchronous callback model, Linux 13 asynchronous mode programming Linux 13 asynchronous models Linux 13 asynchronous polled model Linux 13 asynchronous programming model 9, 20 ATDV_ERRMSGP( ) 15, 17 ATDV_LASTERR( ) 15, 17 ATDV_NAMEP( ) 16 ATDV_SUBDEVS( ) 16 automatic gain control (AGC) 10 C cnf_AddParty( ) 21 CNF_ATTR data structure 20 cnf_Close( ) 22 cnf_CloseConference( ) 22 cnf_CloseParty( ) 22 CNF_DEVICE_COUNT_INFO data structure 20 cnf_Disable
ipmlib.h 30 L libcnf.lib 30 libcnf.so 31 libdevmgmt.lib 30 libdevmgmt.so 31 libdti.so 31 libdtimt.lib 30 libdxxmt.lib 30 libdxxx.so 31 libgc.lib 30 libgc.so 31 libipm.lib 30 libipm.so 31 libsrl.so 31 libsrlmt.lib 30 linking applications 29 sr_waitevt(_) 13 sr_waitevtEx( ) 15 SRL events 13 srllib.
