gst-libs/gst/rtp/gstrtcpbuffer.h

   1 /* GStreamer
   2  * Copyright (C) <2007> Wim Taymans <wim@fluendo.com>
   3  *
   4  * gstrtcpbuffer.h: various helper functions to manipulate buffers
   5  *     with RTCP payload.
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 #ifndef __GST_RTCPBUFFER_H__
  24 #define __GST_RTCPBUFFER_H__
  25
  26 #include <gst/gst.h>
  27
  28 G_BEGIN_DECLS
  29
  30 /**
  31  * GST_RTCP_VERSION:
  32  *
  33  * The supported RTCP version 2.
  34  */
  35 #define GST_RTCP_VERSION 2
  36
  37 /**
  38  * GstRTCPType:
  39  * @GST_RTCP_TYPE_INVALID: Invalid type
  40  * @GST_RTCP_TYPE_SR: Sender report
  41  * @GST_RTCP_TYPE_RR: Receiver report
  42  * @GST_RTCP_TYPE_SDES: Source description
  43  * @GST_RTCP_TYPE_BYE: Goodbye
  44  * @GST_RTCP_TYPE_APP: Application defined
  45  * @GST_RTCP_TYPE_RTPFB: Transport layer feedback. Since: 0.10.23
  46  * @GST_RTCP_TYPE_PSFB: Payload-specific feedback. Since: 0.10.23
  47  *
  48  * Different RTCP packet types.
  49  */
  50 typedef enum
  51 {
  52   GST_RTCP_TYPE_INVALID = 0,
  53   GST_RTCP_TYPE_SR      = 200,
  54   GST_RTCP_TYPE_RR      = 201,
  55   GST_RTCP_TYPE_SDES    = 202,
  56   GST_RTCP_TYPE_BYE     = 203,
  57   GST_RTCP_TYPE_APP     = 204,
  58   GST_RTCP_TYPE_RTPFB   = 205,
  59   GST_RTCP_TYPE_PSFB    = 206
  60 } GstRTCPType;
  61
  62 /**
  63  * GstRTCPFBType:
  64  * @GST_RTCP_FB_TYPE_INVALID: Invalid type
  65  * @GST_RTCP_RTPFB_TYPE_NACK: Generic NACK
  66  * @GST_RTCP_RTPFB_TYPE_TMMBR: Temporary Maximum Media Stream Bit Rate Request
  67  * @GST_RTCP_RTPFB_TYPE_TMMBN: Temporary Maximum Media Stream Bit Rate
  68  *    Notification
  69  * @GST_RTCP_PSFB_TYPE_PLI: Picture Loss Indication
  70  * @GST_RTCP_PSFB_TYPE_SLI: Slice Loss Indication
  71  * @GST_RTCP_PSFB_TYPE_RPSI: Reference Picture Selection Indication
  72  * @GST_RTCP_PSFB_TYPE_AFB: Application layer Feedback
  73  * @GST_RTCP_PSFB_TYPE_FIR: Full Intra Request Command
  74  * @GST_RTCP_PSFB_TYPE_TSTR: Temporal-Spatial Trade-off Request
  75  * @GST_RTCP_PSFB_TYPE_TSTN: Temporal-Spatial Trade-off Notification
  76  * @GST_RTCP_PSFB_TYPE_VBCN: Video Back Channel Message
  77  *
  78  * Different types of feedback messages.
  79  *
  80  * Since: 0.10.23
  81  */
  82 typedef enum
  83 {
  84   /* generic */
  85   GST_RTCP_FB_TYPE_INVALID    = 0,
  86   /* RTPFB types */
  87   GST_RTCP_RTPFB_TYPE_NACK    = 1,
  88   /* RTPFB types assigned in RFC 5104 */
  89   GST_RTCP_RTPFB_TYPE_TMMBR   = 3,
  90   GST_RTCP_RTPFB_TYPE_TMMBN   = 4,
  91   /* PSFB types */
  92   GST_RTCP_PSFB_TYPE_PLI      = 1,
  93   GST_RTCP_PSFB_TYPE_SLI      = 2,
  94   GST_RTCP_PSFB_TYPE_RPSI     = 3,
  95   GST_RTCP_PSFB_TYPE_AFB      = 15,
  96   /* PSFB types assigned in RFC 5104 */
  97   GST_RTCP_PSFB_TYPE_FIR      = 4,
  98   GST_RTCP_PSFB_TYPE_TSTR     = 5,
  99   GST_RTCP_PSFB_TYPE_TSTN     = 6,
 100   GST_RTCP_PSFB_TYPE_VBCN     = 7,
 101 } GstRTCPFBType;
 102
 103 /**
 104  * GstRTCPSDESType:
 105  * @GST_RTCP_SDES_INVALID: Invalid SDES entry
 106  * @GST_RTCP_SDES_END: End of SDES list
 107  * @GST_RTCP_SDES_CNAME: Canonical name
 108  * @GST_RTCP_SDES_NAME: User name
 109  * @GST_RTCP_SDES_EMAIL: User's electronic mail address
 110  * @GST_RTCP_SDES_PHONE: User's phone number
 111  * @GST_RTCP_SDES_LOC: Geographic user location
 112  * @GST_RTCP_SDES_TOOL: Name of application or tool
 113  * @GST_RTCP_SDES_NOTE: Notice about the source
 114  * @GST_RTCP_SDES_PRIV: Private extensions
 115  *
 116  * Different types of SDES content.
 117  */
 118 typedef enum
 119 {
 120   GST_RTCP_SDES_INVALID  = -1,
 121   GST_RTCP_SDES_END      = 0,
 122   GST_RTCP_SDES_CNAME    = 1,
 123   GST_RTCP_SDES_NAME     = 2,
 124   GST_RTCP_SDES_EMAIL    = 3,
 125   GST_RTCP_SDES_PHONE    = 4,
 126   GST_RTCP_SDES_LOC      = 5,
 127   GST_RTCP_SDES_TOOL     = 6,
 128   GST_RTCP_SDES_NOTE     = 7,
 129   GST_RTCP_SDES_PRIV     = 8
 130 } GstRTCPSDESType;
 131
 132 /**
 133  * GST_RTCP_MAX_SDES:
 134  *
 135  * The maximum text length for an SDES item.
 136  */
 137 #define GST_RTCP_MAX_SDES 255
 138
 139 /**
 140  * GST_RTCP_MAX_RB_COUNT:
 141  *
 142  * The maximum amount of Receiver report blocks in RR and SR messages.
 143  */
 144 #define GST_RTCP_MAX_RB_COUNT   31
 145
 146 /**
 147  * GST_RTCP_MAX_SDES_ITEM_COUNT:
 148  *
 149  * The maximum amount of SDES items.
 150  */
 151 #define GST_RTCP_MAX_SDES_ITEM_COUNT   31
 152
 153 /**
 154  * GST_RTCP_MAX_BYE_SSRC_COUNT:
 155  *
 156  * The maximum amount of SSRCs in a BYE packet.
 157  */
 158 #define GST_RTCP_MAX_BYE_SSRC_COUNT   31
 159
 160 /**
 161  * GST_RTCP_VALID_MASK:
 162  *
 163  * Mask for version, padding bit and packet type pair
 164  */
 165 #define GST_RTCP_VALID_MASK (0xc000 | 0x2000 | 0xfe)
 166 /**
 167  * GST_RTCP_VALID_VALUE:
 168  *
 169  * Valid value for the first two bytes of an RTCP packet after applying
 170  * #GST_RTCP_VALID_MASK to them.
 171  */
 172 #define GST_RTCP_VALID_VALUE ((GST_RTCP_VERSION << 14) | GST_RTCP_TYPE_SR)
 173
 174 typedef struct _GstRTCPPacket GstRTCPPacket;
 175
 176 /**
 177  * GstRTCPPacket:
 178  * @buffer: pointer to RTCP buffer
 179  * @offset: offset of packet in buffer data
 180  *
 181  * Data structure that points to a packet at @offset in @buffer.
 182  * The size of the structure is made public to allow stack allocations.
 183  */
 184 struct _GstRTCPPacket
 185 {
 186   GstBuffer   *buffer;
 187   guint        offset;
 188
 189   /*< private >*/
 190   gboolean     padding;      /* padding field of current packet */
 191   guint8       count;        /* count field of current packet */
 192   GstRTCPType  type;         /* type of current packet */
 193   guint16      length;       /* length of current packet in 32-bits words */
 194
 195   guint        item_offset;  /* current item offset for navigating SDES */
 196   guint        item_count;   /* current item count */
 197   guint        entry_offset; /* current entry offset for navigating SDES items */
 198 };
 199
 200 /* creating buffers */
 201 GstBuffer*      gst_rtcp_buffer_new_take_data     (gpointer data, guint len);
 202 GstBuffer*      gst_rtcp_buffer_new_copy_data     (gpointer data, guint len);
 203
 204 gboolean        gst_rtcp_buffer_validate_data     (guint8 *data, guint len);
 205 gboolean        gst_rtcp_buffer_validate          (GstBuffer *buffer);
 206
 207 GstBuffer*      gst_rtcp_buffer_new               (guint mtu);
 208 void            gst_rtcp_buffer_end               (GstBuffer *buffer);
 209
 210 /* adding/retrieving packets */
 211 guint           gst_rtcp_buffer_get_packet_count  (GstBuffer *buffer);
 212 gboolean        gst_rtcp_buffer_get_first_packet  (GstBuffer *buffer, GstRTCPPacket *packet);
 213 gboolean        gst_rtcp_packet_move_to_next      (GstRTCPPacket *packet);
 214
 215 gboolean        gst_rtcp_buffer_add_packet        (GstBuffer *buffer, GstRTCPType type,
 216                                                    GstRTCPPacket *packet);
 217 gboolean        gst_rtcp_packet_remove            (GstRTCPPacket *packet);
 218
 219 /* working with packets */
 220 gboolean        gst_rtcp_packet_get_padding       (GstRTCPPacket *packet);
 221 guint8          gst_rtcp_packet_get_count         (GstRTCPPacket *packet);
 222 GstRTCPType     gst_rtcp_packet_get_type          (GstRTCPPacket *packet);
 223 guint16         gst_rtcp_packet_get_length        (GstRTCPPacket *packet);
 224
 225
 226 /* sender reports */
 227 void            gst_rtcp_packet_sr_get_sender_info    (GstRTCPPacket *packet, guint32 *ssrc,
 228                                                        guint64 *ntptime, guint32 *rtptime,
 229                                                        guint32 *packet_count, guint32 *octet_count);
 230 void            gst_rtcp_packet_sr_set_sender_info    (GstRTCPPacket *packet, guint32 ssrc,
 231                                                        guint64 ntptime, guint32 rtptime,
 232                                                        guint32 packet_count, guint32 octet_count);
 233 /* receiver reports */
 234 guint32         gst_rtcp_packet_rr_get_ssrc           (GstRTCPPacket *packet);
 235 void            gst_rtcp_packet_rr_set_ssrc           (GstRTCPPacket *packet, guint32 ssrc);
 236
 237
 238 /* report blocks for SR and RR */
 239 guint           gst_rtcp_packet_get_rb_count          (GstRTCPPacket *packet);
 240 void            gst_rtcp_packet_get_rb                (GstRTCPPacket *packet, guint nth, guint32 *ssrc,
 241                                                        guint8 *fractionlost, gint32 *packetslost,
 242                                                        guint32 *exthighestseq, guint32 *jitter,
 243                                                        guint32 *lsr, guint32 *dlsr);
 244 gboolean        gst_rtcp_packet_add_rb                (GstRTCPPacket *packet, guint32 ssrc,
 245                                                        guint8 fractionlost, gint32 packetslost,
 246                                                        guint32 exthighestseq, guint32 jitter,
 247                                                        guint32 lsr, guint32 dlsr);
 248 void            gst_rtcp_packet_set_rb                (GstRTCPPacket *packet, guint nth, guint32 ssrc,
 249                                                        guint8 fractionlost, gint32 packetslost,
 250                                                        guint32 exthighestseq, guint32 jitter,
 251                                                        guint32 lsr, guint32 dlsr);
 252
 253 /* source description packet */
 254 guint           gst_rtcp_packet_sdes_get_item_count   (GstRTCPPacket *packet);
 255 gboolean        gst_rtcp_packet_sdes_first_item       (GstRTCPPacket *packet);
 256 gboolean        gst_rtcp_packet_sdes_next_item        (GstRTCPPacket *packet);
 257 guint32         gst_rtcp_packet_sdes_get_ssrc         (GstRTCPPacket *packet);
 258 gboolean        gst_rtcp_packet_sdes_first_entry      (GstRTCPPacket *packet);
 259 gboolean        gst_rtcp_packet_sdes_next_entry       (GstRTCPPacket *packet);
 260 gboolean        gst_rtcp_packet_sdes_get_entry        (GstRTCPPacket *packet,
 261                                                        GstRTCPSDESType *type, guint8 *len,
 262                                                        guint8 **data);
 263 gboolean        gst_rtcp_packet_sdes_copy_entry       (GstRTCPPacket *packet,
 264                                                        GstRTCPSDESType *type, guint8 *len,
 265                                                        guint8 **data);
 266
 267 gboolean        gst_rtcp_packet_sdes_add_item         (GstRTCPPacket *packet, guint32 ssrc);
 268 gboolean        gst_rtcp_packet_sdes_add_entry        (GstRTCPPacket *packet, GstRTCPSDESType type,
 269                                                        guint8 len, const guint8 *data);
 270
 271 /* bye packet */
 272 guint           gst_rtcp_packet_bye_get_ssrc_count    (GstRTCPPacket *packet);
 273 guint32         gst_rtcp_packet_bye_get_nth_ssrc      (GstRTCPPacket *packet, guint nth);
 274 gboolean        gst_rtcp_packet_bye_add_ssrc          (GstRTCPPacket *packet, guint32 ssrc);
 275 gboolean        gst_rtcp_packet_bye_add_ssrcs         (GstRTCPPacket *packet, guint32 *ssrc, guint len);
 276 guint8          gst_rtcp_packet_bye_get_reason_len    (GstRTCPPacket *packet);
 277 gchar*          gst_rtcp_packet_bye_get_reason        (GstRTCPPacket *packet);
 278 gboolean        gst_rtcp_packet_bye_set_reason        (GstRTCPPacket *packet, const gchar *reason);
 279
 280 /* feedback packets */
 281 guint32         gst_rtcp_packet_fb_get_sender_ssrc    (GstRTCPPacket *packet);
 282 void            gst_rtcp_packet_fb_set_sender_ssrc    (GstRTCPPacket *packet, guint32 ssrc);
 283 guint32         gst_rtcp_packet_fb_get_media_ssrc     (GstRTCPPacket *packet);
 284 void            gst_rtcp_packet_fb_set_media_ssrc     (GstRTCPPacket *packet, guint32 ssrc);
 285 GstRTCPFBType   gst_rtcp_packet_fb_get_type           (GstRTCPPacket *packet);
 286 void            gst_rtcp_packet_fb_set_type           (GstRTCPPacket *packet, GstRTCPFBType type);
 287 guint16         gst_rtcp_packet_fb_get_fci_length     (GstRTCPPacket *packet);
 288 gboolean        gst_rtcp_packet_fb_set_fci_length     (GstRTCPPacket *packet, guint16 wordlen);
 289 guint8 *        gst_rtcp_packet_fb_get_fci            (GstRTCPPacket *packet);
 290
 291 /* helper functions */
 292 guint64         gst_rtcp_ntp_to_unix                  (guint64 ntptime);
 293 guint64         gst_rtcp_unix_to_ntp                  (guint64 unixtime);
 294
 295 const gchar *   gst_rtcp_sdes_type_to_name            (GstRTCPSDESType type);
 296 GstRTCPSDESType gst_rtcp_sdes_name_to_type            (const gchar *name);
 297
 298 G_END_DECLS
 299
 300 #endif /* __GST_RTCPBUFFER_H__ */
 301