SoupMessage: libsoup Reference Manual

## 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

GUri * | first-party | Read / Write
SoupMessageFlags | flags | Read / Write
SoupHTTPVersion | http-version | Read
gboolean | is-options-ping | Read / Write
gboolean | is-top-level-navigation | Read / Write
char * | method | Read / Write
SoupMessagePriority | priority | Read / Write
char * | reason-phrase | Read
GSocketAddress * | remote-address | Read
SoupMessageHeaders * | request-headers | Read
SoupMessageHeaders * | response-headers | Read
GUri * | site-for-cookies | Read / Write
guint | status-code | Read
char * | tls-ciphersuite-name | Read
GTlsCertificate * | tls-peer-certificate | Read
GTlsCertificateFlags | tls-peer-certificate-errors | Read
GTlsProtocolVersion | tls-protocol-version | Read
GUri * | uri | Read / Write

## Signals

gboolean | accept-certificate | Run Last
gboolean | authenticate | Run Last
void | content-sniffed | Run First
void | finished | Run First
void | got-body | Run First
void | got-headers | Run First
void | got-informational | Run First
void | hsts-enforced | Run Last
void | network-event | Run First
gboolean | request-certificate | Run Last
gboolean | request-certificate-password | Run Last
void | restarted | Run First
void | starting | Run First
void | wrote-body | Run First
void | wrote-body-data | Run First
void | wrote-headers | Run First

## Types and Values

| SoupMessage
enum | SoupHTTPVersion
enum | SoupMessageFlags
enum | SoupMessagePriority

## 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

the phrase.

[nullable]

### 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 |

#### Returns

a GTlsProtocolVersion

### 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