Soup.Server
Description: Reference for Soup.Server

### Class

# SoupServer

#### Description [src]

    class Soup.Server : GObject.Object {
      parent_instance: GObject
    }

A HTTP server.

`SoupServer` implements a simple HTTP server.

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
      );
      None 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: None`
  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.