SoupMessage

SoupMessage — An HTTP request and response.

Synopsis




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


Object Hierarchy


  GObject
   +----SoupMessage
         +----SoupServerMessage
         +----SoupSoapMessage

Signal Prototypes


"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);

Description

Details

struct SoupMessage

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

enum SoupMessageStatus

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

SOUP_MESSAGE_IS_STARTING()

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

enum SoupTransferEncoding

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

enum SoupOwnership

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.

SoupDataBuffer

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

SoupMessageCallbackFn ()

void        (*SoupMessageCallbackFn)        (SoupMessage *req,
                                             gpointer user_data);

A callback function used by many SoupMessage methods.

req : the SoupMessage in question
user_data : user data

soup_message_new ()

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

soup_message_new_from_uri ()

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

soup_message_set_request ()

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.

soup_message_set_response ()

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.

soup_message_add_header ()

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

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

soup_message_get_header_list ()

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.

soup_message_foreach_header ()

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

soup_message_remove_header ()

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

soup_message_clear_headers ()

void        soup_message_clear_headers      (GHashTable *hash);

Clears hash.

hash : a header table (the request_headers or response_headers field of a SoupMessage)

enum SoupHttpVersion

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)

soup_message_set_http_version ()

void        soup_message_set_http_version   (SoupMessage *msg,
                                             SoupHttpVersion version);

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

msg : a SoupMessage
version : the HTTP version

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.

msg : a SoupMessage
Returns : the HTTP version

soup_message_get_uri ()

const SoupUri* soup_message_get_uri         (SoupMessage *msg);

Gets msg's URI

msg : a SoupMessage
Returns : the URI msg is targeted for.

soup_message_set_uri ()

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

enum SoupMessageFlags

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.

soup_message_set_flags ()

void        soup_message_set_flags          (SoupMessage *msg,
                                             guint flags);

Sets the specified flags on msg.

msg : a SoupMessage
flags : a set of SoupMessageFlags values

soup_message_get_flags ()

guint       soup_message_get_flags          (SoupMessage *msg);

Gets the flags on msg

msg : a SoupMessage
Returns : the flags

soup_message_set_status ()

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

soup_message_set_status_full ()

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

soup_message_add_chunk ()

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

soup_message_add_final_chunk ()

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

soup_message_pop_chunk ()

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.

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.

msg : a SoupMessage
Returns : TRUE or FALSE.

enum SoupHandlerPhase

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.

soup_message_add_handler ()

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

soup_message_add_header_handler ()

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

soup_message_add_status_code_handler ()

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

soup_message_add_status_class_handler ()

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

soup_message_remove_handler ()

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

soup_message_send_request ()

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

soup_message_read_request ()

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

soup_message_io_pause ()

void        soup_message_io_pause           (SoupMessage *msg);

Pauses I/O on msg.

msg : a SoupMessage

soup_message_io_unpause ()

void        soup_message_io_unpause         (SoupMessage *msg);

Resumes I/O on msg.

msg : a SoupMessage

soup_message_io_stop ()

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

Signals

The "finished" signal

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.

The "got-body" signal

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.

The "got-chunk" signal

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.

The "got-headers" signal

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.

The "got-informational" signal

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.

The "restarted" signal

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.

The "wrote-body" signal

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.

The "wrote-chunk" signal

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.

The "wrote-headers" signal

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.

The "wrote-informational" signal

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.