← Back to branch summary

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

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.0.1/pjmedia/include/pjmedia/jbuf.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
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.0.1/pjmedia/include/pjmedia/jbuf.h
1
 
/* $Id: jbuf.h 3841 2011-10-24 09:28:13Z ming $ */
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
 
/*
21
 
 * Based on implementation kindly contributed by Switchlab, Ltd.
22
 
 */
23
 
#ifndef __PJMEDIA_JBUF_H__
24
 
#define __PJMEDIA_JBUF_H__
25
 
 
26
 
 
27
 
/**
28
 
 * @file jbuf.h
29
 
 * @brief Adaptive jitter buffer implementation.
30
 
 */
31
 
#include <pjmedia/types.h>
32
 
 
33
 
/**
34
 
 * @defgroup PJMED_JBUF Adaptive jitter buffer
35
 
 * @ingroup PJMEDIA_FRAME_OP
36
 
 * @brief Adaptive de-jitter buffering implementation
37
 
 * @{
38
 
 *
39
 
 * This section describes PJMEDIA's implementation of de-jitter buffer.
40
 
 * The de-jitter buffer may be set to operate in adaptive mode or fixed
41
 
 * delay mode.
42
 
 */
43
 
 
44
 
 
45
 
PJ_BEGIN_DECL
46
 
 
47
 
 
48
 
/**
49
 
 * Types of frame returned by the jitter buffer.
50
 
 */
51
 
typedef enum pjmedia_jb_frame_type
52
 
{
53
 
    PJMEDIA_JB_MISSING_FRAME       = 0, /**< No frame because it's missing  */
54
 
    PJMEDIA_JB_NORMAL_FRAME        = 1, /**< Normal frame is being returned */
55
 
    PJMEDIA_JB_ZERO_PREFETCH_FRAME = 2, /**< Zero frame is being returned
56
 
                                             because JB is bufferring.      */
57
 
    PJMEDIA_JB_ZERO_EMPTY_FRAME    = 3  /**< Zero frame is being returned
58
 
                                             because JB is empty.           */
59
 
} pjmedia_jb_frame_type;
60
 
 
61
 
 
62
 
/**
63
 
 * Enumeration of jitter buffer discard algorithm. The jitter buffer
64
 
 * continuously calculates the jitter level to get the optimum latency at
65
 
 * any time and in order to adjust the latency, the jitter buffer may need
66
 
 * to discard some frames.
67
 
 */
68
 
typedef enum pjmedia_jb_discard_algo
69
 
{
70
 
    /**
71
 
     * Jitter buffer should not discard any frame, except when the jitter
72
 
     * buffer is full and a new frame arrives, one frame will be discarded
73
 
     * to make space for the new frame.
74
 
     */
75
 
    PJMEDIA_JB_DISCARD_NONE        = 0,
76
 
 
77
 
    /**
78
 
     * Only discard one frame in at least 200ms when the latency is considered
79
 
     * much higher than it should be. When the jitter buffer is full and a new
80
 
     * frame arrives, one frame will be discarded to make space for the new
81
 
     * frame.
82
 
     */
83
 
    PJMEDIA_JB_DISCARD_STATIC,
84
 
 
85
 
    /**
86
 
     * The discard rate is dynamically calculated based on actual parameters
87
 
     * such as jitter level and latency. When the jitter buffer is full and
88
 
     * a new frame arrives, one frame will be discarded to make space for the
89
 
     * new frame.
90
 
     */
91
 
    PJMEDIA_JB_DISCARD_PROGRESSIVE
92
 
 
93
 
} pjmedia_jb_discard_algo;
94
 
 
95
 
 
96
 
/**
97
 
 * This structure describes jitter buffer state.
98
 
 */
99
 
typedef struct pjmedia_jb_state
100
 
{
101
 
    /* Setting */
102
 
    unsigned    frame_size;         /**< Individual frame size, in bytes.   */
103
 
    unsigned    min_prefetch;       /**< Minimum allowed prefetch, in frms. */
104
 
    unsigned    max_prefetch;       /**< Maximum allowed prefetch, in frms. */
105
 
 
106
 
    /* Status */
107
 
    unsigned    burst;              /**< Current burst level, in frames     */
108
 
    unsigned    prefetch;           /**< Current prefetch value, in frames  */
109
 
    unsigned    size;               /**< Current buffer size, in frames.    */
110
 
 
111
 
    /* Statistic */
112
 
    unsigned    avg_delay;          /**< Average delay, in ms.              */
113
 
    unsigned    min_delay;          /**< Minimum delay, in ms.              */
114
 
    unsigned    max_delay;          /**< Maximum delay, in ms.              */
115
 
    unsigned    dev_delay;          /**< Standard deviation of delay, in ms.*/
116
 
    unsigned    avg_burst;          /**< Average burst, in frames.          */
117
 
    unsigned    lost;               /**< Number of lost frames.             */
118
 
    unsigned    discard;            /**< Number of discarded frames.        */
119
 
    unsigned    empty;              /**< Number of empty on GET events.     */
120
 
} pjmedia_jb_state;
121
 
 
122
 
 
123
 
/**
124
 
 * The constant PJMEDIA_JB_DEFAULT_INIT_DELAY specifies default jitter
125
 
 * buffer prefetch count during jitter buffer creation.
126
 
 */
127
 
#define PJMEDIA_JB_DEFAULT_INIT_DELAY    15
128
 
 
129
 
/**
130
 
 * Opaque declaration for jitter buffer.
131
 
 */
132
 
typedef struct pjmedia_jbuf pjmedia_jbuf;
133
 
 
134
 
 
135
 
/**
136
 
 * Create an adaptive jitter buffer according to the specification. If
137
 
 * application wants to have a fixed jitter buffer, it may call
138
 
 * #pjmedia_jbuf_set_fixed() after the jitter buffer is created. Also
139
 
 * if application wants to alter the discard algorithm, which the default
140
 
 * PJMEDIA_JB_DISCARD_PROGRESSIVE, it may call #pjmedia_jbuf_set_discard().
141
 
 *
142
 
 * This function may allocate large chunk of memory to keep the frames in
143
 
 * the buffer.
144
 
 *
145
 
 * @param pool          The pool to allocate memory.
146
 
 * @param name          Name to identify the jitter buffer for logging
147
 
 *                      purpose.
148
 
 * @param frame_size    The size of each frame that will be kept in the
149
 
 *                      jitter buffer, in bytes. This should correspond
150
 
 *                      to the minimum frame size supported by the codec.
151
 
 *                      For example, a 10ms frame (80 bytes) would be
152
 
 *                      recommended for G.711 codec.
153
 
 * @param max_count     Maximum number of frames that can be kept in the
154
 
 *                      jitter buffer. This effectively means the maximum
155
 
 *                      delay that may be introduced by this jitter
156
 
 *                      buffer.
157
 
 * @param ptime         Indication of frame duration, used to calculate
158
 
 *                      the interval between jitter recalculation.
159
 
 * @param p_jb          Pointer to receive jitter buffer instance.
160
 
 *
161
 
 * @return              PJ_SUCCESS on success.
162
 
 */
163
 
PJ_DECL(pj_status_t) pjmedia_jbuf_create(pj_pool_t *pool,
164
 
                                         const pj_str_t *name,
165
 
                                         unsigned frame_size,
166
 
                                         unsigned ptime,
167
 
                                         unsigned max_count,
168
 
                                         pjmedia_jbuf **p_jb);
169
 
 
170
 
/**
171
 
 * Set the jitter buffer to fixed delay mode. The default behavior
172
 
 * is to adapt the delay with actual packet delay.
173
 
 *
174
 
 * @param jb            The jitter buffer
175
 
 * @param prefetch      The fixed delay value, in number of frames.
176
 
 *
177
 
 * @return              PJ_SUCCESS on success.
178
 
 */
179
 
PJ_DECL(pj_status_t) pjmedia_jbuf_set_fixed( pjmedia_jbuf *jb,
180
 
                                             unsigned prefetch);
181
 
 
182
 
 
183
 
/**
184
 
 * Set the jitter buffer to adaptive mode.
185
 
 *
186
 
 * @param jb            The jitter buffer.
187
 
 * @param prefetch      The initial prefetch value to be applied to the
188
 
 *                      jitter buffer. Setting this to other than 0 will
189
 
 *                      activate prefetch buffering, a jitter buffer feature
190
 
 *                      that each time it gets empty, it won't return a
191
 
 *                      normal frame until its size reaches the number
192
 
 *                      specified here.
193
 
 * @param min_prefetch  The minimum delay that must be applied to each
194
 
 *                      incoming packets, in number of frames.
195
 
 * @param max_prefetch  The maximum allowable value for prefetch delay,
196
 
 *                      in number of frames.
197
 
 *
198
 
 * @return              PJ_SUCCESS on success.
199
 
 */
200
 
PJ_DECL(pj_status_t) pjmedia_jbuf_set_adaptive( pjmedia_jbuf *jb,
201
 
                                                unsigned prefetch,
202
 
                                                unsigned min_prefetch,
203
 
                                                unsigned max_prefetch);
204
 
 
205
 
 
206
 
/**
207
 
 * Set the jitter buffer discard algorithm. The default discard algorithm,
208
 
 * set in jitter buffer creation, is PJMEDIA_JB_DISCARD_PROGRESSIVE.
209
 
 *
210
 
 * @param jb            The jitter buffer.
211
 
 * @param algo          The discard algorithm to be used.
212
 
 *
213
 
 * @return              PJ_SUCCESS on success.
214
 
 */
215
 
PJ_DECL(pj_status_t) pjmedia_jbuf_set_discard(pjmedia_jbuf *jb,
216
 
                                              pjmedia_jb_discard_algo algo);
217
 
 
218
 
 
219
 
/**
220
 
 * Destroy jitter buffer instance.
221
 
 *
222
 
 * @param jb            The jitter buffer.
223
 
 *
224
 
 * @return              PJ_SUCCESS on success.
225
 
 */
226
 
PJ_DECL(pj_status_t) pjmedia_jbuf_destroy(pjmedia_jbuf *jb);
227
 
 
228
 
 
229
 
/**
230
 
 * Restart jitter. This function flushes all packets in the buffer and
231
 
 * reset the internal sequence number.
232
 
 *
233
 
 * @param jb            The jitter buffer.
234
 
 *
235
 
 * @return              PJ_SUCCESS on success.
236
 
 */
237
 
PJ_DECL(pj_status_t) pjmedia_jbuf_reset(pjmedia_jbuf *jb);
238
 
 
239
 
/**
240
 
 * Put a frame to the jitter buffer. If the frame can be accepted (based
241
 
 * on the sequence number), the jitter buffer will copy the frame and put
242
 
 * it in the appropriate position in the buffer.
243
 
 *
244
 
 * Application MUST manage it's own synchronization when multiple threads
245
 
 * are accessing the jitter buffer at the same time.
246
 
 *
247
 
 * @param jb            The jitter buffer.
248
 
 * @param frame         Pointer to frame buffer to be stored in the jitter
249
 
 *                      buffer.
250
 
 * @param size          The frame size.
251
 
 * @param frame_seq     The frame sequence number.
252
 
 */
253
 
PJ_DECL(void) pjmedia_jbuf_put_frame( pjmedia_jbuf *jb,
254
 
                                      const void *frame,
255
 
                                      pj_size_t size,
256
 
                                      int frame_seq);
257
 
 
258
 
/**
259
 
 * Put a frame to the jitter buffer. If the frame can be accepted (based
260
 
 * on the sequence number), the jitter buffer will copy the frame and put
261
 
 * it in the appropriate position in the buffer.
262
 
 *
263
 
 * Application MUST manage it's own synchronization when multiple threads
264
 
 * are accessing the jitter buffer at the same time.
265
 
 *
266
 
 * @param jb            The jitter buffer.
267
 
 * @param frame         Pointer to frame buffer to be stored in the jitter
268
 
 *                      buffer.
269
 
 * @param size          The frame size.
270
 
 * @param bit_info      Bit precise info of the frame, e.g: a frame may not
271
 
 *                      exactly start and end at the octet boundary, so this
272
 
 *                      field may be used for specifying start & end bit offset.
273
 
 * @param frame_seq     The frame sequence number.
274
 
 * @param discarded     Flag whether the frame is discarded by jitter buffer.
275
 
 */
276
 
PJ_DECL(void) pjmedia_jbuf_put_frame2( pjmedia_jbuf *jb,
277
 
                                       const void *frame,
278
 
                                       pj_size_t size,
279
 
                                       pj_uint32_t bit_info,
280
 
                                       int frame_seq,
281
 
                                       pj_bool_t *discarded);
282
 
 
283
 
/**
284
 
 * Put a frame to the jitter buffer. If the frame can be accepted (based
285
 
 * on the sequence number), the jitter buffer will copy the frame and put
286
 
 * it in the appropriate position in the buffer.
287
 
 *
288
 
 * Application MUST manage it's own synchronization when multiple threads
289
 
 * are accessing the jitter buffer at the same time.
290
 
 *
291
 
 * @param jb            The jitter buffer.
292
 
 * @param frame         Pointer to frame buffer to be stored in the jitter
293
 
 *                      buffer.
294
 
 * @param size          The frame size.
295
 
 * @param bit_info      Bit precise info of the frame, e.g: a frame may not
296
 
 *                      exactly start and end at the octet boundary, so this
297
 
 *                      field may be used for specifying start & end bit offset.
298
 
 * @param frame_seq     The frame sequence number.
299
 
 * @param frame_ts      The frame timestamp.
300
 
 * @param discarded     Flag whether the frame is discarded by jitter buffer.
301
 
 */
302
 
PJ_DECL(void) pjmedia_jbuf_put_frame3( pjmedia_jbuf *jb,
303
 
                                       const void *frame,
304
 
                                       pj_size_t size,
305
 
                                       pj_uint32_t bit_info,
306
 
                                       int frame_seq,
307
 
                                       pj_uint32_t frame_ts,
308
 
                                       pj_bool_t *discarded);
309
 
/**
310
 
 * Get a frame from the jitter buffer. The jitter buffer will return the
311
 
 * oldest frame from it's buffer, when it is available.
312
 
 *
313
 
 * Application MUST manage it's own synchronization when multiple threads
314
 
 * are accessing the jitter buffer at the same time.
315
 
 *
316
 
 * @param jb            The jitter buffer.
317
 
 * @param frame         Buffer to receive the payload from the jitter buffer.
318
 
 *                      Application MUST make sure that the buffer has
319
 
 *                      appropriate size (i.e. not less than the frame size,
320
 
 *                      as specified when the jitter buffer was created).
321
 
 *                      The jitter buffer only copied a frame to this
322
 
 *                      buffer when the frame type returned by this function
323
 
 *                      is PJMEDIA_JB_NORMAL_FRAME.
324
 
 * @param p_frm_type    Pointer to receive frame type. If jitter buffer is
325
 
 *                      currently empty or bufferring, the frame type will
326
 
 *                      be set to PJMEDIA_JB_ZERO_FRAME, and no frame will
327
 
 *                      be copied. If the jitter buffer detects that frame is
328
 
 *                      missing with current sequence number, the frame type
329
 
 *                      will be set to PJMEDIA_JB_MISSING_FRAME, and no
330
 
 *                      frame will be copied. If there is a frame, the jitter
331
 
 *                      buffer will copy the frame to the buffer, and frame
332
 
 *                      type will be set to PJMEDIA_JB_NORMAL_FRAME.
333
 
 */
334
 
PJ_DECL(void) pjmedia_jbuf_get_frame( pjmedia_jbuf *jb,
335
 
                                      void *frame,
336
 
                                      char *p_frm_type);
337
 
 
338
 
/**
339
 
 * Get a frame from the jitter buffer. The jitter buffer will return the
340
 
 * oldest frame from it's buffer, when it is available.
341
 
 *
342
 
 * @param jb            The jitter buffer.
343
 
 * @param frame         Buffer to receive the payload from the jitter buffer.
344
 
 *                      @see pjmedia_jbuf_get_frame().
345
 
 * @param size          Pointer to receive frame size.
346
 
 * @param p_frm_type    Pointer to receive frame type.
347
 
 *                      @see pjmedia_jbuf_get_frame().
348
 
 * @param bit_info      Bit precise info of the frame, e.g: a frame may not
349
 
 *                      exactly start and end at the octet boundary, so this
350
 
 *                      field may be used for specifying start & end bit offset.
351
 
 */
352
 
PJ_DECL(void) pjmedia_jbuf_get_frame2(pjmedia_jbuf *jb,
353
 
                                      void *frame,
354
 
                                      pj_size_t *size,
355
 
                                      char *p_frm_type,
356
 
                                      pj_uint32_t *bit_info);
357
 
 
358
 
 
359
 
/**
360
 
 * Get a frame from the jitter buffer. The jitter buffer will return the
361
 
 * oldest frame from it's buffer, when it is available.
362
 
 *
363
 
 * @param jb            The jitter buffer.
364
 
 * @param frame         Buffer to receive the payload from the jitter buffer.
365
 
 *                      @see pjmedia_jbuf_get_frame().
366
 
 * @param size          Pointer to receive frame size.
367
 
 * @param p_frm_type    Pointer to receive frame type.
368
 
 *                      @see pjmedia_jbuf_get_frame().
369
 
 * @param bit_info      Bit precise info of the frame, e.g: a frame may not
370
 
 *                      exactly start and end at the octet boundary, so this
371
 
 *                      field may be used for specifying start & end bit offset.
372
 
 * @param ts            Frame timestamp.
373
 
 * @param seq           Frame sequence number.
374
 
 */
375
 
PJ_DECL(void) pjmedia_jbuf_get_frame3(pjmedia_jbuf *jb,
376
 
                                      void *frame,
377
 
                                      pj_size_t *size,
378
 
                                      char *p_frm_type,
379
 
                                      pj_uint32_t *bit_info,
380
 
                                      pj_uint32_t *ts,
381
 
                                      int *seq);
382
 
 
383
 
 
384
 
/**
385
 
 * Peek a frame from the jitter buffer. The jitter buffer state will not be
386
 
 * modified.
387
 
 *
388
 
 * @param jb            The jitter buffer.
389
 
 * @param offset        Offset from the oldest frame to be peeked.
390
 
 * @param frame         Buffer to receive the payload from the jitter buffer.
391
 
 *                      @see pjmedia_jbuf_get_frame().
392
 
 * @param size          Pointer to receive frame size.
393
 
 * @param p_frm_type    Pointer to receive frame type.
394
 
 *                      @see pjmedia_jbuf_get_frame().
395
 
 * @param bit_info      Bit precise info of the frame, e.g: a frame may not
396
 
 *                      exactly start and end at the octet boundary, so this
397
 
 *                      field may be used for specifying start & end bit offset.
398
 
 * @param ts            Frame timestamp.
399
 
 * @param seq           Frame sequence number.
400
 
 */
401
 
PJ_DECL(void) pjmedia_jbuf_peek_frame(pjmedia_jbuf *jb,
402
 
                                      unsigned offset,
403
 
                                      const void **frame,
404
 
                                      pj_size_t *size,
405
 
                                      char *p_frm_type,
406
 
                                      pj_uint32_t *bit_info,
407
 
                                      pj_uint32_t *ts,
408
 
                                      int *seq);
409
 
 
410
 
 
411
 
/**
412
 
 * Remove frames from the jitter buffer.
413
 
 *
414
 
 * @param jb            The jitter buffer.
415
 
 * @param frame_cnt     Number of frames to be removed.
416
 
 *
417
 
 * @return              The number of frame successfully removed.
418
 
 */
419
 
PJ_DECL(unsigned) pjmedia_jbuf_remove_frame(pjmedia_jbuf *jb,
420
 
                                            unsigned frame_cnt);
421
 
 
422
 
/**
423
 
 * Check if the jitter buffer is full.
424
 
 *
425
 
 * @param jb            The jitter buffer.
426
 
 *
427
 
 * @return              PJ_TRUE if it is full.
428
 
 */
429
 
PJ_DECL(pj_bool_t) pjmedia_jbuf_is_full(const pjmedia_jbuf *jb);
430
 
 
431
 
 
432
 
/**
433
 
 * Get jitter buffer current state/settings.
434
 
 *
435
 
 * @param jb            The jitter buffer.
436
 
 * @param state         Buffer to receive jitter buffer state.
437
 
 *
438
 
 * @return              PJ_SUCCESS on success.
439
 
 */
440
 
PJ_DECL(pj_status_t) pjmedia_jbuf_get_state( const pjmedia_jbuf *jb,
441
 
                                             pjmedia_jb_state *state );
442
 
 
443
 
 
444
 
 
445
 
PJ_END_DECL
446
 
 
447
 
/**
448
 
 * @}
449
 
 */
450
 
 
451
 
#endif  /* __PJMEDIA_JBUF_H__ */