![]() |
![]() |
![]() |
libsoup Reference Manual | ![]() |
---|
SoupMessageSoupMessage — An HTTP request and response. |
struct SoupMessage; enum SoupMessageStatus; #define SOUP_MESSAGE_IS_STARTING (msg) enum SoupTransferEncoding; enum SoupOwnership; SoupDataBuffer; void (*SoupMessageCallbackFn) (SoupMessage *req, gpointer user_data); SoupMessage* soup_message_new (const char *method, const char *uri_string); SoupMessage* soup_message_new_from_uri (const char *method, const SoupUri *uri); void soup_message_set_request (SoupMessage *msg, const char *content_type, SoupOwnership req_owner, char *req_body, gulong req_length); void soup_message_set_response (SoupMessage *msg, const char *content_type, SoupOwnership resp_owner, char *resp_body, gulong resp_length); void soup_message_add_header (GHashTable *hash, const char *name, const char *value); const char* soup_message_get_header (GHashTable *hash, const char *name); const GSList* soup_message_get_header_list (GHashTable *hash, const char *name); void soup_message_foreach_header (GHashTable *hash, GHFunc func, gpointer user_data); void soup_message_remove_header (GHashTable *hash, const char *name); void soup_message_clear_headers (GHashTable *hash); enum SoupHttpVersion; void soup_message_set_http_version (SoupMessage *msg, SoupHttpVersion version); SoupHttpVersion soup_message_get_http_version (SoupMessage *msg); const SoupUri* soup_message_get_uri (SoupMessage *msg); void soup_message_set_uri (SoupMessage *msg, const SoupUri *uri); enum SoupMessageFlags; void soup_message_set_flags (SoupMessage *msg, guint flags); guint soup_message_get_flags (SoupMessage *msg); void soup_message_set_status (SoupMessage *msg, guint status_code); void soup_message_set_status_full (SoupMessage *msg, guint status_code, const char *reason_phrase); void soup_message_add_chunk (SoupMessage *msg, SoupOwnership owner, const char *body, guint length); void soup_message_add_final_chunk (SoupMessage *msg); SoupDataBuffer* soup_message_pop_chunk (SoupMessage *msg); gboolean soup_message_is_keepalive (SoupMessage *msg); enum SoupHandlerPhase; void soup_message_add_handler (SoupMessage *msg, SoupHandlerPhase phase, SoupMessageCallbackFn handler_cb, gpointer user_data); void soup_message_add_header_handler (SoupMessage *msg, const char *header, SoupHandlerPhase phase, SoupMessageCallbackFn handler_cb, gpointer user_data); void soup_message_add_status_code_handler (SoupMessage *msg, guint status_code, SoupHandlerPhase phase, SoupMessageCallbackFn handler_cb, gpointer user_data); void soup_message_add_status_class_handler (SoupMessage *msg, SoupStatusClass status_class, SoupHandlerPhase phase, SoupMessageCallbackFn handler_cb, gpointer user_data); void soup_message_remove_handler (SoupMessage *msg, SoupHandlerPhase phase, SoupMessageCallbackFn handler_cb, gpointer user_data); void soup_message_send_request (SoupMessage *req, SoupSocket *sock, gboolean is_via_proxy); void soup_message_read_request (SoupMessage *req, SoupSocket *sock); void soup_message_io_pause (SoupMessage *msg); void soup_message_io_unpause (SoupMessage *msg); void soup_message_io_stop (SoupMessage *msg);
GObject +----SoupMessage +----SoupServerMessage +----SoupSoapMessage +----SoupXmlrpcMessage
"finished" void user_function (SoupMessage *msg, gpointer user_data); "got-body" void user_function (SoupMessage *msg, gpointer user_data); "got-chunk" void user_function (SoupMessage *msg, gpointer user_data); "got-headers" void user_function (SoupMessage *msg, gpointer user_data); "got-informational" void user_function (SoupMessage *msg, gpointer user_data); "restarted" void user_function (SoupMessage *msg, gpointer user_data); "wrote-body" void user_function (SoupMessage *msg, gpointer user_data); "wrote-chunk" void user_function (SoupMessage *msg, gpointer user_data); "wrote-headers" void user_function (SoupMessage *msg, gpointer user_data); "wrote-informational" void user_function (SoupMessage *msg, gpointer user_data);
struct SoupMessage { const char *method; guint status_code; const char *reason_phrase; SoupDataBuffer request; GHashTable *request_headers; SoupDataBuffer response; GHashTable *response_headers; SoupMessageStatus status; };
Represents an HTTP message being sent or received.
const char *method ; |
the HTTP method |
guint status_code ; |
the HTTP status code |
const char *reason_phrase ; |
the status phrase associated with status_code
|
SoupDataBuffer request ; |
the request buffer |
GHashTable *request_headers ; |
the request headers |
SoupDataBuffer response ; |
the response buffer |
GHashTable *response_headers ; |
the response headers |
SoupMessageStatus status ; |
the processing status of the message |
typedef enum { SOUP_MESSAGE_STATUS_IDLE, SOUP_MESSAGE_STATUS_QUEUED, SOUP_MESSAGE_STATUS_CONNECTING, SOUP_MESSAGE_STATUS_RUNNING, SOUP_MESSAGE_STATUS_FINISHED } SoupMessageStatus;
Enum indicating the lifecycle of a SoupMessage.
SOUP_MESSAGE_STATUS_IDLE |
The message has not yet been queued. |
SOUP_MESSAGE_STATUS_QUEUED |
The message has been queued, but is waiting for a connection to be available. |
SOUP_MESSAGE_STATUS_CONNECTING |
The message is waiting for a specific connection to finish connecting. |
SOUP_MESSAGE_STATUS_RUNNING |
The message is being processed. |
SOUP_MESSAGE_STATUS_FINISHED |
The message is complete (request and response both processed). |
#define SOUP_MESSAGE_IS_STARTING(msg) (msg->status == SOUP_MESSAGE_STATUS_QUEUED || msg->status == SOUP_MESSAGE_STATUS_CONNECTING)
Tests if msg
is in a "starting" state, waiting to be sent. (More
commonly used to test if a message has been requeued after its
first attempt.)
msg : |
a SoupMessage |
Returns : | TRUE if msg is waiting to be sent.
|
typedef enum { SOUP_TRANSFER_UNKNOWN = 0, SOUP_TRANSFER_CHUNKED, SOUP_TRANSFER_CONTENT_LENGTH } SoupTransferEncoding;
How the length of a request or response is to be encoded.
SOUP_TRANSFER_UNKNOWN |
HTTP 1.0-style (content ends when the connection is closed) |
SOUP_TRANSFER_CHUNKED |
chunked encoding (only supported for response) |
SOUP_TRANSFER_CONTENT_LENGTH |
Content-Length |
typedef enum { SOUP_BUFFER_SYSTEM_OWNED = 0, SOUP_BUFFER_USER_OWNED, SOUP_BUFFER_STATIC } SoupOwnership;
Used by SoupDataBuffer (and several functions) to indicate the ownership of a buffer.
SOUP_BUFFER_SYSTEM_OWNED |
The data is owned by soup and it can free it when it is done with it. |
SOUP_BUFFER_USER_OWNED |
The data is owned by the user, who is responsible for freeing it at the right point |
SOUP_BUFFER_STATIC |
The data should not be freed. |
typedef struct { SoupOwnership owner; char *body; guint length; } SoupDataBuffer;
A data buffer used in several places.
SoupOwnership owner ; |
the ownership of the data |
char *body ; |
the data itself |
guint length ; |
length of body
|
void (*SoupMessageCallbackFn) (SoupMessage *req, gpointer user_data);
A callback function used by many SoupMessage methods.
req : |
the SoupMessage in question |
user_data : |
user data |
SoupMessage* soup_message_new (const char *method, const char *uri_string);
Creates a new empty SoupMessage, which will connect to uri
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).
|
SoupMessage* soup_message_new_from_uri (const char *method, const SoupUri *uri);
Creates a new empty SoupMessage, which will connect to uri
method : |
the HTTP method for the created request |
uri : |
the destination endpoint (as a SoupUri) |
Returns : | the new SoupMessage |
void soup_message_set_request (SoupMessage *msg, const char *content_type, SoupOwnership req_owner, char *req_body, gulong req_length);
Convenience function to set the request body of a SoupMessage
msg : |
the message |
content_type : |
MIME Content-Type of the body |
req_owner : |
the SoupOwnership of the passed data buffer. |
req_body : |
a data buffer containing the body of the message request. |
req_length : |
the byte length of req_body .
|
void soup_message_set_response (SoupMessage *msg, const char *content_type, SoupOwnership resp_owner, char *resp_body, gulong resp_length);
Convenience function to set the response body of a SoupMessage
msg : |
the message |
content_type : |
MIME Content-Type of the body |
resp_owner : |
the SoupOwnership of the passed data buffer. |
resp_body : |
a data buffer containing the body of the message response. |
resp_length : |
the byte length of resp_body .
|
void soup_message_add_header (GHashTable *hash, const char *name, const char *value);
Adds a header with name name
and value value
to hash
. If there
was already a header with name name
, this one does not replace it,
it is merely added to it.
hash : |
a header table (the request_headers or response_headers
field of a SoupMessage)
|
name : |
the header name to add |
value : |
the value of the new header |
const char* soup_message_get_header (GHashTable *hash, const char *name);
Finds the first header in hash
with name name
.
hash : |
a header table (the request_headers or response_headers
field of a SoupMessage)
|
name : |
header name. |
Returns : | the header's value or NULL if not found.
|
const GSList* soup_message_get_header_list (GHashTable *hash, const char *name);
Finds all headers in hash
with name name
.
hash : |
a header table (the request_headers or response_headers
field of a SoupMessage)
|
name : |
header name. |
Returns : | a (possibly empty) list of values of headers with
name name . The caller should not modify or free this list.
|
void soup_message_foreach_header (GHashTable *hash, GHFunc func, gpointer user_data);
Calls func
once for each header value in hash
. (If there are
headers will multiple values, func
will be called once on each
value.)
hash : |
a header table (the request_headers or response_headers
field of a SoupMessage)
|
func : |
callback function to run for each header |
user_data : |
data to pass to func
|
void soup_message_remove_header (GHashTable *hash, const char *name);
Removes name
from hash
. If there are multiple values for name
,
they are all removed.
hash : |
a header table (the request_headers or response_headers
field of a SoupMessage)
|
name : |
the header name to remove |
void soup_message_clear_headers (GHashTable *hash);
Clears hash
.
hash : |
a header table (the request_headers or response_headers
field of a SoupMessage)
|
typedef enum { SOUP_HTTP_1_0 = 0, SOUP_HTTP_1_1 = 1 } SoupHttpVersion;
Indicates the HTTP protocol version being used.
SOUP_HTTP_1_0 |
HTTP 1.0 (RFC 1945) |
SOUP_HTTP_1_1 |
HTTP 1.1 (RFC 2616) |
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.
msg : |
a SoupMessage |
version : |
the 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.
msg : |
a SoupMessage |
Returns : | the HTTP version |
const SoupUri* soup_message_get_uri (SoupMessage *msg);
Gets msg
's URI
msg : |
a SoupMessage |
Returns : | the URI msg is targeted for.
|
void soup_message_set_uri (SoupMessage *msg, const SoupUri *uri);
Changes the URI that msg
is directed to (generally as a result
of a redirect).
msg : |
a SoupMessage |
uri : |
the new SoupUri |
typedef enum { SOUP_MESSAGE_NO_REDIRECT = (1 << 1), SOUP_MESSAGE_OVERWRITE_CHUNKS = (1 << 3), SOUP_MESSAGE_EXPECT_CONTINUE = (1 << 4) } SoupMessageFlags;
Various flags that can be set on a SoupMessage to alter its behavior.
SOUP_MESSAGE_NO_REDIRECT |
The session should not follow redirect (3xx) responses received by this message. |
SOUP_MESSAGE_OVERWRITE_CHUNKS |
Rather than building up the
response body in response , each new chunk should overwrite the
previous one. (This can be used if you are connecting to the
got_chunk signal or have installed a SOUP_MESSAGE_BODY_CHUNK
handler.
|
SOUP_MESSAGE_EXPECT_CONTINUE |
This will cause an "Expect: 100-continue" header to be added to the outgoing request, giving the server the opportunity to reject the message (eg, with a 401 Unauthorized) before the full request body is sent. |
void soup_message_set_flags (SoupMessage *msg, guint flags);
Sets the specified flags on msg
.
msg : |
a SoupMessage |
flags : |
a set of SoupMessageFlags values |
guint soup_message_get_flags (SoupMessage *msg);
Gets the flags on msg
msg : |
a SoupMessage |
Returns : | the flags |
void soup_message_set_status (SoupMessage *msg, guint status_code);
Sets msg
's status code to status_code
. If status_code
is a
known value, it will also set msg
's reason_phrase.
msg : |
a SoupMessage |
status_code : |
an HTTP status code |
void soup_message_set_status_full (SoupMessage *msg, guint status_code, const char *reason_phrase);
Sets msg
's status code and reason phrase.
msg : |
a SoupMessage |
status_code : |
an HTTP status code |
reason_phrase : |
a description of the status |
void soup_message_add_chunk (SoupMessage *msg, SoupOwnership owner, const char *body, guint length);
Adds a chunk of response data to body
. (Note that currently
there is no way to send a request using chunked encoding.)
msg : |
a SoupMessage |
owner : |
the ownership of body
|
body : |
body data |
length : |
length of body
|
void soup_message_add_final_chunk (SoupMessage *msg);
Adds a final, empty chunk of response data to body
. This must
be called after adding the last real chunk, to indicate that
there is no more data.
msg : |
a SoupMessage |
SoupDataBuffer* soup_message_pop_chunk (SoupMessage *msg);
Pops a chunk of response data from msg
's chunk list. The caller
must free chunk
itself, and must handle the data in chunk
according to its ownership
.
msg : |
a SoupMessage |
Returns : | the chunk, or NULL if there are no chunks left.
|
gboolean soup_message_is_keepalive (SoupMessage *msg);
Determines whether or not msg
's connection can be kept alive for
further requests after processing msg
.
msg : |
a SoupMessage |
Returns : | TRUE or FALSE .
|
typedef enum { SOUP_HANDLER_POST_REQUEST = 1, SOUP_HANDLER_PRE_BODY, SOUP_HANDLER_BODY_CHUNK, SOUP_HANDLER_POST_BODY } SoupHandlerPhase;
Indicates when a handler added with soup_message_add_handler()
or
the like will be run.
SOUP_HANDLER_POST_REQUEST |
The handler should run immediately after sending the request body |
SOUP_HANDLER_PRE_BODY |
The handler should run before reading the response body (after reading the headers). |
SOUP_HANDLER_BODY_CHUNK |
The handler should run after every body
chunk is read. (See also SOUP_MESSAGE_OVERWRITE_CHUNKS .)
|
SOUP_HANDLER_POST_BODY |
The handler should run after the entire message body has been read. |
void soup_message_add_handler (SoupMessage *msg, SoupHandlerPhase phase, SoupMessageCallbackFn handler_cb, gpointer user_data);
Adds a handler to msg
for all messages
msg : |
a SoupMessage |
phase : |
processing phase to run the handler in |
handler_cb : |
the handler |
user_data : |
data to pass to handler_cb
|
void soup_message_add_header_handler (SoupMessage *msg, const char *header, SoupHandlerPhase phase, SoupMessageCallbackFn handler_cb, gpointer user_data);
Adds a handler to msg
for messages containing the given response
header.
msg : |
a SoupMessage |
header : |
HTTP response header to match against |
phase : |
processing phase to run the handler in |
handler_cb : |
the handler |
user_data : |
data to pass to handler_cb
|
void soup_message_add_status_code_handler (SoupMessage *msg, guint status_code, SoupHandlerPhase phase, SoupMessageCallbackFn handler_cb, gpointer user_data);
Adds a handler to msg
for messages receiving the given status
code.
msg : |
a SoupMessage |
status_code : |
HTTP status code to match against |
phase : |
processing phase to run the handler in |
handler_cb : |
the handler |
user_data : |
data to pass to handler_cb
|
void soup_message_add_status_class_handler (SoupMessage *msg, SoupStatusClass status_class, SoupHandlerPhase phase, SoupMessageCallbackFn handler_cb, gpointer user_data);
Adds a handler to msg
for messages receiving a status code in
the given class.
msg : |
a SoupMessage |
status_class : |
HTTP status code class to match against |
phase : |
processing phase to run the handler in |
handler_cb : |
the handler |
user_data : |
data to pass to handler_cb
|
void soup_message_remove_handler (SoupMessage *msg, SoupHandlerPhase phase, SoupMessageCallbackFn handler_cb, gpointer user_data);
Removes all matching handlers from msg
msg : |
a SoupMessage |
phase : |
processing phase to run the handler in |
handler_cb : |
the handler |
user_data : |
data to pass to handler_cb
|
void soup_message_send_request (SoupMessage *req, SoupSocket *sock, gboolean is_via_proxy);
Begins the process of sending msg
across sock
. (If sock
is
synchronous, then soup_message_send_request()
won't return until
the response has been received.)
req : |
a SoupMessage |
sock : |
the SoupSocket to send req on
|
is_via_proxy : |
TRUE if sock is a connection to a proxy server
rather than a direct connection to the desired HTTP server
|
void soup_message_read_request (SoupMessage *req, SoupSocket *sock);
Begins the process of receiving a request from sock
into req
.
req : |
an empty SoupServerMessage |
sock : |
socket to receive the request on |
void soup_message_io_pause (SoupMessage *msg);
Pauses I/O on msg
.
msg : |
a SoupMessage |
void soup_message_io_unpause (SoupMessage *msg);
Resumes I/O on msg
.
msg : |
a SoupMessage |
void soup_message_io_stop (SoupMessage *msg);
Immediately stops I/O on msg; if the connection would be left in an inconsistent state, it will be closed.
msg : |
a SoupMessage |
void user_function (SoupMessage *msg, gpointer user_data);
Emitted when all HTTP processing is finished for a message. (After read-body for client-side code, or after wrote-body for server-side code.)
msg : |
the message |
user_data : |
user data set when the signal handler was connected. |
void user_function (SoupMessage *msg, gpointer user_data);
Emitted after receiving the complete message body.
msg : |
the message |
user_data : |
user data set when the signal handler was connected. |
void user_function (SoupMessage *msg, gpointer user_data);
Emitted after receiving a chunk of a message body. Note that "chunk" in this context means any subpiece of the body, not necessarily the specific HTTP 1.1 chunks sent by the other side.
msg : |
the message |
user_data : |
user data set when the signal handler was connected. |
void user_function (SoupMessage *msg, gpointer user_data);
Emitted after receiving all message headers for a message.
msg : |
the message |
user_data : |
user data set when the signal handler was connected. |
void user_function (SoupMessage *msg, gpointer user_data);
Emitted after receiving a 1xx (Informational) response for a message.
msg : |
the message |
user_data : |
user data set when the signal handler was connected. |
void user_function (SoupMessage *msg, gpointer user_data);
Emitted when a message is about to be re-queued.
msg : |
the message |
user_data : |
user data set when the signal handler was connected. |
void user_function (SoupMessage *msg, gpointer user_data);
Emitted immediately after writing the complete body for a message.
msg : |
the message |
user_data : |
user data set when the signal handler was connected. |
void user_function (SoupMessage *msg, gpointer user_data);
Emitted immediately after writing a body chunk for a message. (This is
msg : |
the message |
user_data : |
user data set when the signal handler was connected. |
void user_function (SoupMessage *msg, gpointer user_data);
Emitted immediately after writing the headers for a message.
msg : |
the message |
user_data : |
user data set when the signal handler was connected. |
void user_function (SoupMessage *msg, gpointer user_data);
Emitted immediately after writing a 1xx (Informational) response for a message.
msg : |
the message |
user_data : |
user data set when the signal handler was connected. |
<< SoupConnectionNTLM | SoupMessageFilter >> |