Functions
=========

.. currentmodule:: gi.repository.Soup



.. function:: check_version(major: int, minor: int, micro: int) -> bool

   Like :obj:`~gi.repository.Soup.CHECK_VERSION`\, but the check for soup_check_version is
   at runtime instead of compile time.

   This is useful for compiling against older versions of libsoup, but using
   features from newer versions.






   :param major: the major version to check

   :param minor: the minor version to check

   :param micro: the micro version to check


   :return: :const:`True` if the version of the libsoup currently loaded
        is the same as or newer than the passed-in version.




.. function:: cookie_parse(header: str, origin: ~gi.repository.GLib.Uri | None = None) -> ~gi.repository.Soup.Cookie | None

   






   :param header: 

   :param origin: 





.. function:: cookies_from_request(msg: ~gi.repository.Soup.Message) -> list[~gi.repository.Soup.Cookie]

   Parses ``msg``\'s Cookie request header and returns a :obj:`~gi.repository.GLib.SList` of
   ``SoupCookie``\s.

   As the "Cookie" header, unlike "Set-Cookie", only contains cookie names and
   values, none of the other :obj:`~gi.repository.Soup.Cookie` fields will be filled in. (Thus, you
   can't generally pass a cookie returned from this method directly to
   :obj:`~gi.repository.Soup.cookies_to_response`\.)






   :param msg: a :obj:`~gi.repository.Soup.Message` containing a "Cookie" request header


   :return: a ``GSList`` of
        ``SoupCookie``\s, which can be freed with :obj:`~gi.repository.Cookie.free`\.




.. function:: cookies_from_response(msg: ~gi.repository.Soup.Message) -> list[~gi.repository.Soup.Cookie]

   Parses ``msg``\'s Set-Cookie response headers and returns a :obj:`~gi.repository.GLib.SList`
   of ``SoupCookie``\s.

   Cookies that do not specify "path" or "domain" attributes will have their
   values defaulted from ``msg``\.






   :param msg: a :obj:`~gi.repository.Soup.Message` containing a "Set-Cookie" response header


   :return: a ``GSList`` of
        ``SoupCookie``\s, which can be freed with :obj:`~gi.repository.Cookie.free`\.




.. function:: cookies_to_cookie_header(cookies: list[~gi.repository.Soup.Cookie]) -> str

   Serializes a :obj:`~gi.repository.GLib.SList` of :obj:`~gi.repository.Soup.Cookie` into a string suitable for
   setting as the value of the "Cookie" header.






   :param cookies: a ``GSList`` of :obj:`~gi.repository.Soup.Cookie`


   :return: the serialization of ``cookies``




.. function:: cookies_to_request(cookies: list[~gi.repository.Soup.Cookie], msg: ~gi.repository.Soup.Message) -> None

   Adds the name and value of each cookie in ``cookies`` to ``msg``\'s
   "Cookie" request.

   If ``msg`` already has a "Cookie" request header, these cookies will be appended
   to the cookies already present. Be careful that you do not append the same
   cookies twice, eg, when requeuing a message.






   :param cookies: a ``GSList`` of :obj:`~gi.repository.Soup.Cookie`

   :param msg: a :obj:`~gi.repository.Soup.Message`





.. function:: cookies_to_response(cookies: list[~gi.repository.Soup.Cookie], msg: ~gi.repository.Soup.Message) -> None

   Appends a "Set-Cookie" response header to ``msg`` for each cookie in
   ``cookies``\.

   This is in addition to any other "Set-Cookie" headers
   ``msg`` may already have.






   :param cookies: a ``GSList`` of :obj:`~gi.repository.Soup.Cookie`

   :param msg: a :obj:`~gi.repository.Soup.Message`





.. function:: date_time_new_from_http_string(date_string: str) -> ~gi.repository.GLib.DateTime | None

   Parses ``date_string`` and tries to extract a date from it.

   This recognizes all of the "HTTP-date" formats from RFC 2616, RFC 2822 dates,
   and reasonable approximations thereof. (Eg, it is lenient about whitespace,
   leading "0"s, etc.)






   :param date_string: The date as a string


   :return: a new :obj:`~gi.repository.GLib.DateTime`\, or :const:`None` if ``date_string``
        could not be parsed.




.. function:: date_time_to_string(date: ~gi.repository.GLib.DateTime, format: ~gi.repository.Soup.DateFormat) -> str

   Converts ``date`` to a string in the format described by ``format``\.






   :param date: a :obj:`~gi.repository.GLib.DateTime`

   :param format: the format to generate the date in


   :return: ``date`` as a string or :const:`None`




.. function:: form_decode(encoded_form: str) -> dict[str, str]

   Decodes ``form``\.

   which is an urlencoded dataset as defined in the HTML 4.01 spec.






   :param encoded_form: data of type "application/x-www-form-urlencoded"


   :return: a hash
        table containing the name/value pairs from ``encoded_form``\, which you
        can free with :obj:`~gi.repository.GLib.HashTable.destroy`\.




.. function:: form_decode_multipart(multipart: ~gi.repository.Soup.Multipart, file_control_name: str | None = None) -> ~typing.Tuple[dict[str, str] | None, str, str, ~gi.repository.GLib.Bytes]

   Decodes the "multipart/form-data" request in ``multipart``\.

   this is a convenience method for the case when you have a single file upload
   control in a form. (Or when you don't have any file upload controls, but are
   still using "multipart/form-data" anyway.) Pass the name of the file upload
   control in ``file_control_name``\, and :obj:`~gi.repository.Soup.form_decode_multipart` will extract
   the uploaded file data into ``filename``\, ``content_type``\, and ``file``\. All of the
   other form control data will be returned (as strings, as with
   :obj:`~gi.repository.Soup.form_decode` in the returned :obj:`~gi.repository.GLib.HashTable`\.

   You may pass :const:`None` for ``filename``\, ``content_type`` and/or ``file`` if you do not
   care about those fields. :obj:`~gi.repository.Soup.form_decode_multipart` may also
   return :const:`None` in those fields if the client did not provide that
   information. You must free the returned filename and content-type
   with :obj:`~gi.repository.GLib.free`\, and the returned file data with :obj:`~gi.repository.Glib.Bytes.unref`\.

   If you have a form with more than one file upload control, you will
   need to decode it manually, using :obj:`~gi.repository.Multipart.new_from_message`
   and :obj:`~gi.repository.Multipart.get_part`\.






   :param multipart: a :obj:`~gi.repository.Soup.Multipart`

   :param file_control_name: the name of the HTML file upload control


   :return: a hash table containing the name/value pairs (other than
        ``file_control_name``\) from ``msg``\, which you can free with
        :obj:`~gi.repository.GLib.HashTable.destroy`\. On error, it will return :const:`None`.




.. function:: form_encode_datalist(form_data_set: ~gi.repository.GLib.Data) -> str

   Encodes ``form_data_set`` into a value of type
   "application/x-www-form-urlencoded".

   Encodes as defined in the HTML 4.01 spec. Unlike :obj:`~gi.repository.Soup.form_encode_hash`\,
   this preserves the ordering of the form elements, which may be required in
   some situations.

   See also: :obj:`~gi.repository.Message.new_from_encoded_form`\.






   :param form_data_set: a datalist containing name/value pairs


   :return: the encoded form




.. function:: form_encode_hash(form_data_set: dict[str, str]) -> str

   Encodes ``form_data_set`` into a value of type
   "application/x-www-form-urlencoded".

   Encodes as defined in the HTML 4.01 spec.

   Note that the HTML spec states that "The control names/values are
   listed in the order they appear in the document." Since this method
   takes a hash table, it cannot enforce that; if you care about the
   ordering of the form fields, use :obj:`~gi.repository.Soup.form_encode_datalist`\.

   See also: :obj:`~gi.repository.Message.new_from_encoded_form`\.






   :param form_data_set: a hash table containing
        name/value pairs (as strings)


   :return: the encoded form




.. function:: get_major_version() -> int

   Returns the major version number of the libsoup library.

   e.g. in libsoup version 2.42.0 this is 2.

   This function is in the library, so it represents the libsoup library
   your code is running against. Contrast with the ``SOUP_MAJOR_VERSION``
   macro, which represents the major version of the libsoup headers you
   have included when compiling your code.







   :return: the major version number of the libsoup library




.. function:: get_micro_version() -> int

   Returns the micro version number of the libsoup library.

   e.g. in libsoup version 2.42.0 this is 0.

   This function is in the library, so it represents the libsoup library
   your code is running against. Contrast with the ``SOUP_MICRO_VERSION``
   macro, which represents the micro version of the libsoup headers you
   have included when compiling your code.







   :return: the micro version number of the libsoup library




.. function:: get_minor_version() -> int

   Returns the minor version number of the libsoup library.

   e.g. in libsoup version 2.42.0 this is 42.

   This function is in the library, so it represents the libsoup library
   your code is running against. Contrast with the ``SOUP_MINOR_VERSION``
   macro, which represents the minor version of the libsoup headers you
   have included when compiling your code.







   :return: the minor version number of the libsoup library




.. function:: header_contains(header: str, token: str) -> bool

   Parses ``header`` to see if it contains the token ``token`` (matched
   case-insensitively).

   Note that this can't be used with lists that have qvalues.






   :param header: An HTTP header suitable for parsing with
        :obj:`~gi.repository.Soup.header_parse_list`

   :param token: a token


   :return: whether or not ``header`` contains ``token``




.. function:: header_free_param_list(param_list: dict[str, str]) -> None

   Frees ``param_list``\.






   :param param_list: a :obj:`~gi.repository.GLib.HashTable` returned from
        :obj:`~gi.repository.Soup.header_parse_param_list` or :obj:`~gi.repository.Soup.header_parse_semi_param_list`





.. function:: header_g_string_append_param(string: ~gi.repository.GLib.String, name: str, value: str | None = None) -> None

   Appends something like ``name=value`` to ``string``\, taking care to quote ``value``
   if needed, and if so, to escape any quotes or backslashes in ``value``\.

   Alternatively, if ``value`` is a non-ASCII UTF-8 string, it will be
   appended using RFC5987 syntax. Although in theory this is supposed
   to work anywhere in HTTP that uses this style of parameter, in
   reality, it can only be used portably with the Content-Disposition
   "filename" parameter.

   If ``value`` is :const:`None`, this will just append ``name`` to ``string``\.






   :param string: a :obj:`~gi.repository.GLib.String` being used to construct an HTTP header value

   :param name: a parameter name

   :param value: a parameter value, or :const:`None`





.. function:: header_g_string_append_param_quoted(string: ~gi.repository.GLib.String, name: str, value: str) -> None

   Appends something like ``name="value"`` to
   ``string``\, taking care to escape any quotes or backslashes in ``value``\.

   If ``value`` is (non-ASCII) UTF-8, this will instead use RFC 5987
   encoding, just like :obj:`~gi.repository.Soup.header_g_string_append_param`\.






   :param string: a :obj:`~gi.repository.GLib.String` being used to construct an HTTP header value

   :param name: a parameter name

   :param value: a parameter value





.. function:: header_parse_list(header: str) -> list[str]

   Parses a header whose content is described by RFC2616 as ``#something``\.

   "something" does not itself contain commas, except as part of quoted-strings.






   :param header: a header value


   :return: a ``GSList`` of
        list elements, as allocated strings




.. function:: header_parse_param_list(header: str) -> dict[str, str]

   Parses a header which is a comma-delimited list of something like:
   ``token [ "=" ( token | quoted-string ) ]``\.

   Tokens that don't have an associated value will still be added to
   the resulting hash table, but with a :const:`None` value.

   This also handles RFC5987 encoding (which in HTTP is mostly used
   for giving UTF8-encoded filenames in the Content-Disposition
   header).






   :param header: a header value


   :return: a
        :obj:`~gi.repository.GLib.HashTable` of list elements, which can be freed with
        :obj:`~gi.repository.Soup.header_free_param_list`\.




.. function:: header_parse_param_list_strict(header: str) -> dict[str, str] | None

   A strict version of :obj:`~gi.repository.Soup.header_parse_param_list`
   that bails out if there are duplicate parameters.

   Note that this function will treat RFC5987-encoded
   parameters as duplicated if an ASCII version is also
   present. For header fields that might contain
   RFC5987-encoded parameters, use
   :obj:`~gi.repository.Soup.header_parse_param_list` instead.






   :param header: a header value


   :return: a :obj:`~gi.repository.GLib.HashTable` of list elements, which can be freed with
        :obj:`~gi.repository.Soup.header_free_param_list` or :const:`None` if there are duplicate
        elements.




.. function:: header_parse_quality_list(header: str) -> ~typing.Tuple[list[str], list[str]]

   Parses a header whose content is a list of items with optional
   "qvalue"s (eg, Accept, Accept-Charset, Accept-Encoding,
   Accept-Language, TE).

   If ``unacceptable`` is not :const:`None`, then on return, it will contain the
   items with qvalue 0. Either way, those items will be removed from
   the main list.






   :param header: a header value


   :return: a ``GSList`` of
        acceptable values (as allocated strings), highest-qvalue first.




.. function:: header_parse_semi_param_list(header: str) -> dict[str, str]

   Parses a header which is a semicolon-delimited list of something
   like: ``token [ "=" ( token | quoted-string ) ]``\.

   Tokens that don't have an associated value will still be added to
   the resulting hash table, but with a :const:`None` value.

   This also handles RFC5987 encoding (which in HTTP is mostly used
   for giving UTF8-encoded filenames in the Content-Disposition
   header).






   :param header: a header value


   :return: a
        :obj:`~gi.repository.GLib.HashTable` of list elements, which can be freed with
        :obj:`~gi.repository.Soup.header_free_param_list`\.




.. function:: header_parse_semi_param_list_strict(header: str) -> dict[str, str] | None

   A strict version of :obj:`~gi.repository.Soup.header_parse_semi_param_list`
   that bails out if there are duplicate parameters.

   Note that this function will treat RFC5987-encoded
   parameters as duplicated if an ASCII version is also
   present. For header fields that might contain
   RFC5987-encoded parameters, use
   :obj:`~gi.repository.Soup.header_parse_semi_param_list` instead.






   :param header: a header value


   :return: a :obj:`~gi.repository.GLib.HashTable` of list elements, which can be freed with
        :obj:`~gi.repository.Soup.header_free_param_list` or :const:`None` if there are duplicate
        elements.




.. function:: headers_parse(str: str, len: int, dest: ~gi.repository.Soup.MessageHeaders) -> bool

   Parses the headers of an HTTP request or response in ``str`` and
   stores the results in ``dest``\.

   Beware that ``dest`` may be modified even on failure.

   This is a low-level method; normally you would use
   :obj:`~gi.repository.Soup.headers_parse_request` or :obj:`~gi.repository.Soup.headers_parse_response`\.






   :param str: the header string (including the Request-Line or Status-Line,
        but not the trailing blank line)

   :param len: length of ``str``

   :param dest: :obj:`~gi.repository.Soup.MessageHeaders` to store the header values in


   :return: success or failure




.. function:: headers_parse_request(str: str, len: int, req_headers: ~gi.repository.Soup.MessageHeaders) -> ~typing.Tuple[int, str, str, ~gi.repository.Soup.HTTPVersion]

   Parses the headers of an HTTP request in ``str`` and stores the
   results in ``req_method``\, ``req_path``\, ``ver``\, and ``req_headers``\.

   Beware that ``req_headers`` may be modified even on failure.






   :param str: the headers (up to, but not including, the trailing blank line)

   :param len: length of ``str``

   :param req_headers: :obj:`~gi.repository.Soup.MessageHeaders` to store the header values in


   :return: :const:`~gi.repository.Soup.Status.OK` if the headers could be parsed, or an
        HTTP error to be returned to the client if they could not be.




.. function:: headers_parse_response(str: str, len: int, headers: ~gi.repository.Soup.MessageHeaders) -> ~typing.Tuple[bool, ~gi.repository.Soup.HTTPVersion, int, str]

   Parses the headers of an HTTP response in ``str`` and stores the
   results in ``ver``\, ``status_code``\, ``reason_phrase``\, and ``headers``\.

   Beware that ``headers`` may be modified even on failure.






   :param str: the headers (up to, but not including, the trailing blank line)

   :param len: length of ``str``

   :param headers: :obj:`~gi.repository.Soup.MessageHeaders` to store the header values in


   :return: success or failure.




.. function:: headers_parse_status_line(status_line: str) -> ~typing.Tuple[bool, ~gi.repository.Soup.HTTPVersion, int, str]

   Parses the HTTP Status-Line string in ``status_line`` into ``ver``\,
   ``status_code``\, and ``reason_phrase``\.

   ``status_line`` must be terminated by either "\0" or "\r\n".






   :param status_line: an HTTP Status-Line


   :return: :const:`True` if ``status_line`` was parsed successfully.




.. function:: message_headers_iter_init(hdrs: ~gi.repository.Soup.MessageHeaders) -> ~gi.repository.Soup.MessageHeadersIter

   






   :param hdrs: 





.. function:: session_error_quark() -> int

   










.. function:: status_get_phrase(status_code: int) -> str

   






   :param status_code: 





.. function:: tld_domain_is_public_suffix(domain: str) -> bool

   Looks whether the ``domain`` passed as argument is a public domain
   suffix (.org, .com, .co.uk, etc) or not.

   Prior to libsoup 2.46, this function required that ``domain`` be in
   UTF-8 if it was an IDN. From 2.46 on, the name can be in either
   UTF-8 or ASCII format.






   :param domain: a domain name


   :return: :const:`True` if it is a public domain, :const:`False` otherwise.




.. function:: tld_error_quark() -> int

   










.. function:: tld_get_base_domain(hostname: str) -> str

   Finds the base domain for a given ``hostname``

   The base domain is composed by the top level domain (such as .org, .com,
   .co.uk, etc) plus the second level domain, for example for
   myhost.mydomain.com it will return mydomain.com.

   Note that :const:`None` will be returned for private URLs (those not ending
   with any well known TLD) because choosing a base domain for them
   would be totally arbitrary.

   Prior to libsoup 2.46, this function required that ``hostname`` be in
   UTF-8 if it was an IDN. From 2.46 on, the name can be in either
   UTF-8 or ASCII format (and the return value will be in the same
   format).






   :param hostname: a hostname


   :return: a pointer to the start of the base domain in ``hostname``\. If
        an error occurs, :const:`None` will be returned and ``error`` set.




.. function:: uri_decode_data_uri(uri: str) -> ~typing.Tuple[~gi.repository.GLib.Bytes, str | None]

   Decodes the given data URI and returns its contents and ``content_type``\.






   :param uri: a data URI, in string form


   :return: a :obj:`~gi.repository.GLib.Bytes` with the contents of ``uri``\,
         or :const:`None` if ``uri`` is not a valid data URI




.. function:: uri_equal(uri1: ~gi.repository.GLib.Uri, uri2: ~gi.repository.GLib.Uri) -> bool

   Tests whether or not ``uri1`` and ``uri2`` are equal in all parts.






   :param uri1: a :obj:`~gi.repository.GLib.Uri`

   :param uri2: another :obj:`~gi.repository.GLib.Uri`


   :return: :const:`True` if equal otherwise :const:`False`




.. function:: websocket_client_prepare_handshake(msg: ~gi.repository.Soup.Message, origin: str | None = None, protocols: list[str] | None = None, supported_extensions: list[~gi.repository.GObject.TypeClass] | None = None) -> None

   Adds the necessary headers to ``msg`` to request a WebSocket
   handshake including supported WebSocket extensions.

   The message body and non-WebSocket-related headers are
   not modified.

   This is a low-level function; if you use
   :obj:`~gi.repository.Session.websocket_connect_async` to create a WebSocket connection, it
   will call this for you.






   :param msg: a :obj:`~gi.repository.Soup.Message`

   :param origin: the "Origin" header to set

   :param protocols: list of
        protocols to offer

   :param supported_extensions: list
        of supported extension types





.. function:: websocket_client_verify_handshake(msg: ~gi.repository.Soup.Message, supported_extensions: list[~gi.repository.GObject.TypeClass] | None = None) -> ~typing.Tuple[bool, list[~gi.repository.Soup.WebsocketExtension]]

   Looks at the response status code and headers in ``msg`` and
   determines if they contain a valid WebSocket handshake response
   (given the handshake request in ``msg``\'s request headers).

   If ``supported_extensions`` is non-:const:`None`, extensions included in the
   response "Sec-WebSocket-Extensions" are verified too. Accepted
   extensions are returned in ``accepted_extensions`` parameter if non-:const:`None`.

   This is a low-level function; if you use
   :obj:`~gi.repository.Session.websocket_connect_async` to create a WebSocket
   connection, it will call this for you.






   :param msg: :obj:`~gi.repository.Soup.Message` containing both client and server sides of a
        WebSocket handshake

   :param supported_extensions: list
        of supported extension types


   :return: :const:`True` if ``msg`` contains a completed valid WebSocket
        handshake, :const:`False` and an error if not.




.. function:: websocket_error_quark() -> int

   










.. function:: websocket_server_check_handshake(msg: ~gi.repository.Soup.ServerMessage, origin: str | None = None, protocols: list[str] | None = None, supported_extensions: list[~gi.repository.GObject.TypeClass] | None = None) -> bool

   Examines the method and request headers in ``msg`` and determines
   whether ``msg`` contains a valid handshake request.

   If ``origin`` is non-:const:`None`, then only requests containing a matching
   "Origin" header will be accepted. If ``protocols`` is non-:const:`None`, then
   only requests containing a compatible "Sec-WebSocket-Protocols"
   header will be accepted. If ``supported_extensions`` is non-:const:`None`, then
   only requests containing valid supported extensions in
   "Sec-WebSocket-Extensions" header will be accepted.

   Normally :obj:`~gi.repository.Soup.websocket_server_process_handshake`
   will take care of this for you, and if you use
   :obj:`~gi.repository.Server.add_websocket_handler` to handle accepting WebSocket
   connections, it will call that for you. However, this function may
   be useful if you need to perform more complicated validation; eg,
   accepting multiple different Origins, or handling different protocols
   depending on the path.






   :param msg: :obj:`~gi.repository.Soup.ServerMessage` containing the client side of a WebSocket handshake

   :param origin: expected Origin header

   :param protocols: allowed WebSocket
        protocols.

   :param supported_extensions: list
        of supported extension types


   :return: :const:`True` if ``msg`` contained a valid WebSocket handshake,
        :const:`False` and an error if not.




.. function:: websocket_server_process_handshake(msg: ~gi.repository.Soup.ServerMessage, expected_origin: str | None = None, protocols: list[str] | None = None, supported_extensions: list[~gi.repository.GObject.TypeClass] | None = None) -> ~typing.Tuple[bool, list[~gi.repository.Soup.WebsocketExtension]]

   Examines the method and request headers in ``msg`` and (assuming ``msg``
   contains a valid handshake request), fills in the handshake
   response.

   If ``expected_origin`` is non-:const:`None`, then only requests containing a matching
   "Origin" header will be accepted. If ``protocols`` is non-:const:`None`, then
   only requests containing a compatible "Sec-WebSocket-Protocols"
   header will be accepted. If ``supported_extensions`` is non-:const:`None`, then
   only requests containing valid supported extensions in
   "Sec-WebSocket-Extensions" header will be accepted. The accepted extensions
   will be returned in ``accepted_extensions`` parameter if non-:const:`None`.

   This is a low-level function; if you use
   :obj:`~gi.repository.Server.add_websocket_handler` to handle accepting WebSocket
   connections, it will call this for you.






   :param msg: :obj:`~gi.repository.Soup.ServerMessage` containing the client side of a WebSocket handshake

   :param expected_origin: expected Origin header

   :param protocols: allowed WebSocket
        protocols.

   :param supported_extensions: list
        of supported extension types


   :return: :const:`True` if ``msg`` contained a valid WebSocket handshake
        request and was updated to contain a handshake response. :const:`False` if not.