manpagez: man pages & more
html files: gstreamer-1.0
Home | html | info | man

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 ()
GHashTable * gst_uri_get_media_fragment_table ()

Types and Values

  GstUri

Includes

#include <gst/gstprotection.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][nullable]

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.

[nullable]


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.

[nullable]

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.

[nullable]

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

(nullable): 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][nullable]

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][nullable]

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*][nullable]

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.

[nullable]

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.

[nullable]

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


gst_uri_get_media_fragment_table ()

GHashTable *
gst_uri_get_media_fragment_table (const GstUri *uri);

Get the media fragment table from the URI, as defined by "Media Fragments URI 1.0". Hash table returned by this API is a list of "key-value" pairs, and the each pair is generated by splitting "URI fragment" per "&" sub-delims, then "key" and "value" are splitted by "=" sub-delims. The "key" returned by this API may be undefined keyword by standard. A value may be NULL to indicate that the key should appear in the fragment 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 does not affect the fragment in the URI.

See more about Media Fragments URI 1.0 (W3C) at https://www.w3.org/TR/media-frags/

Parameters

uri

The GstUri to get the fragment table from.

[nullable]

Returns

The fragment hash table from the URI.

[transfer full][element-type gchar* gchar*][nullable]

Since: 1.12

Types and Values

GstUri

typedef struct _GstUri GstUri;

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

© manpagez.com 2000-2024
Individual documents may contain additional copyright information.