## SoupMessage

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;

### SOUP_MESSAGE_IS_STARTING()

    #define SOUP_MESSAGE_IS_STARTING(msg) (msg->status == SOUP_MESSAGE_STATUS_QUEUED || msg->status == SOUP_MESSAGE_STATUS_CONNECTING)

`msg` : |

### enum SoupTransferEncoding

    typedef enum {
    	SOUP_TRANSFER_UNKNOWN = 0,
    	SOUP_TRANSFER_CHUNKED,
    	SOUP_TRANSFER_CONTENT_LENGTH
    } SoupTransferEncoding;

### enum SoupOwnership

    typedef enum {
    	SOUP_BUFFER_SYSTEM_OWNED = 0,
    	SOUP_BUFFER_USER_OWNED,
    	SOUP_BUFFER_STATIC
    } SoupOwnership;

### struct SoupDataBuffer

    struct SoupDataBuffer {

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

### SoupMessageCallbackFn ()

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

`req` : |
`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);

`hash` : |
`name` : |
`value` : |

### soup_message_get_header ()

    const char* soup_message_get_header         (GHashTable *hash,
                                                 const char *name);

Lookup the first transport header in `hash` with a key equal to `name`.

`hash` : | a header hash table
`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);

Lookup the all transport request headers in `hash` with a key equal to `name`.

`hash` : | a header hash table
`name` : | header name.
Returns : | a const pointer to a GSList of header values or `NULL` if not found.

### soup_message_foreach_header ()

    void        soup_message_foreach_header     (GHashTable *hash,
                                                 GHFunc func,
                                                 gpointer user_data);

`hash` : |
`func` : |
`user_data` : |

### soup_message_remove_header ()

    void        soup_message_remove_header      (GHashTable *hash,
                                                 const char *name);

`hash` : |
`name` : |

### soup_message_clear_headers ()

    void        soup_message_clear_headers      (GHashTable *hash);

`hash` : |

### enum SoupHttpVersion

    typedef enum {
    	SOUP_HTTP_1_0 = 0,
    	SOUP_HTTP_1_1 = 1
    } SoupHttpVersion;

### soup_message_set_http_version ()

    void        soup_message_set_http_version   (SoupMessage *msg,
                                                 SoupHttpVersion version);

`msg` : |
`version` : |

### soup_message_get_http_version ()

    SoupHttpVersion soup_message_get_http_version
                                                (SoupMessage *msg);

`msg` : |
Returns : |

### soup_message_is_keepalive ()

    gboolean    soup_message_is_keepalive       (SoupMessage *msg);

`msg` : |
Returns : |

### soup_message_get_uri ()

    const SoupUri* soup_message_get_uri         (SoupMessage *msg);

`msg` : |
Returns : |

### soup_message_set_uri ()

    void        soup_message_set_uri            (SoupMessage *msg,
                                                 const SoupUri *uri);

`msg` : |
`uri` : |

### enum SoupMessageFlags

    typedef enum {
    	/*
    	 * SOUP_MESSAGE_NO_PIPELINE:
    	 * Use a currently unused connection or establish a new
    	 * connection when issuing this request.
    	 */
    	SOUP_MESSAGE_NO_PIPELINE      = (1 << 0),

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

    	/*
    	 * SOUP_MESSAGE_NO_COOKIE:
    	 * Do not send cookie information with request, and do not
    	 * store cookie information from the response.
    	 */
    	SOUP_MESSAGE_NO_COOKIE        = (1 << 2),

    	/*
    	 * 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;

### soup_message_set_flags ()

    void        soup_message_set_flags          (SoupMessage *msg,
                                                 guint flags);

`msg` : |
`flags` : |

### soup_message_get_flags ()

    guint       soup_message_get_flags          (SoupMessage *msg);

`msg` : |
Returns : |

### enum SoupHandlerPhase

    typedef enum {
    	SOUP_HANDLER_POST_REQUEST = 1,
    	SOUP_HANDLER_PRE_BODY,
    	SOUP_HANDLER_BODY_CHUNK,
    	SOUP_HANDLER_POST_BODY
    } SoupHandlerPhase;

### soup_message_add_handler ()

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

`msg` : |
`type` : |
`handler_cb` : |
`user_data` : |

### soup_message_add_header_handler ()

    void        soup_message_add_header_handler (SoupMessage *msg,
                                                 const char *header,
                                                 SoupHandlerPhase type,
                                                 SoupMessageCallbackFn,
                                                 gpointer user_data);

`msg` : |
`header` : |
`type` : |
`Param4` : |
`user_data` : |

### soup_message_add_status_code_handler ()

    void        soup_message_add_status_code_handler
                                                (SoupMessage *msg,
                                                 guint status_code,
                                                 SoupHandlerPhase type,
                                                 SoupMessageCallbackFn,
                                                 gpointer user_data);

`msg` : |
`status_code` : |
`type` : |
`Param4` : |
`user_data` : |

### soup_message_add_status_class_handler ()

    void        soup_message_add_status_class_handler
                                                (SoupMessage *msg,
                                                 SoupStatusClass status_class,
                                                 SoupHandlerPhase type,
                                                 SoupMessageCallbackFn,
                                                 gpointer user_data);

`msg` : |
`status_class` : |
`type` : |
`Param4` : |
`user_data` : |

### soup_message_remove_handler ()

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

`msg` : |
`type` : |
`Param3` : |
`user_data` : |

### soup_message_set_status ()

    void        soup_message_set_status         (SoupMessage *msg,
                                                 guint status_code);

`msg` : |
`status_code` : |

### soup_message_set_status_full ()

    void        soup_message_set_status_full    (SoupMessage *msg,
                                                 guint status_code,
                                                 const char *reason_phrase);

`msg` : |
`status_code` : |
`reason_phrase` : |

### soup_message_add_chunk ()

    void        soup_message_add_chunk          (SoupMessage *msg,
                                                 SoupOwnership owner,
                                                 const char *body,
                                                 guint length);

`msg` : |
`owner` : |
`body` : |
`length` : |

### soup_message_add_final_chunk ()

    void        soup_message_add_final_chunk    (SoupMessage *msg);

`msg` : |

### soup_message_pop_chunk ()

    SoupDataBuffer* soup_message_pop_chunk      (SoupMessage *msg);

`msg` : |
Returns : |

### soup_message_send_request ()

    void        soup_message_send_request       (SoupMessage *req,
                                                 SoupSocket *sock,
                                                 gboolean via_proxy);

`req` : |
`sock` : |
`via_proxy` : |

### soup_message_read_request ()

    void        soup_message_read_request       (SoupMessage *req,
                                                 SoupSocket *sock);

`req` : |
`sock` : |

### soup_message_io_pause ()

    void        soup_message_io_pause           (SoupMessage *msg);

`msg` : |

### soup_message_io_unpause ()

    void        soup_message_io_unpause         (SoupMessage *msg);

`msg` : |

### soup_message_wrote_informational ()

    void        soup_message_wrote_informational
                                                (SoupMessage *msg);

`msg` : |

### soup_message_wrote_headers ()

    void        soup_message_wrote_headers      (SoupMessage *msg);

`msg` : |

### soup_message_wrote_chunk ()

    void        soup_message_wrote_chunk        (SoupMessage *msg);

`msg` : |

### soup_message_wrote_body ()

    void        soup_message_wrote_body         (SoupMessage *msg);

`msg` : |

### soup_message_got_informational ()

    void        soup_message_got_informational  (SoupMessage *msg);

`msg` : |

### soup_message_got_headers ()

    void        soup_message_got_headers        (SoupMessage *msg);

`msg` : |

### soup_message_got_chunk ()

    void        soup_message_got_chunk          (SoupMessage *msg);

`msg` : |

### soup_message_got_body ()

    void        soup_message_got_body           (SoupMessage *msg);

`msg` : |

### soup_message_finished ()

    void        soup_message_finished           (SoupMessage *msg);

`msg` : |