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 GST_API
  37 GQuark gst_uri_error_quark (void);
  38
  39 /**
  40  * GST_URI_ERROR:
  41  *
  42  * Get access to the error quark of the uri subsystem.
  43  */
  44 #define GST_URI_ERROR gst_uri_error_quark ()
  45
  46 /**
  47  * GstURIError:
  48  * @GST_URI_ERROR_UNSUPPORTED_PROTOCOL: The protocol is not supported
  49  * @GST_URI_ERROR_BAD_URI: There was a problem with the URI
  50  * @GST_URI_ERROR_BAD_STATE: Could not set or change the URI because the
  51  *     URI handler was in a state where that is not possible or not permitted
  52  * @GST_URI_ERROR_BAD_REFERENCE: There was a problem with the entity that
  53  *     the URI references
  54  *
  55  * Different URI-related errors that can occur.
  56  */
  57 typedef enum
  58 {
  59   GST_URI_ERROR_UNSUPPORTED_PROTOCOL,
  60   GST_URI_ERROR_BAD_URI,
  61   GST_URI_ERROR_BAD_STATE,
  62   GST_URI_ERROR_BAD_REFERENCE
  63 } GstURIError;
  64
  65 /**
  66  * GstURIType:
  67  * @GST_URI_UNKNOWN: The URI direction is unknown
  68  * @GST_URI_SINK: The URI is a consumer.
  69  * @GST_URI_SRC: The URI is a producer.
  70  *
  71  * The different types of URI direction.
  72  */
  73
  74 typedef enum {
  75   GST_URI_UNKNOWN,
  76   GST_URI_SINK,
  77   GST_URI_SRC
  78 } GstURIType;
  79
  80 /**
  81  * GST_URI_TYPE_IS_VALID:
  82  * @type: A #GstURIType
  83  *
  84  * Tests if the type direction is valid.
  85  */
  86 #define GST_URI_TYPE_IS_VALID(type) ((type) == GST_URI_SRC || (type) == GST_URI_SINK)
  87
  88 /* uri handler functions */
  89 #define GST_TYPE_URI_HANDLER               (gst_uri_handler_get_type ())
  90 #define GST_URI_HANDLER(obj)               (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_URI_HANDLER, GstURIHandler))
  91 #define GST_IS_URI_HANDLER(obj)            (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_URI_HANDLER))
  92 #define GST_URI_HANDLER_GET_INTERFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), GST_TYPE_URI_HANDLER, GstURIHandlerInterface))
  93
  94 /**
  95  * GstURIHandler:
  96  *
  97  * Opaque #GstURIHandler structure.
  98  */
  99 typedef struct _GstURIHandler GstURIHandler;
 100 typedef struct _GstURIHandlerInterface GstURIHandlerInterface;
 101
 102 #include <gst/gstelement.h>
 103 #include "gstminiobject.h"
 104
 105 /**
 106  * GstURIHandlerInterface:
 107  * @parent: The parent interface type
 108  * @get_type: Method to tell whether the element handles source or sink URI.
 109  * @get_protocols: Method to return the list of protocols handled by the element.
 110  * @get_uri: Method to return the URI currently handled by the element.
 111  * @set_uri: Method to set a new URI.
 112  *
 113  * Any #GstElement using this interface should implement these methods.
 114  */
 115 struct _GstURIHandlerInterface {
 116   GTypeInterface parent;
 117
 118   /* vtable */
 119   /*< public >*/
 120   /* querying capabilities */
 121   GstURIType             (* get_type)           (GType type);
 122   const gchar * const *  (* get_protocols)      (GType type);
 123
 124   /* using the interface */
 125   gchar *                (* get_uri)            (GstURIHandler * handler);
 126   gboolean               (* set_uri)            (GstURIHandler * handler,
 127                                                  const gchar   * uri,
 128                                                  GError       ** error);
 129 };
 130
 131 /* general URI functions */
 132
 133 GST_API
 134 gboolean        gst_uri_protocol_is_valid       (const gchar * protocol);
 135
 136 GST_API
 137 gboolean        gst_uri_protocol_is_supported   (const GstURIType type,
 138                                                  const gchar *protocol);
 139 GST_API
 140 gboolean        gst_uri_is_valid                (const gchar * uri);
 141
 142 GST_API
 143 gchar *         gst_uri_get_protocol            (const gchar * uri) G_GNUC_MALLOC;
 144
 145 GST_API
 146 gboolean        gst_uri_has_protocol            (const gchar * uri,
 147                                                  const gchar * protocol);
 148 GST_API
 149 gchar *         gst_uri_get_location            (const gchar * uri) G_GNUC_MALLOC;
 150
 151 GST_DEPRECATED_FOR(gst_uri_new)
 152 gchar *         gst_uri_construct               (const gchar * protocol,
 153                                                  const gchar * location) G_GNUC_MALLOC;
 154 GST_API
 155 gchar *         gst_filename_to_uri             (const gchar * filename,
 156                                                  GError     ** error) G_GNUC_MALLOC;
 157 GST_API
 158 GstElement *    gst_element_make_from_uri       (const GstURIType type,
 159                                                  const gchar *    uri,
 160                                                  const gchar *    elementname,
 161                                                  GError      **   error) G_GNUC_MALLOC;
 162
 163 /* accessing the interface */
 164
 165 GST_API
 166 GType                 gst_uri_handler_get_type (void);
 167
 168 GST_API
 169 GstURIType            gst_uri_handler_get_uri_type  (GstURIHandler * handler);
 170
 171 GST_API
 172 const gchar * const * gst_uri_handler_get_protocols (GstURIHandler * handler);
 173
 174 GST_API
 175 gchar *               gst_uri_handler_get_uri       (GstURIHandler * handler) G_GNUC_MALLOC;
 176
 177 GST_API
 178 gboolean              gst_uri_handler_set_uri       (GstURIHandler * handler,
 179                                                      const gchar   * uri,
 180                                                      GError       ** error);
 181
 182 /*
 183  * GstUri Type macros.
 184  */
 185 #define GST_TYPE_URI        (gst_uri_get_type ())
 186 #define GST_IS_URI(obj)     (GST_IS_MINI_OBJECT_TYPE (obj, GST_TYPE_URI))
 187 #define GST_URI_CAST(obj)   ((GstUri *)(obj))
 188 #define GST_URI_CONST_CAST(obj) ((const GstUri *)(obj))
 189 #define GST_URI(obj)        (GST_URI_CAST(obj))
 190
 191 /**
 192  * GstUri:
 193  *
 194  * This is a private structure that holds the various parts of a parsed URI.
 195  */
 196 struct _GstUri;
 197 typedef struct _GstUri GstUri;
 198
 199 /**
 200  * GST_URI_NO_PORT:
 201  *
 202  * Value for #GstUri<!-- -->.port to indicate no port number.
 203  */
 204 #define GST_URI_NO_PORT 0
 205
 206 /* used by GST_TYPE_URI */
 207
 208 GST_API
 209 GType gst_uri_get_type (void);
 210
 211 /*
 212  * Method definitions.
 213  */
 214
 215 GST_API
 216 GstUri * gst_uri_new                   (const gchar * scheme,
 217                                         const gchar * userinfo,
 218                                         const gchar * host,
 219                                         guint port,
 220                                         const gchar * path,
 221                                         const gchar * query,
 222                                         const gchar * fragment) G_GNUC_MALLOC;
 223 GST_API
 224 GstUri * gst_uri_new_with_base         (GstUri * base,
 225                                         const gchar * scheme,
 226                                         const gchar * userinfo,
 227                                         const gchar * host,
 228                                         guint port,
 229                                         const gchar * path,
 230                                         const gchar * query,
 231                                         const gchar * fragment) G_GNUC_MALLOC;
 232 GST_API
 233 GstUri * gst_uri_from_string           (const gchar * uri) G_GNUC_MALLOC;
 234
 235 GST_API
 236 GstUri * gst_uri_from_string_with_base (GstUri * base,
 237                                         const gchar * uri) G_GNUC_MALLOC;
 238 GST_API
 239 gboolean gst_uri_equal                 (const GstUri * first,
 240                                         const GstUri * second);
 241 GST_API
 242 GstUri * gst_uri_join                  (GstUri * base_uri,
 243                                         GstUri * ref_uri) G_GNUC_WARN_UNUSED_RESULT;
 244 GST_API
 245 gchar *  gst_uri_join_strings          (const gchar * base_uri,
 246                                         const gchar * ref_uri) G_GNUC_MALLOC;
 247 GST_API
 248 gboolean gst_uri_is_writable           (const GstUri * uri);
 249
 250 GST_API
 251 GstUri * gst_uri_make_writable         (GstUri * uri) G_GNUC_WARN_UNUSED_RESULT;
 252
 253 GST_API
 254 gchar *  gst_uri_to_string             (const GstUri * uri) G_GNUC_MALLOC;
 255
 256 GST_API
 257 gboolean gst_uri_is_normalized         (const GstUri * uri);
 258
 259 GST_API
 260 gboolean gst_uri_normalize             (GstUri * uri);
 261
 262 GST_API
 263 const gchar * gst_uri_get_scheme       (const GstUri * uri);
 264
 265 GST_API
 266 gboolean gst_uri_set_scheme            (GstUri * uri, const gchar * scheme);
 267
 268 GST_API
 269 const gchar * gst_uri_get_userinfo     (const GstUri * uri);
 270
 271 GST_API
 272 gboolean gst_uri_set_userinfo          (GstUri * uri, const gchar * userinfo);
 273
 274 GST_API
 275 const gchar * gst_uri_get_host         (const GstUri * uri);
 276
 277 GST_API
 278 gboolean gst_uri_set_host              (GstUri * uri, const gchar * host);
 279
 280 GST_API
 281 guint gst_uri_get_port                 (const GstUri * uri);
 282
 283 GST_API
 284 gboolean gst_uri_set_port              (GstUri * uri, guint port);
 285
 286 GST_API
 287 gchar * gst_uri_get_path               (const GstUri * uri);
 288
 289 GST_API
 290 gboolean gst_uri_set_path              (GstUri * uri, const gchar * path);
 291
 292 GST_API
 293 gchar * gst_uri_get_path_string        (const GstUri * uri);
 294
 295 GST_API
 296 gboolean gst_uri_set_path_string       (GstUri * uri, const gchar * path);
 297
 298 GST_API
 299 GList * gst_uri_get_path_segments      (const GstUri * uri);
 300
 301 GST_API
 302 gboolean gst_uri_set_path_segments     (GstUri * uri, GList * path_segments);
 303
 304 GST_API
 305 gboolean gst_uri_append_path           (GstUri * uri,
 306                                         const gchar * relative_path);
 307 GST_API
 308 gboolean gst_uri_append_path_segment   (GstUri * uri,
 309                                         const gchar * path_segment);
 310 GST_API
 311 gchar * gst_uri_get_query_string       (const GstUri * uri);
 312
 313 GST_API
 314 gboolean gst_uri_set_query_string      (GstUri * uri, const gchar * query);
 315
 316 GST_API
 317 GHashTable * gst_uri_get_query_table   (const GstUri * uri);
 318
 319 GST_API
 320 gboolean gst_uri_set_query_table       (GstUri * uri,
 321                                         GHashTable * query_table);
 322 GST_API
 323 gboolean gst_uri_set_query_value       (GstUri * uri, const gchar * query_key,
 324                                         const gchar * query_value);
 325 GST_API
 326 gboolean gst_uri_remove_query_key      (GstUri * uri, const gchar * query_key);
 327
 328 GST_API
 329 gboolean gst_uri_query_has_key         (const GstUri * uri,
 330                                         const gchar * query_key);
 331
 332 GST_API
 333 const gchar * gst_uri_get_query_value  (const GstUri * uri,
 334                                         const gchar * query_key);
 335
 336 GST_API
 337 GList * gst_uri_get_query_keys         (const GstUri * uri);
 338
 339 GST_API
 340 const gchar * gst_uri_get_fragment     (const GstUri * uri);
 341
 342 GST_API
 343 gboolean gst_uri_set_fragment          (GstUri * uri, const gchar * fragment);
 344
 345 GST_API
 346 GHashTable * gst_uri_get_media_fragment_table  (const GstUri * uri);
 347
 348 /**
 349  * gst_uri_copy:
 350  * @uri: This #GstUri object.
 351  *
 352  * Create a new #GstUri object with the same data as this #GstUri object.
 353  * If @uri is %NULL then returns %NULL.
 354  *
 355  * Returns: (transfer full): A new #GstUri object which is a copy of this
 356  *          #GstUri or %NULL.
 357  */
 358 static inline GstUri *
 359 gst_uri_copy (const GstUri * uri)
 360 {
 361   return GST_URI_CAST (gst_mini_object_copy (GST_MINI_OBJECT_CONST_CAST (uri)));
 362 }
 363
 364 /**
 365  * gst_uri_ref:
 366  * @uri: (transfer none): This #GstUri object.
 367  *
 368  * Add a reference to this #GstUri object. See gst_mini_object_ref() for further
 369  * info.
 370  *
 371  * Returns: This object with the reference count incremented.
 372  */
 373 static inline GstUri *
 374 gst_uri_ref (GstUri * uri)
 375 {
 376   return GST_URI_CAST (gst_mini_object_ref (GST_MINI_OBJECT_CAST (uri)));
 377 }
 378
 379 /**
 380  * gst_uri_unref:
 381  * @uri: (transfer full): This #GstUri object.
 382  *
 383  * Decrement the reference count to this #GstUri object.
 384  *
 385  * If the reference count drops to 0 then finalize this object.
 386  *
 387  * See gst_mini_object_unref() for further info.
 388  */
 389 static inline void
 390 gst_uri_unref (GstUri * uri)
 391 {
 392   gst_mini_object_unref (GST_MINI_OBJECT_CAST (uri));
 393 }
 394
 395 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
 396 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstUri, gst_uri_unref)
 397 #endif
 398
 399 G_END_DECLS
 400
 401 #endif /* __GST_URI_H__ */