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 GST_DEPRECATED_FOR(gst_uri_new)
 151 gchar *         gst_uri_construct               (const gchar * protocol,
 152                                                  const gchar * location) G_GNUC_MALLOC;
 153 GST_EXPORT
 154 gchar *         gst_filename_to_uri             (const gchar * filename,
 155                                                  GError     ** error) G_GNUC_MALLOC;
 156 GST_EXPORT
 157 GstElement *    gst_element_make_from_uri       (const GstURIType type,
 158                                                  const gchar *    uri,
 159                                                  const gchar *    elementname,
 160                                                  GError      **   error) G_GNUC_MALLOC;
 161
 162 /* accessing the interface */
 163
 164 GST_EXPORT
 165 GType                 gst_uri_handler_get_type (void);
 166
 167 GST_EXPORT
 168 GstURIType            gst_uri_handler_get_uri_type  (GstURIHandler * handler);
 169
 170 GST_EXPORT
 171 const gchar * const * gst_uri_handler_get_protocols (GstURIHandler * handler);
 172
 173 GST_EXPORT
 174 gchar *               gst_uri_handler_get_uri       (GstURIHandler * handler) G_GNUC_MALLOC;
 175
 176 GST_EXPORT
 177 gboolean              gst_uri_handler_set_uri       (GstURIHandler * handler,
 178                                                      const gchar   * uri,
 179                                                      GError       ** error);
 180
 181 /*
 182  * GstUri Type macros.
 183  */
 184 #define GST_TYPE_URI        (gst_uri_get_type ())
 185 #define GST_IS_URI(obj)     (GST_IS_MINI_OBJECT_TYPE (obj, GST_TYPE_URI))
 186 #define GST_URI_CAST(obj)   ((GstUri *)(obj))
 187 #define GST_URI_CONST_CAST(obj) ((const GstUri *)(obj))
 188 #define GST_URI(obj)        (GST_URI_CAST(obj))
 189
 190 /**
 191  * GstUri:
 192  *
 193  * This is a private structure that holds the various parts of a parsed URI.
 194  */
 195 struct _GstUri;
 196 typedef struct _GstUri GstUri;
 197
 198 /**
 199  * GST_URI_NO_PORT:
 200  *
 201  * Value for #GstUri<!-- -->.port to indicate no port number.
 202  */
 203 #define GST_URI_NO_PORT 0
 204
 205 /* used by GST_TYPE_URI */
 206
 207 GST_EXPORT
 208 GType gst_uri_get_type (void);
 209
 210 /*
 211  * Method definitions.
 212  */
 213
 214 GST_EXPORT
 215 GstUri * gst_uri_new                   (const gchar * scheme,
 216                                         const gchar * userinfo,
 217                                         const gchar * host,
 218                                         guint port,
 219                                         const gchar * path,
 220                                         const gchar * query,
 221                                         const gchar * fragment) G_GNUC_MALLOC;
 222 GST_EXPORT
 223 GstUri * gst_uri_new_with_base         (GstUri * base,
 224                                         const gchar * scheme,
 225                                         const gchar * userinfo,
 226                                         const gchar * host,
 227                                         guint port,
 228                                         const gchar * path,
 229                                         const gchar * query,
 230                                         const gchar * fragment) G_GNUC_MALLOC;
 231 GST_EXPORT
 232 GstUri * gst_uri_from_string           (const gchar * uri) G_GNUC_MALLOC;
 233
 234 GST_EXPORT
 235 GstUri * gst_uri_from_string_with_base (GstUri * base,
 236                                         const gchar * uri) G_GNUC_MALLOC;
 237 GST_EXPORT
 238 gboolean gst_uri_equal                 (const GstUri * first,
 239                                         const GstUri * second);
 240 GST_EXPORT
 241 GstUri * gst_uri_join                  (GstUri * base_uri,
 242                                         GstUri * ref_uri) G_GNUC_WARN_UNUSED_RESULT;
 243 GST_EXPORT
 244 gchar *  gst_uri_join_strings          (const gchar * base_uri,
 245                                         const gchar * ref_uri) G_GNUC_MALLOC;
 246 GST_EXPORT
 247 gboolean gst_uri_is_writable           (const GstUri * uri);
 248
 249 GST_EXPORT
 250 GstUri * gst_uri_make_writable         (GstUri * uri) G_GNUC_WARN_UNUSED_RESULT;
 251
 252 GST_EXPORT
 253 gchar *  gst_uri_to_string             (const GstUri * uri) G_GNUC_MALLOC;
 254
 255 GST_EXPORT
 256 gboolean gst_uri_is_normalized         (const GstUri * uri);
 257
 258 GST_EXPORT
 259 gboolean gst_uri_normalize             (GstUri * uri);
 260
 261 GST_EXPORT
 262 const gchar * gst_uri_get_scheme       (const GstUri * uri);
 263
 264 GST_EXPORT
 265 gboolean gst_uri_set_scheme            (GstUri * uri, const gchar * scheme);
 266
 267 GST_EXPORT
 268 const gchar * gst_uri_get_userinfo     (const GstUri * uri);
 269
 270 GST_EXPORT
 271 gboolean gst_uri_set_userinfo          (GstUri * uri, const gchar * userinfo);
 272
 273 GST_EXPORT
 274 const gchar * gst_uri_get_host         (const GstUri * uri);
 275
 276 GST_EXPORT
 277 gboolean gst_uri_set_host              (GstUri * uri, const gchar * host);
 278
 279 GST_EXPORT
 280 guint gst_uri_get_port                 (const GstUri * uri);
 281
 282 GST_EXPORT
 283 gboolean gst_uri_set_port              (GstUri * uri, guint port);
 284
 285 GST_EXPORT
 286 gchar * gst_uri_get_path               (const GstUri * uri);
 287
 288 GST_EXPORT
 289 gboolean gst_uri_set_path              (GstUri * uri, const gchar * path);
 290
 291 GST_EXPORT
 292 gchar * gst_uri_get_path_string        (const GstUri * uri);
 293
 294 GST_EXPORT
 295 gboolean gst_uri_set_path_string       (GstUri * uri, const gchar * path);
 296
 297 GST_EXPORT
 298 GList * gst_uri_get_path_segments      (const GstUri * uri);
 299
 300 GST_EXPORT
 301 gboolean gst_uri_set_path_segments     (GstUri * uri, GList * path_segments);
 302
 303 GST_EXPORT
 304 gboolean gst_uri_append_path           (GstUri * uri,
 305                                         const gchar * relative_path);
 306 GST_EXPORT
 307 gboolean gst_uri_append_path_segment   (GstUri * uri,
 308                                         const gchar * path_segment);
 309 GST_EXPORT
 310 gchar * gst_uri_get_query_string       (const GstUri * uri);
 311
 312 GST_EXPORT
 313 gboolean gst_uri_set_query_string      (GstUri * uri, const gchar * query);
 314
 315 GST_EXPORT
 316 GHashTable * gst_uri_get_query_table   (const GstUri * uri);
 317
 318 GST_EXPORT
 319 gboolean gst_uri_set_query_table       (GstUri * uri,
 320                                         GHashTable * query_table);
 321 GST_EXPORT
 322 gboolean gst_uri_set_query_value       (GstUri * uri, const gchar * query_key,
 323                                         const gchar * query_value);
 324 GST_EXPORT
 325 gboolean gst_uri_remove_query_key      (GstUri * uri, const gchar * query_key);
 326
 327 GST_EXPORT
 328 gboolean gst_uri_query_has_key         (const GstUri * uri,
 329                                         const gchar * query_key);
 330
 331 GST_EXPORT
 332 const gchar * gst_uri_get_query_value  (const GstUri * uri,
 333                                         const gchar * query_key);
 334
 335 GST_EXPORT
 336 GList * gst_uri_get_query_keys         (const GstUri * uri);
 337
 338 GST_EXPORT
 339 const gchar * gst_uri_get_fragment     (const GstUri * uri);
 340
 341 GST_EXPORT
 342 gboolean gst_uri_set_fragment          (GstUri * uri, const gchar * fragment);
 343
 344 GST_EXPORT
 345 GHashTable * gst_uri_get_media_fragment_table  (const GstUri * uri);
 346
 347 /**
 348  * gst_uri_copy:
 349  * @uri: This #GstUri object.
 350  *
 351  * Create a new #GstUri object with the same data as this #GstUri object.
 352  * If @uri is %NULL then returns %NULL.
 353  *
 354  * Returns: (transfer full): A new #GstUri object which is a copy of this
 355  *          #GstUri or %NULL.
 356  */
 357 static inline GstUri *
 358 gst_uri_copy (const GstUri * uri)
 359 {
 360   return GST_URI_CAST (gst_mini_object_copy (GST_MINI_OBJECT_CONST_CAST (uri)));
 361 }
 362
 363 /**
 364  * gst_uri_ref:
 365  * @uri: (transfer none): This #GstUri object.
 366  *
 367  * Add a reference to this #GstUri object. See gst_mini_object_ref() for further
 368  * info.
 369  *
 370  * Returns: This object with the reference count incremented.
 371  */
 372 static inline GstUri *
 373 gst_uri_ref (GstUri * uri)
 374 {
 375   return GST_URI_CAST (gst_mini_object_ref (GST_MINI_OBJECT_CAST (uri)));
 376 }
 377
 378 /**
 379  * gst_uri_unref:
 380  * @uri: (transfer full): This #GstUri object.
 381  *
 382  * Decrement the reference count to this #GstUri object.
 383  *
 384  * If the reference count drops to 0 then finalize this object.
 385  *
 386  * See gst_mini_object_unref() for further info.
 387  */
 388 static inline void
 389 gst_uri_unref (GstUri * uri)
 390 {
 391   gst_mini_object_unref (GST_MINI_OBJECT_CAST (uri));
 392 }
 393
 394 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
 395 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstUri, gst_uri_unref)
 396 #endif
 397
 398 G_END_DECLS
 399
 400 #endif /* __GST_URI_H__ */