1
/* $Id: rtcp.h 3999 2012-03-30 07:10:13Z bennylp $ */
3
* Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4
* Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
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.
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.
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
20
#ifndef __PJMEDIA_RTCP_H__
21
#define __PJMEDIA_RTCP_H__
25
* @brief RTCP implementation.
28
#include <pjmedia/types.h>
29
#include <pjmedia/rtcp_xr.h>
30
#include <pjmedia/rtp.h>
36
* @defgroup PJMED_RTCP RTCP Session and Encapsulation (RFC 3550)
37
* @ingroup PJMEDIA_SESSION
38
* @brief RTCP format and session management
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
49
* The bidirectional media quality statistic is represented with
50
* #pjmedia_rtcp_stat structure.
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.
63
typedef struct pjmedia_rtcp_sr
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. */
74
* RTCP receiver report.
76
typedef struct pjmedia_rtcp_rr
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. */
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. */
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. */
100
typedef struct pjmedia_rtcp_common
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 */
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 */
113
unsigned length:16; /**< packet length */
114
pj_uint32_t ssrc; /**< SSRC identification */
115
} pjmedia_rtcp_common;
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.
123
typedef struct pjmedia_rtcp_sr_pkt
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;
131
* This structure declares RTCP RR (Receiver Report) packet.
133
typedef struct pjmedia_rtcp_rr_pkt
135
pjmedia_rtcp_common common; /**< Common header. */
136
pjmedia_rtcp_rr rr; /**< variable-length list */
137
} pjmedia_rtcp_rr_pkt;
144
* RTCP SDES structure.
146
typedef struct pjmedia_rtcp_sdes
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. */
159
* NTP time representation.
161
typedef struct pjmedia_rtcp_ntp_rec
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;
169
* Unidirectional RTP stream statistics.
171
typedef struct pjmedia_rtcp_stream_stat
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 */
182
pj_math_stat loss_period;/**< Loss period statistics (in usec) */
185
unsigned burst:1; /**< Burst/sequential packet lost detected */
186
unsigned random:1; /**< Random packet lost detected. */
187
} loss_type; /**< Types of loss detected. */
189
pj_math_stat jitter; /**< Jitter statistics (in usec) */
191
} pjmedia_rtcp_stream_stat;
195
* Bidirectional RTP stream statistics.
197
typedef struct pjmedia_rtcp_stat
199
pj_time_val start; /**< Time when session was created */
201
pjmedia_rtcp_stream_stat tx; /**< Encoder stream statistics. */
202
pjmedia_rtcp_stream_stat rx; /**< Decoder stream statistics. */
204
pj_math_stat rtt; /**< Round trip delay statistic(in usec)*/
206
pj_uint32_t rtp_tx_last_ts; /**< Last TX RTP timestamp. */
207
pj_uint16_t rtp_tx_last_seq;/**< Last TX RTP sequence. */
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
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
221
pjmedia_rtcp_sdes peer_sdes; /**< Peer SDES. */
222
char peer_sdes_buf_[PJMEDIA_RTCP_RX_SDES_BUF_LEN];
223
/**< Peer SDES buffer. */
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.
232
typedef struct pjmedia_rtcp_session
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. */
238
pjmedia_rtp_seq_session seq_ctrl; /**< RTCP sequence number control. */
239
unsigned rtp_last_ts;/**< Last timestamp in RX RTP pkt. */
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. */
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 */
257
pjmedia_rtcp_stat stat; /**< Bidirectional stream stat. */
259
#if defined(PJMEDIA_HAS_RTCP_XR) && (PJMEDIA_HAS_RTCP_XR != 0)
261
* Specify whether RTCP XR processing is enabled on this session.
263
pj_bool_t xr_enabled;
266
* RTCP XR session, only valid if RTCP XR processing is enabled
269
pjmedia_rtcp_xr_session xr_session;
271
} pjmedia_rtcp_session;
275
* RTCP session settings.
277
typedef struct pjmedia_rtcp_session_setting
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;
288
* Initialize RTCP session setting.
290
* @param settings The RTCP session setting to be initialized.
292
PJ_DECL(void) pjmedia_rtcp_session_setting_default(
293
pjmedia_rtcp_session_setting *settings);
297
* Initialize bidirectional RTCP statistics.
299
* @param stat The bidirectional RTCP statistics.
301
PJ_DECL(void) pjmedia_rtcp_init_stat(pjmedia_rtcp_stat *stat);
305
* Initialize RTCP session.
307
* @param session The session
308
* @param name Optional name to identify the session (for
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.
314
PJ_DECL(void) pjmedia_rtcp_init( pjmedia_rtcp_session *session,
317
unsigned samples_per_frame,
322
* Initialize RTCP session.
324
* @param session The session
325
* @param settings The RTCP session settings.
327
PJ_DECL(void) pjmedia_rtcp_init2(pjmedia_rtcp_session *session,
328
const pjmedia_rtcp_session_setting *settings);
332
* Utility function to retrieve current NTP timestamp.
334
* @param sess RTCP session.
335
* @param ntp NTP record.
337
* @return PJ_SUCCESS on success.
339
PJ_DECL(pj_status_t) pjmedia_rtcp_get_ntp_time(const pjmedia_rtcp_session *sess,
340
pjmedia_rtcp_ntp_rec *ntp);
344
* Deinitialize RTCP session.
346
* @param session The session.
348
PJ_DECL(void) pjmedia_rtcp_fini( pjmedia_rtcp_session *session);
352
* Call this function everytime an RTP packet is received to let the RTCP
353
* session do its internal calculations.
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.
360
PJ_DECL(void) pjmedia_rtcp_rx_rtp( pjmedia_rtcp_session *session,
367
* Call this function everytime an RTP packet is received to let the RTCP
368
* session do its internal calculations.
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.
376
PJ_DECL(void) pjmedia_rtcp_rx_rtp2(pjmedia_rtcp_session *session,
380
pj_bool_t discarded);
384
* Call this function everytime an RTP packet is sent to let the RTCP session
385
* do its internal calculations.
387
* @param session The session.
388
* @param ptsize The payload size of the RTP packet (ie packet minus
389
* RTP header) in bytes.
391
PJ_DECL(void) pjmedia_rtcp_tx_rtp( pjmedia_rtcp_session *session,
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.
400
* @param session RTCP session.
401
* @param rtcp_pkt The received RTCP packet.
402
* @param size Size of the incoming packet.
404
PJ_DECL(void) pjmedia_rtcp_rx_rtcp( pjmedia_rtcp_session *session,
405
const void *rtcp_pkt,
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.
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
422
PJ_DECL(void) pjmedia_rtcp_build_rtcp( pjmedia_rtcp_session *session,
423
void **rtcp_pkt, int *len);
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
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
436
* @param sdes The source description, see #pjmedia_rtcp_sdes.
438
* @return PJ_SUCCESS on success.
440
PJ_DECL(pj_status_t) pjmedia_rtcp_build_rtcp_sdes(
441
pjmedia_rtcp_session *session,
444
const pjmedia_rtcp_sdes *sdes);
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.
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
455
* @param reason Optional, the BYE reason.
457
* @return PJ_SUCCESS on success.
459
PJ_DECL(pj_status_t) pjmedia_rtcp_build_rtcp_bye(
460
pjmedia_rtcp_session *session,
463
const pj_str_t *reason);
467
* Call this function if RTCP XR needs to be enabled/disabled in the
470
* @param session The RTCP session.
471
* @param enable Enable/disable RTCP XR.
473
* @return PJ_SUCCESS on success.
475
PJ_DECL(pj_status_t) pjmedia_rtcp_enable_xr( pjmedia_rtcp_session *session,
486
#endif /* __PJMEDIA_RTCP_H__ */