1
/* $Id: rtcp_xr.h 3553 2011-05-05 06:14:19Z nanang $ */
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_XR_H__
21
#define __PJMEDIA_RTCP_XR_H__
25
* @brief RTCP XR implementation.
28
#include <pjmedia/types.h>
36
* @defgroup PJMED_RTCP_XR RTCP Extended Report (XR) - RFC 3611
37
* @ingroup PJMEDIA_SESSION
38
* @brief RTCP XR extension to RTCP session
41
* PJMEDIA implements subsets of RTCP XR specification (RFC 3611) to monitor
42
* the quality of the real-time media (audio/video) transmission.
46
* Enumeration of report types of RTCP XR. Useful for user to enable varying
47
* combinations of RTCP XR report blocks.
50
PJMEDIA_RTCP_XR_LOSS_RLE = (1 << 0),
51
PJMEDIA_RTCP_XR_DUP_RLE = (1 << 1),
52
PJMEDIA_RTCP_XR_RCPT_TIMES = (1 << 2),
53
PJMEDIA_RTCP_XR_RR_TIME = (1 << 3),
54
PJMEDIA_RTCP_XR_DLRR = (1 << 4),
55
PJMEDIA_RTCP_XR_STATS = (1 << 5),
56
PJMEDIA_RTCP_XR_VOIP_METRICS = (1 << 6)
57
} pjmedia_rtcp_xr_type;
60
* Enumeration of info need to be updated manually to RTCP XR. Most info
61
* could be updated automatically each time RTP received.
64
PJMEDIA_RTCP_XR_INFO_SIGNAL_LVL = 1,
65
PJMEDIA_RTCP_XR_INFO_NOISE_LVL = 2,
66
PJMEDIA_RTCP_XR_INFO_RERL = 3,
67
PJMEDIA_RTCP_XR_INFO_R_FACTOR = 4,
68
PJMEDIA_RTCP_XR_INFO_MOS_LQ = 5,
69
PJMEDIA_RTCP_XR_INFO_MOS_CQ = 6,
70
PJMEDIA_RTCP_XR_INFO_CONF_PLC = 7,
71
PJMEDIA_RTCP_XR_INFO_CONF_JBA = 8,
72
PJMEDIA_RTCP_XR_INFO_CONF_JBR = 9,
73
PJMEDIA_RTCP_XR_INFO_JB_NOM = 10,
74
PJMEDIA_RTCP_XR_INFO_JB_MAX = 11,
75
PJMEDIA_RTCP_XR_INFO_JB_ABS_MAX = 12
76
} pjmedia_rtcp_xr_info;
79
* Enumeration of PLC types definitions for RTCP XR report.
82
PJMEDIA_RTCP_XR_PLC_UNK = 0,
83
PJMEDIA_RTCP_XR_PLC_DIS = 1,
84
PJMEDIA_RTCP_XR_PLC_ENH = 2,
85
PJMEDIA_RTCP_XR_PLC_STD = 3
86
} pjmedia_rtcp_xr_plc_type;
89
* Enumeration of jitter buffer types definitions for RTCP XR report.
92
PJMEDIA_RTCP_XR_JB_UNKNOWN = 0,
93
PJMEDIA_RTCP_XR_JB_FIXED = 2,
94
PJMEDIA_RTCP_XR_JB_ADAPTIVE = 3
95
} pjmedia_rtcp_xr_jb_type;
101
* This type declares RTCP XR Report Header.
103
typedef struct pjmedia_rtcp_xr_rb_header
105
pj_uint8_t bt; /**< Block type. */
106
pj_uint8_t specific; /**< Block specific data. */
107
pj_uint16_t length; /**< Block length. */
108
} pjmedia_rtcp_xr_rb_header;
111
* This type declares RTCP XR Receiver Reference Time Report Block.
113
typedef struct pjmedia_rtcp_xr_rb_rr_time
115
pjmedia_rtcp_xr_rb_header header; /**< Block header. */
116
pj_uint32_t ntp_sec; /**< NTP time, seconds part. */
117
pj_uint32_t ntp_frac; /**< NTP time, fractions part. */
118
} pjmedia_rtcp_xr_rb_rr_time;
122
* This type declares RTCP XR DLRR Report Sub-block
124
typedef struct pjmedia_rtcp_xr_rb_dlrr_item
126
pj_uint32_t ssrc; /**< receiver SSRC */
127
pj_uint32_t lrr; /**< last receiver report */
128
pj_uint32_t dlrr; /**< delay since last receiver
130
} pjmedia_rtcp_xr_rb_dlrr_item;
133
* This type declares RTCP XR DLRR Report Block
135
typedef struct pjmedia_rtcp_xr_rb_dlrr
137
pjmedia_rtcp_xr_rb_header header; /**< Block header. */
138
pjmedia_rtcp_xr_rb_dlrr_item item; /**< Block contents,
139
variable length list */
140
} pjmedia_rtcp_xr_rb_dlrr;
143
* This type declares RTCP XR Statistics Summary Report Block
145
typedef struct pjmedia_rtcp_xr_rb_stats
147
pjmedia_rtcp_xr_rb_header header; /**< Block header. */
148
pj_uint32_t ssrc; /**< Receiver SSRC */
149
pj_uint16_t begin_seq; /**< Begin RTP sequence reported */
150
pj_uint16_t end_seq; /**< End RTP sequence reported */
151
pj_uint32_t lost; /**< Number of packet lost in this
153
pj_uint32_t dup; /**< Number of duplicated packet in
155
pj_uint32_t jitter_min; /**< Minimum jitter in this interval */
156
pj_uint32_t jitter_max; /**< Maximum jitter in this interval */
157
pj_uint32_t jitter_mean; /**< Average jitter in this interval */
158
pj_uint32_t jitter_dev; /**< Jitter deviation in this
160
pj_uint32_t toh_min:8; /**< Minimum ToH in this interval */
161
pj_uint32_t toh_max:8; /**< Maximum ToH in this interval */
162
pj_uint32_t toh_mean:8; /**< Average ToH in this interval */
163
pj_uint32_t toh_dev:8; /**< ToH deviation in this interval */
164
} pjmedia_rtcp_xr_rb_stats;
167
* This type declares RTCP XR VoIP Metrics Report Block
169
typedef struct pjmedia_rtcp_xr_rb_voip_mtc
171
pjmedia_rtcp_xr_rb_header header; /**< Block header. */
172
pj_uint32_t ssrc; /**< Receiver SSRC */
173
pj_uint8_t loss_rate; /**< Packet loss rate */
174
pj_uint8_t discard_rate; /**< Packet discarded rate */
175
pj_uint8_t burst_den; /**< Burst density */
176
pj_uint8_t gap_den; /**< Gap density */
177
pj_uint16_t burst_dur; /**< Burst duration */
178
pj_uint16_t gap_dur; /**< Gap duration */
179
pj_uint16_t rnd_trip_delay;/**< Round trip delay */
180
pj_uint16_t end_sys_delay; /**< End system delay */
181
pj_uint8_t signal_lvl; /**< Signal level */
182
pj_uint8_t noise_lvl; /**< Noise level */
183
pj_uint8_t rerl; /**< Residual Echo Return Loss */
184
pj_uint8_t gmin; /**< The gap threshold */
185
pj_uint8_t r_factor; /**< Voice quality metric carried
186
over this RTP session */
187
pj_uint8_t ext_r_factor; /**< Voice quality metric carried
188
outside of this RTP session*/
189
pj_uint8_t mos_lq; /**< Mean Opinion Score for
191
pj_uint8_t mos_cq; /**< Mean Opinion Score for
192
Conversation Quality */
193
pj_uint8_t rx_config; /**< Receiver configuration */
194
pj_uint8_t reserved2; /**< Not used */
195
pj_uint16_t jb_nom; /**< Current delay by jitter
197
pj_uint16_t jb_max; /**< Maximum delay by jitter
199
pj_uint16_t jb_abs_max; /**< Maximum possible delay by
201
} pjmedia_rtcp_xr_rb_voip_mtc;
204
* This structure declares RTCP XR (Extended Report) packet.
206
typedef struct pjmedia_rtcp_xr_pkt
209
#if defined(PJ_IS_BIG_ENDIAN) && PJ_IS_BIG_ENDIAN!=0
210
unsigned version:2; /**< packet type */
211
unsigned p:1; /**< padding flag */
212
unsigned count:5; /**< varies by payload type */
213
unsigned pt:8; /**< payload type */
215
unsigned count:5; /**< varies by payload type */
216
unsigned p:1; /**< padding flag */
217
unsigned version:2; /**< packet type */
218
unsigned pt:8; /**< payload type */
220
unsigned length:16; /**< packet length */
221
pj_uint32_t ssrc; /**< SSRC identification */
224
pj_int8_t buf[PJMEDIA_MAX_MTU];/**< Content buffer */
225
} pjmedia_rtcp_xr_pkt;
231
* This structure describes RTCP XR statitic.
233
typedef struct pjmedia_rtcp_xr_stream_stat
236
pj_time_val update; /**< Time of last update. */
238
pj_uint32_t begin_seq; /**< Begin # seq of this interval. */
239
pj_uint32_t end_seq; /**< End # seq of this interval. */
240
unsigned count; /**< Number of packets. */
243
* Flags represent whether the such report is valid/updated
245
unsigned l:1; /**< Lost flag */
246
unsigned d:1; /**< Duplicated flag */
247
unsigned j:1; /**< Jitter flag */
248
unsigned t:2; /**< TTL or Hop Limit,
249
0=none, 1=TTL, 2=HL */
251
unsigned lost; /**< Number of packets lost */
252
unsigned dup; /**< Number of duplicated packets */
253
pj_math_stat jitter; /**< Jitter statistics (in usec) */
254
pj_math_stat toh; /**< TTL of hop limit statistics. */
258
pj_time_val update; /**< Time of last update. */
260
pj_uint8_t loss_rate; /**< Packet loss rate */
261
pj_uint8_t discard_rate; /**< Packet discarded rate */
262
pj_uint8_t burst_den; /**< Burst density */
263
pj_uint8_t gap_den; /**< Gap density */
264
pj_uint16_t burst_dur; /**< Burst duration */
265
pj_uint16_t gap_dur; /**< Gap duration */
266
pj_uint16_t rnd_trip_delay; /**< Round trip delay */
267
pj_uint16_t end_sys_delay; /**< End system delay */
268
pj_int8_t signal_lvl; /**< Signal level */
269
pj_int8_t noise_lvl; /**< Noise level */
270
pj_uint8_t rerl; /**< Residual Echo Return Loss */
271
pj_uint8_t gmin; /**< The gap threshold */
272
pj_uint8_t r_factor; /**< Voice quality metric carried
273
over this RTP session */
274
pj_uint8_t ext_r_factor; /**< Voice quality metric carried
275
outside of this RTP session*/
276
pj_uint8_t mos_lq; /**< Mean Opinion Score for
278
pj_uint8_t mos_cq; /**< Mean Opinion Score for
279
Conversation Quality */
280
pj_uint8_t rx_config; /**< Receiver configuration */
281
pj_uint16_t jb_nom; /**< Current delay by jitter
283
pj_uint16_t jb_max; /**< Maximum delay by jitter
285
pj_uint16_t jb_abs_max; /**< Maximum possible delay by
289
} pjmedia_rtcp_xr_stream_stat;
291
typedef struct pjmedia_rtcp_xr_stat
293
pjmedia_rtcp_xr_stream_stat rx; /**< Decoding direction statistics. */
294
pjmedia_rtcp_xr_stream_stat tx; /**< Encoding direction statistics. */
295
pj_math_stat rtt; /**< Round-trip delay stat (in usec)
296
the value is calculated from
298
} pjmedia_rtcp_xr_stat;
301
* Forward declaration of RTCP session
303
struct pjmedia_rtcp_session;
306
* RTCP session is used to monitor the RTP session of one endpoint. There
307
* should only be one RTCP session for a bidirectional RTP streams.
309
struct pjmedia_rtcp_xr_session
311
char *name; /**< Name identification. */
312
pjmedia_rtcp_xr_pkt pkt; /**< Cached RTCP XR packet. */
314
pj_uint32_t rx_lrr; /**< NTP ts in last RR received. */
315
pj_timestamp rx_lrr_time;/**< Time when last RR is received. */
316
pj_uint32_t rx_last_rr; /**< # pkt received since last
319
pjmedia_rtcp_xr_stat stat; /**< RTCP XR statistics. */
321
/* The reference sequence number is an extended sequence number
322
* that serves as the basis for determining whether a new 16 bit
323
* sequence number comes earlier or later in the 32 bit sequence
326
pj_uint32_t src_ref_seq;
327
pj_bool_t uninitialized_src_ref_seq;
329
/* This structure contains variables needed for calculating
335
pj_uint32_t loss_count;
336
pj_uint32_t discard_count;
345
unsigned ptime; /**< Packet time. */
346
unsigned frames_per_packet; /**< # frames per packet. */
348
struct pjmedia_rtcp_session *rtcp_session;
349
/**< Parent/RTCP session. */
352
typedef struct pjmedia_rtcp_xr_session pjmedia_rtcp_xr_session;
355
* Build an RTCP XR packet which contains one or more RTCP XR report blocks.
356
* There are seven report types as defined in RFC 3611.
358
* @param session The RTCP XR session.
359
* @param rpt_types Report types to be included in the packet, report types
360
* are defined in pjmedia_rtcp_xr_type, set this to zero
361
* will make this function build all reports appropriately.
362
* @param rtcp_pkt Upon return, it will contain pointer to the RTCP XR packet.
363
* @param len Upon return, it will indicate the size of the generated
366
PJ_DECL(void) pjmedia_rtcp_build_rtcp_xr( pjmedia_rtcp_xr_session *session,
368
void **rtcp_pkt, int *len);
371
* Call this function to manually update some info needed by RTCP XR to
372
* generate report which could not be populated directly when receiving
375
* @param session The RTCP XR session.
376
* @param info Info type to be updated, @see pjmedia_rtcp_xr_info.
379
PJ_DECL(pj_status_t) pjmedia_rtcp_xr_update_info(
380
pjmedia_rtcp_xr_session *session,
389
* This function is called internally by RTCP session when RTCP XR is enabled
390
* to initialize the RTCP XR session.
392
* @param session RTCP XR session.
393
* @param r_session RTCP session.
394
* @param gmin Gmin value (defined in RFC 3611), set to 0 for default (16).
395
* @param frames_per_packet
396
Number of frames per packet.
398
void pjmedia_rtcp_xr_init( pjmedia_rtcp_xr_session *session,
399
struct pjmedia_rtcp_session *r_session,
401
unsigned frames_per_packet);
404
* This function is called internally by RTCP session to destroy
405
* the RTCP XR session.
407
* @param session RTCP XR session.
409
void pjmedia_rtcp_xr_fini( pjmedia_rtcp_xr_session *session );
412
* This function is called internally by RTCP session when it receives
413
* incoming RTCP XR packets.
415
* @param session RTCP XR session.
416
* @param rtcp_pkt The received RTCP XR packet.
417
* @param size Size of the incoming packet.
419
void pjmedia_rtcp_xr_rx_rtcp_xr( pjmedia_rtcp_xr_session *session,
420
const void *rtcp_pkt,
424
* This function is called internally by RTCP session whenever an RTP packet
425
* is received or lost to let the RTCP XR session update its statistics.
426
* Data passed to this function is a result of analyzation by RTCP and the
427
* jitter buffer. Whenever some info is available, the value should be zero
428
* or more (no negative info), otherwise if info is not available the info
429
* should be -1 so no update will be done for this info in the RTCP XR session.
431
* @param session RTCP XR session.
432
* @param seq Sequence number of RTP packet.
433
* @param lost Info if this packet is lost.
434
* @param dup Info if this packet is a duplication.
435
* @param discarded Info if this packet is discarded
436
* (not because of duplication).
437
* @param jitter Info jitter of this packet.
438
* @param toh Info Time To Live or Hops Limit of this packet.
439
* @param toh_ipv4 Set PJ_TRUE if packet is transported over IPv4.
441
void pjmedia_rtcp_xr_rx_rtp( pjmedia_rtcp_xr_session *session,
447
int toh, pj_bool_t toh_ipv4);
450
* This function is called internally by RTCP session whenever an RTP
451
* packet is sent to let the RTCP XR session do its internal calculations.
453
* @param session RTCP XR session.
454
* @param ptsize Size of RTP payload being sent.
456
void pjmedia_rtcp_xr_tx_rtp( pjmedia_rtcp_xr_session *session,
466
#endif /* __PJMEDIA_RTCP_XR_H__ */