SoupServerMessage: libsoup Reference Manual

## SoupServerMessage SoupServerMessage — An HTTP server request and response. |

## Functions

SoupMessageHeaders * | soup_server_message_get_request_headers ()
SoupMessageHeaders * | soup_server_message_get_response_headers ()
SoupMessageBody * | soup_server_message_get_request_body ()
SoupMessageBody * | soup_server_message_get_response_body ()
const char * | soup_server_message_get_method ()
SoupHTTPVersion | soup_server_message_get_http_version ()
void | soup_server_message_set_http_version ()
guint | soup_server_message_get_status ()
void | soup_server_message_set_status ()
const char * | soup_server_message_get_reason_phrase ()
GUri * | soup_server_message_get_uri ()
void | soup_server_message_set_response ()
void | soup_server_message_set_redirect ()
GSocket * | soup_server_message_get_socket ()
GSocketAddress * | soup_server_message_get_local_address ()
GSocketAddress * | soup_server_message_get_remote_address ()
const char * | soup_server_message_get_remote_host ()
gboolean | soup_server_message_is_options_ping ()
GIOStream * | soup_server_message_steal_connection ()

## Signals

gboolean | accept-certificate | Run Last
void | disconnected | Run Last
void | finished | Run Last
void | got-body | Run Last
void | got-chunk | Run First
void | got-headers | Run Last
void | wrote-body | Run Last
void | wrote-body-data | Run Last
void | wrote-chunk | Run Last
void | wrote-headers | Run Last
void | wrote-informational | Run Last

## Types and Values

| SoupServerMessage

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

msg | a SoupServerMessage |

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

msg | a SoupServerMessage |

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

msg | a SoupServerMessage |

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

msg | a SoupServerMessage |

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

msg | a SoupServerMessage |

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

msg | a SoupServerMessage |

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

msg | a SoupServerMessage |

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

[nullable]

### soup_server_message_get_uri ()

    GUri *
    soup_server_message_get_uri (SoupServerMessage *msg);

Get `msg` 's URI.

#### Parameters

msg | a SoupServerMessage |

#### 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. | [nullable]
resp_use | a SoupMemoryUse describing how to handle `resp_body` |
resp_body | a data buffer containing the body of the message response. | [nullable][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

msg | a SoupServerMessage |

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

msg | a SoupServerMessage |

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

msg | a SoupServerMessage |

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

msg | a SoupServerMessage |

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

msg | a SoupServerMessage |

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

msg | a SoupServerMessage |

#### 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 `“accept-certificate”` signal

    gboolean
    user_function (SoupServerMessage   *msg,
                   GTlsCertificate     *tls_peer_certificate,
                   GTlsCertificateFlags tls_peer_errors,
                   gpointer             user_data)

Emitted during the `msg` 's connection TLS handshake after client TLS certificate has been received. You can return `TRUE` to accept `tls_certificate` despite `tls_errors` .

#### Parameters

msg | the message |
tls_peer_certificate | the peer's GTlsCertificate |
tls_peer_errors | the tls errors of `tls_certificate` |
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` to accept the TLS certificate and stop other handlers from being invoked, or `FALSE` to propagate the event further.

Flags: Run Last

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