← Back to branch summary

~noskcaj/ubuntu/saucy/sflphone/merge-1.2.3-2

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject/pjmedia/include/pjmedia/rtcp.h

  • Committer: Jackson Doak
  • Date: 2013-07-10 21:04:46 UTC
  • mfrom: (20.1.3 sid)
  • Revision ID: noskcaj@ubuntu.com-20130710210446-y8f587vza807icr9
https://launchpad.net/bugs/1196978
Properly merged from upstream.

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject/pjmedia/include/pjmedia/rtcp.h
1
 
/* $Id: rtcp.h 3960 2012-02-27 14:41:21Z 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_RTCP_H__
21
 
#define __PJMEDIA_RTCP_H__
22
 
 
23
 
/**
24
 
 * @file rtcp.h
25
 
 * @brief RTCP implementation.
26
 
 */
27
 
 
28
 
#include <pjmedia/types.h>
29
 
#include <pjmedia/rtcp_xr.h>
30
 
#include <pjmedia/rtp.h>
31
 
 
32
 
PJ_BEGIN_DECL
33
 
 
34
 
 
35
 
/**
36
 
 * @defgroup PJMED_RTCP RTCP Session and Encapsulation (RFC 3550)
37
 
 * @ingroup PJMEDIA_SESSION
38
 
 * @brief RTCP format and session management
39
 
 * @{
40
 
 *
41
 
 * PJMEDIA implements subsets of RTCP specification (RFC 3550) to monitor
42
 
 * the quality of the real-time media (audio/video) transmission. In
43
 
 * addition to the standard quality monitoring and reporting with RTCP
44
 
 * SR and RR types, PJMEDIA's RTCP implementation is able to report
45
 
 * extended statistics for incoming streams, such as packet duplications,
46
 
 * reorder, discarded, and loss period (to distinguish between random
47
 
 * and burst loss).
48
 
 *
49
 
 * The bidirectional media quality statistic is represented with
50
 
 * #pjmedia_rtcp_stat structure.
51
 
 *
52
 
 * When application uses the stream interface (see @ref PJMED_STRM),
53
 
 * application may retrieve the RTCP statistic by calling 
54
 
 * #pjmedia_stream_get_stat() function.
55
 
 */
56
 
 
57
 
 
58
 
#pragma pack(1)
59
 
 
60
 
/**
61
 
 * RTCP sender report.
62
 
 */
63
 
typedef struct pjmedia_rtcp_sr
64
 
{
65
 
    pj_uint32_t     ntp_sec;        /**< NTP time, seconds part.        */
66
 
    pj_uint32_t     ntp_frac;       /**< NTP time, fractions part.      */
67
 
    pj_uint32_t     rtp_ts;         /**< RTP timestamp.                 */
68
 
    pj_uint32_t     sender_pcount;  /**< Sender packet cound.           */
69
 
    pj_uint32_t     sender_bcount;  /**< Sender octet/bytes count.      */
70
 
} pjmedia_rtcp_sr;
71
 
 
72
 
 
73
 
/**
74
 
 * RTCP receiver report.
75
 
 */
76
 
typedef struct pjmedia_rtcp_rr
77
 
{
78
 
    pj_uint32_t     ssrc;           /**< SSRC identification.           */
79
 
#if defined(PJ_IS_BIG_ENDIAN) && PJ_IS_BIG_ENDIAN!=0
80
 
    pj_uint32_t     fract_lost:8;   /**< Fraction lost.                 */
81
 
    pj_uint32_t     total_lost_2:8; /**< Total lost, bit 16-23.         */
82
 
    pj_uint32_t     total_lost_1:8; /**< Total lost, bit 8-15.          */
83
 
    pj_uint32_t     total_lost_0:8; /**< Total lost, bit 0-7.           */
84
 
#else
85
 
    pj_uint32_t     fract_lost:8;   /**< Fraction lost.                 */
86
 
    pj_uint32_t     total_lost_2:8; /**< Total lost, bit 0-7.           */
87
 
    pj_uint32_t     total_lost_1:8; /**< Total lost, bit 8-15.          */
88
 
    pj_uint32_t     total_lost_0:8; /**< Total lost, bit 16-23.         */
89
 
#endif  
90
 
    pj_uint32_t     last_seq;       /**< Last sequence number.          */
91
 
    pj_uint32_t     jitter;         /**< Jitter.                        */
92
 
    pj_uint32_t     lsr;            /**< Last SR.                       */
93
 
    pj_uint32_t     dlsr;           /**< Delay since last SR.           */
94
 
} pjmedia_rtcp_rr;
95
 
 
96
 
 
97
 
/**
98
 
 * RTCP common header.
99
 
 */
100
 
typedef struct pjmedia_rtcp_common
101
 
{
102
 
#if defined(PJ_IS_BIG_ENDIAN) && PJ_IS_BIG_ENDIAN!=0
103
 
    unsigned        version:2;  /**< packet type            */
104
 
    unsigned        p:1;        /**< padding flag           */
105
 
    unsigned        count:5;    /**< varies by payload type */
106
 
    unsigned        pt:8;       /**< payload type           */
107
 
#else
108
 
    unsigned        count:5;    /**< varies by payload type */
109
 
    unsigned        p:1;        /**< padding flag           */
110
 
    unsigned        version:2;  /**< packet type            */
111
 
    unsigned        pt:8;       /**< payload type           */
112
 
#endif
113
 
    unsigned        length:16;  /**< packet length          */
114
 
    pj_uint32_t     ssrc;       /**< SSRC identification    */
115
 
} pjmedia_rtcp_common;
116
 
 
117
 
 
118
 
/**
119
 
 * This structure declares default RTCP packet (SR) that is sent by pjmedia.
120
 
 * Incoming RTCP packet may have different format, and must be parsed
121
 
 * manually by application.
122
 
 */
123
 
typedef struct pjmedia_rtcp_sr_pkt
124
 
{
125
 
    pjmedia_rtcp_common  common;        /**< Common header.         */
126
 
    pjmedia_rtcp_sr      sr;            /**< Sender report.         */
127
 
    pjmedia_rtcp_rr      rr;            /**< variable-length list   */
128
 
} pjmedia_rtcp_sr_pkt;
129
 
 
130
 
/**
131
 
 * This structure declares RTCP RR (Receiver Report) packet.
132
 
 */
133
 
typedef struct pjmedia_rtcp_rr_pkt
134
 
{
135
 
    pjmedia_rtcp_common  common;        /**< Common header.         */
136
 
    pjmedia_rtcp_rr      rr;            /**< variable-length list   */
137
 
} pjmedia_rtcp_rr_pkt;
138
 
 
139
 
 
140
 
#pragma pack()
141
 
 
142
 
 
143
 
/**
144
 
 * RTCP SDES structure.
145
 
 */
146
 
typedef struct pjmedia_rtcp_sdes
147
 
{
148
 
    pj_str_t    cname;          /**< RTCP SDES type CNAME.      */
149
 
    pj_str_t    name;           /**< RTCP SDES type NAME.       */
150
 
    pj_str_t    email;          /**< RTCP SDES type EMAIL.      */
151
 
    pj_str_t    phone;          /**< RTCP SDES type PHONE.      */
152
 
    pj_str_t    loc;            /**< RTCP SDES type LOC.        */
153
 
    pj_str_t    tool;           /**< RTCP SDES type TOOL.       */
154
 
    pj_str_t    note;           /**< RTCP SDES type NOTE.       */
155
 
} pjmedia_rtcp_sdes;
156
 
 
157
 
 
158
 
/**
159
 
 * NTP time representation.
160
 
 */
161
 
typedef struct pjmedia_rtcp_ntp_rec
162
 
{
163
 
    pj_uint32_t     hi;         /**< High order 32-bit part.    */
164
 
    pj_uint32_t     lo;         /**< Lo order 32-bit part.      */
165
 
} pjmedia_rtcp_ntp_rec;
166
 
 
167
 
 
168
 
/**
169
 
 * Unidirectional RTP stream statistics.
170
 
 */
171
 
typedef struct pjmedia_rtcp_stream_stat
172
 
{
173
 
    pj_time_val     update;     /**< Time of last update.                   */
174
 
    unsigned        update_cnt; /**< Number of updates (to calculate avg)   */
175
 
    pj_uint32_t     pkt;        /**< Total number of packets                */
176
 
    pj_uint32_t     bytes;      /**< Total number of payload/bytes          */
177
 
    unsigned        discard;    /**< Total number of discarded packets.     */
178
 
    unsigned        loss;       /**< Total number of packets lost           */
179
 
    unsigned        reorder;    /**< Total number of out of order packets   */
180
 
    unsigned        dup;        /**< Total number of duplicates packets     */
181
 
 
182
 
    pj_math_stat    loss_period;/**< Loss period statistics (in usec)       */
183
 
 
184
 
    struct {
185
 
        unsigned    burst:1;    /**< Burst/sequential packet lost detected  */
186
 
        unsigned    random:1;   /**< Random packet lost detected.           */
187
 
    } loss_type;                /**< Types of loss detected.                */
188
 
 
189
 
    pj_math_stat    jitter;     /**< Jitter statistics (in usec)            */
190
 
 
191
 
} pjmedia_rtcp_stream_stat;
192
 
 
193
 
 
194
 
/**
195
 
 * Bidirectional RTP stream statistics.
196
 
 */
197
 
typedef struct pjmedia_rtcp_stat
198
 
{
199
 
    pj_time_val              start; /**< Time when session was created      */
200
 
 
201
 
    pjmedia_rtcp_stream_stat tx;    /**< Encoder stream statistics.         */
202
 
    pjmedia_rtcp_stream_stat rx;    /**< Decoder stream statistics.         */
203
 
    
204
 
    pj_math_stat             rtt;   /**< Round trip delay statistic(in usec)*/
205
 
 
206
 
    pj_uint32_t              rtp_tx_last_ts; /**< Last TX RTP timestamp.    */
207
 
    pj_uint16_t              rtp_tx_last_seq;/**< Last TX RTP sequence.     */
208
 
 
209
 
#if defined(PJMEDIA_RTCP_STAT_HAS_IPDV) && PJMEDIA_RTCP_STAT_HAS_IPDV!=0
210
 
    pj_math_stat             rx_ipdv;/**< Statistics of IP packet delay
211
 
                                          variation in receiving direction
212
 
                                          (in usec).                        */
213
 
#endif
214
 
 
215
 
#if defined(PJMEDIA_RTCP_STAT_HAS_RAW_JITTER) && PJMEDIA_RTCP_STAT_HAS_RAW_JITTER!=0
216
 
    pj_math_stat             rx_raw_jitter;/**< Statistic of raw jitter in
217
 
                                                receiving direction 
218
 
                                                (in usec).                  */
219
 
#endif
220
 
 
221
 
    pjmedia_rtcp_sdes        peer_sdes; /**< Peer SDES.                     */
222
 
    char                     peer_sdes_buf_[PJMEDIA_RTCP_RX_SDES_BUF_LEN];
223
 
                                        /**< Peer SDES buffer.              */
224
 
 
225
 
} pjmedia_rtcp_stat;
226
 
 
227
 
 
228
 
/**
229
 
 * RTCP session is used to monitor the RTP session of one endpoint. There
230
 
 * should only be one RTCP session for a bidirectional RTP streams.
231
 
 */
232
 
typedef struct pjmedia_rtcp_session
233
 
{
234
 
    char                   *name;       /**< Name identification.           */
235
 
    pjmedia_rtcp_sr_pkt     rtcp_sr_pkt;/**< Cached RTCP SR packet.         */
236
 
    pjmedia_rtcp_rr_pkt     rtcp_rr_pkt;/**< Cached RTCP RR packet.         */
237
 
    
238
 
    pjmedia_rtp_seq_session seq_ctrl;   /**< RTCP sequence number control.  */
239
 
    unsigned                rtp_last_ts;/**< Last timestamp in RX RTP pkt.  */
240
 
 
241
 
    unsigned                clock_rate; /**< Clock rate of the stream       */
242
 
    unsigned                pkt_size;   /**< Avg pkt size, in samples.      */
243
 
    pj_uint32_t             received;   /**< # pkt received                 */
244
 
    pj_uint32_t             exp_prior;  /**< # pkt expected at last interval*/
245
 
    pj_uint32_t             rx_prior;   /**< # pkt received at last interval*/
246
 
    pj_int32_t              transit;    /**< Rel transit time for prev pkt  */
247
 
    pj_uint32_t             jitter;     /**< Scaled jitter                  */
248
 
    pj_time_val             tv_base;    /**< Base time, in seconds.         */
249
 
    pj_timestamp            ts_base;    /**< Base system timestamp.         */
250
 
    pj_timestamp            ts_freq;    /**< System timestamp frequency.    */
251
 
    pj_uint32_t             rtp_ts_base;/**< Base RTP timestamp.            */
252
 
 
253
 
    pj_uint32_t             rx_lsr;     /**< NTP ts in last SR received     */
254
 
    pj_timestamp            rx_lsr_time;/**< Time when last SR is received  */
255
 
    pj_uint32_t             peer_ssrc;  /**< Peer SSRC                      */
256
 
    
257
 
    pjmedia_rtcp_stat       stat;       /**< Bidirectional stream stat.     */
258
 
 
259
 
#if defined(PJMEDIA_HAS_RTCP_XR) && (PJMEDIA_HAS_RTCP_XR != 0)
260
 
    /**
261
 
     * Specify whether RTCP XR processing is enabled on this session.
262
 
     */
263
 
    pj_bool_t               xr_enabled;
264
 
 
265
 
    /**
266
 
     * RTCP XR session, only valid if RTCP XR processing is enabled
267
 
     * on this session.
268
 
     */
269
 
    pjmedia_rtcp_xr_session xr_session;
270
 
#endif
271
 
} pjmedia_rtcp_session;
272
 
 
273
 
 
274
 
/**
275
 
 * RTCP session settings.
276
 
 */
277
 
typedef struct pjmedia_rtcp_session_setting
278
 
{
279
 
    char            *name;              /**< RTCP session name.         */
280
 
    unsigned         clock_rate;        /**< Sequence.                  */
281
 
    unsigned         samples_per_frame; /**< Timestamp.                 */
282
 
    pj_uint32_t      ssrc;              /**< Sender SSRC.               */
283
 
    pj_uint32_t      rtp_ts_base;       /**< Base RTP timestamp.        */
284
 
} pjmedia_rtcp_session_setting;
285
 
 
286
 
 
287
 
/**
288
 
 * Initialize RTCP session setting.
289
 
 *
290
 
 * @param settings          The RTCP session setting to be initialized.
291
 
 */
292
 
PJ_DECL(void) pjmedia_rtcp_session_setting_default(
293
 
                                    pjmedia_rtcp_session_setting *settings);
294
 
 
295
 
 
296
 
/**
297
 
 * Initialize bidirectional RTCP statistics.
298
 
 *
299
 
 * @param stat              The bidirectional RTCP statistics.
300
 
 */
301
 
PJ_DECL(void) pjmedia_rtcp_init_stat(pjmedia_rtcp_stat *stat);
302
 
 
303
 
 
304
 
/**
305
 
 * Initialize RTCP session.
306
 
 *
307
 
 * @param session           The session
308
 
 * @param name              Optional name to identify the session (for
309
 
 *                          logging purpose).
310
 
 * @param clock_rate        Codec clock rate in samples per second.
311
 
 * @param samples_per_frame Average number of samples per frame.
312
 
 * @param ssrc              The SSRC used in to identify the session.
313
 
 */
314
 
PJ_DECL(void) pjmedia_rtcp_init( pjmedia_rtcp_session *session, 
315
 
                                 char *name,
316
 
                                 unsigned clock_rate,
317
 
                                 unsigned samples_per_frame,
318
 
                                 pj_uint32_t ssrc );
319
 
 
320
 
 
321
 
/**
322
 
 * Initialize RTCP session.
323
 
 *
324
 
 * @param session           The session
325
 
 * @param settings          The RTCP session settings.
326
 
 */
327
 
PJ_DECL(void) pjmedia_rtcp_init2(pjmedia_rtcp_session *session,
328
 
                                 const pjmedia_rtcp_session_setting *settings);
329
 
 
330
 
 
331
 
/**
332
 
 * Utility function to retrieve current NTP timestamp.
333
 
 *
334
 
 * @param sess              RTCP session.
335
 
 * @param ntp               NTP record.
336
 
 *
337
 
 * @return                  PJ_SUCCESS on success.
338
 
 */
339
 
PJ_DECL(pj_status_t) pjmedia_rtcp_get_ntp_time(const pjmedia_rtcp_session *sess,
340
 
                                               pjmedia_rtcp_ntp_rec *ntp);
341
 
 
342
 
 
343
 
/**
344
 
 * Deinitialize RTCP session.
345
 
 *
346
 
 * @param session   The session.
347
 
 */
348
 
PJ_DECL(void) pjmedia_rtcp_fini( pjmedia_rtcp_session *session);
349
 
 
350
 
 
351
 
/**
352
 
 * Call this function everytime an RTP packet is received to let the RTCP
353
 
 * session do its internal calculations.
354
 
 *
355
 
 * @param session   The session.
356
 
 * @param seq       The RTP packet sequence number, in host byte order.
357
 
 * @param ts        The RTP packet timestamp, in host byte order.
358
 
 * @param payload   Size of the payload.
359
 
 */
360
 
PJ_DECL(void) pjmedia_rtcp_rx_rtp( pjmedia_rtcp_session *session, 
361
 
                                   unsigned seq, 
362
 
                                   unsigned ts,
363
 
                                   unsigned payload);
364
 
 
365
 
 
366
 
/**
367
 
 * Call this function everytime an RTP packet is received to let the RTCP
368
 
 * session do its internal calculations.
369
 
 *
370
 
 * @param session   The session.
371
 
 * @param seq       The RTP packet sequence number, in host byte order.
372
 
 * @param ts        The RTP packet timestamp, in host byte order.
373
 
 * @param payload   Size of the payload.
374
 
 * @param discarded Flag to specify whether the packet is discarded.
375
 
 */
376
 
PJ_DECL(void) pjmedia_rtcp_rx_rtp2(pjmedia_rtcp_session *session, 
377
 
                                   unsigned seq, 
378
 
                                   unsigned ts,
379
 
                                   unsigned payload,
380
 
                                   pj_bool_t discarded);
381
 
 
382
 
 
383
 
/**
384
 
 * Call this function everytime an RTP packet is sent to let the RTCP session
385
 
 * do its internal calculations.
386
 
 *
387
 
 * @param session   The session.
388
 
 * @param ptsize    The payload size of the RTP packet (ie packet minus
389
 
 *                  RTP header) in bytes.
390
 
 */
391
 
PJ_DECL(void) pjmedia_rtcp_tx_rtp( pjmedia_rtcp_session *session, 
392
 
                                   unsigned ptsize );
393
 
 
394
 
 
395
 
/**
396
 
 * Call this function when an RTCP packet is received from remote peer.
397
 
 * This RTCP packet received from remote is used to calculate the end-to-
398
 
 * end delay of the network.
399
 
 *
400
 
 * @param session   RTCP session.
401
 
 * @param rtcp_pkt  The received RTCP packet.
402
 
 * @param size      Size of the incoming packet.
403
 
 */
404
 
PJ_DECL(void) pjmedia_rtcp_rx_rtcp( pjmedia_rtcp_session *session,
405
 
                                    const void *rtcp_pkt,
406
 
                                    pj_size_t size);
407
 
 
408
 
 
409
 
/**
410
 
 * Build a RTCP packet to be transmitted to remote RTP peer. This will
411
 
 * create RTCP Sender Report (SR) or Receiver Report (RR) depending on
412
 
 * whether the endpoint has been transmitting RTP since the last interval.
413
 
 * Note that this function will reset the interval counters (such as
414
 
 * the ones to calculate fraction lost) in the session.
415
 
 *
416
 
 * @param session   The RTCP session.
417
 
 * @param rtcp_pkt  Upon return, it will contain pointer to the 
418
 
 *                  RTCP packet, which can be RTCP SR or RR.
419
 
 * @param len       Upon return, it will indicate the size of 
420
 
 *                  the RTCP packet.
421
 
 */
422
 
PJ_DECL(void) pjmedia_rtcp_build_rtcp( pjmedia_rtcp_session *session, 
423
 
                                       void **rtcp_pkt, int *len);
424
 
 
425
 
 
426
 
/**
427
 
 * Build an RTCP SDES (source description) packet. This packet can be
428
 
 * appended to other RTCP packets, e.g: RTCP RR/SR, to compose a compound
429
 
 * RTCP packet.
430
 
 *
431
 
 * @param session   The RTCP session.
432
 
 * @param buf       The buffer to receive RTCP SDES packet.
433
 
 * @param length    On input, it will contain the buffer length.
434
 
 *                  On output, it will contain the generated RTCP SDES
435
 
 *                  packet length.
436
 
 * @param sdes      The source description, see #pjmedia_rtcp_sdes.
437
 
 *
438
 
 * @return          PJ_SUCCESS on success.
439
 
 */
440
 
PJ_DECL(pj_status_t) pjmedia_rtcp_build_rtcp_sdes(
441
 
                                            pjmedia_rtcp_session *session, 
442
 
                                            void *buf,
443
 
                                            pj_size_t *length,
444
 
                                            const pjmedia_rtcp_sdes *sdes);
445
 
 
446
 
/**
447
 
 * Build an RTCP BYE packet. This packet can be appended to other RTCP
448
 
 * packets, e.g: RTCP RR/SR, to compose a compound RTCP packet.
449
 
 *
450
 
 * @param session   The RTCP session.
451
 
 * @param buf       The buffer to receive RTCP BYE packet.
452
 
 * @param length    On input, it will contain the buffer length.
453
 
 *                  On output, it will contain the generated RTCP BYE
454
 
 *                  packet length.
455
 
 * @param reason    Optional, the BYE reason.
456
 
 *
457
 
 * @return          PJ_SUCCESS on success.
458
 
 */
459
 
PJ_DECL(pj_status_t) pjmedia_rtcp_build_rtcp_bye(
460
 
                                            pjmedia_rtcp_session *session, 
461
 
                                            void *buf,
462
 
                                            pj_size_t *length,
463
 
                                            const pj_str_t *reason);
464
 
 
465
 
 
466
 
/**
467
 
 * Call this function if RTCP XR needs to be enabled/disabled in the 
468
 
 * RTCP session.
469
 
 *
470
 
 * @param session   The RTCP session.
471
 
 * @param enable    Enable/disable RTCP XR.
472
 
 *
473
 
 * @return          PJ_SUCCESS on success.
474
 
 */
475
 
PJ_DECL(pj_status_t) pjmedia_rtcp_enable_xr( pjmedia_rtcp_session *session, 
476
 
                                             pj_bool_t enable);
477
 
 
478
 
 
479
 
/**
480
 
 * @}
481
 
 */
482
 
 
483
 
PJ_END_DECL
484
 
 
485
 
 
486
 
#endif  /* __PJMEDIA_RTCP_H__ */