← Back to branch summary

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

« back to all changes in this revision

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

  • Committer: Package Import Robot
  • Author(s): Francois Marier
  • Date: 2011-11-25 13:24:12 UTC
  • mfrom: (4.1.10 sid)
  • Revision ID: package-import@ubuntu.com-20111125132412-dc4qvhyosk74cd42
Tags: 1.0.1-4
http://bugs.debian.org/649726
Don't assume that arch:all packages will get built (closes: #649726)

Show diffs side-by-side

added added

removed removed

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