← 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-audiodev/audiodev.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (1.1.11)
  • mto: This revision was merged to the branch mainline in revision 24.
  • Revision ID: package-import@ubuntu.com-20140128182336-3xenud1kbnwmf3mz
http://bugs.debian.org/735846
http://bugs.debian.org/727164
http://bugs.debian.org/718178
http://bugs.debian.org/736583
http://bugs.debian.org/722040
http://bugs.debian.org/736746
* 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:
daemon/libs/pjproject-2.1.0/pjmedia/include/pjmedia-audiodev/audiodev.h
 
1
/* $Id: audiodev.h 4243 2012-08-31 11:42:17Z 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_AUDIODEV_AUDIODEV_H__
 
21
#define __PJMEDIA_AUDIODEV_AUDIODEV_H__
 
22
 
 
23
/**
 
24
 * @file audiodev.h
 
25
 * @brief Audio device API.
 
26
 */
 
27
#include <pjmedia-audiodev/config.h>
 
28
#include <pjmedia-audiodev/errno.h>
 
29
#include <pjmedia/format.h>
 
30
#include <pjmedia/frame.h>
 
31
#include <pjmedia/types.h>
 
32
#include <pj/pool.h>
 
33
 
 
34
 
 
35
PJ_BEGIN_DECL
 
36
 
 
37
/**
 
38
 * @defgroup s2_audio_device_reference Audio Device API Reference
 
39
 * @ingroup audio_device_api
 
40
 * @brief API Reference
 
41
 * @{
 
42
 */
 
43
 
 
44
/**
 
45
 * Type for device index.
 
46
 */
 
47
typedef pj_int32_t pjmedia_aud_dev_index;
 
48
 
 
49
/**
 
50
 * Device index constants.
 
51
 */
 
52
enum
 
53
{
 
54
    /** 
 
55
     * Constant to denote default capture device 
 
56
     */
 
57
    PJMEDIA_AUD_DEFAULT_CAPTURE_DEV = -1,
 
58
 
 
59
    /** 
 
60
     * Constant to denote default playback device 
 
61
     */
 
62
    PJMEDIA_AUD_DEFAULT_PLAYBACK_DEV = -2,
 
63
 
 
64
    /**
 
65
     * Constant to denote invalid device index.
 
66
     */
 
67
    PJMEDIA_AUD_INVALID_DEV = -3
 
68
};
 
69
 
 
70
 
 
71
/**
 
72
 * This enumeration identifies various audio device capabilities. These audio
 
73
 * capabilities indicates what features are supported by the underlying
 
74
 * audio device implementation.
 
75
 *
 
76
 * Applications get these capabilities in the #pjmedia_aud_dev_info structure.
 
77
 *
 
78
 * Application can also set the specific features/capabilities when opening
 
79
 * the audio stream by setting the \a flags member of #pjmedia_aud_param
 
80
 * structure.
 
81
 *
 
82
 * Once audio stream is running, application can also retrieve or set some
 
83
 * specific audio capability, by using #pjmedia_aud_stream_get_cap() and
 
84
 * #pjmedia_aud_stream_set_cap() and specifying the desired capability. The
 
85
 * value of the capability is specified as pointer, and application needs to
 
86
 * supply the pointer with the correct value, according to the documentation
 
87
 * of each of the capability.
 
88
 */
 
89
typedef enum pjmedia_aud_dev_cap
 
90
{
 
91
    /** 
 
92
     * Support for audio formats other than PCM. The value of this capability
 
93
     * is represented by #pjmedia_format structure.
 
94
     */
 
95
    PJMEDIA_AUD_DEV_CAP_EXT_FORMAT = 1,
 
96
 
 
97
    /** 
 
98
     * Support for audio input latency control or query. The value of this 
 
99
     * capability is an unsigned integer containing milliseconds value of
 
100
     * the latency.
 
101
     */
 
102
    PJMEDIA_AUD_DEV_CAP_INPUT_LATENCY = 2,
 
103
 
 
104
    /** 
 
105
     * Support for audio output latency control or query. The value of this 
 
106
     * capability is an unsigned integer containing milliseconds value of
 
107
     * the latency.
 
108
     */
 
109
    PJMEDIA_AUD_DEV_CAP_OUTPUT_LATENCY = 4,
 
110
 
 
111
    /** 
 
112
     * Support for setting/retrieving the audio input device volume level.
 
113
     * The value of this capability is an unsigned integer representing 
 
114
     * the input audio volume setting in percent.
 
115
     */
 
116
    PJMEDIA_AUD_DEV_CAP_INPUT_VOLUME_SETTING = 8,
 
117
 
 
118
    /** 
 
119
     * Support for setting/retrieving the audio output device volume level.
 
120
     * The value of this capability is an unsigned integer representing 
 
121
     * the output audio volume setting in percent.
 
122
     */
 
123
    PJMEDIA_AUD_DEV_CAP_OUTPUT_VOLUME_SETTING = 16,
 
124
 
 
125
    /** 
 
126
     * Support for monitoring the current audio input signal volume. 
 
127
     * The value of this capability is an unsigned integer representing 
 
128
     * the audio volume in percent.
 
129
     */
 
130
    PJMEDIA_AUD_DEV_CAP_INPUT_SIGNAL_METER = 32,
 
131
 
 
132
    /** 
 
133
     * Support for monitoring the current audio output signal volume. 
 
134
     * The value of this capability is an unsigned integer representing 
 
135
     * the audio volume in percent.
 
136
     */
 
137
    PJMEDIA_AUD_DEV_CAP_OUTPUT_SIGNAL_METER = 64,
 
138
 
 
139
    /** 
 
140
     * Support for audio input routing. The value of this capability is an 
 
141
     * integer containing #pjmedia_aud_dev_route enumeration.
 
142
     */
 
143
    PJMEDIA_AUD_DEV_CAP_INPUT_ROUTE = 128,
 
144
 
 
145
    /** 
 
146
     * Support for audio output routing (e.g. loudspeaker vs earpiece). The
 
147
     * value of this capability is an integer containing #pjmedia_aud_dev_route
 
148
     * enumeration.
 
149
     */
 
150
    PJMEDIA_AUD_DEV_CAP_OUTPUT_ROUTE = 256,
 
151
 
 
152
    /** 
 
153
     * The audio device has echo cancellation feature. The value of this
 
154
     * capability is a pj_bool_t containing boolean PJ_TRUE or PJ_FALSE.
 
155
     */
 
156
    PJMEDIA_AUD_DEV_CAP_EC = 512,
 
157
 
 
158
    /** 
 
159
     * The audio device supports setting echo cancellation fail length. The
 
160
     * value of this capability is an unsigned integer representing the
 
161
     * echo tail in milliseconds.
 
162
     */
 
163
    PJMEDIA_AUD_DEV_CAP_EC_TAIL = 1024,
 
164
 
 
165
    /** 
 
166
     * The audio device has voice activity detection feature. The value
 
167
     * of this capability is a pj_bool_t containing boolean PJ_TRUE or 
 
168
     * PJ_FALSE.
 
169
     */
 
170
    PJMEDIA_AUD_DEV_CAP_VAD = 2048,
 
171
 
 
172
    /** 
 
173
     * The audio device has comfort noise generation feature. The value
 
174
     * of this capability is a pj_bool_t containing boolean PJ_TRUE or 
 
175
     * PJ_FALSE.
 
176
     */
 
177
    PJMEDIA_AUD_DEV_CAP_CNG = 4096,
 
178
 
 
179
    /** 
 
180
     * The audio device has packet loss concealment feature. The value
 
181
     * of this capability is a pj_bool_t containing boolean PJ_TRUE or 
 
182
     * PJ_FALSE.
 
183
     */
 
184
    PJMEDIA_AUD_DEV_CAP_PLC = 8192,
 
185
    
 
186
    /**
 
187
     * End of capability
 
188
     */
 
189
    PJMEDIA_AUD_DEV_CAP_MAX = 16384
 
190
 
 
191
} pjmedia_aud_dev_cap;
 
192
 
 
193
 
 
194
/**
 
195
 * This enumeration describes audio routing setting.
 
196
 */
 
197
typedef enum pjmedia_aud_dev_route
 
198
{
 
199
    /** Default route. */
 
200
    PJMEDIA_AUD_DEV_ROUTE_DEFAULT = 0,
 
201
 
 
202
    /** Route to loudspeaker */
 
203
    PJMEDIA_AUD_DEV_ROUTE_LOUDSPEAKER = 1,
 
204
 
 
205
    /** Route to earpiece */
 
206
    PJMEDIA_AUD_DEV_ROUTE_EARPIECE = 2,
 
207
 
 
208
    /** Route to paired Bluetooth device */
 
209
    PJMEDIA_AUD_DEV_ROUTE_BLUETOOTH = 4
 
210
 
 
211
} pjmedia_aud_dev_route;
 
212
 
 
213
 
 
214
/**
 
215
 * Device information structure returned by #pjmedia_aud_dev_get_info().
 
216
 */
 
217
typedef struct pjmedia_aud_dev_info
 
218
{
 
219
    /** 
 
220
     * The device name 
 
221
     */
 
222
    char name[64];
 
223
 
 
224
    /** 
 
225
     * Maximum number of input channels supported by this device. If the
 
226
     * value is zero, the device does not support input operation (i.e.
 
227
     * it is a playback only device). 
 
228
     */
 
229
    unsigned input_count;
 
230
 
 
231
    /** 
 
232
     * Maximum number of output channels supported by this device. If the
 
233
     * value is zero, the device does not support output operation (i.e. 
 
234
     * it is an input only device).
 
235
     */
 
236
    unsigned output_count;
 
237
 
 
238
    /** 
 
239
     * Default sampling rate.
 
240
     */
 
241
    unsigned default_samples_per_sec;
 
242
 
 
243
    /** 
 
244
     * The underlying driver name 
 
245
     */
 
246
    char driver[32];
 
247
 
 
248
    /** 
 
249
     * Device capabilities, as bitmask combination of #pjmedia_aud_dev_cap.
 
250
     */
 
251
    unsigned caps;
 
252
 
 
253
    /** 
 
254
     * Supported audio device routes, as bitmask combination of 
 
255
     * #pjmedia_aud_dev_route. The value may be zero if the device
 
256
     * does not support audio routing.
 
257
     */
 
258
    unsigned routes;
 
259
 
 
260
    /** 
 
261
     * Number of audio formats supported by this device. The value may be
 
262
     * zero if the device does not support non-PCM format.
 
263
     */
 
264
    unsigned ext_fmt_cnt;
 
265
 
 
266
    /** 
 
267
     * Array of supported extended audio formats 
 
268
     */
 
269
    pjmedia_format ext_fmt[8];
 
270
 
 
271
 
 
272
} pjmedia_aud_dev_info;
 
273
 
 
274
 
 
275
/** 
 
276
 * This callback is called by player stream when it needs additional data
 
277
 * to be played by the device. Application must fill in the whole of output 
 
278
 * buffer with audio samples.
 
279
 *
 
280
 * The frame argument contains the following values:
 
281
 *  - timestamp     Playback timestamp, in samples.
 
282
 *  - buf           Buffer to be filled out by application.
 
283
 *  - size          The size requested in bytes, which will be equal to
 
284
 *                  the size of one whole packet.
 
285
 *
 
286
 * @param user_data User data associated with the stream.
 
287
 * @param frame     Audio frame, which buffer is to be filled in by
 
288
 *                  the application.
 
289
 *
 
290
 * @return          Returning non-PJ_SUCCESS will cause the audio stream
 
291
 *                  to stop
 
292
 */
 
293
typedef pj_status_t (*pjmedia_aud_play_cb)(void *user_data,
 
294
                                           pjmedia_frame *frame);
 
295
 
 
296
/**
 
297
 * This callback is called by recorder stream when it has captured the whole
 
298
 * packet worth of audio samples.
 
299
 *
 
300
 * @param user_data User data associated with the stream.
 
301
 * @param frame     Captured frame.
 
302
 *
 
303
 * @return          Returning non-PJ_SUCCESS will cause the audio stream
 
304
 *                  to stop
 
305
 */
 
306
typedef pj_status_t (*pjmedia_aud_rec_cb)(void *user_data,
 
307
                                          pjmedia_frame *frame);
 
308
 
 
309
/**
 
310
 * This structure specifies the parameters to open the audio stream.
 
311
 */
 
312
typedef struct pjmedia_aud_param
 
313
{
 
314
    /**
 
315
     * The audio direction. This setting is mandatory.
 
316
     */
 
317
    pjmedia_dir dir;
 
318
 
 
319
    /**
 
320
     * The audio recorder device ID. This setting is mandatory if the audio
 
321
     * direction includes input/capture direction.
 
322
     */
 
323
    pjmedia_aud_dev_index rec_id;
 
324
 
 
325
    /**
 
326
     * The audio playback device ID. This setting is mandatory if the audio
 
327
     * direction includes output/playback direction.
 
328
     */
 
329
    pjmedia_aud_dev_index play_id;
 
330
 
 
331
    /** 
 
332
     * Clock rate/sampling rate. This setting is mandatory. 
 
333
     */
 
334
    unsigned clock_rate;
 
335
 
 
336
    /** 
 
337
     * Number of channels. This setting is mandatory. 
 
338
     */
 
339
    unsigned channel_count;
 
340
 
 
341
    /** 
 
342
     * Number of samples per frame. This setting is mandatory. 
 
343
     */
 
344
    unsigned samples_per_frame;
 
345
 
 
346
    /** 
 
347
     * Number of bits per sample. This setting is mandatory. 
 
348
     */
 
349
    unsigned bits_per_sample;
 
350
 
 
351
    /** 
 
352
     * This flags specifies which of the optional settings are valid in this
 
353
     * structure. The flags is bitmask combination of pjmedia_aud_dev_cap.
 
354
     */
 
355
    unsigned flags;
 
356
 
 
357
    /** 
 
358
     * Set the audio format. This setting is optional, and will only be used
 
359
     * if PJMEDIA_AUD_DEV_CAP_EXT_FORMAT is set in the flags.
 
360
     */
 
361
    pjmedia_format ext_fmt;
 
362
 
 
363
    /**
 
364
     * Input latency, in milliseconds. This setting is optional, and will 
 
365
     * only be used if PJMEDIA_AUD_DEV_CAP_INPUT_LATENCY is set in the flags.
 
366
     */
 
367
    unsigned input_latency_ms;
 
368
 
 
369
    /**
 
370
     * Input latency, in milliseconds. This setting is optional, and will 
 
371
     * only be used if PJMEDIA_AUD_DEV_CAP_OUTPUT_LATENCY is set in the flags.
 
372
     */
 
373
    unsigned output_latency_ms;
 
374
 
 
375
    /**
 
376
     * Input volume setting, in percent. This setting is optional, and will 
 
377
     * only be used if PJMEDIA_AUD_DEV_CAP_INPUT_VOLUME_SETTING is set in 
 
378
     * the flags.
 
379
     */
 
380
    unsigned input_vol;
 
381
 
 
382
    /**
 
383
     * Output volume setting, in percent. This setting is optional, and will 
 
384
     * only be used if PJMEDIA_AUD_DEV_CAP_OUTPUT_VOLUME_SETTING is set in 
 
385
     * the flags.
 
386
     */
 
387
    unsigned output_vol;
 
388
 
 
389
    /** 
 
390
     * Set the audio input route. This setting is optional, and will only be
 
391
     * used if PJMEDIA_AUD_DEV_CAP_INPUT_ROUTE is set in the flags.
 
392
     */
 
393
    pjmedia_aud_dev_route input_route;
 
394
 
 
395
    /** 
 
396
     * Set the audio output route. This setting is optional, and will only be
 
397
     * used if PJMEDIA_AUD_DEV_CAP_OUTPUT_ROUTE is set in the flags.
 
398
     */
 
399
    pjmedia_aud_dev_route output_route;
 
400
 
 
401
    /**
 
402
     * Enable/disable echo canceller, if the device supports it. This setting
 
403
     * is optional, and will only be used if PJMEDIA_AUD_DEV_CAP_EC is set in
 
404
     * the flags.
 
405
     */
 
406
    pj_bool_t ec_enabled;
 
407
 
 
408
    /**
 
409
     * Set echo canceller tail length in milliseconds, if the device supports
 
410
     * it. This setting is optional, and will only be used if
 
411
     * PJMEDIA_AUD_DEV_CAP_EC_TAIL is set in the flags.
 
412
     */
 
413
    unsigned ec_tail_ms;
 
414
 
 
415
    /** 
 
416
     * Enable/disable PLC. This setting is optional, and will only be used
 
417
     * if PJMEDIA_AUD_DEV_CAP_PLC is set in the flags.
 
418
     */
 
419
    pj_bool_t plc_enabled;
 
420
 
 
421
    /** 
 
422
     * Enable/disable CNG. This setting is optional, and will only be used
 
423
     * if PJMEDIA_AUD_DEV_CAP_CNG is set in the flags.
 
424
     */
 
425
    pj_bool_t cng_enabled;
 
426
 
 
427
    /** 
 
428
     * Enable/disable VAD. This setting is optional, and will only be used
 
429
     * if PJMEDIA_AUD_DEV_CAP_VAD is set in the flags.
 
430
     */
 
431
    pj_bool_t vad_enabled;
 
432
 
 
433
} pjmedia_aud_param;
 
434
 
 
435
 
 
436
/** Forward declaration for pjmedia_aud_stream */
 
437
typedef struct pjmedia_aud_stream pjmedia_aud_stream;
 
438
 
 
439
/** Forward declaration for audio device factory */
 
440
typedef struct pjmedia_aud_dev_factory pjmedia_aud_dev_factory;
 
441
 
 
442
/* typedef for factory creation function */
 
443
typedef pjmedia_aud_dev_factory*
 
444
(*pjmedia_aud_dev_factory_create_func_ptr)(pj_pool_factory*);
 
445
 
 
446
 
 
447
/**
 
448
 * Get string info for the specified capability.
 
449
 *
 
450
 * @param cap           The capability ID.
 
451
 * @param p_desc        Optional pointer which will be filled with longer 
 
452
 *                      description about the capability.
 
453
 *
 
454
 * @return              Capability name.
 
455
 */
 
456
PJ_DECL(const char*) pjmedia_aud_dev_cap_name(pjmedia_aud_dev_cap cap,
 
457
                                              const char **p_desc);
 
458
 
 
459
 
 
460
/**
 
461
 * Set a capability field value in #pjmedia_aud_param structure. This will
 
462
 * also set the flags field for the specified capability in the structure.
 
463
 *
 
464
 * @param param         The structure.
 
465
 * @param cap           The audio capability which value is to be set.
 
466
 * @param pval          Pointer to value. Please see the type of value to
 
467
 *                      be supplied in the pjmedia_aud_dev_cap documentation.
 
468
 *
 
469
 * @return              PJ_SUCCESS on successful operation or the appropriate
 
470
 *                      error code.
 
471
 */
 
472
PJ_DECL(pj_status_t) pjmedia_aud_param_set_cap(pjmedia_aud_param *param,
 
473
                                               pjmedia_aud_dev_cap cap,
 
474
                                               const void *pval);
 
475
 
 
476
 
 
477
/**
 
478
 * Get a capability field value from #pjmedia_aud_param structure. This
 
479
 * function will return PJMEDIA_EAUD_INVCAP error if the flag for that
 
480
 * capability is not set in the flags field in the structure.
 
481
 *
 
482
 * @param param         The structure.
 
483
 * @param cap           The audio capability which value is to be retrieved.
 
484
 * @param pval          Pointer to value. Please see the type of value to
 
485
 *                      be supplied in the pjmedia_aud_dev_cap documentation.
 
486
 *
 
487
 * @return              PJ_SUCCESS on successful operation or the appropriate
 
488
 *                      error code.
 
489
 */
 
490
PJ_DECL(pj_status_t) pjmedia_aud_param_get_cap(const pjmedia_aud_param *param,
 
491
                                               pjmedia_aud_dev_cap cap,
 
492
                                               void *pval);
 
493
 
 
494
/**
 
495
 * Initialize the audio subsystem. This will register all supported audio 
 
496
 * device factories to the audio subsystem. This function may be called
 
497
 * more than once, but each call to this function must have the
 
498
 * corresponding #pjmedia_aud_subsys_shutdown() call.
 
499
 *
 
500
 * @param pf            The pool factory.
 
501
 *
 
502
 * @return              PJ_SUCCESS on successful operation or the appropriate
 
503
 *                      error code.
 
504
 */
 
505
PJ_DECL(pj_status_t) pjmedia_aud_subsys_init(pj_pool_factory *pf);
 
506
 
 
507
 
 
508
/**
 
509
 * Get the pool factory registered to the audio subsystem.
 
510
 *
 
511
 * @return              The pool factory.
 
512
 */
 
513
PJ_DECL(pj_pool_factory*) pjmedia_aud_subsys_get_pool_factory(void);
 
514
 
 
515
 
 
516
/**
 
517
 * Shutdown the audio subsystem. This will destroy all audio device factories
 
518
 * registered in the audio subsystem. Note that currently opened audio streams
 
519
 * may or may not be closed, depending on the implementation of the audio
 
520
 * device factories.
 
521
 *
 
522
 * @return              PJ_SUCCESS on successful operation or the appropriate
 
523
 *                      error code.
 
524
 */
 
525
PJ_DECL(pj_status_t) pjmedia_aud_subsys_shutdown(void);
 
526
 
 
527
 
 
528
/**
 
529
 * Register a supported audio device factory to the audio subsystem. This
 
530
 * function can only be called after calling #pjmedia_aud_subsys_init().
 
531
 *
 
532
 * @param adf           The audio device factory.
 
533
 *
 
534
 * @return              PJ_SUCCESS on successful operation or the appropriate
 
535
 *                      error code.
 
536
 */
 
537
PJ_DECL(pj_status_t)
 
538
pjmedia_aud_register_factory(pjmedia_aud_dev_factory_create_func_ptr adf);
 
539
 
 
540
 
 
541
/**
 
542
 * Unregister an audio device factory from the audio subsystem. This
 
543
 * function can only be called after calling #pjmedia_aud_subsys_init().
 
544
 * Devices from this factory will be unlisted. If a device from this factory
 
545
 * is currently in use, then the behavior is undefined.
 
546
 *
 
547
 * @param adf           The audio device factory.
 
548
 *
 
549
 * @return              PJ_SUCCESS on successful operation or the appropriate
 
550
 *                      error code.
 
551
 */
 
552
PJ_DECL(pj_status_t)
 
553
pjmedia_aud_unregister_factory(pjmedia_aud_dev_factory_create_func_ptr adf);
 
554
 
 
555
 
 
556
/**
 
557
 * Refresh the list of sound devices installed in the system. This function
 
558
 * will only refresh the list of audio device so all active audio streams will
 
559
 * be unaffected. After refreshing the device list, application MUST make sure
 
560
 * to update all index references to audio devices (i.e. all variables of type
 
561
 * pjmedia_aud_dev_index) before calling any function that accepts audio device
 
562
 * index as its parameter.
 
563
 *
 
564
 * @return              PJ_SUCCESS on successful operation or the appropriate
 
565
 *                      error code.
 
566
 */
 
567
PJ_DECL(pj_status_t) pjmedia_aud_dev_refresh(void);
 
568
 
 
569
 
 
570
/**
 
571
 * Get the number of sound devices installed in the system.
 
572
 *
 
573
 * @return              The number of sound devices installed in the system.
 
574
 */
 
575
PJ_DECL(unsigned) pjmedia_aud_dev_count(void);
 
576
 
 
577
 
 
578
/**
 
579
 * Get device information.
 
580
 *
 
581
 * @param id            The audio device ID.
 
582
 * @param info          The device information which will be filled in by this
 
583
 *                      function once it returns successfully.
 
584
 *
 
585
 * @return              PJ_SUCCESS on successful operation or the appropriate
 
586
 *                      error code.
 
587
 */
 
588
PJ_DECL(pj_status_t) pjmedia_aud_dev_get_info(pjmedia_aud_dev_index id,
 
589
                                              pjmedia_aud_dev_info *info);
 
590
 
 
591
 
 
592
/**
 
593
 * Lookup device index based on the driver and device name.
 
594
 *
 
595
 * @param drv_name      The driver name.
 
596
 * @param dev_name      The device name.
 
597
 * @param id            Pointer to store the returned device ID.
 
598
 *
 
599
 * @return              PJ_SUCCESS if the device can be found.
 
600
 */
 
601
PJ_DECL(pj_status_t) pjmedia_aud_dev_lookup(const char *drv_name,
 
602
                                            const char *dev_name,
 
603
                                            pjmedia_aud_dev_index *id);
 
604
 
 
605
 
 
606
/**
 
607
 * Initialize the audio device parameters with default values for the
 
608
 * specified device.
 
609
 *
 
610
 * @param id            The audio device ID.
 
611
 * @param param         The audio device parameters which will be initialized
 
612
 *                      by this function once it returns successfully.
 
613
 *
 
614
 * @return              PJ_SUCCESS on successful operation or the appropriate
 
615
 *                      error code.
 
616
 */
 
617
PJ_DECL(pj_status_t) pjmedia_aud_dev_default_param(pjmedia_aud_dev_index id,
 
618
                                                   pjmedia_aud_param *param);
 
619
 
 
620
 
 
621
/**
 
622
 * Open audio stream object using the specified parameters.
 
623
 *
 
624
 * @param param         Sound device parameters to be used for the stream.
 
625
 * @param rec_cb        Callback to be called on every input frame captured.
 
626
 * @param play_cb       Callback to be called everytime the sound device needs
 
627
 *                      audio frames to be played back.
 
628
 * @param user_data     Arbitrary user data, which will be given back in the
 
629
 *                      callbacks.
 
630
 * @param p_strm        Pointer to receive the audio stream.
 
631
 *
 
632
 * @return              PJ_SUCCESS on successful operation or the appropriate
 
633
 *                      error code.
 
634
 */
 
635
PJ_DECL(pj_status_t) pjmedia_aud_stream_create(const pjmedia_aud_param *param,
 
636
                                               pjmedia_aud_rec_cb rec_cb,
 
637
                                               pjmedia_aud_play_cb play_cb,
 
638
                                               void *user_data,
 
639
                                               pjmedia_aud_stream **p_strm);
 
640
 
 
641
/**
 
642
 * Get the running parameters for the specified audio stream.
 
643
 *
 
644
 * @param strm          The audio stream.
 
645
 * @param param         Audio stream parameters to be filled in by this 
 
646
 *                      function once it returns successfully.
 
647
 *
 
648
 * @return              PJ_SUCCESS on successful operation or the appropriate
 
649
 *                      error code.
 
650
 */
 
651
PJ_DECL(pj_status_t) pjmedia_aud_stream_get_param(pjmedia_aud_stream *strm,
 
652
                                                  pjmedia_aud_param *param);
 
653
 
 
654
/**
 
655
 * Get the value of a specific capability of the audio stream.
 
656
 *
 
657
 * @param strm          The audio stream.
 
658
 * @param cap           The audio capability which value is to be retrieved.
 
659
 * @param value         Pointer to value to be filled in by this function 
 
660
 *                      once it returns successfully.  Please see the type 
 
661
 *                      of value to be supplied in the pjmedia_aud_dev_cap
 
662
 *                      documentation.
 
663
 *
 
664
 * @return              PJ_SUCCESS on successful operation or the appropriate
 
665
 *                      error code.
 
666
 */
 
667
PJ_DECL(pj_status_t) pjmedia_aud_stream_get_cap(pjmedia_aud_stream *strm,
 
668
                                                pjmedia_aud_dev_cap cap,
 
669
                                                void *value);
 
670
 
 
671
/**
 
672
 * Set the value of a specific capability of the audio stream.
 
673
 *
 
674
 * @param strm          The audio stream.
 
675
 * @param cap           The audio capability which value is to be set.
 
676
 * @param value         Pointer to value. Please see the type of value to
 
677
 *                      be supplied in the pjmedia_aud_dev_cap documentation.
 
678
 *
 
679
 * @return              PJ_SUCCESS on successful operation or the appropriate
 
680
 *                      error code.
 
681
 */
 
682
PJ_DECL(pj_status_t) pjmedia_aud_stream_set_cap(pjmedia_aud_stream *strm,
 
683
                                                pjmedia_aud_dev_cap cap,
 
684
                                                const void *value);
 
685
 
 
686
/**
 
687
 * Start the stream.
 
688
 *
 
689
 * @param strm          The audio stream.
 
690
 *
 
691
 * @return              PJ_SUCCESS on successful operation or the appropriate
 
692
 *                      error code.
 
693
 */
 
694
PJ_DECL(pj_status_t) pjmedia_aud_stream_start(pjmedia_aud_stream *strm);
 
695
 
 
696
/**
 
697
 * Stop the stream.
 
698
 *
 
699
 * @param strm          The audio stream.
 
700
 *
 
701
 * @return              PJ_SUCCESS on successful operation or the appropriate
 
702
 *                      error code.
 
703
 */
 
704
PJ_DECL(pj_status_t) pjmedia_aud_stream_stop(pjmedia_aud_stream *strm);
 
705
 
 
706
/**
 
707
 * Destroy the stream.
 
708
 *
 
709
 * @param strm          The audio stream.
 
710
 *
 
711
 * @return              PJ_SUCCESS on successful operation or the appropriate
 
712
 *                      error code.
 
713
 */
 
714
PJ_DECL(pj_status_t) pjmedia_aud_stream_destroy(pjmedia_aud_stream *strm);
 
715
 
 
716
 
 
717
/**
 
718
 * @}
 
719
 */
 
720
 
 
721
PJ_END_DECL
 
722
 
 
723
 
 
724
#endif  /* __PJMEDIA_AUDIODEV_AUDIODEV_H__ */
 
725