GstUri: GStreamer 1.0 Core Reference Manual

## GstUri GstUri — URI parsing and manipulation. |

## Functions

#define | GST_URI_CAST()
#define | GST_URI_CONST_CAST()
GstUri * | gst_uri_new ()
GstUri * | gst_uri_new_with_base ()
GstUri * | gst_uri_from_string ()
GstUri * | gst_uri_from_string_with_base ()
GstUri * | gst_uri_copy ()
gboolean | gst_uri_equal ()
GstUri * | gst_uri_join ()
gchar * | gst_uri_join_strings ()
gboolean | gst_uri_is_writable ()
GstUri * | gst_uri_make_writable ()
gchar * | gst_uri_to_string ()
GstUri * | gst_uri_ref ()
void | gst_uri_unref ()
gboolean | gst_uri_is_normalized ()
gboolean | gst_uri_normalize ()
const gchar * | gst_uri_get_scheme ()
gboolean | gst_uri_set_scheme ()
const gchar * | gst_uri_get_userinfo ()
gboolean | gst_uri_set_userinfo ()
const gchar * | gst_uri_get_host ()
gboolean | gst_uri_set_host ()
guint | gst_uri_get_port ()
gboolean | gst_uri_set_port ()
gchar * | gst_uri_get_path ()
gboolean | gst_uri_set_path ()
gchar * | gst_uri_get_path_string ()
gboolean | gst_uri_set_path_string ()
GList * | gst_uri_get_path_segments ()
gboolean | gst_uri_set_path_segments ()
gboolean | gst_uri_append_path ()
gboolean | gst_uri_append_path_segment ()
gchar * | gst_uri_get_query_string ()
gboolean | gst_uri_set_query_string ()
GHashTable * | gst_uri_get_query_table ()
gboolean | gst_uri_set_query_table ()
const gchar * | gst_uri_get_query_value ()
gboolean | gst_uri_set_query_value ()
gboolean | gst_uri_remove_query_key ()
gboolean | gst_uri_query_has_key ()
GList * | gst_uri_get_query_keys ()
const gchar * | gst_uri_get_fragment ()
gboolean | gst_uri_set_fragment ()

## Types and Values

| GstUri

## Includes

    #include <gst/gst.h>

## 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.

## Functions

### GST_URI_CAST()

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

### GST_URI_CONST_CAST()

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

### 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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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`.

#### Parameters

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.

#### Parameters

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`.

#### Parameters

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.

#### Parameters

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`.

#### Parameters

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.

#### Parameters

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`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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`.

#### Parameters

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.

#### Parameters

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

## Types and Values

### GstUri

    typedef struct _GstUri GstUri;

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