:right-sidebar: True Uri =================================================================== .. currentmodule:: gi.repository.Gst .. class:: Uri(**kwargs) :no-contents-entry: :Constructors: :: new(scheme:str=None, userinfo:str=None, host:str=None, port:int, path:str=None, query:str=None, fragment:str=None) -> Gst.Uri Constructors ------------ .. rst-class:: interim-class .. class:: Uri :no-index: .. classmethod:: new(scheme: str | None, userinfo: str | None, host: str | None, port: int, path: str | None = None, query: str | None = None, fragment: str | None = None) -> ~gi.repository.Gst.Uri Creates a new :obj:`~gi.repository.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. .. versionadded:: 1.6 :param scheme: The scheme for the new URI. :param userinfo: The user-info for the new URI. :param host: The host name for the new URI. :param port: The port number for the new URI or :const:`~gi.repository.Gst.URI_NO_PORT`. :param path: The path for the new URI with '/' separating path elements. :param query: The query string for the new URI with '&' separating query elements. Elements containing '&' characters should encode them as "%26". :param fragment: The fragment name for the new URI. Methods ------- .. rst-class:: interim-class .. class:: Uri :no-index: .. method:: append_path(relative_path: str | None = None) -> 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. .. versionadded:: 1.6 :param relative_path: Relative path to append to the end of the current path. .. method:: append_path_segment(path_segment: str | None = None) -> bool Append a single path segment onto the end of the URI path. .. versionadded:: 1.6 :param path_segment: The path segment string to append to the URI path. .. method:: construct(protocol: str, location: str) -> str Constructs a URI for a given valid protocol and location. Free-function: g_free .. deprecated:: Unknown Use GstURI instead. :param protocol: Protocol for URI :param location: Location for URI .. method:: equal(second: ~gi.repository.Gst.Uri) -> bool Compares two :obj:`~gi.repository.Gst.Uri` objects to see if they represent the same normalized URI. .. versionadded:: 1.6 :param second: Second :obj:`~gi.repository.Gst.Uri` to compare. .. method:: from_string(uri: str) -> ~gi.repository.Gst.Uri | None Parses a URI string into a new :obj:`~gi.repository.Gst.Uri` object. Will return NULL if the URI cannot be parsed. .. versionadded:: 1.6 :param uri: The URI string to parse. .. method:: from_string_escaped(uri: str) -> ~gi.repository.Gst.Uri | None Parses a URI string into a new :obj:`~gi.repository.Gst.Uri` object. Will return NULL if the URI cannot be parsed. This is identical to :func:`~gi.repository.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. :func:`~gi.repository.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 '#'. .. versionadded:: 1.18 :param uri: The URI string to parse. .. method:: from_string_with_base(uri: str) -> ~gi.repository.Gst.Uri | None Like :func:`~gi.repository.Gst.Uri.from_string` but also joins with a base URI. .. versionadded:: 1.6 :param uri: The URI string to parse. .. method:: get_fragment() -> str | None Get the fragment name from the URI or :const:`None` if it doesn't exist. If ``uri`` is :const:`None` then returns :const:`None`. .. versionadded:: 1.6 .. method:: get_host() -> str | None Get the host name from the URI or :const:`None` if it doesn't exist. If ``uri`` is :const:`None` then returns :const:`None`. .. versionadded:: 1.6 .. method:: get_location(uri: str) -> str | 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 :func:`~gi.repository.GLib.free`. Free-function: g_free :param uri: A URI string .. method:: get_media_fragment_table() -> dict[str, str] | 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 :const:`None` to indicate that the key should appear in the fragment string in the URI, but does not have a value. Free the returned :obj:`~gi.repository.GLib.HashTable` 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/ .. versionadded:: 1.12 .. method:: get_path() -> str | None Extract the path string from the URI object. .. versionadded:: 1.6 .. method:: get_path_segments() -> list[str] Get a list of path segments from the URI. .. versionadded:: 1.6 .. method:: get_path_string() -> str | None Extract the path string from the URI object as a percent encoded URI path. .. versionadded:: 1.6 .. method:: get_port() -> int Get the port number from the URI or :const:`~gi.repository.Gst.URI_NO_PORT` if it doesn't exist. If ``uri`` is :const:`None` then returns :const:`~gi.repository.Gst.URI_NO_PORT`. .. versionadded:: 1.6 .. method:: get_protocol(uri: str) -> str | None Extracts the protocol out of a given valid URI. The returned string must be freed using :func:`~gi.repository.GLib.free`. :param uri: A URI string .. method:: get_query_keys() -> list[str] Get a list of the query keys from the URI. .. versionadded:: 1.6 .. method:: get_query_string() -> str | None Get a percent encoded URI query string from the ``uri``. .. versionadded:: 1.6 .. method:: get_query_string_ordered(keys: list[str] | None = None) -> str | None Get a percent encoded URI query string from the ``uri``, 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 :func:`~gi.repository.Gst.Uri.get_query_keys` and then sorting the list, for example. .. versionadded:: 1.24 :param keys: A GList containing the query argument key strings. .. method:: get_query_table() -> dict[str, str] | None 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 :const:`None` to indicate that the key should appear in the query string in the URI, but does not have a value. Free the returned :obj:`~gi.repository.GLib.HashTable` with ``g_hash_table_unref``() when it is no longer required. Modifying this hash table will modify the query in the URI. .. versionadded:: 1.6 .. method:: get_query_value(query_key: str) -> str | None Get the value associated with the ``query_key`` key. Will return :const:`None` if the key has no value or if the key does not exist in the URI query table. Because :const:`None` is returned for both missing keys and keys with no value, you should use :func:`~gi.repository.Gst.Uri.query_has_key` to determine if a key is present in the URI query. .. versionadded:: 1.6 :param query_key: The key to lookup. .. method:: get_scheme() -> str | None Get the scheme name from the URI or :const:`None` if it doesn't exist. If ``uri`` is :const:`None` then returns :const:`None`. .. method:: get_userinfo() -> str | None Get the userinfo (usually in the form "username:password") from the URI or :const:`None` if it doesn't exist. If ``uri`` is :const:`None` then returns :const:`None`. .. versionadded:: 1.6 .. method:: has_protocol(uri: str, protocol: str) -> bool Checks if the protocol of a given valid URI matches ``protocol``. :param uri: a URI string :param protocol: a protocol string (e.g. "http") .. method:: is_normalized() -> bool Tests the ``uri`` to see if it is normalized. A :const:`None` ``uri`` is considered to be normalized. .. versionadded:: 1.6 .. method:: is_valid(uri: str) -> 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. :param uri: A URI string .. method:: is_writable() -> bool Check if it is safe to write to this :obj:`~gi.repository.Gst.Uri`. Check if the refcount of ``uri`` is exactly 1, meaning that no other reference exists to the :obj:`~gi.repository.Gst.Uri` and that the :obj:`~gi.repository.Gst.Uri` is therefore writable. Modification of a :obj:`~gi.repository.Gst.Uri` should only be done after verifying that it is writable. .. versionadded:: 1.6 .. method:: join(ref_uri: ~gi.repository.Gst.Uri | None = None) -> ~gi.repository.Gst.Uri | None Join a reference URI onto a base URI using the method from RFC 3986. If either URI is :const:`None` then the other URI will be returned with the ref count increased. .. versionadded:: 1.6 :param ref_uri: The reference URI to join onto the base URI. .. method:: join_strings(base_uri: str, ref_uri: str) -> str | None This is a convenience function to join two URI strings and return the result. The returned string should be :func:`~gi.repository.GLib.free`'d after use. .. versionadded:: 1.6 :param base_uri: The percent-encoded base URI. :param ref_uri: The percent-encoded reference URI to join to the ``base_uri``. .. method:: make_writable() -> ~gi.repository.Gst.Uri Make the :obj:`~gi.repository.Gst.Uri` 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 :obj:`~gi.repository.Gst.Uri`. If ``uri`` is :const:`None` then :const:`None` is returned. .. versionadded:: 1.6 .. method:: new_with_base(scheme: str | None, userinfo: str | None, host: str | None, port: int, path: str | None = None, query: str | None = None, fragment: str | None = None) -> ~gi.repository.Gst.Uri Like :func:`~gi.repository.Gst.Uri.new`, but joins the new URI onto a base URI. .. versionadded:: 1.6 :param scheme: The scheme for the new URI. :param userinfo: The user-info for the new URI. :param host: The host name for the new URI. :param port: The port number for the new URI or :const:`~gi.repository.Gst.URI_NO_PORT`. :param path: The path for the new URI with '/' separating path elements. :param query: The query string for the new URI with '&' separating query elements. Elements containing '&' characters should encode them as "%26". :param fragment: The fragment name for the new URI. .. method:: normalize() -> 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 :obj:`~gi.repository.Gst.Uri` object must be writable. Check with :func:`~gi.repository.Gst.Uri.is_writable` or use :func:`~gi.repository.Gst.Uri.make_writable` first. .. versionadded:: 1.6 .. method:: protocol_is_supported(type: ~gi.repository.Gst.URIType, protocol: str) -> 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 :func:`~gi.repository.Gst.Element.make_from_uri` is guaranteed to work. :param type: Whether to check for a source or a sink :param protocol: Protocol that should be checked for (e.g. "http" or "smb") .. method:: protocol_is_valid(protocol: str) -> 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. :param protocol: A string .. method:: query_has_key(query_key: str) -> bool Check if there is a query table entry for the ``query_key`` key. .. versionadded:: 1.6 :param query_key: The key to lookup. .. method:: remove_query_key(query_key: str) -> bool Remove an entry from the query table by key. .. versionadded:: 1.6 :param query_key: The key to remove. .. method:: set_fragment(fragment: str | None = None) -> bool Sets the fragment string in the URI. Use a value of :const:`None` in ``fragment`` to unset the fragment string. .. versionadded:: 1.6 :param fragment: The fragment string to set. .. method:: set_host(host: str) -> bool Set or unset the host for the URI. .. versionadded:: 1.6 :param host: The new host string to set or :const:`None` to unset. .. method:: set_path(path: str | None = None) -> bool Sets or unsets the path in the URI. .. versionadded:: 1.6 :param path: The new path to set with path segments separated by '/', or use :const:`None` to unset the path. .. method:: set_path_segments(path_segments: list[str] | None = None) -> bool Replace the path segments list in the URI. .. versionadded:: 1.6 :param path_segments: The new path list to set. .. method:: set_path_string(path: str) -> bool Sets or unsets the path in the URI. .. versionadded:: 1.6 :param path: The new percent encoded path to set with path segments separated by '/', or use :const:`None` to unset the path. .. method:: set_port(port: int) -> bool Set or unset the port number for the URI. .. versionadded:: 1.6 :param port: The new port number to set or :const:`~gi.repository.Gst.URI_NO_PORT` to unset. .. method:: set_query_string(query: str | None = None) -> bool Sets or unsets the query table in the URI. .. versionadded:: 1.6 :param query: The new percent encoded query string to use to populate the query table, or use :const:`None` to unset the query table. .. method:: set_query_table(query_table: dict[str, str] | None = None) -> 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 :const:`None` for ``query_table`` will remove the query string from the URI. .. versionadded:: 1.6 :param query_table: The new query table to use. .. method:: set_query_value(query_key: str, query_value: str | None = None) -> bool This inserts or replaces a key in the query table. A ``query_value`` of :const:`None` indicates that the key has no associated value, but will still be present in the query string. .. versionadded:: 1.6 :param query_key: The key for the query entry. :param query_value: The value for the key. .. method:: set_scheme(scheme: str) -> bool Set or unset the scheme for the URI. .. versionadded:: 1.6 :param scheme: The new scheme to set or :const:`None` to unset the scheme. .. method:: set_userinfo(userinfo: str) -> bool Set or unset the user information for the URI. .. versionadded:: 1.6 :param userinfo: The new user-information string to set or :const:`None` to unset. .. method:: to_string() -> str Convert the URI to a string. Returns the URI as held in this object as a :obj:`~gi.repository.utf8`* nul-terminated string. The caller should :func:`~gi.repository.GLib.free` the string once they are finished with it. The string is put together as described in RFC 3986. .. versionadded:: 1.6 .. method:: to_string_with_keys(keys: list[str] | None = None) -> 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 :obj:`~gi.repository.utf8`* nul-terminated string. The caller should :func:`~gi.repository.GLib.free` the string once they are finished with it. The string is put together as described in RFC 3986. .. versionadded:: 1.24 :param keys: A GList containing the query argument key strings.