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_string_ordered` (keys)
	`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` ()
	`to_string_with_keys` (keys)

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.

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 or None

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 or None) – 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 or None) – 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 or None

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_string_ordered(keys)[source]¶

Parameters:: keys ([str] or None) – A GLib.List containing the query argument key strings.
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, with query parameters in the order provided by the keys list. Only parameter keys in the list will be added to the resulting URI string. This method can be used by retrieving the keys with Gst.Uri.get_query_keys() and then sorting the list, for example.

New in version 1.24.

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 or None) – 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 or None) – 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.

to_string_with_keys(keys)[source]¶

Parameters:: keys ([str] or None) – A GLib.List containing the query argument key strings.
Returns:: The string version of the URI.
Return type:: str

Convert the URI to a string, with the query arguments in a specific order. Only the keys in the keys list will be added to the resulting 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.24.