Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjmedia / include / pjmedia / rtcp.h
1 /* $Id$ */
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__ */