Soup.Server
Description: Reference for Soup.Server

### Class

# SoupServer

#### Description [src]

    class Soup.Server : GObject.Object
    {
      /* No available fields */
    }

`SoupServer` provides a basic implementation of an HTTP server. The recommended usage of this server is for internal use, tasks like a mock server for tests, a private service for IPC, etc. It is not recommended to be exposed to untrusted clients as it may be vulnerable to denial of service attacks or other exploits.

To begin, create a server using `soup_server_new()`. Add at least one handler by calling `soup_server_add_handler()` or `soup_server_add_early_handler()`; the handler will be called to process any requests underneath the path you pass. (If you want all requests to go to the same handler, just pass “/” (or `NULL`) for the path.)

When a new connection is accepted (or a new request is started on an existing persistent connection), the `SoupServer` will emit `SoupServer::request-started` and then begin processing the request as described below, but note that once the message is assigned a status-code, then callbacks after that point will be skipped. Note also that it is not defined when the callbacks happen relative to various `SoupServerMessage` signals.

Once the headers have been read, `SoupServer` will check if there is a `SoupAuthDomain` `(qv)` covering the Request-URI; if so, and if the message does not contain suitable authorization, then the `SoupAuthDomain` will set a status of `SOUP_STATUS_UNAUTHORIZED` on the message.

After checking for authorization, `SoupServer` will look for “early” handlers (added with `soup_server_add_early_handler()`) matching the Request-URI. If one is found, it will be run; in particular, this can be used to connect to signals to do a streaming read of the request body.

(At this point, if the request headers contain `Expect: 100-continue`, and a status code has been set, then `SoupServer` will skip the remaining steps and return the response. If the request headers contain `Expect: 100-continue` and no status code has been set, `SoupServer` will return a `SOUP_STATUS_CONTINUE` status before continuing.)

The server will then read in the response body (if present). At this point, if there are no handlers at all defined for the Request-URI, then the server will return `SOUP_STATUS_NOT_FOUND` to the client.

Otherwise (assuming no previous step assigned a status to the message) any “normal” handlers (added with `soup_server_add_handler()`) for the message’s Request-URI will be run.

Then, if the path has a WebSocket handler registered (and has not yet been assigned a status), `SoupServer` will attempt to validate the WebSocket handshake, filling in the response and setting a status of `SOUP_STATUS_SWITCHING_PROTOCOLS` or `SOUP_STATUS_BAD_REQUEST` accordingly.

If the message still has no status code at this point (and has not been paused with `soup_server_message_pause()`), then it will be given a status of `SOUP_STATUS_INTERNAL_SERVER_ERROR` (because at least one handler ran, but returned without assigning a status).

Finally, the server will emit `SoupServer::request-finished` (or `SoupServer::request-aborted` if an I/O error occurred before handling was completed).

If you want to handle the special “” URI (eg, “OPTIONS “), you must explicitly register a handler for “*”; the default handler will not be used for that case.

If you want to process https connections in addition to (or instead of) http connections, you can set the `SoupServer:tls-certificate` property.

Once the server is set up, make one or more calls to `soup_server_listen()`, `soup_server_listen_local()`, or `soup_server_listen_all()` to tell it where to listen for connections. (All ports on a `SoupServer` use the same handlers; if you need to handle some ports differently, such as returning different data for http and https, you’ll need to create multiple `SoupServer`s, or else check the passed-in URI in the handler function.).

`SoupServer` will begin processing connections as soon as you return to (or start) the main loop for the current thread-default `GMainContext`.

#### Hierarchy

#### Ancestors

- GObject

#### Constructors

###### soup_server_new

Creates a new `SoupServer`.

#### Instance methods

###### soup_server_accept_iostream

Adds a new client stream to the `server`.

###### soup_server_add_auth_domain

Adds an authentication domain to `server`.

###### soup_server_add_early_handler

Adds an “early” handler to `server` for requests prefixed by `path`.

###### soup_server_add_handler

Adds a handler to `server` for requests prefixed by `path`.

###### soup_server_add_websocket_extension

Add support for a WebSocket extension of the given `extension_type`.

###### soup_server_add_websocket_handler

Adds a WebSocket handler to `server` for requests prefixed by `path`.

###### soup_server_disconnect

Closes and frees `server`‘s listening sockets.

###### soup_server_get_listeners

Gets `server`‘s list of listening sockets.

###### soup_server_get_tls_auth_mode

Gets the `server` SSL/TLS client authentication mode.

###### soup_server_get_tls_certificate

Gets the `server` SSL/TLS certificate.

###### soup_server_get_tls_database

Gets the `server` SSL/TLS database.

###### soup_server_get_uris

Gets a list of URIs corresponding to the interfaces `server` is listening on.

###### soup_server_is_https

Checks whether `server` is capable of https.

###### soup_server_listen

Attempts to set up `server` to listen for connections on `address`.

###### soup_server_listen_all

Attempts to set up `server` to listen for connections on all interfaces on the system.

###### soup_server_listen_local

Attempts to set up `server` to listen for connections on “localhost”.

###### soup_server_listen_socket

Attempts to set up `server` to listen for connections on `socket`.

###### soup_server_pause_message

Pauses I/O on `msg`.

deprecated: 3.2

###### soup_server_remove_auth_domain

Removes `auth_domain` from `server`.

###### soup_server_remove_handler

Removes all handlers (early and normal) registered at `path`.

###### soup_server_remove_websocket_extension

Removes support for WebSocket extension of type `extension_type` (or any subclass of `extension_type`) from `server`.

###### soup_server_set_tls_auth_mode

Sets `server`‘s `GTlsAuthenticationMode` to use for SSL/TLS client authentication.

###### soup_server_set_tls_certificate

Sets `server` up to do https, using the given SSL/TLS `certificate`.

###### soup_server_set_tls_database

Sets `server`‘s `GTlsDatabase` to use for validating SSL/TLS client certificates.

###### soup_server_unpause_message

Resumes I/O on `msg`.

deprecated: 3.2

##### Methods inherited from GObject (43)

Please see GObject for a full list of methods.

#### Properties

###### Soup.Server:raw-paths

If `TRUE`, percent-encoding in the Request-URI path will not be automatically decoded.

###### Soup.Server:server-header

Server header.

###### Soup.Server:tls-auth-mode

A `GTlsAuthenticationMode` for SSL/TLS client authentication.

###### Soup.Server:tls-certificate

A [class@Gio.TlsCertificate[] that has a `GTlsCertificate:private-key` set.

###### Soup.Server:tls-database

A `GTlsDatabase` to use for validating SSL/TLS client certificates.

#### Signals

###### Soup.Server::request-aborted

Emitted when processing has failed for a message.

###### Soup.Server::request-finished

Emitted when the server has finished writing a response to a request.

###### Soup.Server::request-read

Emitted when the server has successfully read a request.

###### Soup.Server::request-started

Emitted when the server has started reading a new request.

##### Signals inherited from GObject (1)

###### GObject::notify

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

#### Class structure

    struct SoupServerClass {
      GObjectClass parent_class;
      void (* request_started) (
        SoupServer* server,
        SoupServerMessage* msg
      );
      void (* request_read) (
        SoupServer* server,
        SoupServerMessage* msg
      );
      void (* request_finished) (
        SoupServer* server,
        SoupServerMessage* msg
      );
      void (* request_aborted) (
        SoupServer* server,
        SoupServerMessage* msg
      );
      gpointer padding;

    }

No description available.

###### Class members

`parent_class: GObjectClass`

  No description available.

`request_started: void (* request_started) ( SoupServer* server, SoupServerMessage* msg )`

  No description available.

`request_read: void (* request_read) ( SoupServer* server, SoupServerMessage* msg )`

  No description available.

`request_finished: void (* request_finished) ( SoupServer* server, SoupServerMessage* msg )`

  No description available.

`request_aborted: void (* request_aborted) ( SoupServer* server, SoupServerMessage* msg )`

  No description available.

`padding: gpointer`

  No description available.

#### Virtual methods

###### Soup.ServerClass.request_aborted

No description available.

###### Soup.ServerClass.request_finished

No description available.

###### Soup.ServerClass.request_read

No description available.

###### Soup.ServerClass.request_started

No description available.