subprojects/gst-plugins-base/gst-libs/gst/rtp/gstrtphdrext.h

   1 /* GStreamer
   2  * Copyright (C) <2012> Wim Taymans <wim.taymans@gmail.com>
   3  * Copyright (C) <2020> Matthew Waters <matthew@centricular.com>
   4  *
   5  * gstrtphdrext.h: RTP header extensions
   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_RTPHDREXT_H__
  24 #define __GST_RTPHDREXT_H__
  25
  26 #include <gst/gst.h>
  27 #include <gst/rtp/gstrtpbuffer.h>
  28
  29 G_BEGIN_DECLS
  30
  31 #define GST_RTP_HDREXT_BASE "urn:ietf:params:rtp-hdrext:"
  32
  33 /* RFC 6051 */
  34 #define GST_RTP_HDREXT_NTP_64 "ntp-64"
  35
  36 #define GST_RTP_HDREXT_NTP_64_SIZE 8
  37
  38 GST_RTP_API
  39 gboolean       gst_rtp_hdrext_set_ntp_64  (gpointer data, guint size, guint64 ntptime);
  40
  41 GST_RTP_API
  42 gboolean       gst_rtp_hdrext_get_ntp_64  (gpointer data, guint size, guint64 *ntptime);
  43
  44 #define GST_RTP_HDREXT_NTP_56 "ntp-56"
  45
  46 #define GST_RTP_HDREXT_NTP_56_SIZE 7
  47
  48 GST_RTP_API
  49 gboolean       gst_rtp_hdrext_set_ntp_56  (gpointer data, guint size, guint64 ntptime);
  50
  51 GST_RTP_API
  52 gboolean       gst_rtp_hdrext_get_ntp_56  (gpointer data, guint size, guint64 *ntptime);
  53
  54 /**
  55  * GST_RTP_HDREXT_ELEMENT_CLASS:
  56  *
  57  * Constant string used in element classification to signal that this element
  58  * is a RTP header extension.
  59  *
  60  * Since: 1.20
  61  */
  62 #define GST_RTP_HDREXT_ELEMENT_CLASS "Network/Extension/RTPHeader"
  63
  64 GST_RTP_API
  65 GType gst_rtp_header_extension_get_type (void);
  66 #define GST_TYPE_RTP_HEADER_EXTENSION (gst_rtp_header_extension_get_type())
  67 #define GST_RTP_HEADER_EXTENSION(obj) \
  68   (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_RTP_HEADER_EXTENSION,GstRTPHeaderExtension))
  69 #define GST_RTP_HEADER_EXTENSION_CLASS(klass) \
  70   (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_RTP_HEADER_EXTENSION,GstRTPHeaderExtensionClass))
  71 #define GST_RTP_HEADER_EXTENSION_GET_CLASS(obj) \
  72         (G_TYPE_INSTANCE_GET_CLASS ((obj),GST_TYPE_RTP_HEADER_EXTENSION,GstRTPHeaderExtensionClass))
  73 #define GST_IS_RTP_HEADER_EXTENSION(obj) \
  74   (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_RTP_HEADER_EXTENSION))
  75 #define GST_IS_RTP_HEADER_EXTENSION_CLASS(klass) \
  76   (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_RTP_HEADER_EXTENSION))
  77 /**
  78  * GST_RTP_HEADER_EXTENSION_CAST:
  79  *
  80  * Since: 1.20
  81  */
  82 #define GST_RTP_HEADER_EXTENSION_CAST(obj) ((GstRTPHeaderExtension *)(obj))
  83
  84 typedef struct _GstRTPHeaderExtension      GstRTPHeaderExtension;
  85 typedef struct _GstRTPHeaderExtensionClass GstRTPHeaderExtensionClass;
  86
  87 /**
  88  * GstRTPHeaderExtensionFlags:
  89  * @GST_RTP_HEADER_EXTENSION_ONE_BYTE: The one byte rtp extension header.
  90  *              1-16 data bytes per extension with a maximum of
  91  *              14 extension ids in total.
  92  * @GST_RTP_HEADER_EXTENSION_TWO_BYTE: The two byte rtp extension header.
  93  *              256 data bytes per extension with a maximum of 255 (or 256
  94  *              including appbits) extensions in total.
  95  *
  96  * Flags that apply to a RTP Audio/Video header extension.
  97  *
  98  * Since: 1.20
  99  */
 100 typedef enum /*< underscore_name=gst_rtp_header_extension_flags >*/
 101 {
 102   GST_RTP_HEADER_EXTENSION_ONE_BYTE = (1 << 0),
 103   GST_RTP_HEADER_EXTENSION_TWO_BYTE = (1 << 1),
 104 } GstRTPHeaderExtensionFlags;
 105
 106 /**
 107  * GstRTPHeaderExtensionDirection:
 108  * @GST_RTP_HEADER_EXTENSION_DIRECTION_INACTIVE: Neither send nor
 109  * receive RTP Header Extensions
 110  * @GST_RTP_HEADER_EXTENSION_DIRECTION_SENDONLY: Only send RTP Header
 111  * Extensions @GST_RTP_HEADER_EXTENSION_DIRECTION_RECVONLY: Only
 112  * receive RTP Header Extensions
 113  * @GST_RTP_HEADER_EXTENSION_DIRECTION_SENDRECV: Send and receive RTP
 114  * Header Extensions ext
 115  * @GST_RTP_HEADER_EXTENSION_DIRECTION_INHERITED: RTP header extension
 116  * direction is inherited from the stream
 117  *
 118  * Direction to which to apply the RTP Header Extension
 119  *
 120  * Since: 1.20
 121  */
 122 typedef enum /*< underscore_name=gst_rtp_header_extension_direction >*/
 123 {
 124   GST_RTP_HEADER_EXTENSION_DIRECTION_INACTIVE = 0,
 125   GST_RTP_HEADER_EXTENSION_DIRECTION_SENDONLY = (1 << 0),
 126   GST_RTP_HEADER_EXTENSION_DIRECTION_RECVONLY = (1 << 1),
 127   GST_RTP_HEADER_EXTENSION_DIRECTION_SENDRECV = (
 128     GST_RTP_HEADER_EXTENSION_DIRECTION_SENDONLY |
 129     GST_RTP_HEADER_EXTENSION_DIRECTION_RECVONLY),
 130   GST_RTP_HEADER_EXTENSION_DIRECTION_INHERITED = (1 << 2)
 131 } GstRTPHeaderExtensionDirection;
 132
 133 /**
 134  * GstRTPHeaderExtension:
 135  * @parent: the parent #GObject
 136  * @ext_id: the configured extension id
 137  *
 138  * Instance struct for a RTP Audio/Video header extension.
 139  *
 140  * Since: 1.20
 141  */
 142 struct _GstRTPHeaderExtension
 143 {
 144   GstElement parent;
 145
 146   /*< private >*/
 147   gpointer _gst_reserved[GST_PADDING];
 148 };
 149
 150 /**
 151  * GstRTPHeaderExtensionClass:
 152  * @parent_class: the parent class
 153  * @get_uri: retrieve the RTP extension uri
 154  * @get_supported_flags: retrieve the supported flags
 155  * @get_max_size: retrieve the maximum size for this extension based on the
 156  *     information available from input_meta.  Implementations should attempt
 157  *     to provide as accurate information as possible as the returned value
 158  *     will be used to control the amount of possible data in the payload.
 159  *     Implementations must return the maximum as the allocated size for
 160  *     writing the extension will be at least the size of the returned value.
 161  *     Return the amount of data read or <0 on failure.
 162  * @write: write into @data the information for this extension.  Various
 163  *     information is provided to help writing extensions in particular cases.
 164  * @read: read from a rtp payloaded buffer and extract the extension
 165  *     information, optionally adding some meta onto the output buffer.
 166  * @set_non_rtp_sink_caps: read any information from sink caps that the header
 167  *     extension needs for its function.
 168  * @update_non_rtp_src_caps: update depayloader non-RTP (depayloaded) caps with
 169  *     the information parsed from RTP header.
 170  * @set_attributes: set the necessary attributes that may be signaled e.g. with
 171  *     an SDP.
 172  * @set_caps_from_attributes: write the necessary caps field/s for the configured
 173  *     attributes e.g. as signalled with SDP.
 174  *
 175  * Base class for RTP Header extensions.
 176  *
 177  * Since: 1.20
 178  */
 179
 180 struct _GstRTPHeaderExtensionClass
 181 {
 182   GstElementClass parent_class;
 183
 184   /*< public >*/
 185   GstRTPHeaderExtensionFlags (*get_supported_flags) (GstRTPHeaderExtension * ext);
 186
 187   gsize                 (*get_max_size)             (GstRTPHeaderExtension * ext,
 188                                                      const GstBuffer * input_meta);
 189
 190   gssize                (*write)                    (GstRTPHeaderExtension * ext,
 191                                                      const GstBuffer * input_meta,
 192                                                      GstRTPHeaderExtensionFlags write_flags,
 193                                                      GstBuffer * output,
 194                                                      guint8 * data,
 195                                                      gsize size);
 196
 197   gboolean              (*read)                     (GstRTPHeaderExtension * ext,
 198                                                      GstRTPHeaderExtensionFlags read_flags,
 199                                                      const guint8 * data,
 200                                                      gsize size,
 201                                                      GstBuffer * buffer);
 202   gboolean              (*set_non_rtp_sink_caps)    (GstRTPHeaderExtension * ext,
 203                                                      const GstCaps * caps);
 204   gboolean              (*update_non_rtp_src_caps)  (GstRTPHeaderExtension * ext,
 205                                                      GstCaps * caps);
 206   gboolean              (*set_attributes)            (GstRTPHeaderExtension * ext,
 207                                                       GstRTPHeaderExtensionDirection direction,
 208                                                       const gchar * attributes);
 209   gboolean              (*set_caps_from_attributes) (GstRTPHeaderExtension * ext,
 210                                                      GstCaps * caps);
 211
 212   /*< private >*/
 213   gpointer _gst_reserved[GST_PADDING_LARGE];
 214 };
 215
 216 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstRTPHeaderExtension, gst_object_unref)
 217
 218 /**
 219  * GST_RTP_HEADER_EXTENSION_URI_METADATA_KEY:
 220  *
 221  * Since: 1.20
 222  */
 223 #define GST_RTP_HEADER_EXTENSION_URI_METADATA_KEY "RTP-Header-Extension-URI"
 224
 225 GST_RTP_API
 226 void                gst_rtp_header_extension_class_set_uri      (GstRTPHeaderExtensionClass *klass,
 227                                                                  const gchar * uri);
 228
 229 GST_RTP_API
 230 const gchar *       gst_rtp_header_extension_get_uri            (GstRTPHeaderExtension * ext);
 231 GST_RTP_API
 232 gsize               gst_rtp_header_extension_get_max_size       (GstRTPHeaderExtension * ext,
 233                                                                  const GstBuffer * input_meta);
 234 GST_RTP_API
 235 GstRTPHeaderExtensionFlags gst_rtp_header_extension_get_supported_flags (GstRTPHeaderExtension * ext);
 236 GST_RTP_API
 237 guint               gst_rtp_header_extension_get_id             (GstRTPHeaderExtension * ext);
 238 GST_RTP_API
 239 void                gst_rtp_header_extension_set_id             (GstRTPHeaderExtension * ext,
 240                                                                  guint ext_id);
 241 GST_RTP_API
 242 gssize              gst_rtp_header_extension_write              (GstRTPHeaderExtension * ext,
 243                                                                  const GstBuffer * input_meta,
 244                                                                  GstRTPHeaderExtensionFlags write_flags,
 245                                                                  GstBuffer * output,
 246                                                                  guint8 * data,
 247                                                                  gsize size);
 248 GST_RTP_API
 249 gboolean            gst_rtp_header_extension_read               (GstRTPHeaderExtension * ext,
 250                                                                  GstRTPHeaderExtensionFlags read_flags,
 251                                                                  const guint8 * data,
 252                                                                  gsize size,
 253                                                                  GstBuffer * buffer);
 254 GST_RTP_API
 255 gboolean            gst_rtp_header_extension_set_non_rtp_sink_caps (GstRTPHeaderExtension * ext,
 256                                                                     const GstCaps * caps);
 257 GST_RTP_API
 258 gboolean            gst_rtp_header_extension_wants_update_non_rtp_src_caps (GstRTPHeaderExtension * ext);
 259 GST_RTP_API
 260 void                gst_rtp_header_extension_set_wants_update_non_rtp_src_caps (GstRTPHeaderExtension * ext,
 261                                                                                 gboolean state);
 262 GST_RTP_API
 263 gboolean            gst_rtp_header_extension_update_non_rtp_src_caps (GstRTPHeaderExtension * ext,
 264                                                                       GstCaps * caps);
 265 GST_RTP_API
 266 gboolean            gst_rtp_header_extension_set_caps_from_attributes (GstRTPHeaderExtension * ext,
 267                                                                        GstCaps * caps);
 268 GST_RTP_API
 269 gboolean            gst_rtp_header_extension_set_attributes_from_caps (GstRTPHeaderExtension * ext,
 270                                                                        const GstCaps * caps);
 271
 272 GST_RTP_API
 273 GList *             gst_rtp_get_header_extension_list           (void);
 274 GST_RTP_API
 275 GstRTPHeaderExtension * gst_rtp_header_extension_create_from_uri (const gchar * uri);
 276
 277 GST_RTP_API
 278 gchar *             gst_rtp_header_extension_get_sdp_caps_field_name (GstRTPHeaderExtension * ext);
 279
 280 GST_RTP_API
 281 void                gst_rtp_header_extension_set_direction (GstRTPHeaderExtension * ext,
 282                                                             GstRTPHeaderExtensionDirection direction);
 283 GST_RTP_API
 284 GstRTPHeaderExtensionDirection  gst_rtp_header_extension_get_direction (GstRTPHeaderExtension * ext);
 285
 286 GST_RTP_API
 287 gboolean    gst_rtp_header_extension_set_caps_from_attributes_helper (GstRTPHeaderExtension * ext,
 288                                                                       GstCaps * caps,
 289                                                                       const gchar * attributes);
 290
 291 G_END_DECLS
 292
 293 #endif /* __GST_RTPHDREXT_H__ */
 294