Top | ![]() |
![]() |
![]() |
![]() |
GUri * | first-party | Read / Write |
SoupMessageFlags | flags | Read / Write |
SoupHTTPVersion | http-version | Read / Write |
gboolean | is-top-level-navigation | Read / Write |
char * | method | Read / Write |
gboolean | options-ping | Read / Write |
SoupMessagePriority | priority | Read / Write |
char * | reason-phrase | Read |
SoupMessageHeaders * | request-headers | Read |
SoupMessageHeaders * | response-headers | Read |
GUri * | site-for-cookies | Read / Write |
guint | status-code | Read |
GTlsCertificate * | tls-certificate | Read |
GTlsCertificateFlags | tls-certificate-errors | Read |
GUri * | uri | Read / Write |
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 |
void | restarted | Run First |
void | starting | Run First |
void | wrote-body | Run First |
void | wrote-body-data | Run First |
void | wrote-headers | Run First |
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.
SoupMessage * soup_message_new (const char *method
,const char *uri_string
);
Creates a new empty SoupMessage, which will connect to uri
SoupMessage * soup_message_new_from_uri (const char *method
,GUri *uri
);
Creates a new empty SoupMessage, which will connect to uri
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()
.
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] |
the new SoupMessage, or NULL
if uri_string
could not be parsed or method
is not "GET, "POST" or "PUT".
[transfer full][nullable]
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.
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).
msg |
the message |
|
content_type |
MIME Content-Type of the body, or |
[allow-none] |
stream |
a GInputStream to read the request body from. |
[allow-none] |
content_length |
the byte length of |
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).
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.
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.
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.
const char *
soup_message_get_method (SoupMessage *msg
);
Returns the method of this message.
SoupStatus
soup_message_get_status (SoupMessage *msg
);
Returns the set status of this message.
const char *
soup_message_get_reason_phrase (SoupMessage *msg
);
Returns the reason phrase for the status of this message.
SoupMessageHeaders *
soup_message_get_request_headers (SoupMessage *msg
);
Returns the headers sent with the request.
SoupMessageHeaders *
soup_message_get_response_headers (SoupMessage *msg
);
Returns the headers recieved with the response.
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.
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.
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.
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.
GUri *
soup_message_get_first_party (SoupMessage *msg
);
Gets msg
's first-party GUri
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]
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]
void soup_message_set_flags (SoupMessage *msg
,SoupMessageFlags flags
);
Sets the specified flags on msg
.
SoupMessageFlags
soup_message_get_flags (SoupMessage *msg
);
Gets the flags on msg
void soup_message_add_flags (SoupMessage *msg
,SoupMessageFlags flags
);
Adds flags
to the set of msg
's flags
void soup_message_remove_flags (SoupMessage *msg
,SoupMessageFlags flags
);
Removes flags
from the set of msg
's flags
gboolean soup_message_query_flags (SoupMessage *msg
,SoupMessageFlags flags
);
Queries if flags
are present in the set of msg
's flags
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.
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()
.
SoupMessagePriority
soup_message_get_priority (SoupMessage *msg
);
Retrieves the SoupMessagePriority. If not set this value defaults to SOUP_MESSAGE_PRIORITY_NORMAL.
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.
GUri *
soup_message_get_site_for_cookies (SoupMessage *msg
);
Gets msg
's site for cookies GUri
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.
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.
void soup_message_set_is_top_level_navigation (SoupMessage *msg
,gboolean is_top_level_navigation
);
See the same-site spec for more information.
msg |
||
is_top_level_navigation |
if |
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.
Various flags that can be set on a SoupMessage to alter its behavior.
The session should not follow redirect (3xx) responses received by this message. |
||
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. |
||
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. |
||
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
|
Priorities that can be set on a SoupMessage to instruct the message queue to process it before any other message with lower priority.
The lowest priority, the messages with this priority will be the last ones to be attended. |
||
Use this for low priority messages, a SoupMessage with the default priority will be processed first. |
||
The default priotity, this is the priority assigned to the SoupMessage by default. |
||
High priority, a SoupMessage with this priority will be processed before the ones with the default priority. |
||
The highest priority, use this for very urgent SoupMessage as they will be the first ones to be attended. |
“first-party”
property“first-party” GUri *
The GUri loaded in the application when the message was queued.
Owner: SoupMessage
Flags: Read / Write
“flags”
property“flags” SoupMessageFlags
Various message options.
Owner: SoupMessage
Flags: Read / Write
“http-version”
property“http-version” SoupHTTPVersion
The HTTP protocol version to use.
Owner: SoupMessage
Flags: Read / Write
Default value: SOUP_HTTP_1_1
“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
“method”
property “method” char *
The message's HTTP method.
Owner: SoupMessage
Flags: Read / Write
Default value: "GET"
“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
“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
“reason-phrase”
property “reason-phrase” char *
The HTTP response reason phrase.
Owner: SoupMessage
Flags: Read
Default value: NULL
“request-headers”
property“request-headers” SoupMessageHeaders *
The HTTP request headers.
Owner: SoupMessage
Flags: Read
“response-headers”
property“response-headers” SoupMessageHeaders *
The HTTP response headers.
Owner: SoupMessage
Flags: Read
“site-for-cookies”
property“site-for-cookies” GUri *
The URI for the site to compare cookies against.
Owner: SoupMessage
Flags: Read / Write
“status-code”
property“status-code” guint
The HTTP response status code.
Owner: SoupMessage
Flags: Read
Allowed values: <= 999
Default value: 0
“tls-certificate”
property“tls-certificate” GTlsCertificate *
The GTlsCertificate associated with the message
Owner: SoupMessage
Flags: Read
“tls-certificate-errors”
property“tls-certificate-errors” GTlsCertificateFlags
The verification errors on “tls-certificate”
Owner: SoupMessage
Flags: Read
“accept-certificate”
signalgboolean 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
.
msg |
the message |
|
tls_certificate |
the peer's GTlsCertificate |
|
tls_errors |
the tls errors of |
|
user_data |
user data set when the signal handler was connected. |
TRUE
to accept the TLS certificate and stop other
handlers from being invoked, or FALSE
to propagate the
event further.
Flags: Run Last
“authenticate”
signalgboolean 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
“content-sniffed”
signalvoid 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
.
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
“finished”
signalvoid user_function (SoupMessage *msg, gpointer user_data)
Emitted when all HTTP processing is finished for a message. (After “got_body”).
Flags: Run First
“got-body”
signalvoid 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
“got-headers”
signalvoid 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
“got-informational”
signalvoid 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
“hsts-enforced”
signalvoid 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
“network-event”
signalvoid 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.
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
“restarted”
signalvoid 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
“starting”
signalvoid user_function (SoupMessage *msg, gpointer user_data)
Emitted just before a message is sent.
Flags: Run First
“wrote-body”
signalvoid user_function (SoupMessage *msg, gpointer user_data)
Emitted immediately after writing the complete body for a message.
Flags: Run First
“wrote-body-data”
signalvoid user_function (SoupMessage *msg, guint chunk_size, gpointer user_data)
Emitted immediately after writing a portion of the message body to the network.
msg |
the message |
|
chunk_size |
the number of bytes written |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
“wrote-headers”
signalvoid user_function (SoupMessage *msg, gpointer user_data)
Emitted immediately after writing the request headers for a message.
Flags: Run First