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