SoupServerMessage

SoupServerMessage — An HTTP server request and response.

Functions

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── SoupServerMessage

Includes

#include <libsoup/soup.h>

Description

A SoupServerMessage represents an HTTP message that is being sent or received on a SoupServer

SoupServer will create SoupServerMessages automatically for incoming requests, which your application will receive via handlers.

Note that libsoup's terminology here does not quite match the HTTP specification: in RFC 2616, an "HTTP-message" is either a Request, or a Response. In libsoup, a SoupServerMessage combines both the request and the response.

Functions

soup_server_message_get_request_headers ()

SoupMessageHeaders *
soup_server_message_get_request_headers
                               (SoupServerMessage *msg);

Get the request headers of msg .

Parameters

Returns

a SoupMessageHeaders with the request headers.

[transfer none]


soup_server_message_get_response_headers ()

SoupMessageHeaders *
soup_server_message_get_response_headers
                               (SoupServerMessage *msg);

Get the response headers of msg .

Parameters

Returns

a SoupMessageHeaders with the response headers.

[transfer none]


soup_server_message_get_request_body ()

SoupMessageBody *
soup_server_message_get_request_body (SoupServerMessage *msg);

Get the request body of msg .

Parameters

Returns

a SoupMessageBody.

[transfer none]


soup_server_message_get_response_body ()

SoupMessageBody *
soup_server_message_get_response_body (SoupServerMessage *msg);

Get the response body of msg .

Parameters

Returns

a SoupMessageBody.

[transfer none]


soup_server_message_get_method ()

const char *
soup_server_message_get_method (SoupServerMessage *msg);

Get the HTTP method of msg .

Parameters

Returns

the HTTP method.


soup_server_message_get_http_version ()

SoupHTTPVersion
soup_server_message_get_http_version (SoupServerMessage *msg);

Get the HTTP version of msg .

Parameters

Returns

a SoupHTTPVersion.


soup_server_message_set_http_version ()

void
soup_server_message_set_http_version (SoupServerMessage *msg,
                                      SoupHTTPVersion version);

Set the HTTP version of msg .

Parameters

msg

a SoupServerMessage

 

version

a SoupHTTPVersion

 

soup_server_message_get_status ()

guint
soup_server_message_get_status (SoupServerMessage *msg);

Get the HTTP status code of msg .

Parameters

Returns

the HTTP status code.


soup_server_message_set_status ()

void
soup_server_message_set_status (SoupServerMessage *msg,
                                guint status_code,
                                const char *reason_phrase);

Sets msg 's status code to status_code . If status_code is a known value and reason_phrase is NULL, the reason_phrase will be set automatically.

Parameters

msg

a SoupServerMessage

 

status_code

an HTTP status code

 

reason_phrase

a reason phrase.

[nullable]

soup_server_message_get_reason_phrase ()

const char *
soup_server_message_get_reason_phrase (SoupServerMessage *msg);

Get the HTTP reason phrase of msg or NULL.

Parameters

msg

a SoupServerMessage:

 

Returns

the reason phrase.


soup_server_message_get_uri ()

GUri *
soup_server_message_get_uri (SoupServerMessage *msg);

Get msg 's URI.

Parameters

Returns

a GUri.

[transfer none]


soup_server_message_set_response ()

void
soup_server_message_set_response (SoupServerMessage *msg,
                                  const char *content_type,
                                  SoupMemoryUse resp_use,
                                  const char *resp_body,
                                  gsize resp_length);

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

Parameters

msg

the message

 

content_type

MIME Content-Type of the body.

[allow-none]

resp_use

a SoupMemoryUse describing how to handle resp_body

 

resp_body

a data buffer containing the body of the message response.

[allow-none][array length=resp_length][element-type guint8]

resp_length

the byte length of resp_body .

 

soup_server_message_set_redirect ()

void
soup_server_message_set_redirect (SoupServerMessage *msg,
                                  guint status_code,
                                  const char *redirect_uri);

Sets msg 's status_code to status_code and adds a Location header pointing to redirect_uri . Use this from a SoupServer when you want to redirect the client to another URI.

redirect_uri can be a relative URI, in which case it is interpreted relative to msg 's current URI. In particular, if redirect_uri is just a path, it will replace the path and query of msg 's URI.

Parameters

msg

a SoupServerMessage

 

status_code

a 3xx status code

 

redirect_uri

the URI to redirect msg to

 

soup_server_message_get_socket ()

GSocket *
soup_server_message_get_socket (SoupServerMessage *msg);

Retrieves the GSocket that msg is associated with.

If you are using this method to observe when multiple requests are made on the same persistent HTTP connection (eg, as the ntlm-test test program does), you will need to pay attention to socket destruction as well (eg, by using weak references), so that you do not get fooled when the allocator reuses the memory address of a previously-destroyed socket to represent a new socket.

Parameters

Returns

the GSocket that msg is associated with, NULL if you used soup_server_accept_iostream().

[nullable][transfer none]


soup_server_message_get_local_address ()

GSocketAddress *
soup_server_message_get_local_address (SoupServerMessage *msg);

Retrieves the GSocketAddress associated with the local end of a connection.

Parameters

Returns

the GSocketAddress associated with the local end of a connection, it may be NULL if you used soup_server_accept_iostream().

[nullable][transfer none]


soup_server_message_get_remote_address ()

GSocketAddress *
soup_server_message_get_remote_address
                               (SoupServerMessage *msg);

Retrieves the GSocketAddress associated with the remote end of a connection.

Parameters

Returns

the GSocketAddress associated with the remote end of a connection, it may be NULL if you used soup_server_accept_iostream().

[nullable][transfer none]


soup_server_message_get_remote_host ()

const char *
soup_server_message_get_remote_host (SoupServerMessage *msg);

Retrieves the IP address associated with the remote end of a connection.

Parameters

Returns

the IP address associated with the remote end of a connection, it may be NULL if you used soup_server_accept_iostream().

[nullable]


soup_server_message_is_options_ping ()

gboolean
soup_server_message_is_options_ping (SoupServerMessage *msg);

Gets if msg represents an OPTIONS message with the path *.

Parameters

Returns

TRUE if is an OPTIONS ping


soup_server_message_steal_connection ()

GIOStream *
soup_server_message_steal_connection (SoupServerMessage *msg);

"Steals" the HTTP connection associated with msg from its SoupServer. This happens immediately, regardless of the current state of the connection; if the response to msg has not yet finished being sent, then it will be discarded; you can steal the connection from a “wrote-informational” or “wrote-body” signal handler if you need to wait for part or all of the response to be sent.

Note that when calling this function from C, msg will most likely be freed as a side effect.

Parameters

Returns

the GIOStream formerly associated with msg (or NULL if msg was no longer associated with a connection). No guarantees are made about what kind of GIOStream is returned.

[transfer full]

Types and Values

SoupServerMessage

typedef struct _SoupServerMessage SoupServerMessage;

Class represnting an HTTP request and response pair for a server.

Signal Details

The “disconnected” signal

void
user_function (SoupServerMessage *msg,
               gpointer           user_data)

Emitted when the msg 's socket is disconnected.

Parameters

msg

the message

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “finished” signal

void
user_function (SoupServerMessage *msg,
               gpointer           user_data)

Emitted when all HTTP processing is finished for a message. (After “wrote-body”).

Parameters

msg

the message

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “got-body” signal

void
user_function (SoupServerMessage *msg,
               gpointer           user_data)

Emitted after receiving the complete request body.

Parameters

msg

the message

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “got-chunk” signal

void
user_function (SoupServerMessage *msg,
               GBytes            *chunk,
               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.

Parameters

msg

the message

 

chunk

the just-read chunk

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “got-headers” signal

void
user_function (SoupServerMessage *msg,
               gpointer           user_data)

Emitted after receiving the Request-Line and request headers.

Parameters

msg

the message

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “wrote-body” signal

void
user_function (SoupServerMessage *msg,
               gpointer           user_data)

Emitted immediately after writing the complete response body for a message.

Parameters

msg

the message

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “wrote-body-data” signal

void
user_function (SoupServerMessage *msg,
               guint              chunk_size,
               gpointer           user_data)

Emitted immediately after writing a portion of the message body to the network.

Parameters

msg

the message

 

chunk_size

the number of bytes written

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “wrote-chunk” signal

void
user_function (SoupServerMessage *msg,
               gpointer           user_data)

Emitted immediately after writing a body chunk for a message.

Note that this signal is not parallel to “got-chunk”; it is emitted only when a complete chunk (added with soup_message_body_append() or soup_message_body_append_bytes()) has been written. To get more useful continuous progress information, use “wrote-body-data”.

Parameters

msg

the message

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “wrote-headers” signal

void
user_function (SoupServerMessage *msg,
               gpointer           user_data)

Emitted immediately after writing the response headers for a message.

Parameters

msg

the message

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “wrote-informational” signal

void
user_function (SoupServerMessage *msg,
               gpointer           user_data)

Emitted immediately after writing a 1xx (Informational) response.

Parameters

msg

the message

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

See Also

SoupMessageHeaders, SoupMessageBody