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., 51 Franklin St, Fifth Floor,
  20  * Boston, MA 02110-1301, 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.
  46  * @GST_RTCP_TYPE_PSFB: Payload-specific feedback.
  47  * @GST_RTCP_TYPE_XR: Extended report.
  48  *
  49  * Different RTCP packet types.
  50  */
  51 typedef enum
  52 {
  53   GST_RTCP_TYPE_INVALID = 0,
  54   GST_RTCP_TYPE_SR      = 200,
  55   GST_RTCP_TYPE_RR      = 201,
  56   GST_RTCP_TYPE_SDES    = 202,
  57   GST_RTCP_TYPE_BYE     = 203,
  58   GST_RTCP_TYPE_APP     = 204,
  59   GST_RTCP_TYPE_RTPFB   = 205,
  60   GST_RTCP_TYPE_PSFB    = 206,
  61   GST_RTCP_TYPE_XR      = 207
  62 } GstRTCPType;
  63
  64 /* FIXME 2.0: backwards compatibility define for enum typo */
  65 #define GST_RTCP_RTPFB_TYPE_RCTP_SR_REQ GST_RTCP_RTPFB_TYPE_RTCP_SR_REQ
  66
  67 /**
  68  * GstRTCPFBType:
  69  * @GST_RTCP_FB_TYPE_INVALID: Invalid type
  70  * @GST_RTCP_RTPFB_TYPE_NACK: Generic NACK
  71  * @GST_RTCP_RTPFB_TYPE_TMMBR: Temporary Maximum Media Stream Bit Rate Request
  72  * @GST_RTCP_RTPFB_TYPE_TMMBN: Temporary Maximum Media Stream Bit Rate
  73  *    Notification
  74  * @GST_RTCP_RTPFB_TYPE_RTCP_SR_REQ: Request an SR packet for early
  75  *    synchronization
  76  * @GST_RTCP_PSFB_TYPE_PLI: Picture Loss Indication
  77  * @GST_RTCP_PSFB_TYPE_SLI: Slice Loss Indication
  78  * @GST_RTCP_PSFB_TYPE_RPSI: Reference Picture Selection Indication
  79  * @GST_RTCP_PSFB_TYPE_AFB: Application layer Feedback
  80  * @GST_RTCP_PSFB_TYPE_FIR: Full Intra Request Command
  81  * @GST_RTCP_PSFB_TYPE_TSTR: Temporal-Spatial Trade-off Request
  82  * @GST_RTCP_PSFB_TYPE_TSTN: Temporal-Spatial Trade-off Notification
  83  * @GST_RTCP_PSFB_TYPE_VBCN: Video Back Channel Message
  84  *
  85  * Different types of feedback messages.
  86  */
  87 typedef enum
  88 {
  89   /* generic */
  90   GST_RTCP_FB_TYPE_INVALID        = 0,
  91   /* RTPFB types */
  92   GST_RTCP_RTPFB_TYPE_NACK        = 1,
  93   /* RTPFB types assigned in RFC 5104 */
  94   GST_RTCP_RTPFB_TYPE_TMMBR       = 3,
  95   GST_RTCP_RTPFB_TYPE_TMMBN       = 4,
  96   /* RTPFB types assigned in RFC 6051 */
  97   GST_RTCP_RTPFB_TYPE_RTCP_SR_REQ = 5,
  98   /* PSFB types */
  99   GST_RTCP_PSFB_TYPE_PLI          = 1,
 100   GST_RTCP_PSFB_TYPE_SLI          = 2,
 101   GST_RTCP_PSFB_TYPE_RPSI         = 3,
 102   GST_RTCP_PSFB_TYPE_AFB          = 15,
 103   /* PSFB types assigned in RFC 5104 */
 104   GST_RTCP_PSFB_TYPE_FIR          = 4,
 105   GST_RTCP_PSFB_TYPE_TSTR         = 5,
 106   GST_RTCP_PSFB_TYPE_TSTN         = 6,
 107   GST_RTCP_PSFB_TYPE_VBCN         = 7,
 108 } GstRTCPFBType;
 109
 110 /**
 111  * GstRTCPSDESType:
 112  * @GST_RTCP_SDES_INVALID: Invalid SDES entry
 113  * @GST_RTCP_SDES_END: End of SDES list
 114  * @GST_RTCP_SDES_CNAME: Canonical name
 115  * @GST_RTCP_SDES_NAME: User name
 116  * @GST_RTCP_SDES_EMAIL: User's electronic mail address
 117  * @GST_RTCP_SDES_PHONE: User's phone number
 118  * @GST_RTCP_SDES_LOC: Geographic user location
 119  * @GST_RTCP_SDES_TOOL: Name of application or tool
 120  * @GST_RTCP_SDES_NOTE: Notice about the source
 121  * @GST_RTCP_SDES_PRIV: Private extensions
 122  *
 123  * Different types of SDES content.
 124  */
 125 typedef enum
 126 {
 127   GST_RTCP_SDES_INVALID  = -1,
 128   GST_RTCP_SDES_END      = 0,
 129   GST_RTCP_SDES_CNAME    = 1,
 130   GST_RTCP_SDES_NAME     = 2,
 131   GST_RTCP_SDES_EMAIL    = 3,
 132   GST_RTCP_SDES_PHONE    = 4,
 133   GST_RTCP_SDES_LOC      = 5,
 134   GST_RTCP_SDES_TOOL     = 6,
 135   GST_RTCP_SDES_NOTE     = 7,
 136   GST_RTCP_SDES_PRIV     = 8
 137 } GstRTCPSDESType;
 138
 139 /**
 140  * GST_RTCP_MAX_SDES:
 141  *
 142  * The maximum text length for an SDES item.
 143  */
 144 #define GST_RTCP_MAX_SDES 255
 145
 146 /**
 147  * GST_RTCP_MAX_RB_COUNT:
 148  *
 149  * The maximum amount of Receiver report blocks in RR and SR messages.
 150  */
 151 #define GST_RTCP_MAX_RB_COUNT   31
 152
 153 /**
 154  * GST_RTCP_MAX_SDES_ITEM_COUNT:
 155  *
 156  * The maximum amount of SDES items.
 157  */
 158 #define GST_RTCP_MAX_SDES_ITEM_COUNT   31
 159
 160 /**
 161  * GST_RTCP_MAX_BYE_SSRC_COUNT:
 162  *
 163  * The maximum amount of SSRCs in a BYE packet.
 164  */
 165 #define GST_RTCP_MAX_BYE_SSRC_COUNT   31
 166
 167 /**
 168  * GST_RTCP_VALID_MASK:
 169  *
 170  * Mask for version, padding bit and packet type pair
 171  */
 172 #define GST_RTCP_VALID_MASK (0xc000 | 0x2000 | 0xfe)
 173
 174 /**
 175  * GST_RTCP_REDUCED_SIZE_VALID_MASK:
 176  *
 177  * Mask for version, padding bit and packet type pair allowing reduced size
 178  * packets, basically it accepts other types than RR and SR
 179  */
 180 #define GST_RTCP_REDUCED_SIZE_VALID_MASK (0xc000 | 0x2000 | 0xf8)
 181
 182 /**
 183  * GST_RTCP_VALID_VALUE:
 184  *
 185  * Valid value for the first two bytes of an RTCP packet after applying
 186  * #GST_RTCP_VALID_MASK to them.
 187  */
 188 #define GST_RTCP_VALID_VALUE ((GST_RTCP_VERSION << 14) | GST_RTCP_TYPE_SR)
 189
 190 typedef struct _GstRTCPBuffer GstRTCPBuffer;
 191 typedef struct _GstRTCPPacket GstRTCPPacket;
 192
 193 struct _GstRTCPBuffer
 194 {
 195   GstBuffer   *buffer;
 196   GstMapInfo   map;
 197 };
 198
 199 #define GST_RTCP_BUFFER_INIT { NULL, GST_MAP_INFO_INIT }
 200
 201 /**
 202  * GstRTCPPacket:
 203  * @rtcp: pointer to RTCP buffer
 204  * @offset: offset of packet in buffer data
 205  *
 206  * Data structure that points to a packet at @offset in @buffer.
 207  * The size of the structure is made public to allow stack allocations.
 208  */
 209 struct _GstRTCPPacket
 210 {
 211   GstRTCPBuffer *rtcp;
 212   guint          offset;
 213
 214   /*< private >*/
 215   gboolean       padding;      /* padding field of current packet */
 216   guint8         count;        /* count field of current packet */
 217   GstRTCPType    type;         /* type of current packet */
 218   guint16        length;       /* length of current packet in 32-bits words */
 219
 220   guint          item_offset;  /* current item offset for navigating SDES */
 221   guint          item_count;   /* current item count */
 222   guint          entry_offset; /* current entry offset for navigating SDES items */
 223 };
 224
 225 /* creating buffers */
 226
 227 GST_EXPORT
 228 GstBuffer*      gst_rtcp_buffer_new_take_data     (gpointer data, guint len);
 229
 230 GST_EXPORT
 231 GstBuffer*      gst_rtcp_buffer_new_copy_data     (gconstpointer data, guint len);
 232
 233 GST_EXPORT
 234 gboolean        gst_rtcp_buffer_validate_data     (guint8 *data, guint len);
 235
 236 GST_EXPORT
 237 gboolean        gst_rtcp_buffer_validate          (GstBuffer *buffer);
 238
 239 GST_EXPORT
 240 gboolean        gst_rtcp_buffer_validate_data_reduced   (guint8 *data, guint len);
 241
 242 GST_EXPORT
 243 gboolean        gst_rtcp_buffer_validate_reduced        (GstBuffer *buffer);
 244
 245
 246 GST_EXPORT
 247 GstBuffer*      gst_rtcp_buffer_new               (guint mtu);
 248
 249 GST_EXPORT
 250 gboolean        gst_rtcp_buffer_map               (GstBuffer *buffer, GstMapFlags flags, GstRTCPBuffer *rtcp);
 251
 252 GST_EXPORT
 253 gboolean        gst_rtcp_buffer_unmap             (GstRTCPBuffer *rtcp);
 254
 255 /* adding/retrieving packets */
 256
 257 GST_EXPORT
 258 guint           gst_rtcp_buffer_get_packet_count  (GstRTCPBuffer *rtcp);
 259
 260 GST_EXPORT
 261 gboolean        gst_rtcp_buffer_get_first_packet  (GstRTCPBuffer *rtcp, GstRTCPPacket *packet);
 262
 263 GST_EXPORT
 264 gboolean        gst_rtcp_packet_move_to_next      (GstRTCPPacket *packet);
 265
 266 GST_EXPORT
 267 gboolean        gst_rtcp_buffer_add_packet        (GstRTCPBuffer *rtcp, GstRTCPType type,
 268                                                    GstRTCPPacket *packet);
 269
 270 GST_EXPORT
 271 gboolean        gst_rtcp_packet_remove            (GstRTCPPacket *packet);
 272
 273 /* working with packets */
 274
 275 GST_EXPORT
 276 gboolean        gst_rtcp_packet_get_padding       (GstRTCPPacket *packet);
 277
 278 GST_EXPORT
 279 guint8          gst_rtcp_packet_get_count         (GstRTCPPacket *packet);
 280
 281 GST_EXPORT
 282 GstRTCPType     gst_rtcp_packet_get_type          (GstRTCPPacket *packet);
 283
 284 GST_EXPORT
 285 guint16         gst_rtcp_packet_get_length        (GstRTCPPacket *packet);
 286
 287
 288 /* sender reports */
 289
 290 GST_EXPORT
 291 void            gst_rtcp_packet_sr_get_sender_info    (GstRTCPPacket *packet, guint32 *ssrc,
 292                                                        guint64 *ntptime, guint32 *rtptime,
 293                                                        guint32 *packet_count, guint32 *octet_count);
 294
 295 GST_EXPORT
 296 void            gst_rtcp_packet_sr_set_sender_info    (GstRTCPPacket *packet, guint32 ssrc,
 297                                                        guint64 ntptime, guint32 rtptime,
 298                                                        guint32 packet_count, guint32 octet_count);
 299 /* receiver reports */
 300
 301 GST_EXPORT
 302 guint32         gst_rtcp_packet_rr_get_ssrc           (GstRTCPPacket *packet);
 303
 304 GST_EXPORT
 305 void            gst_rtcp_packet_rr_set_ssrc           (GstRTCPPacket *packet, guint32 ssrc);
 306
 307
 308 /* report blocks for SR and RR */
 309
 310 GST_EXPORT
 311 guint           gst_rtcp_packet_get_rb_count          (GstRTCPPacket *packet);
 312
 313 GST_EXPORT
 314 void            gst_rtcp_packet_get_rb                (GstRTCPPacket *packet, guint nth, guint32 *ssrc,
 315                                                        guint8 *fractionlost, gint32 *packetslost,
 316                                                        guint32 *exthighestseq, guint32 *jitter,
 317                                                        guint32 *lsr, guint32 *dlsr);
 318
 319 GST_EXPORT
 320 gboolean        gst_rtcp_packet_add_rb                (GstRTCPPacket *packet, guint32 ssrc,
 321                                                        guint8 fractionlost, gint32 packetslost,
 322                                                        guint32 exthighestseq, guint32 jitter,
 323                                                        guint32 lsr, guint32 dlsr);
 324
 325 GST_EXPORT
 326 void            gst_rtcp_packet_set_rb                (GstRTCPPacket *packet, guint nth, guint32 ssrc,
 327                                                        guint8 fractionlost, gint32 packetslost,
 328                                                        guint32 exthighestseq, guint32 jitter,
 329                                                        guint32 lsr, guint32 dlsr);
 330
 331 /* profile-specific extensions for SR and RR */
 332
 333 GST_EXPORT
 334 gboolean        gst_rtcp_packet_add_profile_specific_ext        (GstRTCPPacket * packet,
 335                                                                  const guint8 * data, guint len);
 336
 337 GST_EXPORT
 338 guint16         gst_rtcp_packet_get_profile_specific_ext_length (GstRTCPPacket * packet);
 339
 340 GST_EXPORT
 341 gboolean        gst_rtcp_packet_get_profile_specific_ext        (GstRTCPPacket * packet,
 342                                                                  guint8 ** data, guint * len);
 343
 344 GST_EXPORT
 345 gboolean        gst_rtcp_packet_copy_profile_specific_ext       (GstRTCPPacket * packet,
 346                                                                  guint8 ** data, guint * len);
 347
 348 /* source description packet */
 349
 350 GST_EXPORT
 351 guint           gst_rtcp_packet_sdes_get_item_count   (GstRTCPPacket *packet);
 352
 353 GST_EXPORT
 354 gboolean        gst_rtcp_packet_sdes_first_item       (GstRTCPPacket *packet);
 355
 356 GST_EXPORT
 357 gboolean        gst_rtcp_packet_sdes_next_item        (GstRTCPPacket *packet);
 358
 359 GST_EXPORT
 360 guint32         gst_rtcp_packet_sdes_get_ssrc         (GstRTCPPacket *packet);
 361
 362 GST_EXPORT
 363 gboolean        gst_rtcp_packet_sdes_first_entry      (GstRTCPPacket *packet);
 364
 365 GST_EXPORT
 366 gboolean        gst_rtcp_packet_sdes_next_entry       (GstRTCPPacket *packet);
 367
 368 GST_EXPORT
 369 gboolean        gst_rtcp_packet_sdes_get_entry        (GstRTCPPacket *packet,
 370                                                        GstRTCPSDESType *type, guint8 *len,
 371                                                        guint8 **data);
 372
 373 GST_EXPORT
 374 gboolean        gst_rtcp_packet_sdes_copy_entry       (GstRTCPPacket *packet,
 375                                                        GstRTCPSDESType *type, guint8 *len,
 376                                                        guint8 **data);
 377
 378 GST_EXPORT
 379 gboolean        gst_rtcp_packet_sdes_add_item         (GstRTCPPacket *packet, guint32 ssrc);
 380
 381 GST_EXPORT
 382 gboolean        gst_rtcp_packet_sdes_add_entry        (GstRTCPPacket *packet, GstRTCPSDESType type,
 383                                                        guint8 len, const guint8 *data);
 384
 385 /* bye packet */
 386
 387 GST_EXPORT
 388 guint           gst_rtcp_packet_bye_get_ssrc_count    (GstRTCPPacket *packet);
 389
 390 GST_EXPORT
 391 guint32         gst_rtcp_packet_bye_get_nth_ssrc      (GstRTCPPacket *packet, guint nth);
 392
 393 GST_EXPORT
 394 gboolean        gst_rtcp_packet_bye_add_ssrc          (GstRTCPPacket *packet, guint32 ssrc);
 395
 396 GST_EXPORT
 397 gboolean        gst_rtcp_packet_bye_add_ssrcs         (GstRTCPPacket *packet, guint32 *ssrc, guint len);
 398
 399 GST_EXPORT
 400 guint8          gst_rtcp_packet_bye_get_reason_len    (GstRTCPPacket *packet);
 401
 402 GST_EXPORT
 403 gchar*          gst_rtcp_packet_bye_get_reason        (GstRTCPPacket *packet);
 404
 405 GST_EXPORT
 406 gboolean        gst_rtcp_packet_bye_set_reason        (GstRTCPPacket *packet, const gchar *reason);
 407
 408 /* app packets */
 409
 410 GST_EXPORT
 411 void            gst_rtcp_packet_app_set_subtype       (GstRTCPPacket * packet, guint8 subtype);
 412
 413 GST_EXPORT
 414 guint8          gst_rtcp_packet_app_get_subtype       (GstRTCPPacket * packet);
 415
 416 GST_EXPORT
 417 void            gst_rtcp_packet_app_set_ssrc          (GstRTCPPacket * packet, guint32 ssrc);
 418
 419 GST_EXPORT
 420 guint32         gst_rtcp_packet_app_get_ssrc          (GstRTCPPacket * packet);
 421
 422 GST_EXPORT
 423 void            gst_rtcp_packet_app_set_name          (GstRTCPPacket * packet, const gchar *name);
 424
 425 GST_EXPORT
 426 const gchar*    gst_rtcp_packet_app_get_name          (GstRTCPPacket * packet);
 427
 428 GST_EXPORT
 429 guint16         gst_rtcp_packet_app_get_data_length   (GstRTCPPacket * packet);
 430
 431 GST_EXPORT
 432 gboolean        gst_rtcp_packet_app_set_data_length   (GstRTCPPacket * packet, guint16 wordlen);
 433
 434 GST_EXPORT
 435 guint8*         gst_rtcp_packet_app_get_data          (GstRTCPPacket * packet);
 436
 437 /* feedback packets */
 438
 439 GST_EXPORT
 440 guint32         gst_rtcp_packet_fb_get_sender_ssrc    (GstRTCPPacket *packet);
 441
 442 GST_EXPORT
 443 void            gst_rtcp_packet_fb_set_sender_ssrc    (GstRTCPPacket *packet, guint32 ssrc);
 444
 445 GST_EXPORT
 446 guint32         gst_rtcp_packet_fb_get_media_ssrc     (GstRTCPPacket *packet);
 447
 448 GST_EXPORT
 449 void            gst_rtcp_packet_fb_set_media_ssrc     (GstRTCPPacket *packet, guint32 ssrc);
 450
 451 GST_EXPORT
 452 GstRTCPFBType   gst_rtcp_packet_fb_get_type           (GstRTCPPacket *packet);
 453
 454 GST_EXPORT
 455 void            gst_rtcp_packet_fb_set_type           (GstRTCPPacket *packet, GstRTCPFBType type);
 456
 457 GST_EXPORT
 458 guint16         gst_rtcp_packet_fb_get_fci_length     (GstRTCPPacket *packet);
 459
 460 GST_EXPORT
 461 gboolean        gst_rtcp_packet_fb_set_fci_length     (GstRTCPPacket *packet, guint16 wordlen);
 462
 463 GST_EXPORT
 464 guint8 *        gst_rtcp_packet_fb_get_fci            (GstRTCPPacket *packet);
 465
 466 /* helper functions */
 467
 468 GST_EXPORT
 469 guint64         gst_rtcp_ntp_to_unix                  (guint64 ntptime);
 470
 471 GST_EXPORT
 472 guint64         gst_rtcp_unix_to_ntp                  (guint64 unixtime);
 473
 474 GST_EXPORT
 475 const gchar *   gst_rtcp_sdes_type_to_name            (GstRTCPSDESType type);
 476
 477 GST_EXPORT
 478 GstRTCPSDESType gst_rtcp_sdes_name_to_type            (const gchar *name);
 479
 480 G_END_DECLS
 481
 482 #endif /* __GST_RTCPBUFFER_H__ */
 483