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  * GstRTPHeaderExtension:
 108  * @parent: the parent #GObject
 109  * @ext_id: the configured extension id
 110  *
 111  * Instance struct for a RTP Audio/Video header extension.
 112  *
 113  * Since: 1.20
 114  */
 115 struct _GstRTPHeaderExtension
 116 {
 117   GstElement parent;
 118
 119   /*< private >*/
 120   gpointer _gst_reserved[GST_PADDING];
 121 };
 122
 123 /**
 124  * GstRTPHeaderExtensionClass:
 125  * @parent_class: the parent class
 126  * @get_uri: retrieve the RTP extension uri
 127  * @get_supported_flags: retrieve the supported flags
 128  * @get_max_size: retrieve the maximum size for this extension based on the
 129  *     information available from input_meta.  Implementations should attempt
 130  *     to provide as accurate information as possible as the returned value
 131  *     will be used to control the amount of possible data in the payload.
 132  *     Implementations must return the maximum as the allocated size for
 133  *     writing the extension will be at least the size of the returned value.
 134  *     Return the amount of data read or <0 on failure.
 135  * @write: write into @data the information for this extension.  Various
 136  *     information is provided to help writing extensions in particular cases.
 137  * @read: read from a rtp payloaded buffer and extract the extension
 138  *     information, optionally adding some meta onto the output buffer.
 139  * @set_non_rtp_sink_caps: read any information from sink caps that the header
 140  *     extension needs for its function.
 141  * @update_non_rtp_src_caps: update depayloader non-RTP (depayloaded) caps with
 142  *     the information parsed from RTP header.
 143  * @set_attributes_from_caps: read the caps information to set the necessary
 144  *     attributes that may be signaled e.g. with an SDP.
 145  * @set_caps_from_attributes: write the necessary caps field/s for the configured
 146  *     attributes e.g. as signalled with SDP.
 147  *
 148  * Base class for RTP Header extensions.
 149  *
 150  * Since: 1.20
 151  */
 152 struct _GstRTPHeaderExtensionClass
 153 {
 154   GstElementClass parent_class;
 155
 156   /*< public >*/
 157   GstRTPHeaderExtensionFlags (*get_supported_flags) (GstRTPHeaderExtension * ext);
 158
 159   gsize                 (*get_max_size)             (GstRTPHeaderExtension * ext,
 160                                                      const GstBuffer * input_meta);
 161
 162   gssize                (*write)                    (GstRTPHeaderExtension * ext,
 163                                                      const GstBuffer * input_meta,
 164                                                      GstRTPHeaderExtensionFlags write_flags,
 165                                                      GstBuffer * output,
 166                                                      guint8 * data,
 167                                                      gsize size);
 168
 169   gboolean              (*read)                     (GstRTPHeaderExtension * ext,
 170                                                      GstRTPHeaderExtensionFlags read_flags,
 171                                                      const guint8 * data,
 172                                                      gsize size,
 173                                                      GstBuffer * buffer);
 174   gboolean              (*set_non_rtp_sink_caps)    (GstRTPHeaderExtension * ext,
 175                                                      const GstCaps * caps);
 176   gboolean              (*update_non_rtp_src_caps)  (GstRTPHeaderExtension * ext,
 177                                                      GstCaps * caps);
 178   gboolean              (*set_attributes_from_caps) (GstRTPHeaderExtension * ext,
 179                                                      const GstCaps * caps);
 180   gboolean              (*set_caps_from_attributes) (GstRTPHeaderExtension * ext,
 181                                                      GstCaps * caps);
 182
 183   /*< private >*/
 184   gpointer _gst_reserved[GST_PADDING];
 185 };
 186
 187 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstRTPHeaderExtension, gst_object_unref)
 188
 189 /**
 190  * GST_RTP_HEADER_EXTENSION_URI_METADATA_KEY:
 191  *
 192  * Since: 1.20
 193  */
 194 #define GST_RTP_HEADER_EXTENSION_URI_METADATA_KEY "RTP-Header-Extension-URI"
 195
 196 GST_RTP_API
 197 void                gst_rtp_header_extension_class_set_uri      (GstRTPHeaderExtensionClass *klass,
 198                                                                  const gchar * uri);
 199
 200 GST_RTP_API
 201 const gchar *       gst_rtp_header_extension_get_uri            (GstRTPHeaderExtension * ext);
 202 GST_RTP_API
 203 gsize               gst_rtp_header_extension_get_max_size       (GstRTPHeaderExtension * ext,
 204                                                                  const GstBuffer * input_meta);
 205 GST_RTP_API
 206 GstRTPHeaderExtensionFlags gst_rtp_header_extension_get_supported_flags (GstRTPHeaderExtension * ext);
 207 GST_RTP_API
 208 guint               gst_rtp_header_extension_get_id             (GstRTPHeaderExtension * ext);
 209 GST_RTP_API
 210 void                gst_rtp_header_extension_set_id             (GstRTPHeaderExtension * ext,
 211                                                                  guint ext_id);
 212 GST_RTP_API
 213 gssize              gst_rtp_header_extension_write              (GstRTPHeaderExtension * ext,
 214                                                                  const GstBuffer * input_meta,
 215                                                                  GstRTPHeaderExtensionFlags write_flags,
 216                                                                  GstBuffer * output,
 217                                                                  guint8 * data,
 218                                                                  gsize size);
 219 GST_RTP_API
 220 gboolean            gst_rtp_header_extension_read               (GstRTPHeaderExtension * ext,
 221                                                                  GstRTPHeaderExtensionFlags read_flags,
 222                                                                  const guint8 * data,
 223                                                                  gsize size,
 224                                                                  GstBuffer * buffer);
 225 GST_RTP_API
 226 gboolean            gst_rtp_header_extension_set_non_rtp_sink_caps (GstRTPHeaderExtension * ext,
 227                                                                     const GstCaps * caps);
 228 GST_RTP_API
 229 gboolean            gst_rtp_header_extension_wants_update_non_rtp_src_caps (GstRTPHeaderExtension * ext);
 230 GST_RTP_API
 231 void                gst_rtp_header_extension_set_wants_update_non_rtp_src_caps (GstRTPHeaderExtension * ext,
 232                                                                                 gboolean state);
 233 GST_RTP_API
 234 gboolean            gst_rtp_header_extension_update_non_rtp_src_caps (GstRTPHeaderExtension * ext,
 235                                                                       GstCaps * caps);
 236 GST_RTP_API
 237 gboolean            gst_rtp_header_extension_set_caps_from_attributes (GstRTPHeaderExtension * ext,
 238                                                                        GstCaps * caps);
 239 GST_RTP_API
 240 gboolean            gst_rtp_header_extension_set_attributes_from_caps (GstRTPHeaderExtension * ext,
 241                                                                        const GstCaps * caps);
 242
 243 GST_RTP_API
 244 GList *             gst_rtp_get_header_extension_list           (void);
 245 GST_RTP_API
 246 GstRTPHeaderExtension * gst_rtp_header_extension_create_from_uri (const gchar * uri);
 247
 248 GST_RTP_API
 249 gchar *             gst_rtp_header_extension_get_sdp_caps_field_name (GstRTPHeaderExtension * ext);
 250
 251 G_END_DECLS
 252
 253 #endif /* __GST_RTPHDREXT_H__ */
 254