SoupMessage

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