Functions ¶

Like 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.

New in version 2.42.

Soup.cookie_parse(header, origin)¶

Parameters:

header (str) – a cookie string (eg, the value of a Set-Cookie header)
origin (Soup.URI) – origin of the cookie, or None

Returns:

a new Soup.Cookie, or None if it could not be parsed, or contained an illegal “domain” attribute for a cookie originating from origin.

Return type:

Soup.Cookie or None

Parses header and returns a Soup.Cookie. (If header contains multiple cookies, only the first one will be parsed.)

If header does not have “path” or “domain” attributes, they will be defaulted from origin. If origin is None, path will default to “/”, but domain will be left as None. Note that this is not a valid state for a Soup.Cookie, and you will need to fill in some appropriate string for the domain if you want to actually make use of the cookie.

New in version 2.24.

Soup.cookies_from_request(msg)¶

Parameters:: msg (Soup.Message) – a Soup.Message containing a “Cookie” request header
Returns:: a GLib.SList of Soup.Cookie s, which can be freed with soup_cookies_free().
Return type:: [Soup.Cookie]

Parses msg's Cookie request header and returns a GLib.SList of Soup.Cookie s. As the “Cookie” header, unlike “Set-Cookie”, only contains cookie names and values, none of the other Soup.Cookie fields will be filled in. (Thus, you can’t generally pass a cookie returned from this method directly to Soup.cookies_to_response().)

New in version 2.24.

Soup.cookies_from_response(msg)¶

Parameters:: msg (Soup.Message) – a Soup.Message containing a “Set-Cookie” response header
Returns:: a GLib.SList of Soup.Cookie s, which can be freed with soup_cookies_free().
Return type:: [Soup.Cookie]

Parses msg's Set-Cookie response headers and returns a GLib.SList of Soup.Cookie s. Cookies that do not specify “path” or “domain” attributes will have their values defaulted from msg.

New in version 2.24.

Soup.cookies_to_cookie_header(cookies)¶

Parameters:: cookies ([Soup.Cookie]) – a GLib.SList of Soup.Cookie
Returns:: the serialization of cookies
Return type:: str

Serializes a GLib.SList of Soup.Cookie into a string suitable for setting as the value of the “Cookie” header.

New in version 2.24.

Soup.cookies_to_request(cookies, msg)¶

Parameters:

cookies ([Soup.Cookie]) – a GLib.SList of Soup.Cookie
msg (Soup.Message) – a Soup.Message

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.)

New in version 2.24.

Soup.cookies_to_response(cookies, msg)¶

Parameters:

cookies ([Soup.Cookie]) – a GLib.SList of Soup.Cookie
msg (Soup.Message) – a Soup.Message

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.)

New in version 2.24.

Soup.form_decode(encoded_form)¶

Parameters:: encoded_form (str) – data of type “application/x-www-form-urlencoded”
Returns:: a hash table containing the name/value pairs from encoded_form, which you can free with GLib.HashTable.destroy().
Return type:: {str: str}

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

Soup.form_decode_multipart(msg, file_control_name)¶

Parameters:

msg (Soup.Message) – a Soup.Message containing a “multipart/form-data” request body
file_control_name (str or None) – the name of the HTML file upload control, or None

Returns:

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

filename:: return location for the name of the uploaded file, or None
content_type:: return location for the MIME type of the uploaded file, or None
file:: return location for the uploaded file data, or None

Return type:

({str: str} or None, filename: str, content_type: str, file: Soup.Buffer)

Decodes the “multipart/form-data” request in msg; 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 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 Soup.form_decode()) in the returned GLib.HashTable.

You may pass None for filename, content_type and/or file if you do not care about those fields. Soup.form_decode_multipart() may also return None in those fields if the client did not provide that information. You must free the returned filename and content-type with GLib.free(), and the returned file data with Soup.Buffer.free().

If you have a form with more than one file upload control, you will need to decode it manually, using Soup.Multipart.new_from_message() and Soup.Multipart.get_part().

New in version 2.26.

Soup.form_encode_datalist(form_data_set)¶

Parameters:: form_data_set (GLib.Data) – a datalist containing name/value pairs
Returns:: the encoded form
Return type:: str

Encodes form_data_set into a value of type “application/x-www-form-urlencoded”, as defined in the HTML 4.01 spec. Unlike Soup.form_encode_hash(), this preserves the ordering of the form elements, which may be required in some situations.

Soup.form_encode_hash(form_data_set)¶

Parameters:: form_data_set ({str: str}) – a hash table containing name/value pairs (as strings)
Returns:: the encoded form
Return type:: str

Encodes form_data_set into a value of type “application/x-www-form-urlencoded”, 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 Soup.form_encode_datalist().

Soup.form_request_new_from_datalist(method, uri, form_data_set)¶

Parameters:

method (str) – the HTTP method, either “GET” or “POST”
uri (str) – the URI to send the form data to
form_data_set (GLib.Data) – the data to send to uri

Returns:

the new Soup.Message

Return type:

Creates a new Soup.Message and sets it up to send form_data_set to uri via method, as with soup_form_request_new().

Soup.form_request_new_from_hash(method, uri, form_data_set)¶

Parameters:

method (str) – the HTTP method, either “GET” or “POST”
uri (str) – the URI to send the form data to
form_data_set ({str: str}) – the data to send to uri

Returns:

the new Soup.Message

Return type:

Creates a new Soup.Message and sets it up to send form_data_set to uri via method, as with soup_form_request_new().

Soup.form_request_new_from_multipart(uri, multipart)¶

Parameters:

uri (str) – the URI to send the form data to
multipart (Soup.Multipart) – a “multipart/form-data” Soup.Multipart

Returns:

the new Soup.Message

Return type:

Creates a new Soup.Message and sets it up to send multipart to uri via POST.

To send a "multipart/form-data" POST, first create a Soup.Multipart, using Soup.FORM_MIME_TYPE_MULTIPART as the MIME type. Then use Soup.Multipart.append_form_string() and Soup.Multipart.append_form_file() to add the value of each form control to the multipart. (These are just convenience methods, and you can use Soup.Multipart.append_part() if you need greater control over the part headers.) Finally, call Soup.form_request_new_from_multipart() to serialize the multipart structure and create a Soup.Message.

New in version 2.26.

Soup.get_major_version()¶

Returns:: the major version number of the libsoup library
Return type:: 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.

New in version 2.42.

Soup.get_micro_version()¶

Returns:: the micro version number of the libsoup library
Return type:: 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.

New in version 2.42.

Soup.get_minor_version()¶

Returns:: the minor version number of the libsoup library
Return type:: 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.

New in version 2.42.

Soup.get_resource()¶

Return type:: Gio.Resource

Soup.header_contains(header, token)¶

Parameters:

header (str) – An HTTP header suitable for parsing with Soup.header_parse_list()
token (str) – a token

Returns:

whether or not header contains token

Return type:

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.

Soup.header_free_param_list(param_list)¶

Parameters:: param_list ({str: str}) – a GLib.HashTable returned from Soup.header_parse_param_list() or Soup.header_parse_semi_param_list()

Frees param_list.

Soup.header_g_string_append_param(string, name, value)¶

Parameters:

string (GLib.String) – a GLib.String being used to construct an HTTP header value
name (str) – a parameter name
value (str) – a parameter value, or 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 None, this will just append name to string.

New in version 2.26.

Soup.header_g_string_append_param_quoted(string, name, value)¶

Parameters:

string (GLib.String) – a GLib.String being used to construct an HTTP header value
name (str) – a parameter name
value (str) – a parameter value

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 Soup.header_g_string_append_param().

New in version 2.30.

Soup.header_parse_list(header)¶

Parameters:: header (str) – a header value
Returns:: a GLib.SList of list elements, as allocated strings
Return type:: [str]

Parses a header whose content is described by RFC2616 as “#something”, where “something” does not itself contain commas, except as part of quoted-strings.

Soup.header_parse_param_list(header)¶

Parameters:: header (str) – a header value
Returns:: a GLib.HashTable of list elements, which can be freed with Soup.header_free_param_list().
Return type:: {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 None value.

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

Soup.header_parse_param_list_strict(header)¶

Parameters:: header (str) – a header value
Returns:: a GLib.HashTable of list elements, which can be freed with Soup.header_free_param_list() or None if there are duplicate elements.
Return type:: {str: str} or None

A strict version of 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 Soup.header_parse_param_list() instead.

New in version 2.66.

Soup.header_parse_quality_list(header)¶

Parameters:

header (str) – a header value

Returns:

a GLib.SList of acceptable values (as allocated strings), highest-qvalue first.

unacceptable:: on return, will contain a list of unacceptable values

Return type:

([str], unacceptable: [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 None, then on return, it will contain the items with qvalue 0. Either way, those items will be removed from the main list.

Soup.header_parse_semi_param_list(header)¶

Parameters:: header (str) – a header value
Returns:: a GLib.HashTable of list elements, which can be freed with Soup.header_free_param_list().
Return type:: {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 None value.

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

New in version 2.24.

Soup.header_parse_semi_param_list_strict(header)¶

Parameters:: header (str) – a header value
Returns:: a GLib.HashTable of list elements, which can be freed with Soup.header_free_param_list() or None if there are duplicate elements.
Return type:: {str: str} or None

A strict version of 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 Soup.header_parse_semi_param_list() instead.

New in version 2.66.

Soup.headers_parse(str, len, dest)¶

Parameters:

str (str) – the header string (including the Request-Line or Status-Line, but not the trailing blank line)
len (int) – length of str
dest (Soup.MessageHeaders) – Soup.MessageHeaders to store the header values in

Returns:

success or failure

Return type:

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 Soup.headers_parse_request() or Soup.headers_parse_response().

New in version 2.26.

Soup.headers_parse_request(str, len, req_headers)¶

Parameters:

str (str) – the headers (up to, but not including, the trailing blank line)
len (int) – length of str
req_headers (Soup.MessageHeaders) – Soup.MessageHeaders to store the header values in

Returns:

Soup.Status.OK if the headers could be parsed, or an HTTP error to be returned to the client if they could not be.

req_method:: if non-None, will be filled in with the request method
req_path:: if non-None, will be filled in with the request path
ver:: if non-None, will be filled in with the HTTP version

Return type:

(int, req_method: str, req_path: str, ver: 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.

Soup.headers_parse_response(str, len, headers)¶

Parameters:

str (str) – the headers (up to, but not including, the trailing blank line)
len (int) – length of str
headers (Soup.MessageHeaders) – Soup.MessageHeaders to store the header values in

Returns:

success or failure.

ver:: if non-None, will be filled in with the HTTP version
status_code:: if non-None, will be filled in with the status code
reason_phrase:: if non-None, will be filled in with the reason phrase

Return type:

(bool, ver: Soup.HTTPVersion, status_code: int, reason_phrase: 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.

Soup.headers_parse_status_line(status_line)¶

Parameters:

status_line (str) – an HTTP Status-Line

Returns:

True if status_line was parsed successfully.

ver:: if non-None, will be filled in with the HTTP version
status_code:: if non-None, will be filled in with the status code
reason_phrase:: if non-None, will be filled in with the reason phrase

Return type:

(bool, ver: Soup.HTTPVersion, status_code: int, reason_phrase: 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”.

Soup.http_error_quark()¶

Return type:: int

Soup.message_headers_iter_init(hdrs)¶

Parameters:: hdrs (Soup.MessageHeaders) – a Soup.MessageHeaders
Returns:: a pointer to a Soup.MessageHeadersIter structure
Return type:: iter: Soup.MessageHeadersIter

Initializes iter for iterating hdrs.

Soup.request_error_quark()¶

Return type:: int

Soup.requester_error_quark()¶

Return type:: int

Soup.status_get_phrase(status_code)¶

Parameters:: status_code (int) – an HTTP status code
Returns:: the (terse, English) description of status_code
Return type:: str

Looks up the stock HTTP description of status_code. This is used by Soup.Message.set_status() to get the correct text to go with a given status code.

There is no reason for you to ever use this function. If you wanted the textual description for the #SoupMessage:status_code of a given Soup.Message, you should just look at the message’s #SoupMessage:reason_phrase. However, you should only do that for use in debugging messages; HTTP reason phrases are not localized, and are not generally very descriptive anyway, and so they should never be presented to the user directly. Instead, you should create you own error messages based on the status code, and on what you were trying to do.

Soup.status_proxify(status_code)¶

Parameters:: status_code (int) – a status code
Returns:: the “proxified” equivalent of status_code.
Return type:: int

Turns Soup.Status.CANT_RESOLVE into Soup.Status.CANT_RESOLVE_PROXY and Soup.Status.CANT_CONNECT into Soup.Status.CANT_CONNECT_PROXY. Other status codes are passed through unchanged.

New in version 2.26.

Soup.str_case_equal(v1, v2)¶

Parameters:

v1 (object or None) – an ASCII string
v2 (object or None) – another ASCII string

Returns:

True if they are equal (modulo case)

Return type:

Compares v1 and v2 in a case-insensitive manner

Soup.str_case_hash(key)¶

Parameters:: key (object or None) – ASCII string to hash
Returns:: the hash code.
Return type:: int

Hashes key in a case-insensitive manner.

Soup.tld_domain_is_public_suffix(domain)¶

Parameters:: domain (str) – a domain name
Returns:: True if it is a public domain, False otherwise.
Return type:: 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.

New in version 2.40.

Soup.tld_error_quark()¶

Return type:: int

Soup.tld_get_base_domain(hostname)¶

Parameters:: hostname (str) – a hostname
Raises:: GLib.Error
Returns:: a pointer to the start of the base domain in hostname. If an error occurs, None will be returned and error set.
Return type:: 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 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).

New in version 2.40.

Soup.uri_decode(part)¶

Parameters:: part (str) – a URI part
Returns:: the decoded URI part.
Return type:: str

Fully % -decodes part.

In the past, this would return None if part contained invalid percent-encoding, but now it just ignores the problem (as Soup.URI.new() already did).

Soup.uri_encode(part, escape_extra)¶

Parameters:

part (str) – a URI part
escape_extra (str or None) – additional reserved characters to escape (or None)

Returns:

the encoded URI part

Return type:

str

This % -encodes the given URI part and returns the escaped version in allocated memory, which the caller must free when it is done.

Soup.uri_normalize(part, unescape_extra)¶

Parameters:

part (str) – a URI part
unescape_extra (str or None) – reserved characters to unescape (or None)

Returns:

the normalized URI part

Return type:

str

% -decodes any “unreserved” characters (or characters in unescape_extra) in part, and % -encodes any non-ASCII characters, spaces, and non-printing characters in part.

“Unreserved” characters are those that are not allowed to be used for punctuation according to the URI spec. For example, letters are unreserved, so Soup.URI.normalize() will turn http://example.com/foo/b%61r into http://example.com/foo/bar, which is guaranteed to mean the same thing. However, “/” is “reserved”, so http://example.com/foo%2Fbar would not be changed, because it might mean something different to the server.

In the past, this would return None if part contained invalid percent-encoding, but now it just ignores the problem (as Soup.URI.new() already did).

Soup.value_array_new()¶

Returns:: a new GObject.ValueArray
Return type:: GObject.ValueArray

Creates a new GObject.ValueArray. (This is just a wrapper around GObject.ValueArray.new(), for naming consistency purposes.)

Deprecated since version ???: Use GLib.Variant API instead.

Soup.value_hash_insert_value(hash, key, value)¶

Parameters:

hash ({str: GObject.Value}) – a value hash
key (str) – the key
value (GObject.Value) – a value

Inserts value into hash. (Unlike with GLib.HashTable.insert(), both the key and the value are copied).

Deprecated since version ???: Use GLib.Variant API instead.

Soup.value_hash_new()¶

Returns:: a new empty GLib.HashTable
Return type:: {str: GObject.Value}

Creates a GLib.HashTable whose keys are strings and whose values are GObject.Value.

Deprecated since version ???: Use GLib.Variant API instead.

Soup.websocket_client_prepare_handshake(msg, origin, protocols)¶

Parameters:

msg (Soup.Message) – a Soup.Message
origin (str or None) – the “Origin” header to set
protocols ([str] or None) – list of protocols to offer

Adds the necessary headers to msg to request a WebSocket handshake. The message body and non-WebSocket-related headers are not modified.

Use Soup.websocket_client_prepare_handshake_with_extensions() if you want to include “Sec-WebSocket-Extensions” header in the request.

This is a low-level function; if you use Soup.Session.websocket_connect_async() to create a WebSocket connection, it will call this for you.

New in version 2.50.

Soup.websocket_client_prepare_handshake_with_extensions(msg, origin, protocols, supported_extensions)¶

Parameters:

msg (Soup.Message) – a Soup.Message
origin (str or None) – the “Origin” header to set
protocols ([str] or None) – list of protocols to offer
supported_extensions ([GObject.TypeClass] or None) – list of supported extension types

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 Soup.Session.websocket_connect_async() to create a WebSocket connection, it will call this for you.

New in version 2.68.

Soup.websocket_client_verify_handshake(msg)¶

Parameters:: msg (Soup.Message) – Soup.Message containing both client and server sides of a WebSocket handshake
Raises:: GLib.Error
Returns:: True if msg contains a completed valid WebSocket handshake, False and an error if not.
Return type:: bool

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 the response contains the “Sec-WebSocket-Extensions” header, the handshake will be considered invalid. You need to use Soup.websocket_client_verify_handshake_with_extensions() to handle responses with extensions.

This is a low-level function; if you use Soup.Session.websocket_connect_async() to create a WebSocket connection, it will call this for you.

New in version 2.50.

Soup.websocket_client_verify_handshake_with_extensions(msg, supported_extensions)¶

Parameters:

msg (Soup.Message) – Soup.Message containing both client and server sides of a WebSocket handshake
supported_extensions ([GObject.TypeClass] or None) – list of supported extension types

Raises:

Returns:

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

accepted_extensions:: a GLib.List of Soup.WebsocketExtension objects

Return type:

(bool, accepted_extensions: [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-None, extensions included in the response “Sec-WebSocket-Extensions” are verified too. Accepted extensions are returned in accepted_extensions parameter if non-None.

This is a low-level function; if you use Soup.Session.websocket_connect_async() to create a WebSocket connection, it will call this for you.

New in version 2.68.

Soup.websocket_error_get_quark()¶

Return type:: int

Soup.websocket_server_check_handshake(msg, origin, protocols)¶

Parameters:

msg (Soup.Message) – Soup.Message containing the client side of a WebSocket handshake
origin (str or None) – expected Origin header
protocols ([str] or None) – allowed WebSocket protocols.

Raises:

Returns:

True if msg contained a valid WebSocket handshake, False and an error if not.

Return type:

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

If origin is non-None, then only requests containing a matching “Origin” header will be accepted. If protocols is non-None, then only requests containing a compatible “Sec-WebSocket-Protocols” header will be accepted.

Requests containing “Sec-WebSocket-Extensions” header will be accepted even if the header is not valid. To check a request with extensions you need to use Soup.websocket_server_check_handshake_with_extensions() and provide the list of supported extension types.

Normally Soup.websocket_server_process_handshake() will take care of this for you, and if you use Soup.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.

New in version 2.50.

Soup.websocket_server_check_handshake_with_extensions(msg, origin, protocols, supported_extensions)¶

Parameters:

msg (Soup.Message) – Soup.Message containing the client side of a WebSocket handshake
origin (str or None) – expected Origin header
protocols ([str] or None) – allowed WebSocket protocols.
supported_extensions ([GObject.TypeClass] or None) – list of supported extension types

Raises:

Returns:

True if msg contained a valid WebSocket handshake, False and an error if not.

Return type:

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

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

Normally soup_websocket_server_process_handshake_with_extensioins() will take care of this for you, and if you use Soup.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.

New in version 2.68.

Soup.websocket_server_process_handshake(msg, expected_origin, protocols)¶

Parameters:

msg (Soup.Message) – Soup.Message containing the client side of a WebSocket handshake
expected_origin (str or None) – expected Origin header
protocols ([str] or None) – allowed WebSocket protocols.

Returns:

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

Return type:

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-None, then only requests containing a matching “Origin” header will be accepted. If protocols is non-None, then only requests containing a compatible “Sec-WebSocket-Protocols” header will be accepted.

Requests containing “Sec-WebSocket-Extensions” header will be accepted even if the header is not valid. To process a request with extensions you need to use Soup.websocket_server_process_handshake_with_extensions() and provide the list of supported extension types.

This is a low-level function; if you use Soup.Server.add_websocket_handler() to handle accepting WebSocket connections, it will call this for you.

New in version 2.50.

Soup.websocket_server_process_handshake_with_extensions(msg, expected_origin, protocols, supported_extensions)¶

Parameters:

msg (Soup.Message) – Soup.Message containing the client side of a WebSocket handshake
expected_origin (str or None) – expected Origin header
protocols ([str] or None) – allowed WebSocket protocols.
supported_extensions ([GObject.TypeClass] or None) – list of supported extension types

Returns:

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

accepted_extensions:: a GLib.List of Soup.WebsocketExtension objects

Return type:

(bool, accepted_extensions: [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-None, then only requests containing a matching “Origin” header will be accepted. If protocols is non-None, then only requests containing a compatible “Sec-WebSocket-Protocols” header will be accepted. If supported_extensions is non-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-None.

This is a low-level function; if you use Soup.Server.add_websocket_handler() to handle accepting WebSocket connections, it will call this for you.

New in version 2.68.

Soup.xmlrpc_build_method_call(method_name, params)¶

Parameters:

method_name (str) – the name of the XML-RPC method
params ([GObject.Value]) – arguments to method

Returns:

the text of the methodCall, or None on error

Return type:

str or None

This creates an XML-RPC methodCall and returns it as a string. This is the low-level method that soup_xmlrpc_request_new() is built on.

params is an array of GObject.Value representing the parameters to method. (It is *not* a GObject.ValueArray, although if you have a GObject.ValueArray, you can just pass its values``f and ``n_values fields.)

The correspondence between glib types and XML-RPC types is:

int: #int (GObject.TYPE_INT) boolean: bool (GObject.TYPE_BOOLEAN) string: str (GObject.TYPE_STRING) double: #double (GObject.TYPE_DOUBLE) datetime.iso8601: Soup.Date (%SOUP_TYPE_DATE) base64: GLib.ByteArray (%SOUP_TYPE_BYTE_ARRAY) struct: GLib.HashTable (%G_TYPE_HASH_TABLE) array: GObject.ValueArray (%G_TYPE_VALUE_ARRAY)

For structs, use a GLib.HashTable that maps strings to GObject.Value; Soup.value_hash_new() and related methods can help with this.

Deprecated since version ???: Use Soup.xmlrpc_build_request() instead.

Soup.xmlrpc_build_method_response(value)¶

Parameters:: value (GObject.Value) – the return value
Returns:: the text of the methodResponse, or None on error
Return type:: str or None

This creates a (successful) XML-RPC methodResponse and returns it as a string. To create a fault response, use soup_xmlrpc_build_fault().

The glib type to XML-RPC type mapping is as with Soup.xmlrpc_build_method_call(), qv.

Deprecated since version ???: Use Soup.xmlrpc_build_response() instead.

Soup.xmlrpc_build_request(method_name, params)¶

Parameters:

method_name (str) – the name of the XML-RPC method
params (GLib.Variant) – a GLib.Variant tuple

Raises:

Returns:

the text of the methodCall, or None on error.

Return type:

str

This creates an XML-RPC methodCall and returns it as a string. This is the low-level method that Soup.xmlrpc_message_new() is built on.

params is a GLib.Variant tuple representing the method parameters.

Serialization details:

“a{s*}” and “{s*}” are serialized as <struct>
“ay” is serialized as <base64>
Other arrays and tuples are serialized as <array>
booleans are serialized as <boolean>
byte, int16, uint16 and int32 are serialized as <int>
uint32 and int64 are serialized as the nonstandard <i8> type
doubles are serialized as <double>
Strings are serialized as <string>
Variants (i.e. “v” type) are unwrapped and their child is serialized.
GLib.Variants created by Soup.xmlrpc_variant_new_datetime() are serialized as <dateTime.iso8601>
Other types are not supported and will return None and set error. This notably includes: object-paths, signatures, uint64, handles, maybes and dictionaries with non-string keys.

If params is floating, it is consumed.

New in version 2.52.

Soup.xmlrpc_build_response(value)¶

Parameters:: value (GLib.Variant) – the return value
Raises:: GLib.Error
Returns:: the text of the methodResponse, or None on error.
Return type:: str

This creates a (successful) XML-RPC methodResponse and returns it as a string. To create a fault response, use soup_xmlrpc_build_fault(). This is the low-level method that Soup.xmlrpc_message_set_response() is built on.

See Soup.xmlrpc_build_request() for serialization details, but note that since a method can only have a single return value, value should not be a tuple here (unless the return value is an array).

If value is floating, it is consumed.

New in version 2.52.

Soup.xmlrpc_error_quark()¶

Return type:: int

Soup.xmlrpc_fault_quark()¶

Return type:: int

Soup.xmlrpc_message_new(uri, method_name, params)¶

Parameters:

uri (str) – URI of the XML-RPC service
method_name (str) – the name of the XML-RPC method to invoke at uri
params (GLib.Variant) – a GLib.Variant tuple

Raises:

Returns:

a Soup.Message encoding the indicated XML-RPC request, or None on error.

Return type:

Creates an XML-RPC methodCall and returns a Soup.Message, ready to send, for that method call.

See Soup.xmlrpc_build_request() for serialization details.

If params is floating, it is consumed.

New in version 2.52.

Soup.xmlrpc_message_set_response(msg, value)¶

Parameters:

msg (Soup.Message) – an XML-RPC request
value (GLib.Variant) – a GLib.Variant

Raises:

Returns:

True on success, False otherwise.

Return type:

Sets the status code and response body of msg to indicate a successful XML-RPC call, with a return value given by value. To set a fault response, use soup_xmlrpc_message_set_fault().

See Soup.xmlrpc_build_request() for serialization details.

If value is floating, it is consumed.

New in version 2.52.

Soup.xmlrpc_parse_method_call(method_call, length)¶

Parameters:

method_call (str) – the XML-RPC methodCall string
length (int) – the length of method_call, or -1 if it is NUL-terminated

Returns:

success or failure.

method_name:: on return, the methodName from method_call
params:: on return, the parameters from method_call

Return type:

(bool, method_name: str, params: GObject.ValueArray)

Parses method_call to get the name and parameters, and returns the parameter values in a GObject.ValueArray; see also soup_xmlrpc_extract_method_call(), which is more convenient if you know in advance what the types of the parameters will be.

Deprecated since version ???: Use soup_xmlrpc_parse_request_full() instead.

Soup.xmlrpc_parse_method_response(method_response, length)¶

Parameters:

method_response (str) – the XML-RPC methodResponse string
length (int) – the length of method_response, or -1 if it is NUL-terminated

Raises:

Returns:

True if a return value was parsed, False if the response could not be parsed, or contained a fault.

value:: on return, the return value from method_call

Return type:

(bool, value: GObject.Value)

Parses method_response and returns the return value in value. If method_response is a fault, value will be unchanged, and error will be set to an error of type %SOUP_XMLRPC_FAULT, with the error #code containing the fault code, and the error #message containing the fault string. (If method_response cannot be parsed at all, Soup.xmlrpc_parse_method_response() will return False, but error will be unset.)

Deprecated since version ???: Use Soup.xmlrpc_parse_response() instead.

Soup.xmlrpc_parse_request(method_call, length)¶

Parameters:

method_call (str) – the XML-RPC methodCall string
length (int) – the length of method_call, or -1 if it is NUL-terminated

Raises:

Returns:

method’s name, or None on error.

params:: on success, a new Soup.XMLRPCParams

Return type:

(str, params: Soup.XMLRPCParams)

Parses method_call and return the method name. Method parameters can be parsed later using Soup.XMLRPCParams.parse().

New in version 2.52.

Soup.xmlrpc_parse_response(method_response, length, signature)¶

Parameters:

method_response (str) – the XML-RPC methodResponse string
length (int) – the length of method_response, or -1 if it is NUL-terminated
signature (str or None) – A valid GLib.Variant type string, or None

Raises: