SoupMessage

SoupMessage — An HTTP request and response.

Synopsis




struct              SoupMessage;

SoupMessage*        soup_message_new                    (const char *method,
                                                         const char *uri_string);
SoupMessage*        soup_message_new_from_uri           (const char *method,
                                                         SoupURI *uri);
void                soup_message_set_request            (SoupMessage *msg,
                                                         const char *content_type,
                                                         SoupMemoryUse req_use,
                                                         const char *req_body,
                                                         gsize req_length);
void                soup_message_set_response           (SoupMessage *msg,
                                                         const char *content_type,
                                                         SoupMemoryUse resp_use,
                                                         const char *resp_body,
                                                         gsize resp_length);

enum                SoupHTTPVersion;
void                soup_message_set_http_version       (SoupMessage *msg,
                                                         SoupHTTPVersion version);
SoupHTTPVersion     soup_message_get_http_version       (SoupMessage *msg);
SoupURI*            soup_message_get_uri                (SoupMessage *msg);
void                soup_message_set_uri                (SoupMessage *msg,
                                                         SoupURI *uri);
enum                SoupMessageFlags;
void                soup_message_set_flags              (SoupMessage *msg,
                                                         SoupMessageFlags flags);
SoupMessageFlags    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);
gboolean            soup_message_is_keepalive           (SoupMessage *msg);

guint               soup_message_add_header_handler     (SoupMessage *msg,
                                                         const char *signal,
                                                         const char *header,
                                                         GCallback callback,
                                                         gpointer user_data);
guint               soup_message_add_status_code_handler
                                                        (SoupMessage *msg,
                                                         const char *signal,
                                                         guint status_code,
                                                         GCallback callback,
                                                         gpointer user_data);

#define             SOUP_MESSAGE_METHOD
#define             SOUP_MESSAGE_URI
#define             SOUP_MESSAGE_HTTP_VERSION
#define             SOUP_MESSAGE_FLAGS
#define             SOUP_MESSAGE_STATUS_CODE
#define             SOUP_MESSAGE_REASON_PHRASE


Object Hierarchy


  GObject
   +----SoupMessage

Properties


  "flags"                    SoupMessageFlags      : Read / Write
  "http-version"             SoupHTTPVersion       : Read / Write
  "method"                   gchararray            : Read / Write
  "reason-phrase"            gchararray            : Read / Write
  "status-code"              guint                 : Read / Write
  "uri"                      SoupURI               : Read / Write

Signals


  "finished"                                       : Run First
  "got-body"                                       : Run First
  "got-chunk"                                      : Run First
  "got-headers"                                    : Run First
  "got-informational"                              : Run First
  "restarted"                                      : Run First
  "wrote-body"                                     : Run First
  "wrote-chunk"                                    : Run First
  "wrote-headers"                                  : Run First
  "wrote-informational"                            : Run First

Description

Details

struct SoupMessage

struct SoupMessage {
	const char         *method;

	guint               status_code;
	const char         *reason_phrase;

	SoupMessageBody    *request_body;
	SoupMessageHeaders *request_headers;

	SoupMessageBody    *response_body;
	SoupMessageHeaders *response_headers;
};

Represents an HTTP message being sent or received.

As described in the SoupMessageBody documentation, the request_body and response_body data fields will not necessarily be filled in at all times. When they are filled in, they will be terminated with a '\0' byte (which is not included in the length), so you can use them as ordinary C strings (assuming that you know that the body doesn't have any other '\0' bytes).

For a client-side SoupMessage, request_body's data is usually filled in right before libsoup writes the request to the network, but you should not count on this; use soup_message_body_flatten() if you want to ensure that data is filled in. response_body's data will be filled in before SoupMessage::finished is emitted, unless you set the SOUP_MESSAGE_OVERWRITE_CHUNKS flag.

For a server-side SoupMessage, request_body's data will be filled in before SoupMessage::got_body is emitted.

const char *method;

the HTTP method

guint status_code;

the HTTP status code

const char *reason_phrase;

the status phrase associated with status_code

SoupMessageBody *request_body;

the request body

SoupMessageHeaders *request_headers;

the request headers

SoupMessageBody *response_body;

the response body

SoupMessageHeaders *response_headers;

the response headers

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,
                                                         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,
                                                         SoupMemoryUse req_use,
                                                         const char *req_body,
                                                         gsize req_length);

Convenience function to set the request body of a SoupMessage. If content_type is NULL, the request body must be empty as well.

msg :

the message

content_type :

MIME Content-Type of the body

req_use :

a SoupMemoryUse describing how to handle req_body

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,
                                                         SoupMemoryUse resp_use,
                                                         const char *resp_body,
                                                         gsize resp_length);

Convenience function to set the response body of a SoupMessage. If content_type is NULL, the response body must be empty as well.

msg :

the message

content_type :

MIME Content-Type of the body

resp_use :

a SoupMemoryUse describing how to handle resp_body

resp_body :

a data buffer containing the body of the message response.

resp_length :

the byte length of resp_body.

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

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,
                                                         SoupURI *uri);

Sets msg's URI to uri. If msg has already been sent and you want to re-send it with the new URI, you need to call soup_session_requeue_message().

msg :

a SoupMessage

uri :

the new SoupURI

enum SoupMessageFlags

typedef enum {
	SOUP_MESSAGE_NO_REDIRECT      = (1 << 1),
	SOUP_MESSAGE_OVERWRITE_CHUNKS = (1 << 3),
} 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

Each chunk of the response will be freed after its corresponding got_chunk signal is emitted, meaning response will still be empty after the message is complete. You can use this to save memory if you expect the response to be large and you are able to process it a chunk at a time.

soup_message_set_flags ()

void                soup_message_set_flags              (SoupMessage *msg,
                                                         SoupMessageFlags flags);

Sets the specified flags on msg.

msg :

a SoupMessage

flags :

a set of SoupMessageFlags values

soup_message_get_flags ()

SoupMessageFlags    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_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, based on the HTTP version, Connection header, etc.

msg :

a SoupMessage

Returns :

TRUE or FALSE.

soup_message_add_header_handler ()

guint               soup_message_add_header_handler     (SoupMessage *msg,
                                                         const char *signal,
                                                         const char *header,
                                                         GCallback callback,
                                                         gpointer user_data);

Adds a signal handler to msg for signal, as with g_signal_connect(), but with two differences: the callback will only be run if msg has a header named header, and it will only be run if no earlier handler cancelled or requeued the message.

If signal is one of the "got" signals (eg, "got_headers"), or "finished" or "restarted", then header is matched against the incoming message headers (that is, the request_headers for a client SoupMessage, or the response_headers for a server SoupMessage). If signal is one of the "wrote" signals, then header is matched against the outgoing message headers.

msg :

a SoupMessage

signal :

signal to connect the handler to.

header :

HTTP response header to match against

callback :

the header handler

user_data :

data to pass to handler_cb

Returns :

the handler ID from g_signal_connect()

soup_message_add_status_code_handler ()

guint               soup_message_add_status_code_handler
                                                        (SoupMessage *msg,
                                                         const char *signal,
                                                         guint status_code,
                                                         GCallback callback,
                                                         gpointer user_data);

Adds a signal handler to msg for signal, as with g_signal_connect() but with two differences: the callback will only be run if msg has the status status_code, and it will only be run if no earlier handler cancelled or requeued the message.

signal must be a signal that will be emitted after msg's status is set. For a client SoupMessage, this means it can't be a "wrote" signal. For a server SoupMessage, this means it can't be a "got" signal.

msg :

a SoupMessage

signal :

signal to connect the handler to.

status_code :

status code to match against

callback :

the header handler

user_data :

data to pass to handler_cb

Returns :

the handler ID from g_signal_connect()

SOUP_MESSAGE_METHOD

#define SOUP_MESSAGE_METHOD        "method"


SOUP_MESSAGE_URI

#define SOUP_MESSAGE_URI           "uri"


SOUP_MESSAGE_HTTP_VERSION

#define SOUP_MESSAGE_HTTP_VERSION  "http-version"


SOUP_MESSAGE_FLAGS

#define SOUP_MESSAGE_FLAGS         "flags"


SOUP_MESSAGE_STATUS_CODE

#define SOUP_MESSAGE_STATUS_CODE   "status-code"


SOUP_MESSAGE_REASON_PHRASE

#define SOUP_MESSAGE_REASON_PHRASE "reason-phrase"

Property Details

The "flags" property

  "flags"                    SoupMessageFlags      : Read / Write

Various message options.


The "http-version" property

  "http-version"             SoupHTTPVersion       : Read / Write

The HTTP protocol version to use.

Default value: SOUP_HTTP_1_1


The "method" property

  "method"                   gchararray            : Read / Write

The message's HTTP method.

Default value: "GET"


The "reason-phrase" property

  "reason-phrase"            gchararray            : Read / Write

The HTTP response reason phrase.

Default value: NULL


The "status-code" property

  "status-code"              guint                 : Read / Write

The HTTP response status code.

Allowed values: <= 599

Default value: 0


The "uri" property

  "uri"                      SoupURI               : Read / Write

The message's Request-URI.

Signal Details

The "finished" signal

void                user_function                      (SoupMessage *msg,
                                                        gpointer     user_data)      : Run First

Emitted when all HTTP processing is finished for a message. (After SoupMessage::got_body for client-side messages, or after SoupMessage::wrote_body for server-side messages.)

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)      : Run First

Emitted after receiving the complete message body. (For a server-side message, this means it has received the request body. For a client-side message, this means it has received the response body and is nearly done with the message.)

See also soup_message_add_header_handler() and soup_message_add_status_code_handler(), which can be used to connect to a subset of emissions of this signal.

msg :

the message

user_data :

user data set when the signal handler was connected.

The "got-chunk" signal

void                user_function                      (SoupMessage *msg,
                                                        SoupBuffer  *chunk,
                                                        gpointer     user_data)      : Run First

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.

If you cancel or requeue msg while processing this signal, then the current HTTP I/O will be stopped after this signal emission finished, and msg's connection will be closed.

msg :

the message

chunk :

the just-read chunk

user_data :

user data set when the signal handler was connected.

The "got-headers" signal

void                user_function                      (SoupMessage *msg,
                                                        gpointer     user_data)      : Run First

Emitted after receiving all message headers for a message. (For a client-side message, this is after receiving the Status-Line and response headers; for a server-side message, it is after receiving the Request-Line and request headers.)

See also soup_message_add_header_handler() and soup_message_add_status_code_handler(), which can be used to connect to a subset of emissions of this signal.

If you cancel or requeue msg while processing this signal, then the current HTTP I/O will be stopped after this signal emission finished, and msg's connection will be closed. (If you need to requeue a message--eg, after handling authentication or redirection--it is usually better to requeue it from a SoupMessage::got_body handler rather than a SoupMessage::got_header handler, so that the existing HTTP connection can be reused.)

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)      : Run First

Emitted after receiving a 1xx (Informational) response for a (client-side) message. The response_headers will be filled in with the headers associated with the informational response; however, those header values will be erased after this signal is done.

If you cancel or requeue msg while processing this signal, then the current HTTP I/O will be stopped after this signal emission finished, and msg's connection will be closed.

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)      : Run First

Emitted when a request that was already sent once is now being sent again (eg, because the first attempt received a redirection response, or because we needed to use authentication).

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)      : Run First

Emitted immediately after writing the complete body for a message. (For a client-side message, this means that libsoup is done writing and is now waiting for the response from the server. For a server-side message, this means that libsoup has finished writing the response and is nearly done with the 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)      : Run First

Emitted immediately after writing a body chunk for a message.

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)      : Run First

Emitted immediately after writing the headers for a message. (For a client-side message, this is after writing the request headers; for a server-side message, it is after writing the response headers.)

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)      : Run First

Emitted immediately after writing a 1xx (Informational) response for a (server-side) message.

msg :

the message

user_data :

user data set when the signal handler was connected.

See Also

SoupMessageHeaders, SoupMessageBody