/* GStreamer
* Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
* 2000 Wim Taymans <wtay@chello.be>
+ * 2014 David Waring, British Broadcasting Corporation
+ * <david.waring@rd.bbc.co.uk>
*
- * gsturi.h: Header for uri to element mappings
+ * gsturi.h: Header for uri to element mappings and URI manipulation.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
*
* You should have received a copy of the GNU Library General Public
* License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
+ * Boston, MA 02110-1301, USA.
*/
#define __GST_URI_H__
#include <glib.h>
-#include <gst/gstelement.h>
-#include <gst/gstpluginfeature.h>
+#include <glib-object.h>
G_BEGIN_DECLS
+#include <gst/gstconfig.h>
+
+GST_API
+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:
+ * @GST_URI_ERROR_UNSUPPORTED_PROTOCOL: The protocol is not supported
+ * @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
+{
+ GST_URI_ERROR_UNSUPPORTED_PROTOCOL,
+ GST_URI_ERROR_BAD_URI,
+ GST_URI_ERROR_BAD_STATE,
+ GST_URI_ERROR_BAD_REFERENCE
+} GstURIError;
+
/**
* GstURIType:
- * @GST_URI_UNKNOWN : The URI direction is unknown
- * @GST_URI_SINK : The URI is a consumer.
- * @GST_URI_SRC : The URI is a producer.
+ * @GST_URI_UNKNOWN: The URI direction is unknown
+ * @GST_URI_SINK: The URI is a consumer.
+ * @GST_URI_SRC: The URI is a producer.
*
* The different types of URI direction.
*/
#define GST_URI_TYPE_IS_VALID(type) ((type) == GST_URI_SRC || (type) == GST_URI_SINK)
/* uri handler functions */
-#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))
+#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))
/**
* GstURIHandler:
typedef struct _GstURIHandler GstURIHandler;
typedef struct _GstURIHandlerInterface GstURIHandlerInterface;
+#include <gst/gstelement.h>
+#include "gstminiobject.h"
+
/**
* GstURIHandlerInterface:
* @parent: The parent interface type
* @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.
- * @get_type_full: Variant of get_type which takes a GType argument. This is
- * for use by bindings that need to pass context when creating a URI Handler. * If implemented, get_type will be used in preference to get_type_full. Since: 0.10.15.
- * @get_protocols_full: Variant of get_type which takes a GType argument.
- * This is for use by bindings that need to pass context when creating a URI
- * Handler. If implemented, get_protocols will be used in preference to
- * get_protocols_full. Since: 0.10.15.
*
* Any #GstElement using this interface should implement these methods.
*/
struct _GstURIHandlerInterface {
- GTypeInterface parent;
-
- /*< private >*/
- /* signals */
- void (* new_uri) (GstURIHandler * handler,
- const gchar * uri);
- /* idea for the future ?
- gboolean (* require_password) (GstURIHandler * handler,
- gchar ** username,
- gchar ** password);
- */
+ GTypeInterface parent;
/* vtable */
-
/*< public >*/
/* querying capabilities */
- GstURIType (* get_type) (void);
- gchar ** (* get_protocols) (void);
+ GstURIType (* get_type) (GType type);
+ const gchar * const * (* get_protocols) (GType type);
/* using the interface */
- G_CONST_RETURN gchar *(* get_uri) (GstURIHandler * handler);
- gboolean (* set_uri) (GstURIHandler * handler,
- const gchar * uri);
+ gchar * (* get_uri) (GstURIHandler * handler);
+ gboolean (* set_uri) (GstURIHandler * handler,
+ const gchar * uri,
+ GError ** error);
+};
- GstURIType (* get_type_full) (GType type);
- gchar ** (* get_protocols_full) (GType type);
+/* general URI functions */
- /*< private >*/
- /* we might want to add functions here to query features,
- * someone with gnome-vfs knowledge go ahead */
+GST_API
+gboolean gst_uri_protocol_is_valid (const gchar * protocol);
- gpointer _gst_reserved[GST_PADDING - 2];
-};
+GST_API
+gboolean gst_uri_protocol_is_supported (const GstURIType type,
+ const gchar *protocol);
+GST_API
+gboolean gst_uri_is_valid (const gchar * uri);
-/* general URI functions */
+GST_API
+gchar * gst_uri_get_protocol (const gchar * uri) G_GNUC_MALLOC;
-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);
-gchar * gst_uri_get_protocol (const gchar * uri);
+GST_API
gboolean gst_uri_has_protocol (const gchar * uri,
const gchar * protocol);
-gchar * gst_uri_get_location (const gchar * uri);
-gchar * gst_uri_construct (const gchar * protocol,
- const gchar * location);
+GST_API
+gchar * gst_uri_get_location (const gchar * uri) G_GNUC_MALLOC;
-GstElement * gst_element_make_from_uri (const GstURIType type,
- const gchar * uri,
- const gchar * elementname);
+GST_DEPRECATED_FOR(gst_uri_new)
+gchar * gst_uri_construct (const gchar * protocol,
+ const gchar * location) G_GNUC_MALLOC;
+GST_API
+gchar * gst_filename_to_uri (const gchar * filename,
+ GError ** error) G_GNUC_MALLOC;
+GST_API
+GstElement * gst_element_make_from_uri (const GstURIType type,
+ const gchar * uri,
+ const gchar * elementname,
+ GError ** error) G_GNUC_MALLOC;
/* accessing the interface */
-GType gst_uri_handler_get_type (void);
-
-guint gst_uri_handler_get_uri_type (GstURIHandler * handler);
-gchar ** gst_uri_handler_get_protocols (GstURIHandler * handler);
-G_CONST_RETURN
-gchar * gst_uri_handler_get_uri (GstURIHandler * handler);
-gboolean gst_uri_handler_set_uri (GstURIHandler * handler,
- const gchar * uri);
-void gst_uri_handler_new_uri (GstURIHandler * handler,
- const gchar * uri);
+
+GST_API
+GType gst_uri_handler_get_type (void);
+
+GST_API
+GstURIType gst_uri_handler_get_uri_type (GstURIHandler * handler);
+
+GST_API
+const gchar * const * gst_uri_handler_get_protocols (GstURIHandler * handler);
+
+GST_API
+gchar * gst_uri_handler_get_uri (GstURIHandler * handler) G_GNUC_MALLOC;
+
+GST_API
+gboolean gst_uri_handler_set_uri (GstURIHandler * handler,
+ const gchar * uri,
+ GError ** error);
+
+/*
+ * 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:
+ *
+ * Value for #GstUri<!-- -->.port to indicate no port number.
+ */
+#define GST_URI_NO_PORT 0
+
+/* used by GST_TYPE_URI */
+
+GST_API
+GType gst_uri_get_type (void);
+
+/*
+ * Method definitions.
+ */
+
+GST_API
+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;
+GST_API
+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;
+GST_API
+GstUri * gst_uri_from_string (const gchar * uri) G_GNUC_MALLOC;
+
+GST_API
+GstUri * gst_uri_from_string_with_base (GstUri * base,
+ const gchar * uri) G_GNUC_MALLOC;
+GST_API
+gboolean gst_uri_equal (const GstUri * first,
+ const GstUri * second);
+GST_API
+GstUri * gst_uri_join (GstUri * base_uri,
+ GstUri * ref_uri) G_GNUC_WARN_UNUSED_RESULT;
+GST_API
+gchar * gst_uri_join_strings (const gchar * base_uri,
+ const gchar * ref_uri) G_GNUC_MALLOC;
+GST_API
+gboolean gst_uri_is_writable (const GstUri * uri);
+
+GST_API
+GstUri * gst_uri_make_writable (GstUri * uri) G_GNUC_WARN_UNUSED_RESULT;
+
+GST_API
+gchar * gst_uri_to_string (const GstUri * uri) G_GNUC_MALLOC;
+
+GST_API
+gboolean gst_uri_is_normalized (const GstUri * uri);
+
+GST_API
+gboolean gst_uri_normalize (GstUri * uri);
+
+GST_API
+const gchar * gst_uri_get_scheme (const GstUri * uri);
+
+GST_API
+gboolean gst_uri_set_scheme (GstUri * uri, const gchar * scheme);
+
+GST_API
+const gchar * gst_uri_get_userinfo (const GstUri * uri);
+
+GST_API
+gboolean gst_uri_set_userinfo (GstUri * uri, const gchar * userinfo);
+
+GST_API
+const gchar * gst_uri_get_host (const GstUri * uri);
+
+GST_API
+gboolean gst_uri_set_host (GstUri * uri, const gchar * host);
+
+GST_API
+guint gst_uri_get_port (const GstUri * uri);
+
+GST_API
+gboolean gst_uri_set_port (GstUri * uri, guint port);
+
+GST_API
+gchar * gst_uri_get_path (const GstUri * uri);
+
+GST_API
+gboolean gst_uri_set_path (GstUri * uri, const gchar * path);
+
+GST_API
+gchar * gst_uri_get_path_string (const GstUri * uri);
+
+GST_API
+gboolean gst_uri_set_path_string (GstUri * uri, const gchar * path);
+
+GST_API
+GList * gst_uri_get_path_segments (const GstUri * uri);
+
+GST_API
+gboolean gst_uri_set_path_segments (GstUri * uri, GList * path_segments);
+
+GST_API
+gboolean gst_uri_append_path (GstUri * uri,
+ const gchar * relative_path);
+GST_API
+gboolean gst_uri_append_path_segment (GstUri * uri,
+ const gchar * path_segment);
+GST_API
+gchar * gst_uri_get_query_string (const GstUri * uri);
+
+GST_API
+gboolean gst_uri_set_query_string (GstUri * uri, const gchar * query);
+
+GST_API
+GHashTable * gst_uri_get_query_table (const GstUri * uri);
+
+GST_API
+gboolean gst_uri_set_query_table (GstUri * uri,
+ GHashTable * query_table);
+GST_API
+gboolean gst_uri_set_query_value (GstUri * uri, const gchar * query_key,
+ const gchar * query_value);
+GST_API
+gboolean gst_uri_remove_query_key (GstUri * uri, const gchar * query_key);
+
+GST_API
+gboolean gst_uri_query_has_key (const GstUri * uri,
+ const gchar * query_key);
+
+GST_API
+const gchar * gst_uri_get_query_value (const GstUri * uri,
+ const gchar * query_key);
+
+GST_API
+GList * gst_uri_get_query_keys (const GstUri * uri);
+
+GST_API
+const gchar * gst_uri_get_fragment (const GstUri * uri);
+
+GST_API
+gboolean gst_uri_set_fragment (GstUri * uri, const gchar * fragment);
+
+GST_API
+GHashTable * gst_uri_get_media_fragment_table (const GstUri * uri);
+
+/**
+ * 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));
+}
+
+#ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
+G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstUri, gst_uri_unref)
+#endif
G_END_DECLS