Namespace Soup

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

You may pass %NULL for filename, content_type and/or file if you do not care about those fields. soup_form_decode_multipart() may also return %NULL in those fields if the client did not provide that information. You must free the returned filename and content-type with g_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().

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

To send a "multipart/form-data" POST, first create a #SoupMultipart, 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 #SoupMessage.

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.

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.

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.

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 %NULL, this will just append name to string.

If value is (non-ASCII) UTF-8, this will instead use RFC 5987 encoding, just like soup_header_g_string_append_param().

Tokens that don't have an associated value will still be added to the resulting hash table, but with a %NULL value.

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

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

Tokens that don't have an associated value will still be added to the resulting hash table, but with a %NULL value.

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

This is a low-level method; normally you would use soup_headers_parse_request() or soup_headers_parse_response().

Beware that req_headers may be modified even on failure.

Beware that headers may be modified even on failure.

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 #SoupMessage, 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.

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.

Note that %NULL 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).

In the past, this would return %NULL if part contained invalid percent-encoding, but now it just ignores the problem (as soup_uri_new() already did).

"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 %NULL if part contained invalid percent-encoding, but now it just ignores the problem (as soup_uri_new() already did).

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.

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.

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.

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

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.

If origin is non-%NULL, then only requests containing a matching "Origin" header will be accepted. If protocols is non-%NULL, 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.

If origin is non-%NULL, then only requests containing a matching "Origin" header will be accepted. If protocols is non-%NULL, then only requests containing a compatible "Sec-WebSocket-Protocols" header will be accepted. If supported_extensions is non-%NULL, 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.

If expected_origin is non-%NULL, then only requests containing a matching "Origin" header will be accepted. If protocols is non-%NULL, 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.

If expected_origin is non-%NULL, then only requests containing a matching "Origin" header will be accepted. If protocols is non-%NULL, then only requests containing a compatible "Sec-WebSocket-Protocols" header will be accepted. If supported_extensions is non-%NULL, 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-%NULL.

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.

params is an array of #GValue representing the parameters to method. (It is not a #GValueArray, although if you have a #GValueArray, you can just pass its valuesf and n_values fields.)

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

int: #int (%G_TYPE_INT) boolean: #gboolean (%G_TYPE_BOOLEAN) string: #char* (%G_TYPE_STRING) double: #double (%G_TYPE_DOUBLE) datetime.iso8601: #SoupDate (%SOUP_TYPE_DATE) base64: #GByteArray (%SOUP_TYPE_BYTE_ARRAY) struct: #GHashTable (%G_TYPE_HASH_TABLE) array: #GValueArray (%G_TYPE_VALUE_ARRAY)

For structs, use a #GHashTable that maps strings to #GValue; soup_value_hash_new() and related methods can help with this.

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

params is a #GVariant 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.
• #GVariants created by soup_xmlrpc_variant_new_datetime() are serialized as <dateTime.iso8601>
• Other types are not supported and will return %NULL 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.

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.

See soup_xmlrpc_build_request() for serialization details.

If params is floating, it is consumed.

See soup_xmlrpc_build_request() for serialization details.

If value is floating, it is consumed.

See soup_xmlrpc_params_parse() for deserialization details.

If variant does not contain a datetime it will return an error but it is not considered a programmer error because it generally means parameters received are not in the expected type.

The actual type of the returned #GVariant is unspecified and "v" or "*" should be used in variant format strings. For example: args = g_variant_new ("(v)", soup_xmlrpc_variant_new_datetime (date));