Gst.Uri¶

Fields¶

None

Methods¶

class	`construct` (protocol, location)
class	`from_string` (uri)
class	`from_string_escaped` (uri)
class	`get_location` (uri)
class	`get_protocol` (uri)
class	`has_protocol` (uri, protocol)
class	`is_valid` (uri)
class	`join_strings` (base_uri, ref_uri)
class	`new` (scheme, userinfo, host, port, path, query, fragment)
class	`protocol_is_supported` (type, protocol)
class	`protocol_is_valid` (protocol)
	`append_path` (relative_path)
	`append_path_segment` (path_segment)
	`equal` (second)
	`from_string_with_base` (uri)
	`get_fragment` ()
	`get_host` ()
	`get_media_fragment_table` ()
	`get_path` ()
	`get_path_segments` ()
	`get_path_string` ()
	`get_port` ()
	`get_query_keys` ()
	`get_query_string` ()
	`get_query_table` ()
	`get_query_value` (query_key)
	`get_scheme` ()
	`get_userinfo` ()
	`is_normalized` ()
	`is_writable` ()
	`join` (ref_uri)
	`make_writable` ()
	`new_with_base` (scheme, userinfo, host, port, path, query, fragment)
	`normalize` ()
	`query_has_key` (query_key)
	`remove_query_key` (query_key)
	`set_fragment` (fragment)
	`set_host` (host)
	`set_path` (path)
	`set_path_segments` (path_segments)
	`set_path_string` (path)
	`set_port` (port)
	`set_query_string` (query)
	`set_query_table` (query_table)
	`set_query_value` (query_key, query_value)
	`set_scheme` (scheme)
	`set_userinfo` (userinfo)
	`to_string` ()

Details¶

class Gst.Uri¶

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

classmethod construct(protocol, location)[source]¶

Parameters:	protocol (`str`) – Protocol for URI location (`str`) – Location for URI
Returns:	a new string for this URI. Returns `None` if the given URI protocol is not valid, or the given location is `None`.
Return type:	`str`

Constructs a URI for a given valid protocol and location.

Free-function: GLib.free

Deprecated since version ???: Use GstURI instead.

classmethod from_string(uri)[source]¶

Parameters:	uri (`str`) – The URI string to parse.
Returns:	A new `Gst.Uri` object, or `None`.
Return type:	`Gst.Uri` or `None`

Parses a URI string into a new Gst.Uri object. Will return None if the URI cannot be parsed.

New in version 1.6.

classmethod from_string_escaped(uri)[source]¶

Parameters:	uri (`str`) – The URI string to parse.
Returns:	A new `Gst.Uri` object, or `None`.
Return type:	`Gst.Uri` or `None`

Parses a URI string into a new Gst.Uri object. Will return None if the URI cannot be parsed. This is identical to Gst.Uri.from_string() except that the userinfo and fragment components of the URI will not be unescaped while parsing.

Use this when you need to extract a username and password from the userinfo such as https://user:password`example`.com since either may contain a URI-escaped ‘:’ character. Gst.Uri.from_string() will unescape the entire userinfo component, which will make it impossible to know which ‘:’ delineates the username and password.

The same applies to the fragment component of the URI, such as https://example.com/path#fragment which may contain a URI-escaped ‘#’.

New in version 1.18.

classmethod get_location(uri)[source]¶

Parameters:	uri (`str`) – A URI string
Returns:	the location for this URI. Returns `None` if the URI isn’t valid. If the URI does not contain a location, an empty string is returned.
Return type:	`str` or `None`

Extracts the location out of a given valid URI, ie. the protocol and “://” are stripped from the URI, which means that the location returned includes the hostname if one is specified. The returned string must be freed using GLib.free().

Free-function: GLib.free

classmethod get_protocol(uri)[source]¶

Parameters:	uri (`str`) – A URI string
Returns:	The protocol for this URI.
Return type:	`str` or `None`

Extracts the protocol out of a given valid URI. The returned string must be freed using GLib.free().

classmethod has_protocol(uri, protocol)[source]¶

Parameters:	uri (`str`) – a URI string protocol (`str`) – a protocol string (e.g. “http”)
Returns:	`True` if the protocol matches.
Return type:	`bool`

Checks if the protocol of a given valid URI matches protocol.

classmethod is_valid(uri)[source]¶

Parameters:	uri (`str`) – A URI string
Returns:	`True` if the string is a valid URI
Return type:	`bool`

Tests if the given string is a valid URI identifier. URIs start with a valid scheme followed by “:” and maybe a string identifying the location.

classmethod join_strings(base_uri, ref_uri)[source]¶

Parameters:	base_uri (`str`) – The percent-encoded base URI. ref_uri (`str`) – The percent-encoded reference URI to join to the base_uri.
Returns:	A string representing the percent-encoded join of the two URIs.
Return type:	`str`

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

New in version 1.6.

classmethod new(scheme, userinfo, host, port, path, query, fragment)[source]¶

Parameters:	scheme (`str` or `None`) – The scheme for the new URI. userinfo (`str` or `None`) – The user-info for the new URI. host (`str` or `None`) – The host name for the new URI. port (`int`) – The port number for the new URI or `Gst.URI_NO_PORT`. path (`str` or `None`) – The path for the new URI with ‘/’ separating path elements. query (`str` or `None`) – The query string for the new URI with ‘&’ separating query elements. Elements containing ‘&’ characters should encode them as “&percnt;26”. fragment (`str` or `None`) – The fragment name for the new URI.
Returns:	A new `Gst.Uri` object.
Return type:	`Gst.Uri`

Creates a new Gst.Uri 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.

New in version 1.6.

classmethod protocol_is_supported(type, protocol)[source]¶

Parameters:	type (`Gst.URIType`) – Whether to check for a source or a sink protocol (`str`) – Protocol that should be checked for (e.g. “http” or “smb”)
Returns:	`True`
Return type:	`bool`

Checks if an element exists that supports the given URI protocol. Note that a positive return value does not imply that a subsequent call to Gst.Element.make_from_uri() is guaranteed to work.

classmethod protocol_is_valid(protocol)[source]¶

Parameters:	protocol (`str`) – A string
Returns:	`True` if the string is a valid protocol identifier, `False` otherwise.
Return type:	`bool`

Tests if the given string is a valid protocol identifier. Protocols must consist of alphanumeric characters, ‘+’, ‘-’ and ‘.’ and must start with a alphabetic character. See RFC 3986 Section 3.1.

append_path(relative_path)[source]¶

Parameters:	relative_path (`str`) – Relative path to append to the end of the current path.
Returns:	`True` if the path was appended successfully.
Return type:	`bool`

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.

New in version 1.6.

append_path_segment(path_segment)[source]¶

Parameters:	path_segment (`str`) – The path segment string to append to the URI path.
Returns:	`True` if the path was appended successfully.
Return type:	`bool`

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

New in version 1.6.

equal(second)[source]¶

Parameters:	second (`Gst.Uri`) – Second `Gst.Uri` to compare.
Returns:	`True` if the normalized versions of the two URI’s would be equal.
Return type:	`bool`

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

New in version 1.6.

from_string_with_base(uri)[source]¶

Parameters:	uri (`str`) – The URI string to parse.
Returns:	A new `Gst.Uri` object.
Return type:	`Gst.Uri`

Like Gst.Uri.from_string() but also joins with a base URI.

New in version 1.6.

get_fragment()[source]¶

Returns:	The host name from the `Gst.Uri` object or `None`.
Return type:	`str` or `None`

Get the fragment name from the URI or None if it doesn’t exist. If self is None then returns None.

New in version 1.6.

get_host()[source]¶

Returns:	The host name from the `Gst.Uri` object or `None`.
Return type:	`str` or `None`

Get the host name from the URI or None if it doesn’t exist. If self is None then returns None.

New in version 1.6.

get_media_fragment_table()[source]¶

Returns:	The fragment hash table from the URI.
Return type:	{`str`: `str`} or `None`

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 split by “=” sub-delims. The “key” returned by this API may be undefined keyword by standard. A value may be None to indicate that the key should appear in the fragment string in the URI, but does not have a value. Free the returned GLib.HashTable with GLib.HashTable.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/

New in version 1.12.

get_path()[source]¶

Returns:	The path from the URI. Once finished with the string should be `GLib.free`()’d.
Return type:	`str` or `None`

Extract the path string from the URI object.

New in version 1.6.

get_path_segments()[source]¶

Returns:	A `GLib.List` of path segment strings or `None` if no path segments are available. Free the list when no longer needed with g_list_free_full(list, `GLib.free`).
Return type:	[`str`]

Get a list of path segments from the URI.

New in version 1.6.

get_path_string()[source]¶

Returns:	The path from the URI. Once finished with the string should be `GLib.free`()’d.
Return type:	`str` or `None`

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

New in version 1.6.

get_port()[source]¶

Returns:	The port number from the `Gst.Uri` object or `Gst.URI_NO_PORT`.
Return type:	`int`

Get the port number from the URI or Gst.URI_NO_PORT if it doesn’t exist. If self is None then returns Gst.URI_NO_PORT.

New in version 1.6.

get_query_keys()[source]¶

Returns:	A list of keys from the URI query. Free the list with g_list_free().
Return type:	[`str`]

Get a list of the query keys from the URI.

New in version 1.6.

get_query_string()[source]¶

Returns:	A percent encoded query string. Use `GLib.free`() when no longer needed.
Return type:	`str` or `None`

Get a percent encoded URI query string from the self.

New in version 1.6.

get_query_table()[source]¶

Returns:	The query hash table from the URI.
Return type:	{`str`: `str`} or `None`

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

New in version 1.6.

get_query_value(query_key)[source]¶

Parameters:	query_key (`str`) – The key to lookup.
Returns:	The value for the given key, or `None` if not found.
Return type:	`str` or `None`

Get the value associated with the query_key key. Will return None if the key has no value or if the key does not exist in the URI query table. Because None 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.

New in version 1.6.

get_scheme()[source]¶

Returns:	The scheme from the `Gst.Uri` object or `None`.
Return type:	`str` or `None`

Get the scheme name from the URI or None if it doesn’t exist. If self is None then returns None.

get_userinfo()[source]¶

Returns:	The userinfo from the `Gst.Uri` object or `None`.
Return type:	`str` or `None`

Get the userinfo (usually in the form “username:password”) from the URI or None if it doesn’t exist. If self is None then returns None.

New in version 1.6.

is_normalized()[source]¶

Returns:	`True` if the URI is normalized or is `None`.
Return type:	`bool`

Tests the self to see if it is normalized. A None self is considered to be normalized.

New in version 1.6.

is_writable()[source]¶

Returns:	`True` if it is safe to write to the object.
Return type:	`bool`

Check if it is safe to write to this Gst.Uri.

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

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

New in version 1.6.

join(ref_uri)[source]¶

Parameters:	ref_uri (`Gst.Uri` or `None`) – The reference URI to join onto the base URI.
Returns:	A `Gst.Uri` which represents the base with the reference URI joined on.
Return type:	`Gst.Uri` or `None`

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

New in version 1.6.

make_writable()[source]¶

Returns:	A writable version of self.
Return type:	`Gst.Uri`

Make the Gst.Uri writable.

Checks if self 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 self and returns a reference to the new Gst.Uri. If self is None then None is returned.

New in version 1.6.

new_with_base(scheme, userinfo, host, port, path, query, fragment)[source]¶

Parameters:	scheme (`str` or `None`) – The scheme for the new URI. userinfo (`str` or `None`) – The user-info for the new URI. host (`str` or `None`) – The host name for the new URI. port (`int`) – The port number for the new URI or `Gst.URI_NO_PORT`. path (`str` or `None`) – The path for the new URI with ‘/’ separating path elements. query (`str` or `None`) – The query string for the new URI with ‘&’ separating query elements. Elements containing ‘&’ characters should encode them as “&percnt;26”. fragment (`str` or `None`) – The fragment name for the new URI.
Returns:	The new URI joined onto self.
Return type:	`Gst.Uri`

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

New in version 1.6.

normalize()[source]¶

Returns:	`True` if the URI was modified.
Return type:	`bool`

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 Gst.Uri object must be writable. Check with Gst.Uri.is_writable() or use Gst.Uri.make_writable() first.

New in version 1.6.

query_has_key(query_key)[source]¶

Parameters:	query_key (`str`) – The key to lookup.
Returns:	`True` if query_key exists in the URI query table.
Return type:	`bool`

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

New in version 1.6.

remove_query_key(query_key)[source]¶

Parameters:	query_key (`str`) – The key to remove.
Returns:	`True` if the key existed in the table and was removed.
Return type:	`bool`

Remove an entry from the query table by key.

New in version 1.6.

set_fragment(fragment)[source]¶

Parameters:	fragment (`str` or `None`) – The fragment string to set.
Returns:	`True` if the fragment was set/unset successfully.
Return type:	`bool`

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

New in version 1.6.

set_host(host)[source]¶

Parameters:	host (`str`) – The new host string to set or `None` to unset.
Returns:	`True` if the host was set/unset successfully.
Return type:	`bool`

Set or unset the host for the URI.

New in version 1.6.

set_path(path)[source]¶

Parameters:	path (`str`) – The new path to set with path segments separated by ‘/’, or use `None` to unset the path.
Returns:	`True` if the path was set successfully.
Return type:	`bool`

Sets or unsets the path in the URI.

New in version 1.6.

set_path_segments(path_segments)[source]¶

Parameters:	path_segments ([`str`] or `None`) – The new path list to set.
Returns:	`True` if the path segments were set successfully.
Return type:	`bool`

Replace the path segments list in the URI.

New in version 1.6.

set_path_string(path)[source]¶

Parameters:	path (`str`) – The new percent encoded path to set with path segments separated by ‘/’, or use `None` to unset the path.
Returns:	`True` if the path was set successfully.
Return type:	`bool`

Sets or unsets the path in the URI.

New in version 1.6.

set_port(port)[source]¶

Parameters:	port (`int`) – The new port number to set or `Gst.URI_NO_PORT` to unset.
Returns:	`True` if the port number was set/unset successfully.
Return type:	`bool`

Set or unset the port number for the URI.

New in version 1.6.

set_query_string(query)[source]¶

Parameters:	query (`str`) – The new percent encoded query string to use to populate the query table, or use `None` to unset the query table.
Returns:	`True` if the query table was set successfully.
Return type:	`bool`

Sets or unsets the query table in the URI.

New in version 1.6.

set_query_table(query_table)[source]¶

Parameters:	query_table ({`str`: `str`} or `None`) – The new query table to use.
Returns:	`True` if the new table was successfully used for the query table.
Return type:	`bool`

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 None for query_table will remove the query string from the URI.

New in version 1.6.

set_query_value(query_key, query_value)[source]¶

Parameters:	query_key (`str`) – The key for the query entry. query_value (`str` or `None`) – The value for the key.
Returns:	`True` if the query table was successfully updated.
Return type:	`bool`

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

New in version 1.6.

set_scheme(scheme)[source]¶

Parameters:	scheme (`str`) – The new scheme to set or `None` to unset the scheme.
Returns:	`True` if the scheme was set/unset successfully.
Return type:	`bool`

Set or unset the scheme for the URI.

New in version 1.6.

set_userinfo(userinfo)[source]¶

Parameters:	userinfo (`str`) – The new user-information string to set or `None` to unset.
Returns:	`True` if the user information was set/unset successfully.
Return type:	`bool`

Set or unset the user information for the URI.

New in version 1.6.

to_string()[source]¶

Returns:	The string version of the URI.
Return type:	`str`

Convert the URI to a string.

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

New in version 1.6.