← Back to branch summary

~ubuntu-branches/ubuntu/wily/sflphone/wily

« 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): Francois Marier, Francois Marier, Mark Purcell
  • Date: 2014-10-18 15:08:50 UTC
  • mfrom: (1.1.12)
  • mto: This revision was merged to the branch mainline in revision 29.
  • Revision ID: package-import@ubuntu.com-20141018150850-2exfk34ckb15pcwi
Tags: 1.4.1-0.1
http://bugs.debian.org/759576
http://bugs.debian.org/741130
[ Francois Marier ]
* Non-maintainer upload
* New upstream release (closes: #759576, #741130)
  - debian/rules +PJPROJECT_VERSION := 2.2.1
  - add upstream patch to fix broken TLS support
  - add patch to fix pjproject regression

[ Mark Purcell ]
* Build-Depends:
  - sflphone-daemon + libavformat-dev, libavcodec-dev, libswscale-dev,
  libavdevice-dev, libavutil-dev
  - sflphone-gnome + libclutter-gtk-1.0-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.1.0/pjmedia/include/pjmedia/conference.h
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