subprojects/gstreamer/gst/gsturi.h

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wtay@chello.be>
   4  *                    2014 David Waring, British Broadcasting Corporation
   5  *                             <david.waring@rd.bbc.co.uk>
   6  *
   7  * gsturi.h: Header for uri to element mappings and URI manipulation.
   8  *
   9  * This library is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Library General Public
  11  * License as published by the Free Software Foundation; either
  12  * version 2 of the License, or (at your option) any later version.
  13  *
  14  * This library is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Library General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Library General Public
  20  * License along with this library; if not, write to the
  21  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  22  * Boston, MA 02110-1301, USA.
  23  */
  24
  25
  26 #ifndef __GST_URI_H__
  27 #define __GST_URI_H__
  28
  29 #include <glib.h>
  30 #include <glib-object.h>
  31
  32 G_BEGIN_DECLS
  33
  34 #include <gst/gstconfig.h>
  35
  36 /**
  37  * gst_uri_error_quark: (attributes doc.skip=true)
  38  */
  39 GST_API
  40 GQuark gst_uri_error_quark (void);
  41
  42 /**
  43  * GST_URI_ERROR:
  44  *
  45  * Get access to the error quark of the uri subsystem.
  46  */
  47 #define GST_URI_ERROR gst_uri_error_quark ()
  48
  49 /**
  50  * GstURIError:
  51  * @GST_URI_ERROR_UNSUPPORTED_PROTOCOL: The protocol is not supported
  52  * @GST_URI_ERROR_BAD_URI: There was a problem with the URI
  53  * @GST_URI_ERROR_BAD_STATE: Could not set or change the URI because the
  54  *     URI handler was in a state where that is not possible or not permitted
  55  * @GST_URI_ERROR_BAD_REFERENCE: There was a problem with the entity that
  56  *     the URI references
  57  *
  58  * Different URI-related errors that can occur.
  59  */
  60 typedef enum
  61 {
  62   GST_URI_ERROR_UNSUPPORTED_PROTOCOL,
  63   GST_URI_ERROR_BAD_URI,
  64   GST_URI_ERROR_BAD_STATE,
  65   GST_URI_ERROR_BAD_REFERENCE
  66 } GstURIError;
  67
  68 /**
  69  * GstURIType:
  70  * @GST_URI_UNKNOWN: The URI direction is unknown
  71  * @GST_URI_SINK: The URI is a consumer.
  72  * @GST_URI_SRC: The URI is a producer.
  73  *
  74  * The different types of URI direction.
  75  */
  76
  77 typedef enum {
  78   GST_URI_UNKNOWN,
  79   GST_URI_SINK,
  80   GST_URI_SRC
  81 } GstURIType;
  82
  83 /**
  84  * GST_URI_TYPE_IS_VALID:
  85  * @type: A #GstURIType
  86  *
  87  * Tests if the type direction is valid.
  88  */
  89 #define GST_URI_TYPE_IS_VALID(type) ((type) == GST_URI_SRC || (type) == GST_URI_SINK)
  90
  91 /* uri handler functions */
  92 #define GST_TYPE_URI_HANDLER               (gst_uri_handler_get_type ())
  93 #define GST_URI_HANDLER(obj)               (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_URI_HANDLER, GstURIHandler))
  94 #define GST_IS_URI_HANDLER(obj)            (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_URI_HANDLER))
  95 #define GST_URI_HANDLER_GET_INTERFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), GST_TYPE_URI_HANDLER, GstURIHandlerInterface))
  96
  97 /**
  98  * GstURIHandler:
  99  *
 100  * Opaque #GstURIHandler structure.
 101  */
 102 typedef struct _GstURIHandler GstURIHandler;
 103 typedef struct _GstURIHandlerInterface GstURIHandlerInterface;
 104
 105 #include <gst/gstelement.h>
 106 #include "gstminiobject.h"
 107
 108 /**
 109  * GstURIHandlerInterface:
 110  * @parent: The parent interface type
 111  * @get_type: Method to tell whether the element handles source or sink URI.
 112  * @get_protocols: Method to return the list of protocols handled by the element.
 113  * @get_uri: Method to return the URI currently handled by the element.
 114  * @set_uri: Method to set a new URI.
 115  *
 116  * Any #GstElement using this interface should implement these methods.
 117  */
 118 struct _GstURIHandlerInterface {
 119   GTypeInterface parent;
 120
 121   /* vtable */
 122   /*< public >*/
 123   /* querying capabilities */
 124   GstURIType             (* get_type)           (GType type);
 125   const gchar * const *  (* get_protocols)      (GType type);
 126
 127   /* using the interface */
 128   gchar *                (* get_uri)            (GstURIHandler * handler);
 129   gboolean               (* set_uri)            (GstURIHandler * handler,
 130                                                  const gchar   * uri,
 131                                                  GError       ** error);
 132 };
 133
 134 /* general URI functions */
 135
 136 GST_API
 137 gboolean        gst_uri_protocol_is_valid       (const gchar * protocol);
 138
 139 GST_API
 140 gboolean        gst_uri_protocol_is_supported   (const GstURIType type,
 141                                                  const gchar *protocol);
 142 GST_API
 143 gboolean        gst_uri_is_valid                (const gchar * uri);
 144
 145 GST_API
 146 gchar *         gst_uri_get_protocol            (const gchar * uri) G_GNUC_MALLOC;
 147
 148 GST_API
 149 gboolean        gst_uri_has_protocol            (const gchar * uri,
 150                                                  const gchar * protocol);
 151 GST_API
 152 gchar *         gst_uri_get_location            (const gchar * uri) G_GNUC_MALLOC;
 153
 154 GST_DEPRECATED_FOR(gst_uri_new)
 155 gchar *         gst_uri_construct               (const gchar * protocol,
 156                                                  const gchar * location) G_GNUC_MALLOC;
 157 GST_API
 158 gchar *         gst_filename_to_uri             (const gchar * filename,
 159                                                  GError     ** error) G_GNUC_MALLOC;
 160 GST_API
 161 GstElement *    gst_element_make_from_uri       (const GstURIType type,
 162                                                  const gchar *    uri,
 163                                                  const gchar *    elementname,
 164                                                  GError      **   error) G_GNUC_MALLOC;
 165
 166 /* accessing the interface */
 167
 168 GST_API
 169 GType                 gst_uri_handler_get_type (void);
 170
 171 GST_API
 172 GstURIType            gst_uri_handler_get_uri_type  (GstURIHandler * handler);
 173
 174 GST_API
 175 const gchar * const * gst_uri_handler_get_protocols (GstURIHandler * handler);
 176
 177 GST_API
 178 gchar *               gst_uri_handler_get_uri       (GstURIHandler * handler) G_GNUC_MALLOC;
 179
 180 GST_API
 181 gboolean              gst_uri_handler_set_uri       (GstURIHandler * handler,
 182                                                      const gchar   * uri,
 183                                                      GError       ** error);
 184
 185 /*
 186  * GstUri Type macros.
 187  */
 188 #define GST_TYPE_URI        (gst_uri_get_type ())
 189 #define GST_IS_URI(obj)     (GST_IS_MINI_OBJECT_TYPE (obj, GST_TYPE_URI))
 190 #define GST_URI_CAST(obj)   ((GstUri *)(obj))
 191 #define GST_URI_CONST_CAST(obj) ((const GstUri *)(obj))
 192 #define GST_URI(obj)        (GST_URI_CAST(obj))
 193
 194 /**
 195  * GstUri:
 196  *
 197  * This is a private structure that holds the various parts of a parsed URI.
 198  */
 199 struct _GstUri;
 200 typedef struct _GstUri GstUri;
 201
 202 /**
 203  * GST_URI_NO_PORT:
 204  *
 205  * Value for #GstUri<!-- -->.port to indicate no port number.
 206  */
 207 #define GST_URI_NO_PORT 0
 208
 209 /* used by GST_TYPE_URI */
 210
 211 GST_API
 212 GType gst_uri_get_type (void);
 213
 214 /*
 215  * Method definitions.
 216  */
 217
 218 GST_API
 219 GstUri * gst_uri_new                   (const gchar * scheme,
 220                                         const gchar * userinfo,
 221                                         const gchar * host,
 222                                         guint port,
 223                                         const gchar * path,
 224                                         const gchar * query,
 225                                         const gchar * fragment) G_GNUC_MALLOC;
 226 GST_API
 227 GstUri * gst_uri_new_with_base         (GstUri * base,
 228                                         const gchar * scheme,
 229                                         const gchar * userinfo,
 230                                         const gchar * host,
 231                                         guint port,
 232                                         const gchar * path,
 233                                         const gchar * query,
 234                                         const gchar * fragment) G_GNUC_MALLOC;
 235 GST_API
 236 GstUri * gst_uri_from_string           (const gchar * uri) G_GNUC_MALLOC;
 237
 238 GST_API
 239 GstUri * gst_uri_from_string_escaped   (const gchar * uri) G_GNUC_MALLOC;
 240
 241 GST_API
 242 GstUri * gst_uri_from_string_with_base (GstUri * base,
 243                                         const gchar * uri) G_GNUC_MALLOC;
 244 GST_API
 245 gboolean gst_uri_equal                 (const GstUri * first,
 246                                         const GstUri * second);
 247 GST_API
 248 GstUri * gst_uri_join                  (GstUri * base_uri,
 249                                         GstUri * ref_uri) G_GNUC_WARN_UNUSED_RESULT;
 250 GST_API
 251 gchar *  gst_uri_join_strings          (const gchar * base_uri,
 252                                         const gchar * ref_uri) G_GNUC_MALLOC;
 253 GST_API
 254 gboolean gst_uri_is_writable           (const GstUri * uri);
 255
 256 GST_API
 257 GstUri * gst_uri_make_writable         (GstUri * uri) G_GNUC_WARN_UNUSED_RESULT;
 258
 259 GST_API
 260 gchar *  gst_uri_to_string             (const GstUri * uri) G_GNUC_MALLOC;
 261
 262 GST_API
 263 gboolean gst_uri_is_normalized         (const GstUri * uri);
 264
 265 GST_API
 266 gboolean gst_uri_normalize             (GstUri * uri);
 267
 268 GST_API
 269 const gchar * gst_uri_get_scheme       (const GstUri * uri);
 270
 271 GST_API
 272 gboolean gst_uri_set_scheme            (GstUri * uri, const gchar * scheme);
 273
 274 GST_API
 275 const gchar * gst_uri_get_userinfo     (const GstUri * uri);
 276
 277 GST_API
 278 gboolean gst_uri_set_userinfo          (GstUri * uri, const gchar * userinfo);
 279
 280 GST_API
 281 const gchar * gst_uri_get_host         (const GstUri * uri);
 282
 283 GST_API
 284 gboolean gst_uri_set_host              (GstUri * uri, const gchar * host);
 285
 286 GST_API
 287 guint gst_uri_get_port                 (const GstUri * uri);
 288
 289 GST_API
 290 gboolean gst_uri_set_port              (GstUri * uri, guint port);
 291
 292 GST_API
 293 gchar * gst_uri_get_path               (const GstUri * uri);
 294
 295 GST_API
 296 gboolean gst_uri_set_path              (GstUri * uri, const gchar * path);
 297
 298 GST_API
 299 gchar * gst_uri_get_path_string        (const GstUri * uri);
 300
 301 GST_API
 302 gboolean gst_uri_set_path_string       (GstUri * uri, const gchar * path);
 303
 304 GST_API
 305 GList * gst_uri_get_path_segments      (const GstUri * uri);
 306
 307 GST_API
 308 gboolean gst_uri_set_path_segments     (GstUri * uri, GList * path_segments);
 309
 310 GST_API
 311 gboolean gst_uri_append_path           (GstUri * uri,
 312                                         const gchar * relative_path);
 313 GST_API
 314 gboolean gst_uri_append_path_segment   (GstUri * uri,
 315                                         const gchar * path_segment);
 316 GST_API
 317 gchar * gst_uri_get_query_string       (const GstUri * uri);
 318
 319 GST_API
 320 gboolean gst_uri_set_query_string      (GstUri * uri, const gchar * query);
 321
 322 GST_API
 323 GHashTable * gst_uri_get_query_table   (const GstUri * uri);
 324
 325 GST_API
 326 gboolean gst_uri_set_query_table       (GstUri * uri,
 327                                         GHashTable * query_table);
 328 GST_API
 329 gboolean gst_uri_set_query_value       (GstUri * uri, const gchar * query_key,
 330                                         const gchar * query_value);
 331 GST_API
 332 gboolean gst_uri_remove_query_key      (GstUri * uri, const gchar * query_key);
 333
 334 GST_API
 335 gboolean gst_uri_query_has_key         (const GstUri * uri,
 336                                         const gchar * query_key);
 337
 338 GST_API
 339 const gchar * gst_uri_get_query_value  (const GstUri * uri,
 340                                         const gchar * query_key);
 341
 342 GST_API
 343 GList * gst_uri_get_query_keys         (const GstUri * uri);
 344
 345 GST_API
 346 const gchar * gst_uri_get_fragment     (const GstUri * uri);
 347
 348 GST_API
 349 gboolean gst_uri_set_fragment          (GstUri * uri, const gchar * fragment);
 350
 351 GST_API
 352 GHashTable * gst_uri_get_media_fragment_table  (const GstUri * uri);
 353
 354 #ifndef GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS
 355 static inline GstUri *
 356 gst_uri_copy (const GstUri * uri)
 357 {
 358   return GST_URI_CAST (gst_mini_object_copy (GST_MINI_OBJECT_CONST_CAST (uri)));
 359 }
 360
 361 static inline GstUri *
 362 gst_uri_ref (GstUri * uri)
 363 {
 364   return GST_URI_CAST (gst_mini_object_ref (GST_MINI_OBJECT_CAST (uri)));
 365 }
 366
 367 static inline void
 368 gst_uri_unref (GstUri * uri)
 369 {
 370   gst_mini_object_unref (GST_MINI_OBJECT_CAST (uri));
 371 }
 372
 373 static inline void
 374 gst_clear_uri (GstUri ** uri_ptr)
 375 {
 376   gst_clear_mini_object ((GstMiniObject **) uri_ptr);
 377 }
 378 #else /* GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS */
 379 GST_API
 380 GstUri * gst_uri_copy  (const GstUri * uri);
 381
 382 GST_API
 383 GstUri * gst_uri_ref   (GstUri * uri);
 384
 385 GST_API
 386 void     gst_uri_unref (GstUri * uri);
 387
 388 GST_API
 389 void     gst_clear_uri (GstUri ** uri_ptr);
 390 #endif /* GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS */
 391
 392 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstUri, gst_uri_unref)
 393
 394 G_END_DECLS
 395
 396 #endif /* __GST_URI_H__ */