git.sesse.net Git - vlc/blob - modules/mux/rtp/rtcp.h

   1 /*****************************************************************************
   2  * rtcp.h: RTP/RTCP headerfile
   3  *****************************************************************************
   4  * Copyright (C) 2005-2007 M2X
   5  *
   6  * $Id$
   7  *
   8  * Authors: Jean-Paul Saman <jpsaman #_at_# videolan dot org>
   9  *
  10  * This program is free software; you can redistribute it and/or modify
  11  * it under the terms of the GNU General Public License as published by
  12  * the Free Software Foundation; either version 2 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License
  21  * along with this program; if not, write to the Free Software
  22  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
  23  *****************************************************************************/
  24
  25 #ifndef _RTCP_H
  26 #define _RTCP_H 1
  27
  28 /* RTCP packet types */
  29 #define RTCP_SR     200
  30 #define RTCP_RR     201
  31 #define RTCP_SDES   202
  32 #define RTCP_BYE    203
  33 #define RTCP_APP    204
  34 /* End of RTCP packet types */
  35
  36 /* SDES type */
  37 #define RTCP_SDES_CNAME 1
  38 #define RTCP_SDES_NAME  2
  39 #define RTCP_SDES_EMAIL 3
  40 #define RTCP_SDES_PHONE 4
  41 #define RTCP_SDES_LOC   5
  42 #define RTCP_SDES_TOOL  6
  43 #define RTCP_SDES_NOTE  7
  44 #define RTCP_SDES_PRIV  8
  45 /* End of SDES type */
  46
  47 #define RTCP_HEADER_LEN 3
  48
  49 typedef enum rtcp_event_enum
  50 {
  51     EVENT_BYE,
  52     EVENT_REPORT
  53
  54 } rtcp_event_t;
  55
  56 typedef struct
  57 {
  58     uint32_t ntp_timestampH;
  59     uint32_t ntp_timestampL;
  60     uint32_t rtp_timestamp;
  61     uint32_t u_pkt_count;
  62     uint32_t u_octet_count;
  63
  64 } rtcp_SR_t;
  65
  66 typedef struct
  67 {
  68
  69 } rtcp_RR_t;
  70
  71 typedef struct SDES_item_t
  72 {
  73     uint32_t       i_index;     /*< index */
  74     uint8_t        u_type;      /*< type field */
  75     char           *psz_data;    /*< null terminated string */
  76
  77 } rtcp_SDES_item_t;
  78
  79 typedef struct
  80 {
  81     uint32_t    u_length;        /*< length of packet */
  82     uint32_t    u_items;         /*< number of SDES_items */
  83     rtcp_SDES_item_t **pp_items; /*< list of SDES_items */
  84
  85 } rtcp_SDES_t;
  86
  87 typedef struct
  88 {
  89     uint32_t u_length;        /*< length of packet */
  90
  91 } rtcp_BYE_t;
  92
  93 typedef struct
  94 {
  95     uint32_t u_length;        /*< length of packet */
  96     uint32_t u_prefix_len;    /*< length of prefix data */
  97     unsigned char *psz_prefix;/*< prefix string (null terminated) */
  98     unsigned char *psz_data;  /*< data string (null terminated) */
  99
 100 } rtcp_APP_t;
 101
 102 /**
 103  * structure rtcp_stats_t
 104  */
 105 typedef struct
 106 {
 107     uint32_t  u_RR_received;   /*< RR records received */
 108     uint32_t  u_SR_received;   /*< SR records received */
 109     uint64_t  l_dest_SSRC;     /*< SSRC of first source */
 110     uint32_t  u_pkt_count;     /*< count of packets received */
 111     uint32_t  u_octet_count;   /*< ? */
 112     uint32_t  u_pkt_lost;      /*< cumulative count of packets lost */
 113     uint8_t   u_fraction_lost; /*< count of fractional packets lost */
 114     uint32_t  u_highest_seq_no;/*< highest sequence number found */
 115     uint32_t  u_jitter;        /*< inter arrival jitter calculated */
 116     uint32_t  u_last_SR;       /*< last SR record received */
 117     uint32_t  u_last_RR;       /*< last RR record received */
 118     mtime_t   u_delay_since_last_SR; /*< delay since last SR record received */
 119     mtime_t   u_delay_since_last_RR; /*< delay since last RR record received */
 120
 121     uint64_t  u_avg_pkt_size;  /*< average RTCP packet size */
 122     uint64_t  u_sent_pkt_size; /*< RTCP packet size sent */
 123
 124 } rtcp_stats_t;
 125
 126 typedef struct
 127 {
 128     uint32_t u_version;        /*< RTCP version number */
 129     vlc_bool_t b_padding;      /*< indicates if packets has padding */
 130     uint32_t u_report;         /*< reception packet count */
 131     uint32_t u_payload_type;   /*< type of RTCP payload */
 132     uint32_t u_length;         /*< length of packet */
 133     uint32_t u_ssrc;           /*< channel name this packet belongs to */
 134
 135     union {
 136         rtcp_SR_t sr;                /*< SR record */
 137         rtcp_RR_t rr;                /*< RR record */
 138         rtcp_SDES_t sdes;            /*< SDES record */
 139         rtcp_BYE_t bye;              /*< BYE record */
 140         rtcp_APP_t app;              /*< APP record */
 141     } report;
 142
 143 } rtcp_pkt_t;
 144
 145 typedef struct rtcp_client_t
 146 {
 147     int fd;                        /*< socket descriptor of rtcp stream */
 148
 149     uint32_t    i_index;
 150     uint32_t    u_ssrc;            /*< channel name */
 151     vlc_bool_t  b_deleted;         /*< channel deleted ? */
 152     mtime_t     i_timeout;         /*< remove timeout before real deletion,
 153                                     * this is recommended by RFC 3550 at
 154                                     * page 27 to ignore out-of-order packets.
 155                                     */
 156     rtcp_stats_t *p_stats;         /*< RTCP statistics */
 157
 158     uint32_t         i_items;      /*< count of SDES item structures */
 159     rtcp_SDES_item_t **pp_sdes;    /*< SDES client items */
 160 } rtcp_client_t;
 161
 162 /**
 163  * structure rtcp_t
 164  * This structure is a VLC_OBJECT and holds RTCP statistical information.
 165  */
 166 typedef struct rtcp_t
 167 {
 168     VLC_COMMON_MEMBERS
 169
 170     uint32_t u_clients;            /*< number of clients connected */
 171     uint32_t u_active;             /*< number of active senders */
 172     uint32_t u_members;            /*< number of clients in previous interval */
 173
 174     mtime_t i_date;                 /*< current RTCP packet interval */
 175     mtime_t i_last_date;            /*< previous RTCP packet interval */
 176     mtime_t i_next_date;            /*< next scheduled transmision time
 177                                         of RTCP packet */
 178
 179     uint32_t i_clients;            /*< count of clients structures */
 180     rtcp_client_t **pp_clients;    /*< RTCP clients */
 181
 182     /* bitstream data pointer used for decoding */
 183     bs_t    *bs;                   /*< bitstream decoding data pointer */
 184
 185     /* functions */
 186     int (*pf_add_client)( vlc_object_t *p_this, uint32_t u_ssrc, uint32_t *i_pos );
 187     int (*pf_del_client)( vlc_object_t *p_this, uint32_t u_ssrc );
 188     int (*pf_find_client)( vlc_object_t *p_this, uint32_t u_ssrc, uint32_t *i_pos );
 189     int (*pf_cleanup_clients)( vlc_object_t *p_this );
 190     int (*pf_destroy_clients)( vlc_object_t *p_this );
 191 } rtcp_t;
 192
 193 int rtcp_add_client( vlc_object_t *p_this, uint32_t u_ssrc, uint32_t *i_pos );
 194 int rtcp_del_client( vlc_object_t *p_this, uint32_t u_ssrc );
 195 /* Should be called with vlc_mutex_lock( &p_this->objec_lock ) held */
 196 int rtcp_find_client( vlc_object_t *p_this, uint32_t u_ssrc, uint32_t *i_pos );
 197 int rtcp_cleanup_clients( vlc_object_t *p_this );
 198 int rtcp_destroy_clients( vlc_object_t *p_this );
 199
 200 /**
 201  * rtcp_cleanup_clients - Permanently remove clients from the list
 202  * Permanently delete struct rtcp_client_t from member list when it is there
 203  * time to be removed. RFC 3550 recommends a grace period of five times the
 204  * RTCP packet send/receive interval before permanent removal of session. This
 205  * is to ignore out of order packets for the same SSRC that arrive after the
 206  * BYE report for that SSRC has been received.
 207  * Arguments:
 208  * \param p_this    VLC_OBJECT_T of type rtcp_t
 209  */
 210 int rtcp_cleanup_clients( vlc_object_t *p_this );
 211 //VLC_EXPORT( int, rtcp_cleanup_clients, ( vlc_object_t * ) );
 212
 213 /**
 214  * rtcp_pkt_decode - Decode RTCP packet
 215  * Decode incoming RTCP packet and inspect the records types.
 216  * Arguments:
 217  * \param p_this
 218  * \param p_pkt
 219  * \param p_block
 220  */
 221 int rtcp_pkt_decode( vlc_object_t *p_this, rtcp_pkt_t *p_pkt, block_t *p_block );
 222 //VLC_EXPORT( int, rtcp_decode, ( rtcp_pkt_t *, block_t * ) );
 223
 224 /**
 225  * rtcp_pkt_new - Encode RTCP packet
 226  * Create a new RTCP packet of type 'type'
 227  * Arguments:
 228  * \param type  type of RTCP packet @see
 229  */
 230 rtcp_pkt_t *rtcp_pkt_new( vlc_object_t *p_this, int type );
 231 //VLC_EXPORT( block_t* , rtcp_encode, ( vlc_object_t *, int ) );
 232 void rtcp_pkt_del( vlc_object_t *p_this, rtcp_pkt_t *pkt );
 233
 234 block_t *rtcp_encode_SR( vlc_object_t *p_this, rtcp_pkt_t *p_pkt );
 235 block_t *rtcp_encode_RR( vlc_object_t *p_this, rtcp_pkt_t *p_pkt );
 236 block_t *rtcp_encode_SDES( vlc_object_t *p_this, rtcp_pkt_t *p_pkt );
 237 block_t *rtcp_encode_BYE( vlc_object_t *p_this, rtcp_pkt_t *p_pkt, char *psz_reason );
 238
 239 /**
 240  * rtcp_interval
 241  * Calculate the interval at which RTCP compound packets are going to be
 242  * sent or received.
 243  * Arguments:
 244  * \param p_this        VLC_OBJECT of type rtcp_t
 245  * \param u_bandwith    bandwidth of RTP connection
 246  * \param u_ssrc        client to sent or receive from
 247  * \param b_sender      are we the sender or the receiver
 248  * \param b_first       the first time this function is called use only half
 249  *                      of the initial waiting time
 250  */
 251 uint64_t rtcp_interval( vlc_object_t *p_this, uint64_t u_bandwidth, uint32_t u_ssrc,
 252                         vlc_bool_t b_sender, vlc_bool_t b_first );
 253
 254 /**
 255  * rtcp_expire
 256  * Decides to sent an RTCP report or a BYE record
 257  * Arguments:
 258  * \param p_this        VLC_OBJECT of type rtcp_t
 259  * \param u_bandwith    bandwidth of RTP connection
 260  * \param u_ssrc        client to sent or receive from
 261  * \param rtcp_event    type of event received
 262  * \param b_sender      are we the sender or the receiver
 263  * \param *b_first      the first time this function is called use only half
 264  *                      of the initial waiting time. If b_first is VLC_TRUE, then
 265  *                      it will return *b_first = VLC_FALSE;
 266  */
 267 void rtcp_expire( vlc_object_t *p_this, rtcp_event_t rtcp_event, uint64_t u_bandwidth,
 268                   uint32_t u_ssrc, vlc_bool_t b_sender, vlc_bool_t *b_first );
 269
 270 /**
 271  * rtcp_received
 272  * Determine what to do on the received Sender Report, decode it
 273  * or leave the channel (BYE record).
 274  * Arguments:
 275  * \param p_this        VLC_OBJECT of type rtcp_t
 276  * \param p_pkt         RTCP packet that was received
 277  * \param rtcp_event    type of event received
 278  */
 279 void rtcp_received( vlc_object_t *p_this, rtcp_pkt_t *pkt,
 280                     rtcp_event_t rtcp_event );
 281
 282 #endif /* RTCP_H */