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 SoupServers, 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.

Ancestors

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 servers listening sockets.

soup_server_get_listeners

Gets servers 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 since: 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 servers 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 servers GTlsDatabase to use for validating SSL/TLS client certificates.

soup_server_unpause_message

Resumes I/O on msg.

Deprecated since: 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.Object::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;
  
}
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.