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