gsturi.h 11.8 KB
Newer Older
1 2 3
/* GStreamer
 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
 *                    2000 Wim Taymans <wtay@chello.be>
4 5
 *                    2014 David Waring, British Broadcasting Corporation
 *                             <david.waring@rd.bbc.co.uk>
6
 *
7
 * gsturi.h: Header for uri to element mappings and URI manipulation.
8 9 10 11 12 13 14 15 16 17 18 19 20
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
21 22
 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
 * Boston, MA 02110-1301, USA.
23 24 25 26 27 28 29
 */


#ifndef __GST_URI_H__
#define __GST_URI_H__

#include <glib.h>
30
#include <glib-object.h>
31

32 33
G_BEGIN_DECLS

34 35 36 37 38 39 40 41 42 43 44
GQuark gst_uri_error_quark (void);

/**
 * GST_URI_ERROR:
 *
 * Get access to the error quark of the uri subsystem.
 */
#define GST_URI_ERROR gst_uri_error_quark ()

/**
 * GstURIError:
45
 * @GST_URI_ERROR_UNSUPPORTED_PROTOCOL: The protocol is not supported
46 47 48 49 50 51 52 53 54 55
 * @GST_URI_ERROR_BAD_URI: There was a problem with the URI
 * @GST_URI_ERROR_BAD_STATE: Could not set or change the URI because the
 *     URI handler was in a state where that is not possible or not permitted
 * @GST_URI_ERROR_BAD_REFERENCE: There was a problem with the entity that
 *     the URI references
 *
 * Different URI-related errors that can occur.
 */
typedef enum
{
56
  GST_URI_ERROR_UNSUPPORTED_PROTOCOL,
57 58 59 60 61
  GST_URI_ERROR_BAD_URI,
  GST_URI_ERROR_BAD_STATE,
  GST_URI_ERROR_BAD_REFERENCE
} GstURIError;

Edward Hervey's avatar
Edward Hervey committed
62 63
/**
 * GstURIType:
64 65 66
 * @GST_URI_UNKNOWN: The URI direction is unknown
 * @GST_URI_SINK: The URI is a consumer.
 * @GST_URI_SRC: The URI is a producer.
Edward Hervey's avatar
Edward Hervey committed
67 68 69 70
 *
 * The different types of URI direction.
 */

71
typedef enum {
Benjamin Otte's avatar
Benjamin Otte committed
72 73 74
  GST_URI_UNKNOWN,
  GST_URI_SINK,
  GST_URI_SRC
75
} GstURIType;
Benjamin Otte's avatar
Benjamin Otte committed
76

Edward Hervey's avatar
Edward Hervey committed
77 78 79 80 81 82
/**
 * GST_URI_TYPE_IS_VALID:
 * @type: A #GstURIType
 *
 * Tests if the type direction is valid.
 */
Benjamin Otte's avatar
Benjamin Otte committed
83 84
#define GST_URI_TYPE_IS_VALID(type) ((type) == GST_URI_SRC || (type) == GST_URI_SINK)

Wim Taymans's avatar
Wim Taymans committed
85
/* uri handler functions */
86 87 88 89
#define GST_TYPE_URI_HANDLER               (gst_uri_handler_get_type ())
#define GST_URI_HANDLER(obj)               (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_URI_HANDLER, GstURIHandler))
#define GST_IS_URI_HANDLER(obj)            (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_URI_HANDLER))
#define GST_URI_HANDLER_GET_INTERFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), GST_TYPE_URI_HANDLER, GstURIHandlerInterface))
90

Wim Taymans's avatar
Wim Taymans committed
91 92 93 94 95
/**
 * GstURIHandler:
 *
 * Opaque #GstURIHandler structure.
 */
96
typedef struct _GstURIHandler GstURIHandler;
Benjamin Otte's avatar
Benjamin Otte committed
97
typedef struct _GstURIHandlerInterface GstURIHandlerInterface;
98

99 100 101 102
#include <gst/gstelement.h>
#include <gst/gstconfig.h>
#include "gstminiobject.h"

Edward Hervey's avatar
Edward Hervey committed
103 104
/**
 * GstURIHandlerInterface:
Wim Taymans's avatar
Wim Taymans committed
105
 * @parent: The parent interface type
106
 * @get_type: Method to tell whether the element handles source or sink URI.
Edward Hervey's avatar
Edward Hervey committed
107 108 109 110
 * @get_protocols: Method to return the list of protocols handled by the element.
 * @get_uri: Method to return the URI currently handled by the element.
 * @set_uri: Method to set a new URI.
 *
Stefan Kost's avatar
Stefan Kost committed
111
 * Any #GstElement using this interface should implement these methods.
Edward Hervey's avatar
Edward Hervey committed
112
 */
113
struct _GstURIHandlerInterface {
114
  GTypeInterface parent;
115

Benjamin Otte's avatar
Benjamin Otte committed
116
  /* vtable */
Edward Hervey's avatar
Edward Hervey committed
117
  /*< public >*/
Benjamin Otte's avatar
Benjamin Otte committed
118
  /* querying capabilities */
119 120
  GstURIType             (* get_type)           (GType type);
  const gchar * const *  (* get_protocols)      (GType type);
121

Benjamin Otte's avatar
Benjamin Otte committed
122
  /* using the interface */
123 124 125 126
  gchar *                (* get_uri)            (GstURIHandler * handler);
  gboolean               (* set_uri)            (GstURIHandler * handler,
                                                 const gchar   * uri,
                                                 GError       ** error);
127 128
};

Benjamin Otte's avatar
Benjamin Otte committed
129
/* general URI functions */
130

131 132 133 134
gboolean        gst_uri_protocol_is_valid       (const gchar * protocol);
gboolean        gst_uri_protocol_is_supported   (const GstURIType type,
                                                 const gchar *protocol);
gboolean        gst_uri_is_valid                (const gchar * uri);
135
gchar *         gst_uri_get_protocol            (const gchar * uri) G_GNUC_MALLOC;
136 137
gboolean        gst_uri_has_protocol            (const gchar * uri,
                                                 const gchar * protocol);
138
gchar *         gst_uri_get_location            (const gchar * uri) G_GNUC_MALLOC;
139
gchar *         gst_uri_construct               (const gchar * protocol,
140
                                                 const gchar * location) G_GNUC_MALLOC;
141

142
gchar *         gst_filename_to_uri             (const gchar * filename,
143
                                                 GError     ** error) G_GNUC_MALLOC;
144

145 146
GstElement *    gst_element_make_from_uri       (const GstURIType type,
                                                 const gchar *    uri,
147 148
                                                 const gchar *    elementname,
                                                 GError      **   error) G_GNUC_MALLOC;
149

Benjamin Otte's avatar
Benjamin Otte committed
150
/* accessing the interface */
151 152 153 154
GType                 gst_uri_handler_get_type (void);

GstURIType            gst_uri_handler_get_uri_type  (GstURIHandler * handler);
const gchar * const * gst_uri_handler_get_protocols (GstURIHandler * handler);
155
gchar *               gst_uri_handler_get_uri       (GstURIHandler * handler) G_GNUC_MALLOC;
156 157 158
gboolean              gst_uri_handler_set_uri       (GstURIHandler * handler,
                                                     const gchar   * uri,
                                                     GError       ** error);
159

160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179
/*
 * GstUri Type macros.
 */
#define GST_TYPE_URI        (gst_uri_get_type ())
#define GST_IS_URI(obj)	    (GST_IS_MINI_OBJECT_TYPE (obj, GST_TYPE_URI))
#define GST_URI_CAST(obj)   ((GstUri *)(obj))
#define GST_URI_CONST_CAST(obj) ((const GstUri *)(obj))
#define GST_URI(obj)        (GST_URI_CAST(obj))

/**
 * GstUri:
 *
 * This is a private structure that holds the various parts of a parsed URI.
 */
struct _GstUri;
typedef struct _GstUri GstUri;

/**
 * GST_URI_NO_PORT:
 *
180
 * Value for #GstUri<!-- -->.port to indicate no port number.
181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211
 */
#define GST_URI_NO_PORT 0

/* used by GST_TYPE_URI */
GType gst_uri_get_type (void);

/*
 * Method definitions.
 */

GstUri * gst_uri_new                   (const gchar * scheme,
                                        const gchar * userinfo,
                                        const gchar * host,
                                        guint port,
                                        const gchar * path,
                                        const gchar * query,
                                        const gchar * fragment) G_GNUC_MALLOC;
GstUri * gst_uri_new_with_base         (GstUri * base,
                                        const gchar * scheme,
                                        const gchar * userinfo,
                                        const gchar * host,
                                        guint port,
                                        const gchar * path,
                                        const gchar * query,
                                        const gchar * fragment) G_GNUC_MALLOC;
GstUri * gst_uri_from_string           (const gchar * uri) G_GNUC_MALLOC;
GstUri * gst_uri_from_string_with_base (GstUri * base,
                                        const gchar * uri) G_GNUC_MALLOC;
gboolean gst_uri_equal                 (const GstUri * first,
                                        const GstUri * second);
GstUri * gst_uri_join                  (GstUri * base_uri,
212
                                        GstUri * ref_uri) G_GNUC_WARN_UNUSED_RESULT;
213 214 215
gchar *  gst_uri_join_strings          (const gchar * base_uri,
                                        const gchar * ref_uri) G_GNUC_MALLOC;
gboolean gst_uri_is_writable           (const GstUri * uri);
216
GstUri * gst_uri_make_writable         (GstUri * uri) G_GNUC_WARN_UNUSED_RESULT;
217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252
gchar *  gst_uri_to_string             (const GstUri * uri) G_GNUC_MALLOC;
gboolean gst_uri_is_normalized         (const GstUri * uri);
gboolean gst_uri_normalize             (GstUri * uri);
const gchar * gst_uri_get_scheme       (const GstUri * uri);
gboolean gst_uri_set_scheme            (GstUri * uri, const gchar * scheme);
const gchar * gst_uri_get_userinfo     (const GstUri * uri);
gboolean gst_uri_set_userinfo          (GstUri * uri, const gchar * userinfo);
const gchar * gst_uri_get_host         (const GstUri * uri);
gboolean gst_uri_set_host              (GstUri * uri, const gchar * host);
guint gst_uri_get_port                 (const GstUri * uri);
gboolean gst_uri_set_port              (GstUri * uri, guint port);
gchar * gst_uri_get_path               (const GstUri * uri);
gboolean gst_uri_set_path              (GstUri * uri, const gchar * path);
gchar * gst_uri_get_path_string        (const GstUri * uri);
gboolean gst_uri_set_path_string       (GstUri * uri, const gchar * path);
GList * gst_uri_get_path_segments      (const GstUri * uri);
gboolean gst_uri_set_path_segments     (GstUri * uri, GList * path_segments);
gboolean gst_uri_append_path           (GstUri * uri,
                                        const gchar * relative_path);
gboolean gst_uri_append_path_segment   (GstUri * uri,
                                        const gchar * path_segment);
gchar * gst_uri_get_query_string       (const GstUri * uri);
gboolean gst_uri_set_query_string      (GstUri * uri, const gchar * query);
GHashTable * gst_uri_get_query_table   (const GstUri * uri);
gboolean gst_uri_set_query_table       (GstUri * uri,
                                        GHashTable * query_table);
gboolean gst_uri_set_query_value       (GstUri * uri, const gchar * query_key,
                                        const gchar * query_value);
gboolean gst_uri_remove_query_key      (GstUri * uri, const gchar * query_key);
gboolean gst_uri_query_has_key         (const GstUri * uri,
                                        const gchar * query_key);
const gchar * gst_uri_get_query_value  (const GstUri * uri,
                                        const gchar * query_key);
GList * gst_uri_get_query_keys         (const GstUri * uri);
const gchar * gst_uri_get_fragment     (const GstUri * uri);
gboolean gst_uri_set_fragment          (GstUri * uri, const gchar * fragment);
253
GHashTable * gst_uri_get_media_fragment_table  (const GstUri * uri);
254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301

/**
 * gst_uri_copy:
 * @uri: This #GstUri object.
 *
 * Create a new #GstUri object with the same data as this #GstUri object.
 * If @uri is %NULL then returns %NULL.
 *
 * Returns: (transfer full): A new #GstUri object which is a copy of this
 *          #GstUri or %NULL.
 */
static inline GstUri *
gst_uri_copy (const GstUri * uri)
{
  return GST_URI_CAST (gst_mini_object_copy (GST_MINI_OBJECT_CONST_CAST (uri)));
}

/**
 * gst_uri_ref:
 * @uri: (transfer none): This #GstUri object.
 *
 * Add a reference to this #GstUri object. See gst_mini_object_ref() for further
 * info.
 *
 * Returns: This object with the reference count incremented.
 */
static inline GstUri *
gst_uri_ref (GstUri * uri)
{
  return GST_URI_CAST (gst_mini_object_ref (GST_MINI_OBJECT_CAST (uri)));
}

/**
 * gst_uri_unref:
 * @uri: (transfer full): This #GstUri object.
 *
 * Decrement the reference count to this #GstUri object.
 *
 * If the reference count drops to 0 then finalize this object.
 *
 * See gst_mini_object_unref() for further info.
 */
static inline void
gst_uri_unref (GstUri * uri)
{
  gst_mini_object_unref (GST_MINI_OBJECT_CAST (uri));
}

302 303 304 305
#ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstUri, gst_uri_unref)
#endif

306
G_END_DECLS
307

Benjamin Otte's avatar
Benjamin Otte committed
308
#endif /* __GST_URI_H__ */