soup_message_new ()

SoupMessage *
soup_message_new (const char *method,
                  const char *uri_string);

Creates a new empty SoupMessage, which will connect to uri

soup_message_new_from_uri ()

SoupMessage *
soup_message_new_from_uri (const char *method,
                           GUri *uri);

Creates a new empty SoupMessage, which will connect to uri

soup_message_new_from_encoded_form ()

SoupMessage *
soup_message_new_from_encoded_form (const char *method,
                                    const char *uri_string,
                                    char *encoded_form);

Creates a new SoupMessage and sets it up to send the given encoded_form to uri via method . If method is "GET", it will include the form data into uri 's query field, and if method is "POST" or "PUT", it will be set as request body. This function takes the ownership of encoded_form , that will be released with g_free() when no longer in use. See also soup_form_encode(), soup_form_encode_hash() and soup_form_encode_datalist().

soup_message_new_from_multipart ()

SoupMessage *
soup_message_new_from_multipart (const char *uri_string,
                                 SoupMultipart *multipart);

Creates a new SoupMessage and sets it up to send multipart to uri_string via POST.

soup_message_set_request_body ()

void
soup_message_set_request_body (SoupMessage *msg,
                               const char *content_type,
                               GInputStream *stream,
                               gssize content_length);

Set the request body of a SoupMessage. If content_type is NULL and stream is not NULL the Content-Type header will not be changed if present. The request body needs to be set again in case msg is restarted (in case of redirection or authentication).

soup_message_set_request_body_from_bytes ()

void
soup_message_set_request_body_from_bytes
                               (SoupMessage *msg,
                                const char *content_type,
                                GBytes *bytes);

Set the request body of a SoupMessage from GBytes. If content_type is NULL and bytes is not NULL the Content-Type header will not be changed if present. The request body needs to be set again in case msg is restarted (in case of redirection or authentication).

soup_message_set_http_version ()

void
soup_message_set_http_version (SoupMessage *msg,
                               SoupHTTPVersion version);

Sets the HTTP version on msg . The default version is SOUP_HTTP_1_1. Setting it to SOUP_HTTP_1_0 will prevent certain functionality from being used.

soup_message_get_http_version ()

SoupHTTPVersion
soup_message_get_http_version (SoupMessage *msg);

Gets the HTTP version of msg . This is the minimum of the version from the request and the version from the response.

soup_message_get_uri ()

GUri *
soup_message_get_uri (SoupMessage *msg);

Gets msg 's URI

soup_message_set_uri ()

void
soup_message_set_uri (SoupMessage *msg,
                      GUri *uri);

Sets msg 's URI to uri . If msg has already been sent and you want to re-send it with the new URI, you need to send it again.

soup_message_get_method ()

const char *
soup_message_get_method (SoupMessage *msg);

Returns the method of this message.

soup_message_get_status ()

SoupStatus
soup_message_get_status (SoupMessage *msg);

Returns the set status of this message.

soup_message_get_reason_phrase ()

const char *
soup_message_get_reason_phrase (SoupMessage *msg);

Returns the reason phrase for the status of this message.

soup_message_get_request_headers ()

SoupMessageHeaders *
soup_message_get_request_headers (SoupMessage *msg);

Returns the headers sent with the request.

soup_message_get_response_headers ()

SoupMessageHeaders *
soup_message_get_response_headers (SoupMessage *msg);

Returns the headers recieved with the response.

soup_message_is_keepalive ()

gboolean
soup_message_is_keepalive (SoupMessage *msg);

Determines whether or not msg 's connection can be kept alive for further requests after processing msg , based on the HTTP version, Connection header, etc.

soup_message_get_tls_certificate ()

GTlsCertificate *
soup_message_get_tls_certificate (SoupMessage *msg);

Gets the GTlsCertificate associated with msg 's connection. Note that this is not set yet during the emission of SoupMessage::accept-certificate signal.

soup_message_get_tls_certificate_errors ()

GTlsCertificateFlags
soup_message_get_tls_certificate_errors
                               (SoupMessage *msg);

Gets the errors associated with validating msg 's TLS certificate. Note that this is not set yet during the emission of SoupMessage::accept-certificate signal.

soup_message_set_first_party ()

void
soup_message_set_first_party (SoupMessage *msg,
                              GUri *first_party);

Sets first_party as the main document GUri for msg . For details of when and how this is used refer to the documentation for SoupCookieJarAcceptPolicy.

soup_message_get_first_party ()

GUri *
soup_message_get_first_party (SoupMessage *msg);

Gets msg 's first-party GUri

soup_message_add_header_handler ()

guint
soup_message_add_header_handler (SoupMessage *msg,
                                 const char *signal,
                                 const char *header,
                                 GCallback callback,
                                 gpointer user_data);

Adds a signal handler to msg for signal , as with g_signal_connect(), but the callback will only be run if msg 's incoming messages headers (that is, the request_headers) contain a header named header .

[skip]

soup_message_add_status_code_handler ()

guint
soup_message_add_status_code_handler (SoupMessage *msg,
                                      const char *signal,
                                      guint status_code,
                                      GCallback callback,
                                      gpointer user_data);

Adds a signal handler to msg for signal , as with g_signal_connect(), but the callback will only be run if msg has the status status_code .

signal must be a signal that will be emitted after msg 's status is set (this means it can't be a "wrote" signal).

[skip]

soup_message_set_flags ()

void
soup_message_set_flags (SoupMessage *msg,
                        SoupMessageFlags flags);

Sets the specified flags on msg .

soup_message_get_flags ()

SoupMessageFlags
soup_message_get_flags (SoupMessage *msg);

Gets the flags on msg

soup_message_add_flags ()

void
soup_message_add_flags (SoupMessage *msg,
                        SoupMessageFlags flags);

Adds flags to the set of msg 's flags

soup_message_remove_flags ()

void
soup_message_remove_flags (SoupMessage *msg,
                           SoupMessageFlags flags);

Removes flags from the set of msg 's flags

soup_message_query_flags ()

gboolean
soup_message_query_flags (SoupMessage *msg,
                          SoupMessageFlags flags);

Queries if flags are present in the set of msg 's flags

soup_message_disable_feature ()

void
soup_message_disable_feature (SoupMessage *msg,
                              GType feature_type);

This disables the actions of SoupSessionFeatures with the given feature_type (or a subclass of that type) on msg , so that msg is processed as though the feature(s) hadn't been added to the session. Eg, passing SOUP_TYPE_CONTENT_SNIFFER for feature_type will disable Content-Type sniffing on the message.

You must call this before queueing msg on a session; calling it on a message that has already been queued is undefined. In particular, you cannot call this on a message that is being requeued after a redirect or authentication.

soup_message_is_feature_disabled ()

gboolean
soup_message_is_feature_disabled (SoupMessage *msg,
                                  GType feature_type);

Get whether SoupSessionFeatures of the given feature_type (or a subclass of that type) are disabled on msg . See soup_message_disable_feature().

soup_message_get_priority ()

SoupMessagePriority
soup_message_get_priority (SoupMessage *msg);

Retrieves the SoupMessagePriority. If not set this value defaults to SOUP_MESSAGE_PRIORITY_NORMAL.

soup_message_set_priority ()

void
soup_message_set_priority (SoupMessage *msg,
                           SoupMessagePriority priority);

Sets the priority of a message. Note that this won't have any effect unless used before the message is added to the session's message processing queue.

The message will be placed just before any other previously added message with lower priority (messages with the same priority are processed on a FIFO basis).

Setting priorities does not currently work with synchronous messages because in the synchronous/blocking case, priority ends up being determined semi-randomly by thread scheduling.

soup_message_get_site_for_cookies ()

GUri *
soup_message_get_site_for_cookies (SoupMessage *msg);

Gets msg 's site for cookies GUri

soup_message_set_site_for_cookies ()

void
soup_message_set_site_for_cookies (SoupMessage *msg,
                                   GUri *site_for_cookies);

Sets site_for_cookies as the policy URL for same-site cookies for msg .

It is either the URL of the top-level document or NULL depending on whether the registrable domain of this document's URL matches the registrable domain of its parent's/opener's URL. For the top-level document it is set to the document's URL.

See the same-site spec for more information.

soup_message_get_is_top_level_navigation ()

gboolean
soup_message_get_is_top_level_navigation
                               (SoupMessage *msg);

Returns if this message is set as a top level navigation. Used for same-site policy checks.

soup_message_set_is_top_level_navigation ()

void
soup_message_set_is_top_level_navigation
                               (SoupMessage *msg,
                                gboolean is_top_level_navigation);

See the same-site spec for more information.

SoupMessage

typedef struct _SoupMessage SoupMessage;

Represents an HTTP message being sent or received.

status_code will normally be a SoupStatus value, eg, SOUP_STATUS_OK, though of course it might actually be an unknown status code. reason_phrase is the actual text returned from the server, which may or may not correspond to the "standard" description of status_code . At any rate, it is almost certainly not localized, and not very descriptive even if it is in the user's language; you should not use reason_phrase in user-visible messages. Rather, you should look at status_code , and determine an end-user-appropriate message based on that and on what you were trying to do.

enum SoupHTTPVersion

Indicates the HTTP protocol version being used.

enum SoupMessageFlags

Various flags that can be set on a SoupMessage to alter its behavior.

enum SoupMessagePriority

Priorities that can be set on a SoupMessage to instruct the message queue to process it before any other message with lower priority.

The “first-party” property

  “first-party”              GUri *

The GUri loaded in the application when the message was queued.

Owner: SoupMessage

Flags: Read / Write

The “flags” property

  “flags”                    SoupMessageFlags

Various message options.

Owner: SoupMessage

Flags: Read / Write

The “http-version” property

  “http-version”             SoupHTTPVersion

The HTTP protocol version to use.

Owner: SoupMessage

Flags: Read / Write

Default value: SOUP_HTTP_1_1

The “is-top-level-navigation” property

  “is-top-level-navigation”  gboolean

Set when the message is navigating between top level domains.

Owner: SoupMessage

Flags: Read / Write

Default value: FALSE

The “method” property

  “method”                   char *

The message's HTTP method.

Owner: SoupMessage

Flags: Read / Write

Default value: "GET"

The “options-ping” property

  “options-ping”             gboolean

The SoupMessage is intended to be used to send OPTIONS * to a server and the path of “uri” will be ignored.

Owner: SoupMessage

Flags: Read / Write

Default value: FALSE

The “priority” property

  “priority”                 SoupMessagePriority

Sets the priority of the SoupMessage. See soup_message_set_priority() for further details.

Owner: SoupMessage

Flags: Read / Write

Default value: SOUP_MESSAGE_PRIORITY_NORMAL

The “reason-phrase” property

  “reason-phrase”            char *

The HTTP response reason phrase.

Owner: SoupMessage

Flags: Read

Default value: NULL

The “request-headers” property

  “request-headers”          SoupMessageHeaders *

The HTTP request headers.

Owner: SoupMessage

Flags: Read

The “response-headers” property

  “response-headers”         SoupMessageHeaders *

The HTTP response headers.

Owner: SoupMessage

Flags: Read

The “site-for-cookies” property

  “site-for-cookies”         GUri *

The URI for the site to compare cookies against.

Owner: SoupMessage

Flags: Read / Write

The “status-code” property

  “status-code”              guint

The HTTP response status code.

Owner: SoupMessage

Flags: Read

Allowed values: <= 999

Default value: 0

The “tls-certificate” property

  “tls-certificate”          GTlsCertificate *

The GTlsCertificate associated with the message

Owner: SoupMessage

Flags: Read

The “tls-certificate-errors” property

  “tls-certificate-errors”   GTlsCertificateFlags

The verification errors on “tls-certificate”

Owner: SoupMessage

Flags: Read

The “uri” property

  “uri”                      GUri *

The message's Request-URI.

Owner: SoupMessage

Flags: Read / Write

The “accept-certificate” signal

gboolean
user_function (SoupMessage         *msg,
               GTlsCertificate     *tls_certificate,
               GTlsCertificateFlags tls_errors,
               gpointer             user_data)

Emitted during the msg 's connection TLS handshake after an unacceptable TLS certificate has been received. You can return TRUE to accept tls_certificate despite tls_errors .

Flags: Run Last

The “authenticate” signal

gboolean
user_function (SoupMessage *msg,
               SoupAuth    *auth,
               gboolean     retrying,
               gpointer     user_data)

Emitted when the message requires authentication. If credentials are available call soup_auth_authenticate() on auth . If these credentials fail, the signal will be emitted again, with retrying set to TRUE, which will continue until you return without calling soup_auth_authenticate() on auth .

Note that this may be emitted before msg 's body has been fully read.

You can authenticate auth asynchronously by calling g_object_ref() on auth and returning TRUE. The operation will complete once either soup_auth_authenticate() or soup_auth_cancel() are called.

Flags: Run Last

The “content-sniffed” signal

void
user_function (SoupMessage *msg,
               char        *type,
               GHashTable  *params,
               gpointer     user_data)

This signal is emitted after “got-headers”. If content sniffing is disabled, or no content sniffing will be performed, due to the sniffer deciding to trust the Content-Type sent by the server, this signal is emitted immediately after “got-headers”, and type is NULL.

Flags: Run First

The “finished” signal

void
user_function (SoupMessage *msg,
               gpointer     user_data)

Emitted when all HTTP processing is finished for a message. (After “got_body”).

Flags: Run First

The “got-body” signal

void
user_function (SoupMessage *msg,
               gpointer     user_data)

Emitted after receiving the complete message request body.

See also soup_message_add_header_handler() and soup_message_add_status_code_handler(), which can be used to connect to a subset of emissions of this signal.

Flags: Run First

The “got-headers” signal

void
user_function (SoupMessage *msg,
               gpointer     user_data)

Emitted after receiving the Status-Line and response headers.

See also soup_message_add_header_handler() and soup_message_add_status_code_handler(), which can be used to connect to a subset of emissions of this signal.

If you cancel or requeue msg while processing this signal, then the current HTTP I/O will be stopped after this signal emission finished, and msg 's connection will be closed. (If you need to requeue a message--eg, after handling authentication or redirection--it is usually better to requeue it from a “got_body” handler rather than a “got_headers” handler, so that the existing HTTP connection can be reused.)

Flags: Run First

The “got-informational” signal

void
user_function (SoupMessage *msg,
               gpointer     user_data)

Emitted after receiving a 1xx (Informational) response for a (client-side) message. The response_headers will be filled in with the headers associated with the informational response; however, those header values will be erased after this signal is done.

If you cancel or requeue msg while processing this signal, then the current HTTP I/O will be stopped after this signal emission finished, and msg 's connection will be closed.

Flags: Run First

The “hsts-enforced” signal

void
user_function (SoupMessage *msg,
               gpointer     user_data)

Emitted when SoupHSTSEnforcer has upgraded the protocol for msg to HTTPS as a result of matching its domain with a HSTS policy.

Flags: Run Last

The “network-event” signal

void
user_function (SoupMessage       *msg,
               GSocketClientEvent event,
               GIOStream         *connection,
               gpointer           user_data)

Emitted to indicate that some network-related event related to msg has occurred. This essentially proxies the “event” signal, but only for events that occur while msg "owns" the connection; if msg is sent on an existing persistent connection, then this signal will not be emitted. (If you want to force the message to be sent on a new connection, set the SOUP_MESSAGE_NEW_CONNECTION flag on it.)

See “event” for more information on what the different values of event correspond to, and what connection will be in each case.

Flags: Run First

The “restarted” signal

void
user_function (SoupMessage *msg,
               gpointer     user_data)

Emitted when a request that was already sent once is now being sent again (eg, because the first attempt received a redirection response, or because we needed to use authentication).

Flags: Run First

The “starting” signal

void
user_function (SoupMessage *msg,
               gpointer     user_data)

Emitted just before a message is sent.

Flags: Run First

The “wrote-body” signal

void
user_function (SoupMessage *msg,
               gpointer     user_data)

Emitted immediately after writing the complete body for a message.

Flags: Run First

The “wrote-body-data” signal

void
user_function (SoupMessage *msg,
               guint        chunk_size,
               gpointer     user_data)

Emitted immediately after writing a portion of the message body to the network.

Flags: Run First

The “wrote-headers” signal

void
user_function (SoupMessage *msg,
               gpointer     user_data)

Emitted immediately after writing the request headers for a message.

Flags: Run First