SoupMessage

SoupMessage — An HTTP request and response.

Functions

SoupMessage * soup_message_new ()
SoupMessage * soup_message_new_from_uri ()
SoupMessage * soup_message_new_from_encoded_form ()
SoupMessage * soup_message_new_from_multipart ()
void soup_message_set_request_body ()
void soup_message_set_request_body_from_bytes ()
SoupMessage * soup_message_new_options_ping ()
gboolean soup_message_get_is_options_ping ()
void soup_message_set_is_options_ping ()
SoupHTTPVersion soup_message_get_http_version ()
GUri * soup_message_get_uri ()
void soup_message_set_uri ()
const char * soup_message_get_method ()
void soup_message_set_method ()
SoupStatus soup_message_get_status ()
const char * soup_message_get_reason_phrase ()
SoupMessageHeaders * soup_message_get_request_headers ()
SoupMessageHeaders * soup_message_get_response_headers ()
gboolean soup_message_is_keepalive ()
guint64 soup_message_get_connection_id ()
GSocketAddress * soup_message_get_remote_address ()
GTlsCertificate * soup_message_get_tls_peer_certificate ()
GTlsCertificateFlags soup_message_get_tls_peer_certificate_errors ()
GTlsProtocolVersion soup_message_get_tls_protocol_version ()
const char * soup_message_get_tls_ciphersuite_name ()
void soup_message_set_tls_client_certificate ()
void soup_message_tls_client_certificate_password_request_complete ()
void soup_message_set_first_party ()
GUri * soup_message_get_first_party ()
guint soup_message_add_header_handler ()
guint soup_message_add_status_code_handler ()
void soup_message_set_flags ()
SoupMessageFlags soup_message_get_flags ()
void soup_message_add_flags ()
void soup_message_remove_flags ()
gboolean soup_message_query_flags ()
void soup_message_disable_feature ()
gboolean soup_message_is_feature_disabled ()
SoupMessagePriority soup_message_get_priority ()
void soup_message_set_priority ()
GUri * soup_message_get_site_for_cookies ()
void soup_message_set_site_for_cookies ()
gboolean soup_message_get_is_top_level_navigation ()
void soup_message_set_is_top_level_navigation ()
SoupMessageMetrics * soup_message_get_metrics ()

Properties

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── SoupMessage

Includes

#include <libsoup/soup.h>

Description

A SoupMessage represents an HTTP message that is being sent or received.

You would create a SoupMessage with soup_message_new() or soup_message_new_from_uri(), set up its fields appropriately, and send it.

Note that libsoup's terminology here does not quite match the HTTP specification: in RFC 2616, an "HTTP-message" is either a Request, or a Response. In libsoup, a SoupMessage combines both the request and the response.

Functions

soup_message_new ()

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

Creates a new empty SoupMessage, which will connect to uri

Parameters

method

the HTTP method for the created request

 

uri_string

the destination endpoint (as a string)

 

Returns

the new SoupMessage (or NULL if uri could not be parsed).

[transfer full][nullable]


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

Parameters

method

the HTTP method for the created request

 

uri

the destination endpoint (as a GUri)

 

Returns

the new SoupMessage.

[transfer full]


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

Parameters

method

the HTTP method for the created request (GET, POST or PUT)

 

uri_string

the destination endpoint (as a string)

 

encoded_form

a encoded form.

[transfer full]

Returns

the new SoupMessage, or NULL if uri_string could not be parsed or method is not "GET, "POST" or "PUT".

[transfer full][nullable]


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.

Parameters

uri_string

the destination endpoint (as a string)

 

multipart

a SoupMultipart

 

Returns

the new SoupMessage, or NULL if uri_string could not be parsed.

[transfer full][nullable]


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

Parameters

msg

the message

 

content_type

MIME Content-Type of the body, or NULL if unknown.

[nullable]

stream

a GInputStream to read the request body from.

[nullable]

content_length

the byte length of stream or -1 if unknown

 

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

Parameters

msg

the message

 

content_type

MIME Content-Type of the body, or NULL if unknown.

[nullable]

bytes

a GBytes with the request body data.

[nullable]

soup_message_new_options_ping ()

SoupMessage *
soup_message_new_options_ping (GUri *base_uri);

Creates a new SoupMessage to send OPTIONS * to a server. The path of base_uri will be ignored.

Parameters

base_uri

the destination endpoint (as a GUri)

 

Returns

the new SoupMessage.

[transfer full]


soup_message_get_is_options_ping ()

gboolean
soup_message_get_is_options_ping (SoupMessage *msg);

Gets whether msg is intended to be used to send OPTIONS * to a server.

Parameters

msg

a SoupMessage

 

Returns

TRUE if the message is options ping, or FALSE otherwise


soup_message_set_is_options_ping ()

void
soup_message_set_is_options_ping (SoupMessage *msg,
                                  gboolean is_options_ping);

Set whether msg is intended to be used to send OPTIONS * to a server. When set to TRUE, the path of “uri” will be ignored and “method” set to SOUP_METHOD_OPTIONS.

Parameters

msg

a SoupMessage

 

is_options_ping

the value to set

 

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.

Parameters

msg

a SoupMessage

 

Returns

the HTTP version


soup_message_get_uri ()

GUri *
soup_message_get_uri (SoupMessage *msg);

Gets msg 's URI

Parameters

msg

a SoupMessage

 

Returns

the URI msg is targeted for.

[transfer none]


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.

Parameters

msg

a SoupMessage

 

uri

the new GUri

 

soup_message_get_method ()

const char *
soup_message_get_method (SoupMessage *msg);

Returns the method of this message.

Parameters

msg

The SoupMessage

 

Returns

A method such as SOUP_METHOD_GET


soup_message_set_method ()

void
soup_message_set_method (SoupMessage *msg,
                         const char *method);

Set msg 's HTTP method to method .

Parameters

msg

a SoupMessage

 

method

the value to set

 

soup_message_get_status ()

SoupStatus
soup_message_get_status (SoupMessage *msg);

Returns the set status of this message.

Parameters

msg

The SoupMessage

 

Returns

The SoupStatus


soup_message_get_reason_phrase ()

const char *
soup_message_get_reason_phrase (SoupMessage *msg);

Returns the reason phrase for the status of this message.

Parameters

msg

The SoupMessage

 

Returns

Phrase or NULL


soup_message_get_request_headers ()

SoupMessageHeaders *
soup_message_get_request_headers (SoupMessage *msg);

Returns the headers sent with the request.

Parameters

msg

The SoupMessage

 

Returns

The SoupMessageHeaders.

[transfer none]


soup_message_get_response_headers ()

SoupMessageHeaders *
soup_message_get_response_headers (SoupMessage *msg);

Returns the headers recieved with the response.

Parameters

msg

The SoupMessage

 

Returns

The SoupMessageHeaders.

[transfer none]


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.

Parameters

msg

a SoupMessage

 

Returns

TRUE or FALSE.


soup_message_get_connection_id ()

guint64
soup_message_get_connection_id (SoupMessage *msg);

Returns the unique idenfier for the last connection used. This may be 0 if it was a cached resource or it has not gotten a connection yet.

Parameters

msg

The SoupMessage

 

Returns

An id or 0 if no connection.


soup_message_get_remote_address ()

GSocketAddress *
soup_message_get_remote_address (SoupMessage *msg);

Get the remote GSocketAddress of the connection associated with the message. The returned address can be NULL if the connection hasn't been established yet, or the resource was loaded from the disk cache. In case of proxy connections, the remote address returned is a GProxyAddress. If “remote-connetable” is set the returned address id for the connection ot the session's remote connectable.

Parameters

msg

The SoupMessage

 

Returns

a GSocketAddress or NULL if the connection hasn't been established.

[transfer none][nullable]


soup_message_get_tls_peer_certificate ()

GTlsCertificate *
soup_message_get_tls_peer_certificate (SoupMessage *msg);

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

Parameters

msg

a SoupMessage

 

Returns

msg 's TLS peer certificate, or NULL if msg 's connection is not SSL.

[transfer none][nullable]


soup_message_get_tls_peer_certificate_errors ()

GTlsCertificateFlags
soup_message_get_tls_peer_certificate_errors
                               (SoupMessage *msg);

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

Parameters

msg

a SoupMessage

 

Returns

a GTlsCertificateFlags with msg 's TLS peer certificate errors.


soup_message_get_tls_protocol_version ()

GTlsProtocolVersion
soup_message_get_tls_protocol_version (SoupMessage *msg);

Gets the TLS protocol version negotiated for msg 's connection. If the message connection is not SSL, G_TLS_PROTOCOL_VERSION_UNKNOWN is returned.

Parameters

msg

a SoupMessage

 

soup_message_get_tls_ciphersuite_name ()

const char *
soup_message_get_tls_ciphersuite_name (SoupMessage *msg);

Gets the name of the TLS ciphersuite negotiated for msg 's connection.

Parameters

msg

a SoupMessage

 

Returns

the name of the TLS ciphersuite, or NULL if msg 's connection is not SSL.

[transfer none]


soup_message_set_tls_client_certificate ()

void
soup_message_set_tls_client_certificate
                               (SoupMessage *msg,
                                GTlsCertificate *certificate);

Sets the certificate to be used by msg 's connection when a client certificate is requested during the TLS handshake. You can call this as a response to “request-certificate” signal, or before the connection is started. If certificate is NULL the handshake will continue without providing a GTlsCertificate. Note that the GTlsCertificate set by this function will be ignored if “tls-interaction” is not NULL.

Parameters

msg

a SoupMessage

 

certificate

the GTlsCertificate to set, or NULL.

[nullable]

soup_message_tls_client_certificate_password_request_complete ()

void
soup_message_tls_client_certificate_password_request_complete
                               (SoupMessage *msg);

Completes a certificate password request.

You must call this as a response to “request-certificate-password” signal, to notify msg that the GTlsPassword has already been updated.

Parameters

msg

a SoupMessage

 

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.

Parameters

msg

a SoupMessage

 

first_party

the GUri for the msg 's first party

 

soup_message_get_first_party ()

GUri *
soup_message_get_first_party (SoupMessage *msg);

Gets msg 's first-party GUri

Parameters

msg

a SoupMessage

 

Returns

the msg 's first party GUri.

[transfer none]


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]

Parameters

msg

a SoupMessage

 

signal

signal to connect the handler to.

 

header

HTTP response header to match against

 

callback

the header handler

 

user_data

data to pass to handler_cb

 

Returns

the handler ID from g_signal_connect()


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]

Parameters

msg

a SoupMessage

 

signal

signal to connect the handler to.

 

status_code

status code to match against

 

callback

the header handler

 

user_data

data to pass to handler_cb

 

Returns

the handler ID from g_signal_connect()


soup_message_set_flags ()

void
soup_message_set_flags (SoupMessage *msg,
                        SoupMessageFlags flags);

Sets the specified flags on msg .

Parameters

msg

a SoupMessage

 

flags

a set of SoupMessageFlags values

 

soup_message_get_flags ()

SoupMessageFlags
soup_message_get_flags (SoupMessage *msg);

Gets the flags on msg

Parameters

msg

a SoupMessage

 

Returns

the flags


soup_message_add_flags ()

void
soup_message_add_flags (SoupMessage *msg,
                        SoupMessageFlags flags);

Adds flags to the set of msg 's flags

Parameters

msg

a SoupMessage

 

flags

a set of SoupMessageFlags values

 

soup_message_remove_flags ()

void
soup_message_remove_flags (SoupMessage *msg,
                           SoupMessageFlags flags);

Removes flags from the set of msg 's flags

Parameters

msg

a SoupMessage

 

flags

a set of SoupMessageFlags values

 

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

Parameters

msg

a SoupMessage

 

flags

a set of SoupMessageFlags values

 

Returns

TRUE if flags are enabled in msg


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.

Parameters

msg

a SoupMessage

 

feature_type

the GType of a SoupSessionFeature

 

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

Parameters

msg

a SoupMessage

 

feature_type

the GType of a SoupSessionFeature

 

Returns

TRUE if feature is disabled, or FALSE otherwise.


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.

Parameters

msg

a SoupMessage

 

Returns

the priority of the message.


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.

Parameters

msg

a SoupMessage

 

priority

the SoupMessagePriority

 

soup_message_get_site_for_cookies ()

GUri *
soup_message_get_site_for_cookies (SoupMessage *msg);

Gets msg 's site for cookies GUri

Parameters

msg

a SoupMessage

 

Returns

the msg 's site for cookies GUri.

[transfer none]


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.

Parameters

msg

a SoupMessage

 

site_for_cookies

the GUri for the msg 's site for cookies.

[nullable]

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.

Parameters

msg

a SoupMessage

 

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.

Parameters

msg

a SoupMessage

 

is_top_level_navigation

if TRUE indicate the current request is a top-level navigation

 

soup_message_get_metrics ()

SoupMessageMetrics *
soup_message_get_metrics (SoupMessage *msg);

Get the SoupMessageMetrics of msg . If the flag SOUP_MESSAGE_COLLECT_METRICS is not enabled for msg this will return NULL.

Parameters

msg

The SoupMessage

 

Returns

a SoupMessageMetrics, or NULL.

[transfer none][nullable]

Types and Values

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.

Members

SOUP_HTTP_1_0

HTTP 1.0 (RFC 1945)

 

SOUP_HTTP_1_1

HTTP 1.1 (RFC 2616)

 

SOUP_HTTP_2_0

HTTP 2.0 (RFC 7540)

 

enum SoupMessageFlags

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

Members

SOUP_MESSAGE_NO_REDIRECT

The session should not follow redirect (3xx) responses received by this message.

 

SOUP_MESSAGE_NEW_CONNECTION

Requests that the message should be sent on a newly-created connection, not reusing an existing persistent connection. Note that messages with non-idempotent “method”s behave this way by default, unless SOUP_MESSAGE_IDEMPOTENT is set.

 

SOUP_MESSAGE_IDEMPOTENT

The message is considered idempotent, regardless its “method”, and allows reuse of existing idle connections, instead of always requiring a new one, unless SOUP_MESSAGE_NEW_CONNECTION is set.

 

SOUP_MESSAGE_DO_NOT_USE_AUTH_CACHE

The SoupAuthManager should not use the credentials cache for this message, neither to use cached credentials to automatically authenticate this message nor to cache the credentials after the message is successfully authenticated. This applies to both server and proxy authentication. Note that “authenticate” signal will be emitted, if you want to disable authentication for a message use soup_message_disable_feature() passing SOUP_TYPE_AUTH_MANAGER instead.

 

SOUP_MESSAGE_COLLECT_METRICS

Metrics will be collected for this message.

 

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.

Members

SOUP_MESSAGE_PRIORITY_VERY_LOW

The lowest priority, the messages with this priority will be the last ones to be attended.

 

SOUP_MESSAGE_PRIORITY_LOW

Use this for low priority messages, a SoupMessage with the default priority will be processed first.

 

SOUP_MESSAGE_PRIORITY_NORMAL

The default priotity, this is the priority assigned to the SoupMessage by default.

 

SOUP_MESSAGE_PRIORITY_HIGH

High priority, a SoupMessage with this priority will be processed before the ones with the default priority.

 

SOUP_MESSAGE_PRIORITY_VERY_HIGH

The highest priority, use this for very urgent SoupMessage as they will be the first ones to be attended.

 

Property Details

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

Default value: SOUP_HTTP_1_1


The “is-options-ping” property

  “is-options-ping”          gboolean

The SoupMessage is intended to be used to send OPTIONS * to a server. When set to TRUE, the path of “uri” will be ignored and “method” set to SOUP_METHOD_OPTIONS.

Owner: SoupMessage

Flags: Read / Write

Default value: FALSE


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 “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 “remote-address” property

  “remote-address”           GSocketAddress *

The remote GSocketAddress of the connection associated with the message

Owner: SoupMessage

Flags: Read


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-ciphersuite-name” property

  “tls-ciphersuite-name”     char *

The Name of TLS ciphersuite negotiated for this message connection.

Owner: SoupMessage

Flags: Read

Default value: NULL


The “tls-peer-certificate” property

  “tls-peer-certificate”     GTlsCertificate *

The peer's GTlsCertificate associated with the message

Owner: SoupMessage

Flags: Read


The “tls-peer-certificate-errors” property

  “tls-peer-certificate-errors” GTlsCertificateFlags

The verification errors on “tls-peer-certificate”

Owner: SoupMessage

Flags: Read


The “tls-protocol-version” property

  “tls-protocol-version”     GTlsProtocolVersion

The TLS protocol version negotiated for the message connection.

Owner: SoupMessage

Flags: Read

Default value: G_TLS_PROTOCOL_VERSION_UNKNOWN


The “uri” property

  “uri”                      GUri *

The message's Request-URI.

Owner: SoupMessage

Flags: Read / Write

Signal Details

The “accept-certificate” signal

gboolean
user_function (SoupMessage         *msg,
               GTlsCertificate     *tls_peer_certificate,
               GTlsCertificateFlags tls_peer_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 .

Parameters

msg

the message

 

tls_peer_certificate

the peer's GTlsCertificate

 

tls_peer_errors

the tls errors of tls_certificate

 

user_data

user data set when the signal handler was connected.

 

Returns

TRUE to accept the TLS certificate and stop other handlers from being invoked, or FALSE to propagate the event further.

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.

Parameters

msg

the message

 

auth

the SoupAuth to authenticate

 

retrying

TRUE if this is the second (or later) attempt

 

user_data

user data set when the signal handler was connected.

 

Returns

TRUE to stop other handlers from being invoked or FALSE to propagate the event further.

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.

Parameters

msg

the message

 

type

the content type that we got from sniffing

 

params

a GHashTable with the parameters.

[element-type utf8 utf8]

user_data

user data set when the signal handler was connected.

 

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

Parameters

msg

the message

 

user_data

user data set when the signal handler was connected.

 

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.

Parameters

msg

the message

 

user_data

user data set when the signal handler was connected.

 

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

Parameters

msg

the message

 

user_data

user data set when the signal handler was connected.

 

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.

Parameters

msg

the message

 

user_data

user data set when the signal handler was connected.

 

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.

Parameters

msg

the message

 

user_data

user data set when the signal handler was connected.

 

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.

Parameters

msg

the message

 

event

the network event

 

connection

the current state of the network connection

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “request-certificate” signal

gboolean
user_function (SoupMessage          *msg,
               GTlsClientConnection *tls_connection,
               gpointer              user_data)

Emitted during the msg 's connection TLS handshake when tls_connection requests a certificate from the client. You can set the client certificate by calling soup_message_set_tls_client_certificate() and returning TRUE. It's possible to handle the request asynchornously by returning TRUE and call soup_message_set_tls_client_certificate() later once the certificate is available. Note that this signal is not emitted if “tls-interaction” was set, or if soup_message_set_tls_client_certificate() was called before the connection TLS handshake started.

Parameters

msg

the message

 

tls_connection

the GTlsClientConnection

 

user_data

user data set when the signal handler was connected.

 

Returns

TRUE to handle the request, or FALSE to make the connection fail with G_TLS_ERROR_CERTIFICATE_REQUIRED.

Flags: Run Last


The “request-certificate-password” signal

gboolean
user_function (SoupMessage  *msg,
               GTlsPassword *tls_password,
               gpointer      user_data)

Emitted during the msg 's connection TLS handshake when tls_connection requests a certificate password from the client. You can set the certificate password on password , then call soup_message_tls_client_certificate_password_request_complete() and return TRUE to handle the signal synchronously. It's possible to handle the request asynchornously by calling g_object_ref() on password , then returning TRUE and call soup_message_tls_client_certificate_password_request_complete() later after setting the password on password . Note that this signal is not emitted if “tls-interaction” was set.

Parameters

msg

the message

 

tls_password

the GTlsPassword

 

user_data

user data set when the signal handler was connected.

 

Returns

TRUE to handle the request, or FALSE to make the connection fail with G_TLS_ERROR_CERTIFICATE_REQUIRED.

Flags: Run Last


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

Parameters

msg

the message

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “starting” signal

void
user_function (SoupMessage *msg,
               gpointer     user_data)

Emitted just before a message is sent.

Parameters

msg

the message

 

user_data

user data set when the signal handler was connected.

 

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.

Parameters

msg

the message

 

user_data

user data set when the signal handler was connected.

 

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.

Parameters

msg

the message

 

chunk_size

the number of bytes written

 

user_data

user data set when the signal handler was connected.

 

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.

Parameters

msg

the message

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

See Also

SoupMessageHeaders