~ubuntu-branches/ubuntu/trusty/sflphone/trusty

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.1.0/pjmedia/include/pjmedia/conference.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (4.3.4 sid)
  • Revision ID: package-import@ubuntu.com-20140128182336-jrsv0k9u6cawc068
Tags: 1.3.0-1
* New upstream release 
  - Fixes "New Upstream Release" (Closes: #735846)
  - Fixes "Ringtone does not stop" (Closes: #727164)
  - Fixes "[sflphone-kde] crash on startup" (Closes: #718178)
  - Fixes "sflphone GUI crashes when call is hung up" (Closes: #736583)
* Build-Depends: ensure GnuTLS 2.6
  - libucommon-dev (>= 6.0.7-1.1), libccrtp-dev (>= 2.0.6-3)
  - Fixes "FTBFS Build-Depends libgnutls{26,28}-dev" (Closes: #722040)
* Fix "boost 1.49 is going away" unversioned Build-Depends: (Closes: #736746)
* Add Build-Depends: libsndfile-dev, nepomuk-core-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
/* $Id: conference.h 3664 2011-07-19 03:42:28Z nanang $ */
 
2
/* 
 
3
 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
 
4
 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
 
5
 *
 
6
 * This program is free software; you can redistribute it and/or modify
 
7
 * it under the terms of the GNU General Public License as published by
 
8
 * the Free Software Foundation; either version 2 of the License, or
 
9
 * (at your option) any later version.
 
10
 *
 
11
 * This program is distributed in the hope that it will be useful,
 
12
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 
13
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
14
 * GNU General Public License for more details.
 
15
 *
 
16
 * You should have received a copy of the GNU General Public License
 
17
 * along with this program; if not, write to the Free Software
 
18
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
 
19
 */
 
20
#ifndef __PJMEDIA_CONF_H__
 
21
#define __PJMEDIA_CONF_H__
 
22
 
 
23
 
 
24
/**
 
25
 * @file conference.h
 
26
 * @brief Conference bridge.
 
27
 */
 
28
#include <pjmedia/port.h>
 
29
 
 
30
/**
 
31
 * @defgroup PJMEDIA_CONF Conference Bridge
 
32
 * @ingroup PJMEDIA_PORT
 
33
 * @brief Audio conference bridge implementation
 
34
 * @{
 
35
 *
 
36
 * This describes the conference bridge implementation in PJMEDIA. The
 
37
 * conference bridge provides powerful and very efficient mechanism to
 
38
 * route the audio flow and mix the audio signal when required.
 
39
 *
 
40
 * Some more information about the media flow when conference bridge is
 
41
 * used is described in http://www.pjsip.org/trac/wiki/media-flow .
 
42
 */
 
43
 
 
44
PJ_BEGIN_DECL
 
45
 
 
46
/**
 
47
 * The conference bridge signature in pjmedia_port_info.
 
48
 */
 
49
#define PJMEDIA_CONF_BRIDGE_SIGNATURE   PJMEDIA_SIG_PORT_CONF
 
50
 
 
51
/**
 
52
 * The audio switchboard signature in pjmedia_port_info.
 
53
 */
 
54
#define PJMEDIA_CONF_SWITCH_SIGNATURE   PJMEDIA_SIG_PORT_CONF_SWITCH
 
55
 
 
56
 
 
57
/**
 
58
 * Opaque type for conference bridge.
 
59
 */
 
60
typedef struct pjmedia_conf pjmedia_conf;
 
61
 
 
62
/**
 
63
 * Conference port info.
 
64
 */
 
65
typedef struct pjmedia_conf_port_info
 
66
{
 
67
    unsigned            slot;               /**< Slot number.               */
 
68
    pj_str_t            name;               /**< Port name.                 */
 
69
    pjmedia_format      format;             /**< Format.                    */
 
70
    pjmedia_port_op     tx_setting;         /**< Transmit settings.         */
 
71
    pjmedia_port_op     rx_setting;         /**< Receive settings.          */
 
72
    unsigned            listener_cnt;       /**< Number of listeners.       */
 
73
    unsigned           *listener_slots;     /**< Array of listeners.        */
 
74
    unsigned            transmitter_cnt;    /**< Number of transmitter.     */
 
75
    unsigned            clock_rate;         /**< Clock rate of the port.    */
 
76
    unsigned            channel_count;      /**< Number of channels.        */
 
77
    unsigned            samples_per_frame;  /**< Samples per frame          */
 
78
    unsigned            bits_per_sample;    /**< Bits per sample.           */
 
79
    int                 tx_adj_level;       /**< Tx level adjustment.       */
 
80
    int                 rx_adj_level;       /**< Rx level adjustment.       */
 
81
} pjmedia_conf_port_info;
 
82
 
 
83
 
 
84
/**
 
85
 * Conference port options. The values here can be combined in bitmask to
 
86
 * be specified when the conference bridge is created.
 
87
 */
 
88
enum pjmedia_conf_option
 
89
{
 
90
    PJMEDIA_CONF_NO_MIC  = 1,   /**< Disable audio streams from the
 
91
                                     microphone device.                     */
 
92
    PJMEDIA_CONF_NO_DEVICE = 2, /**< Do not create sound device.            */
 
93
    PJMEDIA_CONF_SMALL_FILTER=4,/**< Use small filter table when resampling */
 
94
    PJMEDIA_CONF_USE_LINEAR=8   /**< Use linear resampling instead of filter
 
95
                                     based.                                 */
 
96
};
 
97
 
 
98
 
 
99
/**
 
100
 * Create conference bridge with the specified parameters. The sampling rate,
 
101
 * samples per frame, and bits per sample will be used for the internal
 
102
 * operation of the bridge (e.g. when mixing audio frames). However, ports 
 
103
 * with different configuration may be connected to the bridge. In this case,
 
104
 * the bridge is able to perform sampling rate conversion, and buffering in 
 
105
 * case the samples per frame is different.
 
106
 *
 
107
 * For this version of PJMEDIA, only 16bits per sample is supported.
 
108
 *
 
109
 * For this version of PJMEDIA, the channel count of the ports MUST match
 
110
 * the channel count of the bridge.
 
111
 *
 
112
 * Under normal operation (i.e. when PJMEDIA_CONF_NO_DEVICE option is NOT
 
113
 * specified), the bridge internally create an instance of sound device
 
114
 * and connect the sound device to port zero of the bridge. 
 
115
 *
 
116
 * If PJMEDIA_CONF_NO_DEVICE options is specified, no sound device will
 
117
 * be created in the conference bridge. Application MUST acquire the port
 
118
 * interface of the bridge by calling #pjmedia_conf_get_master_port(), and
 
119
 * connect this port interface to a sound device port by calling
 
120
 * #pjmedia_snd_port_connect(), or to a master port (pjmedia_master_port)
 
121
 * if application doesn't want to instantiate any sound devices.
 
122
 *
 
123
 * The sound device or master port are crucial for the bridge's operation, 
 
124
 * because it provides the bridge with necessary clock to process the audio
 
125
 * frames periodically. Internally, the bridge runs when get_frame() to 
 
126
 * port zero is called.
 
127
 *
 
128
 * @param pool              Pool to use to allocate the bridge and 
 
129
 *                          additional buffers for the sound device.
 
130
 * @param max_slots         Maximum number of slots/ports to be created in
 
131
 *                          the bridge. Note that the bridge internally uses
 
132
 *                          one port for the sound device, so the actual 
 
133
 *                          maximum number of ports will be less one than
 
134
 *                          this value.
 
135
 * @param sampling_rate     Set the sampling rate of the bridge. This value
 
136
 *                          is also used to set the sampling rate of the
 
137
 *                          sound device.
 
138
 * @param channel_count     Number of channels in the PCM stream. Normally
 
139
 *                          the value will be 1 for mono, but application may
 
140
 *                          specify a value of 2 for stereo. Note that all
 
141
 *                          ports that will be connected to the bridge MUST 
 
142
 *                          have the same number of channels as the bridge.
 
143
 * @param samples_per_frame Set the number of samples per frame. This value
 
144
 *                          is also used to set the sound device.
 
145
 * @param bits_per_sample   Set the number of bits per sample. This value
 
146
 *                          is also used to set the sound device. Currently
 
147
 *                          only 16bit per sample is supported.
 
148
 * @param options           Bitmask options to be set for the bridge. The
 
149
 *                          options are constructed from #pjmedia_conf_option
 
150
 *                          enumeration.
 
151
 * @param p_conf            Pointer to receive the conference bridge instance.
 
152
 *
 
153
 * @return                  PJ_SUCCESS if conference bridge can be created.
 
154
 */
 
155
PJ_DECL(pj_status_t) pjmedia_conf_create( pj_pool_t *pool,
 
156
                                          unsigned max_slots,
 
157
                                          unsigned sampling_rate,
 
158
                                          unsigned channel_count,
 
159
                                          unsigned samples_per_frame,
 
160
                                          unsigned bits_per_sample,
 
161
                                          unsigned options,
 
162
                                          pjmedia_conf **p_conf );
 
163
 
 
164
 
 
165
/**
 
166
 * Destroy conference bridge.
 
167
 *
 
168
 * @param conf              The conference bridge.
 
169
 *
 
170
 * @return                  PJ_SUCCESS on success.
 
171
 */
 
172
PJ_DECL(pj_status_t) pjmedia_conf_destroy( pjmedia_conf *conf );
 
173
 
 
174
 
 
175
/**
 
176
 * Get the master port interface of the conference bridge. The master port
 
177
 * corresponds to the port zero of the bridge. This is only usefull when 
 
178
 * application wants to manage the sound device by itself, instead of 
 
179
 * allowing the bridge to automatically create a sound device implicitly.
 
180
 *
 
181
 * This function will only return a port interface if PJMEDIA_CONF_NO_DEVICE
 
182
 * option was specified when the bridge was created.
 
183
 *
 
184
 * Application can connect the port returned by this function to a 
 
185
 * sound device by calling #pjmedia_snd_port_connect().
 
186
 *
 
187
 * @param conf              The conference bridge.
 
188
 *
 
189
 * @return                  The port interface of port zero of the bridge,
 
190
 *                          only when PJMEDIA_CONF_NO_DEVICE options was
 
191
 *                          specified when the bridge was created.
 
192
 */
 
193
PJ_DECL(pjmedia_port*) pjmedia_conf_get_master_port(pjmedia_conf *conf);
 
194
 
 
195
 
 
196
/**
 
197
 * Set master port name.
 
198
 *
 
199
 * @param conf              The conference bridge.
 
200
 * @param name              Name to be assigned.
 
201
 *
 
202
 * @return                  PJ_SUCCESS on success.
 
203
 */
 
204
PJ_DECL(pj_status_t) pjmedia_conf_set_port0_name(pjmedia_conf *conf,
 
205
                                                 const pj_str_t *name);
 
206
 
 
207
 
 
208
/**
 
209
 * Add media port to the conference bridge.
 
210
 *
 
211
 * By default, the new conference port will have both TX and RX enabled, 
 
212
 * but it is not connected to any other ports. Application SHOULD call 
 
213
 * #pjmedia_conf_connect_port() to  enable audio transmission and receipt 
 
214
 * to/from this port.
 
215
 *
 
216
 * Once the media port is connected to other port(s) in the bridge,
 
217
 * the bridge will continuosly call get_frame() and put_frame() to the
 
218
 * port, allowing media to flow to/from the port.
 
219
 *
 
220
 * @param conf          The conference bridge.
 
221
 * @param pool          Pool to allocate buffers for this port.
 
222
 * @param strm_port     Stream port interface.
 
223
 * @param name          Optional name for the port. If this value is NULL,
 
224
 *                      the name will be taken from the name in the port 
 
225
 *                      info.
 
226
 * @param p_slot        Pointer to receive the slot index of the port in
 
227
 *                      the conference bridge.
 
228
 *
 
229
 * @return              PJ_SUCCESS on success.
 
230
 */
 
231
PJ_DECL(pj_status_t) pjmedia_conf_add_port( pjmedia_conf *conf,
 
232
                                            pj_pool_t *pool,
 
233
                                            pjmedia_port *strm_port,
 
234
                                            const pj_str_t *name,
 
235
                                            unsigned *p_slot );
 
236
 
 
237
 
 
238
/**
 
239
 * <i><b>Warning:</b> This API has been deprecated since 1.3 and will be
 
240
 * removed in the future release, use @ref PJMEDIA_SPLITCOMB instead.</i>
 
241
 *
 
242
 * Create and add a passive media port to the conference bridge. Unlike
 
243
 * "normal" media port that is added with #pjmedia_conf_add_port(), media
 
244
 * port created with this function will not have its get_frame() and
 
245
 * put_frame() called by the bridge; instead, application MUST continuosly
 
246
 * call these functions to the port, to allow media to flow from/to the
 
247
 * port.
 
248
 *
 
249
 * Upon return of this function, application will be given two objects:
 
250
 * the slot number of the port in the bridge, and pointer to the media
 
251
 * port where application MUST start calling get_frame() and put_frame()
 
252
 * to the port.
 
253
 *
 
254
 * @param conf              The conference bridge.
 
255
 * @param pool              Pool to allocate buffers etc for this port.
 
256
 * @param name              Name to be assigned to the port.
 
257
 * @param clock_rate        Clock rate/sampling rate.
 
258
 * @param channel_count     Number of channels.
 
259
 * @param samples_per_frame Number of samples per frame.
 
260
 * @param bits_per_sample   Number of bits per sample.
 
261
 * @param options           Options (should be zero at the moment).
 
262
 * @param p_slot            Pointer to receive the slot index of the port in
 
263
 *                          the conference bridge.
 
264
 * @param p_port            Pointer to receive the port instance.
 
265
 *
 
266
 * @return                  PJ_SUCCESS on success, or the appropriate error 
 
267
 *                          code.
 
268
 */
 
269
PJ_DECL(pj_status_t) pjmedia_conf_add_passive_port( pjmedia_conf *conf,
 
270
                                                    pj_pool_t *pool,
 
271
                                                    const pj_str_t *name,
 
272
                                                    unsigned clock_rate,
 
273
                                                    unsigned channel_count,
 
274
                                                    unsigned samples_per_frame,
 
275
                                                    unsigned bits_per_sample,
 
276
                                                    unsigned options,
 
277
                                                    unsigned *p_slot,
 
278
                                                    pjmedia_port **p_port );
 
279
 
 
280
 
 
281
/**
 
282
 * Change TX and RX settings for the port.
 
283
 *
 
284
 * @param conf          The conference bridge.
 
285
 * @param slot          Port number/slot in the conference bridge.
 
286
 * @param tx            Settings for the transmission TO this port.
 
287
 * @param rx            Settings for the receipt FROM this port.
 
288
 *
 
289
 * @return              PJ_SUCCESS on success.
 
290
 */
 
291
PJ_DECL(pj_status_t) pjmedia_conf_configure_port( pjmedia_conf *conf,
 
292
                                                  unsigned slot,
 
293
                                                  pjmedia_port_op tx,
 
294
                                                  pjmedia_port_op rx);
 
295
 
 
296
 
 
297
/**
 
298
 * Enable unidirectional audio from the specified source slot to the
 
299
 * specified sink slot.
 
300
 *
 
301
 * @param conf          The conference bridge.
 
302
 * @param src_slot      Source slot.
 
303
 * @param sink_slot     Sink slot.
 
304
 * @param level         This argument is reserved for future improvements
 
305
 *                      where it is possible to adjust the level of signal
 
306
 *                      transmitted in a specific connection. For now,
 
307
 *                      this argument MUST be zero.
 
308
 *
 
309
 * @return              PJ_SUCCES on success.
 
310
 */
 
311
PJ_DECL(pj_status_t) pjmedia_conf_connect_port( pjmedia_conf *conf,
 
312
                                                unsigned src_slot,
 
313
                                                unsigned sink_slot,
 
314
                                                int level );
 
315
 
 
316
 
 
317
/**
 
318
 * Disconnect unidirectional audio from the specified source to the specified
 
319
 * sink slot.
 
320
 *
 
321
 * @param conf          The conference bridge.
 
322
 * @param src_slot      Source slot.
 
323
 * @param sink_slot     Sink slot.
 
324
 *
 
325
 * @return              PJ_SUCCESS on success.
 
326
 */
 
327
PJ_DECL(pj_status_t) pjmedia_conf_disconnect_port( pjmedia_conf *conf,
 
328
                                                   unsigned src_slot,
 
329
                                                   unsigned sink_slot );
 
330
 
 
331
 
 
332
/**
 
333
 * Get number of ports currently registered to the conference bridge.
 
334
 *
 
335
 * @param conf          The conference bridge.
 
336
 *
 
337
 * @return              Number of ports currently registered to the conference
 
338
 *                      bridge.
 
339
 */
 
340
PJ_DECL(unsigned) pjmedia_conf_get_port_count(pjmedia_conf *conf);
 
341
 
 
342
 
 
343
/**
 
344
 * Get total number of ports connections currently set up in the bridge.
 
345
 * 
 
346
 * @param conf          The conference bridge.
 
347
 *
 
348
 * @return              PJ_SUCCESS on success.
 
349
 */
 
350
PJ_DECL(unsigned) pjmedia_conf_get_connect_count(pjmedia_conf *conf);
 
351
 
 
352
 
 
353
/**
 
354
 * Remove the specified port from the conference bridge.
 
355
 *
 
356
 * @param conf          The conference bridge.
 
357
 * @param slot          The port index to be removed.
 
358
 *
 
359
 * @return              PJ_SUCCESS on success.
 
360
 */
 
361
PJ_DECL(pj_status_t) pjmedia_conf_remove_port( pjmedia_conf *conf,
 
362
                                               unsigned slot );
 
363
 
 
364
 
 
365
 
 
366
/**
 
367
 * Enumerate occupied ports in the bridge.
 
368
 *
 
369
 * @param conf          The conference bridge.
 
370
 * @param ports         Array of port numbers to be filled in.
 
371
 * @param count         On input, specifies the maximum number of ports
 
372
 *                      in the array. On return, it will be filled with
 
373
 *                      the actual number of ports.
 
374
 *
 
375
 * @return              PJ_SUCCESS on success.
 
376
 */
 
377
PJ_DECL(pj_status_t) pjmedia_conf_enum_ports( pjmedia_conf *conf,
 
378
                                              unsigned ports[],
 
379
                                              unsigned *count );
 
380
 
 
381
 
 
382
/**
 
383
 * Get port info.
 
384
 *
 
385
 * @param conf          The conference bridge.
 
386
 * @param slot          Port index.
 
387
 * @param info          Pointer to receive the info.
 
388
 *
 
389
 * @return              PJ_SUCCESS on success.
 
390
 */
 
391
PJ_DECL(pj_status_t) pjmedia_conf_get_port_info( pjmedia_conf *conf,
 
392
                                                 unsigned slot,
 
393
                                                 pjmedia_conf_port_info *info);
 
394
 
 
395
 
 
396
/**
 
397
 * Get occupied ports info.
 
398
 *
 
399
 * @param conf          The conference bridge.
 
400
 * @param size          On input, contains maximum number of infos
 
401
 *                      to be retrieved. On output, contains the actual
 
402
 *                      number of infos that have been copied.
 
403
 * @param info          Array of info.
 
404
 *
 
405
 * @return              PJ_SUCCESS on success.
 
406
 */
 
407
PJ_DECL(pj_status_t) pjmedia_conf_get_ports_info(pjmedia_conf *conf,
 
408
                                                 unsigned *size,
 
409
                                                 pjmedia_conf_port_info info[]
 
410
                                                 );
 
411
 
 
412
 
 
413
/**
 
414
 * Get last signal level transmitted to or received from the specified port.
 
415
 * This will retrieve the "real-time" signal level of the audio as they are
 
416
 * transmitted or received by the specified port. Application may call this
 
417
 * function periodically to display the signal level to a VU meter.
 
418
 *
 
419
 * The signal level is an integer value in zero to 255, with zero indicates
 
420
 * no signal, and 255 indicates the loudest signal level.
 
421
 *
 
422
 * @param conf          The conference bridge.
 
423
 * @param slot          Slot number.
 
424
 * @param tx_level      Optional argument to receive the level of signal
 
425
 *                      transmitted to the specified port (i.e. the direction
 
426
 *                      is from the bridge to the port).
 
427
 * @param rx_level      Optional argument to receive the level of signal
 
428
 *                      received from the port (i.e. the direction is from the
 
429
 *                      port to the bridge).
 
430
 *
 
431
 * @return              PJ_SUCCESS on success.
 
432
 */
 
433
PJ_DECL(pj_status_t) pjmedia_conf_get_signal_level(pjmedia_conf *conf,
 
434
                                                   unsigned slot,
 
435
                                                   unsigned *tx_level,
 
436
                                                   unsigned *rx_level);
 
437
 
 
438
 
 
439
/**
 
440
 * Adjust the level of signal received from the specified port.
 
441
 * Application may adjust the level to make signal received from the port
 
442
 * either louder or more quiet. The level adjustment is calculated with this
 
443
 * formula: <b><tt>output = input * (adj_level+128) / 128</tt></b>. Using 
 
444
 * this, zero indicates no adjustment, the value -128 will mute the signal, 
 
445
 * and the value of +128 will make the signal 100% louder, +256 will make it
 
446
 * 200% louder, etc.
 
447
 *
 
448
 * The level adjustment value will stay with the port until the port is
 
449
 * removed from the bridge or new adjustment value is set. The current
 
450
 * level adjustment value is reported in the media port info when
 
451
 * the #pjmedia_conf_get_port_info() function is called.
 
452
 *
 
453
 * @param conf          The conference bridge.
 
454
 * @param slot          Slot number of the port.
 
455
 * @param adj_level     Adjustment level, which must be greater than or equal
 
456
 *                      to -128. A value of zero means there is no level
 
457
 *                      adjustment to be made, the value -128 will mute the 
 
458
 *                      signal, and the value of +128 will make the signal 
 
459
 *                      100% louder, +256 will make it 200% louder, etc. 
 
460
 *                      See the function description for the formula.
 
461
 *
 
462
 * @return              PJ_SUCCESS on success.
 
463
 */
 
464
PJ_DECL(pj_status_t) pjmedia_conf_adjust_rx_level( pjmedia_conf *conf,
 
465
                                                   unsigned slot,
 
466
                                                   int adj_level );
 
467
 
 
468
 
 
469
/**
 
470
 * Adjust the level of signal to be transmitted to the specified port.
 
471
 * Application may adjust the level to make signal transmitted to the port
 
472
 * either louder or more quiet. The level adjustment is calculated with this
 
473
 * formula: <b><tt>output = input * (adj_level+128) / 128</tt></b>. Using 
 
474
 * this, zero indicates no adjustment, the value -128 will mute the signal, 
 
475
 * and the value of +128 will make the signal 100% louder, +256 will make it
 
476
 * 200% louder, etc.
 
477
 *
 
478
 * The level adjustment value will stay with the port until the port is
 
479
 * removed from the bridge or new adjustment value is set. The current
 
480
 * level adjustment value is reported in the media port info when
 
481
 * the #pjmedia_conf_get_port_info() function is called.
 
482
 *
 
483
 * @param conf          The conference bridge.
 
484
 * @param slot          Slot number of the port.
 
485
 * @param adj_level     Adjustment level, which must be greater than or equal
 
486
 *                      to -128. A value of zero means there is no level
 
487
 *                      adjustment to be made, the value -128 will mute the 
 
488
 *                      signal, and the value of +128 will make the signal 
 
489
 *                      100% louder, +256 will make it 200% louder, etc. 
 
490
 *                      See the function description for the formula.
 
491
 *
 
492
 * @return              PJ_SUCCESS on success.
 
493
 */
 
494
PJ_DECL(pj_status_t) pjmedia_conf_adjust_tx_level( pjmedia_conf *conf,
 
495
                                                   unsigned slot,
 
496
                                                   int adj_level );
 
497
 
 
498
 
 
499
 
 
500
PJ_END_DECL
 
501
 
 
502
 
 
503
/**
 
504
 * @}
 
505
 */
 
506
 
 
507
 
 
508
#endif  /* __PJMEDIA_CONF_H__ */
 
509