GstUri

GstUri — URI parsing and manipulation.

Synopsis

#include <gst/gst.h>

#define             GST_URI_CAST                        (obj)
#define             GST_URI_CONST_CAST                  (obj)
                    GstUri;
GstUri *            gst_uri_new                         (const gchar *scheme,
                                                         const gchar *userinfo,
                                                         const gchar *host,
                                                         guint port,
                                                         const gchar *path,
                                                         const gchar *query,
                                                         const gchar *fragment);
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);
GstUri *            gst_uri_from_string                 (const gchar *uri);
GstUri *            gst_uri_from_string_with_base       (GstUri *base,
                                                         const gchar *uri);
GstUri *            gst_uri_copy                        (const GstUri *uri);
gboolean            gst_uri_equal                       (const GstUri *first,
                                                         const GstUri *second);
GstUri *            gst_uri_join                        (GstUri *base_uri,
                                                         GstUri *ref_uri);
gchar *             gst_uri_join_strings                (const gchar *base_uri,
                                                         const gchar *ref_uri);
gboolean            gst_uri_is_writable                 (const GstUri *uri);
GstUri *            gst_uri_make_writable               (GstUri *uri);
gchar *             gst_uri_to_string                   (const GstUri *uri);
GstUri *            gst_uri_ref                         (GstUri *uri);
void                gst_uri_unref                       (GstUri *uri);
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);
const gchar *       gst_uri_get_query_value             (const GstUri *uri,
                                                         const gchar *query_key);
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);
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);

Description

A GstUri object can be used to parse and split a URI string into its constituant parts. Two GstUri objects can be joined to make a new GstUri using the algorithm described in RFC3986.

Details

GST_URI_CAST()

#define GST_URI_CAST(obj)   ((GstUri *)(obj))

GST_URI_CONST_CAST()

#define GST_URI_CONST_CAST(obj) ((const GstUri *)(obj))

GstUri

typedef struct _GstUri GstUri;

This is a private structure that holds the various parts of a parsed URI.


gst_uri_new ()

GstUri *            gst_uri_new                         (const gchar *scheme,
                                                         const gchar *userinfo,
                                                         const gchar *host,
                                                         guint port,
                                                         const gchar *path,
                                                         const gchar *query,
                                                         const gchar *fragment);

Creates a new GstUri object with the given URI parts. The path and query strings will be broken down into their elements. All strings should not be escaped except where indicated.

scheme :

The scheme for the new URI. [nullable]

userinfo :

The user-info for the new URI. [nullable]

host :

The host name for the new URI. [nullable]

port :

The port number for the new URI or GST_URI_NO_PORT.

path :

The path for the new URI with '/' separating path elements. [nullable]

query :

The query string for the new URI with '&' separating query elements. Elements containing '&' characters should encode them as "%26". [nullable]

fragment :

The fragment name for the new URI. [nullable]

Returns :

A new GstUri object. [transfer full]

Since 1.6


gst_uri_new_with_base ()

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);

Like gst_uri_new(), but joins the new URI onto a base URI.

base :

The base URI to join the new URI to. [transfer none][nullable]

scheme :

The scheme for the new URI. [nullable]

userinfo :

The user-info for the new URI. [nullable]

host :

The host name for the new URI. [nullable]

port :

The port number for the new URI or GST_URI_NO_PORT.

path :

The path for the new URI with '/' separating path elements. [nullable]

query :

The query string for the new URI with '&' separating query elements. Elements containing '&' characters should encode them as "%26". [nullable]

fragment :

The fragment name for the new URI. [nullable]

Returns :

The new URI joined onto base. [transfer full]

Since 1.6


gst_uri_from_string ()

GstUri *            gst_uri_from_string                 (const gchar *uri);

Parses a URI string into a new GstUri object. Will return NULL if the URI cannot be parsed.

uri :

The URI string to parse.

Returns :

A new GstUri object, or NULL. [transfer full][nullable]

Since 1.6


gst_uri_from_string_with_base ()

GstUri *            gst_uri_from_string_with_base       (GstUri *base,
                                                         const gchar *uri);

Like gst_uri_from_string() but also joins with a base URI.

base :

The base URI to join the new URI with. [transfer none][nullable]

uri :

The URI string to parse.

Returns :

A new GstUri object. [transfer full]

Since 1.6


gst_uri_copy ()

GstUri *            gst_uri_copy                        (const GstUri *uri);

Create a new GstUri object with the same data as this GstUri object. If uri is NULL then returns NULL.

uri :

This GstUri object.

Returns :

A new GstUri object which is a copy of this GstUri or NULL. [transfer full]

gst_uri_equal ()

gboolean            gst_uri_equal                       (const GstUri *first,
                                                         const GstUri *second);

Compares two GstUri objects to see if they represent the same normalized URI.

first :

First GstUri to compare.

second :

Second GstUri to compare.

Returns :

TRUE if the normalized versions of the two URI's would be equal.

Since 1.6


gst_uri_join ()

GstUri *            gst_uri_join                        (GstUri *base_uri,
                                                         GstUri *ref_uri);

Join a reference URI onto a base URI using the method from RFC 3986. If either URI is NULL then the other URI will be returned with the ref count increased.

base_uri :

The base URI to join another to. [transfer none][nullable]

ref_uri :

The reference URI to join onto the base URI. [transfer none][nullable]

Returns :

A GstUri which represents the base with the reference URI joined on. [transfer full]

Since 1.6


gst_uri_join_strings ()

gchar *             gst_uri_join_strings                (const gchar *base_uri,
                                                         const gchar *ref_uri);

This is a convenience function to join two URI strings and return the result. The returned string should be g_free()'d after use.

base_uri :

The percent-encoded base URI.

ref_uri :

The percent-encoded reference URI to join to the base_uri.

Returns :

A string representing the percent-encoded join of the two URIs. [transfer full]

Since 1.6


gst_uri_is_writable ()

gboolean            gst_uri_is_writable                 (const GstUri *uri);

Check if it is safe to write to this GstUri.

Check if the refcount of uri is exactly 1, meaning that no other reference exists to the GstUri and that the GstUri is therefore writable.

Modification of a GstUri should only be done after verifying that it is writable.

uri :

The GstUri object to test.

Returns :

TRUE if it is safe to write to the object.

Since 1.6


gst_uri_make_writable ()

GstUri *            gst_uri_make_writable               (GstUri *uri);

Make the GstUri writable.

Checks if uri is writable, and if so the original object is returned. If not, then a writable copy is made and returned. This gives away the reference to uri and returns a reference to the new GstUri. If uri is NULL then NULL is returned.

uri :

The GstUri object to make writable. [transfer full]

Returns :

A writable version of uri. [transfer full]

Since 1.6


gst_uri_to_string ()

gchar *             gst_uri_to_string                   (const GstUri *uri);

Convert the URI to a string.

Returns the URI as held in this object as a gchar* nul-terminated string. The caller should g_free() the string once they are finished with it. The string is put together as described in RFC 3986.

uri :

This GstUri to convert to a string.

Returns :

The string version of the URI. [transfer full]

Since 1.6


gst_uri_ref ()

GstUri *            gst_uri_ref                         (GstUri *uri);

Add a reference to this GstUri object. See gst_mini_object_ref() for further info.

uri :

This GstUri object. [transfer none]

Returns :

This object with the reference count incremented.

gst_uri_unref ()

void                gst_uri_unref                       (GstUri *uri);

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.

uri :

This GstUri object. [transfer full]

gst_uri_is_normalized ()

gboolean            gst_uri_is_normalized               (const GstUri *uri);

Tests the uri to see if it is normalized. A NULL uri is considered to be normalized.

uri :

The GstUri to test to see if it is normalized.

Returns :

TRUE if the URI is normalized or is NULL.

Since 1.6


gst_uri_normalize ()

gboolean            gst_uri_normalize                   (GstUri *uri);

Normalization will remove extra path segments ("." and "..") from the URI. It will also convert the scheme and host name to lower case and any percent-encoded values to uppercase.

The GstUri object must be writable. Check with gst_uri_is_writable() or use gst_uri_make_writable() first.

uri :

The GstUri to normalize. [transfer none]

Returns :

TRUE if the URI was modified.

Since 1.6


gst_uri_get_scheme ()

const gchar *       gst_uri_get_scheme                  (const GstUri *uri);

Get the scheme name from the URI or NULL if it doesn't exist. If uri is NULL then returns NULL.

uri :

This GstUri object. [nullable]

Returns :

The scheme from the GstUri object or NULL.

gst_uri_set_scheme ()

gboolean            gst_uri_set_scheme                  (GstUri *uri,
                                                         const gchar *scheme);

Set or unset the scheme for the URI.

uri :

The GstUri to modify. [transfer none][nullable]

scheme :

The new scheme to set or NULL to unset the scheme.

Returns :

TRUE if the scheme was set/unset successfully.

Since 1.6


gst_uri_get_userinfo ()

const gchar *       gst_uri_get_userinfo                (const GstUri *uri);

Get the userinfo (usually in the form "username:password") from the URI or NULL if it doesn't exist. If uri is NULL then returns NULL.

uri :

This GstUri object. [nullable]

Returns :

The userinfo from the GstUri object or NULL.

Since 1.6


gst_uri_set_userinfo ()

gboolean            gst_uri_set_userinfo                (GstUri *uri,
                                                         const gchar *userinfo);

Set or unset the user information for the URI.

uri :

The GstUri to modify. [transfer none][nullable]

userinfo :

The new user-information string to set or NULL to unset.

Returns :

TRUE if the user information was set/unset successfully.

Since 1.6


gst_uri_get_host ()

const gchar *       gst_uri_get_host                    (const GstUri *uri);

Get the host name from the URI or NULL if it doesn't exist. If uri is NULL then returns NULL.

uri :

This GstUri object. [nullable]

Returns :

The host name from the GstUri object or NULL.

Since 1.6


gst_uri_set_host ()

gboolean            gst_uri_set_host                    (GstUri *uri,
                                                         const gchar *host);

Set or unset the host for the URI.

uri :

The GstUri to modify. [transfer none][nullable]

host :

The new host string to set or NULL to unset.

Returns :

TRUE if the host was set/unset successfully.

Since 1.6


gst_uri_get_port ()

guint               gst_uri_get_port                    (const GstUri *uri);

Get the port number from the URI or GST_URI_NO_PORT if it doesn't exist. If uri is NULL then returns GST_URI_NO_PORT.

uri :

This GstUri object. [nullable]

Returns :

The port number from the GstUri object or GST_URI_NO_PORT.

Since 1.6


gst_uri_set_port ()

gboolean            gst_uri_set_port                    (GstUri *uri,
                                                         guint port);

Set or unset the port number for the URI.

uri :

The GstUri to modify. [transfer none][nullable]

port :

The new port number to set or GST_URI_NO_PORT to unset.

Returns :

TRUE if the port number was set/unset successfully.

Since 1.6


gst_uri_get_path ()

gchar *             gst_uri_get_path                    (const GstUri *uri);

Extract the path string from the URI object.

uri :

The GstUri to get the path from.

Returns :

The path from the URI. Once finished with the string should be g_free()'d. [transfer full]

Since 1.6


gst_uri_set_path ()

gboolean            gst_uri_set_path                    (GstUri *uri,
                                                         const gchar *path);

Sets or unsets the path in the URI.

uri :

The GstUri to modify. [transfer none][nullable]

path :

The new path to set with path segments separated by '/', or use NULL to unset the path.

Returns :

TRUE if the path was set successfully.

Since 1.6


gst_uri_get_path_string ()

gchar *             gst_uri_get_path_string             (const GstUri *uri);

Extract the path string from the URI object as a percent encoded URI path.

uri :

The GstUri to get the path from.

Returns :

The path from the URI. Once finished with the string should be g_free()'d. [transfer full]

Since 1.6


gst_uri_set_path_string ()

gboolean            gst_uri_set_path_string             (GstUri *uri,
                                                         const gchar *path);

Sets or unsets the path in the URI.

uri :

The GstUri to modify. [transfer none][nullable]

path :

The new percent encoded path to set with path segments separated by '/', or use NULL to unset the path.

Returns :

TRUE if the path was set successfully.

Since 1.6


gst_uri_get_path_segments ()

GList *             gst_uri_get_path_segments           (const GstUri *uri);

Get a list of path segments from the URI.

uri :

The GstUri to get the path from. [nullable]

Returns :

A GList of path segment strings or NULL if no path segments are available. Free the list when no longer needed with g_list_free_full(list, g_free). [transfer full][element-type gchar*]

Since 1.6


gst_uri_set_path_segments ()

gboolean            gst_uri_set_path_segments           (GstUri *uri,
                                                         GList *path_segments);

Replace the path segments list in the URI.

uri :

The GstUri to modify. [transfer none][nullable]

path_segments :

The new path list to set. [transfer full][nullable][element-type gchar*]

Returns :

TRUE if the path segments were set successfully.

Since 1.6


gst_uri_append_path ()

gboolean            gst_uri_append_path                 (GstUri *uri,
                                                         const gchar *relative_path);

Append a path onto the end of the path in the URI. The path is not normalized, call #gst_uri_normalize() to normalize the path.

uri :

The GstUri to modify. [transfer none][nullable]

relative_path :

Relative path to append to the end of the current path.

Returns :

TRUE if the path was appended successfully.

Since 1.6


gst_uri_append_path_segment ()

gboolean            gst_uri_append_path_segment         (GstUri *uri,
                                                         const gchar *path_segment);

Append a single path segment onto the end of the URI path.

uri :

The GstUri to modify. [transfer none][nullable]

path_segment :

The path segment string to append to the URI path.

Returns :

TRUE if the path was appended successfully.

Since 1.6


gst_uri_get_query_string ()

gchar *             gst_uri_get_query_string            (const GstUri *uri);

Get a percent encoded URI query string from the uri.

uri :

The GstUri to get the query string from. [nullable]

Returns :

A percent encoded query string. Use g_free() when no longer needed. [transfer full]

Since 1.6


gst_uri_set_query_string ()

gboolean            gst_uri_set_query_string            (GstUri *uri,
                                                         const gchar *query);

Sets or unsets the query table in the URI.

uri :

The GstUri to modify. [transfer none][nullable]

query :

The new percent encoded query string to use to populate the query table, or use NULL to unset the query table.

Returns :

TRUE if the query table was set successfully.

Since 1.6


gst_uri_get_query_table ()

GHashTable *        gst_uri_get_query_table             (const GstUri *uri);

Get the query table from the URI. Keys and values in the table are freed with g_free when they are deleted. A value may be NULL to indicate that the key should appear in the query string in the URI, but does not have a value. Free the returned GHashTable with #g_hash_table_unref() when it is no longer required. Modifying this hash table will modify the query in the URI.

uri :

The GstUri to get the query table from. [nullable]

Returns :

The query hash table from the URI. [transfer full][element-type gchar* gchar*]

Since 1.6


gst_uri_set_query_table ()

gboolean            gst_uri_set_query_table             (GstUri *uri,
                                                         GHashTable *query_table);

Set the query table to use in the URI. The old table is unreferenced and a reference to the new one is used instead. A value if NULL for query_table will remove the query string from the URI.

uri :

The GstUri to modify. [transfer none][nullable]

query_table :

The new query table to use. [transfer none][nullable][element-type gchar* gchar*]

Returns :

TRUE if the new table was sucessfully used for the query table.

Since 1.6


gst_uri_get_query_value ()

const gchar *       gst_uri_get_query_value             (const GstUri *uri,
                                                         const gchar *query_key);

Get the value associated with the query_key key. Will return NULL if the key has no value or if the key does not exist in the URI query table. Because NULL is returned for both missing keys and keys with no value, you should use gst_uri_query_has_key() to determine if a key is present in the URI query.

uri :

The GstUri to examine. [nullable]

query_key :

The key to lookup.

Returns :

The value for the given key, or NULL if not found.

Since 1.6


gst_uri_set_query_value ()

gboolean            gst_uri_set_query_value             (GstUri *uri,
                                                         const gchar *query_key,
                                                         const gchar *query_value);

This inserts or replaces a key in the query table. A query_value of NULL indicates that the key has no associated value, but will still be present in the query string.

uri :

The GstUri to modify. [transfer none][nullable]

query_key :

The key for the query entry. [transfer none]

query_value :

The value for the key. [transfer none][nullable]

Returns :

TRUE if the query table was sucessfully updated.

Since 1.6


gst_uri_remove_query_key ()

gboolean            gst_uri_remove_query_key            (GstUri *uri,
                                                         const gchar *query_key);

Remove an entry from the query table by key.

uri :

The GstUri to modify. [transfer none][nullable]

query_key :

The key to remove.

Returns :

TRUE if the key existed in the table and was removed.

Since 1.6


gst_uri_query_has_key ()

gboolean            gst_uri_query_has_key               (const GstUri *uri,
                                                         const gchar *query_key);

Check if there is a query table entry for the query_key key.

uri :

The GstUri to examine. [nullable]

query_key :

The key to lookup.

Returns :

TRUE if query_key exists in the URI query table.

Since 1.6


gst_uri_get_query_keys ()

GList *             gst_uri_get_query_keys              (const GstUri *uri);

Get a list of the query keys from the URI.

uri :

The GstUri to examine. [nullable]

Returns :

A list of keys from the URI query. Free the list with g_list_free(). [transfer container][element-type gchar*]

Since 1.6


gst_uri_get_fragment ()

const gchar *       gst_uri_get_fragment                (const GstUri *uri);

Get the fragment name from the URI or NULL if it doesn't exist. If uri is NULL then returns NULL.

uri :

This GstUri object. [nullable]

Returns :

The host name from the GstUri object or NULL.

Since 1.6


gst_uri_set_fragment ()

gboolean            gst_uri_set_fragment                (GstUri *uri,
                                                         const gchar *fragment);

Sets the fragment string in the URI. Use a value of NULL in fragment to unset the fragment string.

uri :

The GstUri to modify. [transfer none][nullable]

fragment :

The fragment string to set. [nullable]

Returns :

TRUE if the fragment was set/unset successfully.

Since 1.6