SoupMessage 3 LIBSOUP Library
SoupMessage

## Synopsis

    enum        SoupMessageStatus;
    #define     SOUP_MESSAGE_IS_STARTING        (msg)
    enum        SoupTransferEncoding;
    enum        SoupOwnership;
    struct      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);
    gboolean    soup_message_is_keepalive       (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);
    enum        SoupHandlerPhase;
    void        soup_message_add_handler        (SoupMessage *msg,
                                                 SoupHandlerPhase type,
                                                 SoupMessageCallbackFn handler_cb,
                                                 gpointer user_data);
    void        soup_message_add_header_handler (SoupMessage *msg,
                                                 const char *header,
                                                 SoupHandlerPhase type,
                                                 SoupMessageCallbackFn,
                                                 gpointer user_data);
    void        soup_message_add_status_code_handler
                                                (SoupMessage *msg,
                                                 guint status_code,
                                                 SoupHandlerPhase type,
                                                 SoupMessageCallbackFn,
                                                 gpointer user_data);
    void        soup_message_add_status_class_handler
                                                (SoupMessage *msg,
                                                 SoupStatusClass status_class,
                                                 SoupHandlerPhase type,
                                                 SoupMessageCallbackFn,
                                                 gpointer user_data);
    void        soup_message_remove_handler     (SoupMessage *msg,
                                                 SoupHandlerPhase type,
                                                 SoupMessageCallbackFn,
                                                 gpointer user_data);
    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);
    void        soup_message_send_request       (SoupMessage *req,
                                                 SoupSocket *sock,
                                                 gboolean 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_wrote_informational
                                                (SoupMessage *msg);
    void        soup_message_wrote_headers      (SoupMessage *msg);
    void        soup_message_wrote_chunk        (SoupMessage *msg);
    void        soup_message_wrote_body         (SoupMessage *msg);
    void        soup_message_got_informational  (SoupMessage *msg);
    void        soup_message_got_headers        (SoupMessage *msg);
    void        soup_message_got_chunk          (SoupMessage *msg);
    void        soup_message_got_body           (SoupMessage *msg);
    void        soup_message_finished           (SoupMessage *msg);

## Description

## Details

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

SoupMessageStatus

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

SOUP_MESSAGE_IS_STARTING

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

SoupTransferEncoding

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

SoupOwnership

### struct SoupDataBuffer

    struct SoupDataBuffer {

    	SoupOwnership  owner;
    	char          *body;
    	guint          length;
    };

A data buffer used in several places.

SoupOwnership owner

  the ownership of the data

char *body

  the data itself

guint length

  length of body

SoupDataBuffer

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

SoupMessageCallbackFn

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

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

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

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

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

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

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

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

soup_message_clear_headers

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

SoupHttpVersion

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

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

soup_message_is_keepalive

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

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

soup_message_set_uri

### enum SoupMessageFlags

    typedef enum {
    	/*
    	 * SOUP_MESSAGE_NO_REDIRECT:
    	 * Do not follow redirection responses.
    	 */
    	SOUP_MESSAGE_NO_REDIRECT      = (1 << 1),

    	/*
    	 * SOUP_MESSAGE_OVERWRITE_CHUNKS:
    	 * Downloaded data chunks should not be stored in the response
    	 * data buffer.  Instead only send data to SOUP_HANDLER_BODY_CHUNK
    	 * handlers, then truncate the data buffer.
    	 *
    	 * Useful when the response is expected to be very large, and
    	 * storage in memory is not desired.
    	 */
    	SOUP_MESSAGE_OVERWRITE_CHUNKS = (1 << 3),

    	/*
    	 * SOUP_MESSAGE_EXPECT_CONTINUE: The message includes an
    	 * "Expect: 100-continue" header, and we should not send the
    	 * body until the Continue response has been received. (This
    	 * is automatically set if there is an "Expect: 100-continue"
    	 * header.)
    	 */
    	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.

SoupMessageFlags

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

### soup_message_get_flags ()

    guint       soup_message_get_flags          (SoupMessage *msg);

Gets the flags on msg

msg :

  a SoupMessage

Returns :

  the flags

soup_message_get_flags

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

SoupHandlerPhase

### soup_message_add_handler ()

    void        soup_message_add_handler        (SoupMessage *msg,
                                                 SoupHandlerPhase type,
                                                 SoupMessageCallbackFn handler_cb,
                                                 gpointer user_data);

Adds a handler to msg for all messages

msg :

  a SoupMessage

type :

handler_cb :

  the handler

user_data :

  data to pass to handler_cb

soup_message_add_handler

### soup_message_add_header_handler ()

    void        soup_message_add_header_handler (SoupMessage *msg,
                                                 const char *header,
                                                 SoupHandlerPhase type,
                                                 SoupMessageCallbackFn,
                                                 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

type :

Param4 :

user_data :

  data to pass to handler_cb

soup_message_add_header_handler

### soup_message_add_status_code_handler ()

    void        soup_message_add_status_code_handler
                                                (SoupMessage *msg,
                                                 guint status_code,
                                                 SoupHandlerPhase type,
                                                 SoupMessageCallbackFn,
                                                 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

type :

Param4 :

user_data :

  data to pass to handler_cb

soup_message_add_status_code_handler

### soup_message_add_status_class_handler ()

    void        soup_message_add_status_class_handler
                                                (SoupMessage *msg,
                                                 SoupStatusClass status_class,
                                                 SoupHandlerPhase type,
                                                 SoupMessageCallbackFn,
                                                 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

type :

Param4 :

user_data :

  data to pass to handler_cb

soup_message_add_status_class_handler

### soup_message_remove_handler ()

    void        soup_message_remove_handler     (SoupMessage *msg,
                                                 SoupHandlerPhase type,
                                                 SoupMessageCallbackFn,
                                                 gpointer user_data);

Removes all matching handlers from msg

msg :

  a SoupMessage

type :

Param3 :

user_data :

  data to pass to handler_cb

soup_message_remove_handler

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

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

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

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

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

### soup_message_send_request ()

    void        soup_message_send_request       (SoupMessage *req,
                                                 SoupSocket *sock,
                                                 gboolean 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

via_proxy :

soup_message_send_request

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

### soup_message_io_pause ()

    void        soup_message_io_pause           (SoupMessage *msg);

Pauses I/O on msg.

msg :

  a SoupMessage

soup_message_io_pause

### soup_message_io_unpause ()

    void        soup_message_io_unpause         (SoupMessage *msg);

Resumes I/O on msg.

msg :

  a SoupMessage

soup_message_io_unpause

### soup_message_wrote_informational ()

    void        soup_message_wrote_informational
                                                (SoupMessage *msg);

Emits the `wrote_informational` signal, indicating that the IO layer finished writing an informational (1xx) response for msg.

msg :

  a SoupMessage

soup_message_wrote_informational

### soup_message_wrote_headers ()

    void        soup_message_wrote_headers      (SoupMessage *msg);

Emits the `wrote_headers` signal, indicating that the IO layer finished writing the (non-informational) headers for msg.

msg :

  a SoupMessage

soup_message_wrote_headers

### soup_message_wrote_chunk ()

    void        soup_message_wrote_chunk        (SoupMessage *msg);

Emits the `wrote_chunk` signal, indicating that the IO layer finished writing a chunk of msg's body.

msg :

  a SoupMessage

soup_message_wrote_chunk

### soup_message_wrote_body ()

    void        soup_message_wrote_body         (SoupMessage *msg);

Emits the `wrote_body` signal, indicating that the IO layer finished writing the body for msg.

msg :

  a SoupMessage

soup_message_wrote_body

### soup_message_got_informational ()

    void        soup_message_got_informational  (SoupMessage *msg);

Emits the `got_informational` signal, indicating that the IO layer read a complete informational (1xx) response for msg.

msg :

  a SoupMessage

soup_message_got_informational

### soup_message_got_headers ()

    void        soup_message_got_headers        (SoupMessage *msg);

Emits the `got_headers` signal, indicating that the IO layer finished reading the (non-informational) headers for msg.

msg :

  a SoupMessage

soup_message_got_headers

### soup_message_got_chunk ()

    void        soup_message_got_chunk          (SoupMessage *msg);

Emits the `got_chunk` signal, indicating that the IO layer finished reading a chunk of msg's body.

msg :

  a SoupMessage

soup_message_got_chunk

### soup_message_got_body ()

    void        soup_message_got_body           (SoupMessage *msg);

Emits the `got_body` signal, indicating that the IO layer finished reading the body for msg.

msg :

  a SoupMessage

soup_message_got_body

### soup_message_finished ()

    void        soup_message_finished           (SoupMessage *msg);

Emits the `finished` signal, indicating that msg has been completely processed.

msg :

  a SoupMessage

soup_message_finished