soup.c.types

The type of cache; this affects what kinds of responses will be saved.

Indicates if a message should or shouldn't be cached.

The policy for accepting or rejecting cookies returned in responses.

Date formats that func@date_time_to_string can use.

@SOUP_DATE_HTTP and @SOUP_DATE_COOKIE always coerce the time to UTC.

This enum may be extended with more values in future releases.

How a message body is encoded for transport

Represents the parsed value of the "Expect" header.

Indicates the HTTP protocol version being used.

Describes the level of logging output to provide.

The lifetime of the memory being passed.

Various flags that can be set on a #SoupMessage to alter its behavior.

Value passed to soup.message_headers.MessageHeaders.new_ to set certain default behaviors.

Priorities that can be set on a soup.message.Message to instruct the message queue to process it before any other message with lower priority.

Represents the same-site policies of a cookie.

Options to pass to soup.server.Server.listen, etc.

soup.types.ServerListenOptions.Ipv4Only and soup.types.ServerListenOptions.Ipv6Only only make sense with soup.server.Server.listenAll and soup.server.Server.listenLocal, not plain soup.server.Server.listen (which simply listens on whatever kind of socket you give it). And you cannot specify both of them in a single call.

A #SoupSession error.

These represent the known HTTP status code values, plus various network and internal errors.

Note that no libsoup functions take or return this type directly; any function that works with status codes will accept unrecognized status codes as well.

Error codes for SOUP_TLD_ERROR.

Enum values passed to func@uri_copy to indicate the components of the URI that should be updated with the given values.

Pre-defined close codes that can be passed to soup.websocket_connection.WebsocketConnection.close or received from soup.websocket_connection.WebsocketConnection.getCloseCode.

However, other codes are also allowed.

The type of a soup.websocket_connection.WebsocketConnection.

The type of data contained in a soup.websocket_connection.WebsocketConnection.message signal.

WebSocket-related errors.

The state of the WebSocket connection.

The abstract base class for handling authentication.

Specific HTTP Authentication mechanisms are implemented by its subclasses, but applications never need to be aware of the specific subclasses being used.

#SoupAuth objects store the authentication data associated with a given bit of web space. They are created automatically by soup.session.Session.

HTTP "Basic" authentication.

soup.session.Sessions support this by default; if you want to disable support for it, call soup.session.Session.removeFeatureByType, passing SOUP_TYPE_AUTH_BASIC.

HTTP "Digest" authentication.

soup.session.Sessions support this by default; if you want to disable support for it, call soup.session.Session.removeFeatureByType passing SOUP_TYPE_AUTH_DIGEST.

Server-side authentication.

A #SoupAuthDomain manages authentication for all or part of a soup.server.Server. To make a server require authentication, first create an appropriate subclass of #SoupAuthDomain, and then add it to the server with soup.server.Server.addAuthDomain.

In order for an auth domain to have any effect, you must add one or more paths to it (via soup.auth_domain.AuthDomain.addPath). To require authentication for all ordinary requests, add the path `"/"`. (Note that this does not include the special `""` URI (eg, "OPTIONS "), which must be added as a separate path if you want to cover it.)

If you need greater control over which requests should and shouldn't be authenticated, add paths covering everything you might want authenticated, and then use a filter (soup.auth_domain.AuthDomain.setFilter to bypass authentication for those requests that don't need it.

Server-side "Basic" authentication.

#SoupAuthDomainBasic handles the server side of HTTP "Basic" (ie, cleartext password) authentication.

Server-side "Digest" authentication.

#SoupAuthDomainDigest handles the server side of HTTP "Digest" authentication.

HTTP client-side authentication handler.

#SoupAuthManager is the soup.session_feature.SessionFeature that handles HTTP authentication for a soup.session.Session.

A #SoupAuthManager is added to the session by default, and normally you don't need to worry about it at all. However, if you want to disable HTTP authentication, you can remove the feature from the session with soup.session.Session.removeFeatureByType or disable it on individual requests with soup.message.Message.disableFeature.

You can use this with soup.session.Session.removeFeatureByType or soup.message.Message.disableFeature.

(Although this type has only been publicly visible since libsoup 2.42, it has always existed in the background, and you can use g_type_from_name ("SoupAuthManager") to get its alias@GLib.Type in earlier releases.)

HTTP-based NTLM authentication.

soup.session.Sessions do not support this type by default; if you want to enable support for it, call soup.session.Session.addFeatureByType, passing SOUP_TYPE_AUTH_NTLM.

HTTP-based GSS-Negotiate authentication, as defined by RFC 4559.

soup.session.Sessions do not support this type by default; if you want to enable support for it, call soup.session.Session.addFeatureByType, passing SOUP_TYPE_AUTH_NEGOTIATE.

This auth type will only work if libsoup was compiled with GSSAPI support; you can check soup.auth_negotiate.AuthNegotiate.supported to see if it was.

File-based cache for HTTP resources.

Handles decoding of HTTP messages.

#SoupContentDecoder handles adding the "Accept-Encoding" header on outgoing messages, and processing the "Content-Encoding" header on incoming ones. Currently it supports the "gzip", "deflate", and "br" content codings.

A #SoupContentDecoder will automatically be added to the session by default. (You can use soup.session.Session.removeFeatureByType if you don't want this.)

If #SoupContentDecoder successfully decodes the Content-Encoding, the message body will contain the decoded data; however, the message headers will be unchanged (and so "Content-Encoding" will still be present, "Content-Length" will describe the original encoded length, etc).

If "Content-Encoding" contains any encoding types that #SoupContentDecoder doesn't recognize, then none of the encodings will be decoded.

(Note that currently there is no way to (automatically) use Content-Encoding when sending a request body, or to pick specific encoding types to support.)

Sniffs the mime type of messages.

A #SoupContentSniffer tries to detect the actual content type of the files that are being downloaded by looking at some of the data before the soup.message.Message emits its soup.message.Message.gotHeaders signal. #SoupContentSniffer implements soup.session_feature.SessionFeature, so you can add content sniffing to a session with soup.session.Session.addFeature or soup.session.Session.addFeatureByType.

Implements HTTP cookies, as described by RFC 6265.

To have a soup.session.Session handle cookies for your appliction automatically, use a soup.cookie_jar.CookieJar.

@name and @value will be set for all cookies. If the cookie is generated from a string that appears to have no name, then @name will be the empty string.

@domain and @path give the host or domain, and path within that host/domain, to restrict this cookie to. If @domain starts with ".", that indicates a domain (which matches the string after the ".", or any hostname that has @domain as a suffix). Otherwise, it is a hostname and must match exactly.

@expires will be non-null if the cookie uses either the original "expires" attribute, or the newer "max-age" attribute. If @expires is null, it indicates that neither "expires" nor "max-age" was specified, and the cookie expires at the end of the session.

If @http_only is set, the cookie should not be exposed to untrusted code (eg, javascript), so as to minimize the danger posed by cross-site scripting attacks.

Automatic cookie handling for SoupSession.

A #SoupCookieJar stores soup.cookie.Cookies and arrange for them to be sent with the appropriate soup.message.Messages. #SoupCookieJar implements soup.session_feature.SessionFeature, so you can add a cookie jar to a session with soup.session.Session.addFeature or soup.session.Session.addFeatureByType.

Note that the base #SoupCookieJar class does not support any form of long-term cookie persistence.

Database-based Cookie Jar.

#SoupCookieJarDB is a soup.cookie_jar.CookieJar that reads cookies from and writes them to a sqlite database in the new Mozilla format.

(This is identical to SoupCookieJarSqlite in libsoup-gnome; it has just been moved into libsoup proper, and renamed to avoid conflicting.)

Text-file-based ("cookies.txt") Cookie Jar

#SoupCookieJarText is a soup.cookie_jar.CookieJar that reads cookies from and writes them to a text file in format similar to Mozilla's "cookies.txt".

Automatic HTTP Strict Transport Security enforcing for soup.session.Session.

A #SoupHSTSEnforcer stores HSTS policies and enforces them when required. #SoupHSTSEnforcer implements soup.session_feature.SessionFeature, so you can add an HSTS enforcer to a session with soup.session.Session.addFeature or soup.session.Session.addFeatureByType.

#SoupHSTSEnforcer keeps track of all the HTTPS destinations that, when connected to, return the Strict-Transport-Security header with valid values. #SoupHSTSEnforcer will forget those destinations upon expiry or when the server requests it.

When the soup.session.Session the #SoupHSTSEnforcer is attached to queues or restarts a message, the #SoupHSTSEnforcer will rewrite the URI to HTTPS if the destination is a known HSTS host and is contacted over an insecure transport protocol (HTTP). Users of #SoupHSTSEnforcer are advised to listen to changes in the soup.message.Message.uri property in order to be aware of changes in the message URI.

Note that #SoupHSTSEnforcer does not support any form of long-term HSTS policy persistence. See soup.hstsenforcer_db.HSTSEnforcerDB for a persistent enforcer.

Class structure for #SoupHSTSEnforcer.

Persistent HTTP Strict Transport Security enforcer.

#SoupHSTSEnforcerDB is a soup.hstsenforcer.HSTSEnforcer that uses a SQLite database as a backend for persistency.

#SoupHSTSPolicy implements HTTP policies, as described by RFC 6797.

@domain represents the host that this policy applies to. The domain must be IDNA-canonicalized. soup.hstspolicy.HSTSPolicy.new_ and related methods will do this for you.

@max_age contains the 'max-age' value from the Strict Transport Security header and indicates the time to live of this policy, in seconds.

@expires will be non-null if the policy has been set by the host and hence has an expiry time. If @expires is null, it indicates that the policy is a permanent session policy set by the user agent.

If @include_subdomains is true, the Strict Transport Security policy must also be enforced on subdomains of @domain.

Debug logging support

#SoupLogger watches a soup.session.Session and logs the HTTP traffic that it generates, for debugging purposes. Many applications use an environment variable to determine whether or not to use #SoupLogger, and to determine the amount of debugging output.

To use #SoupLogger, first create a logger with soup.logger.Logger.new_, optionally configure it with soup.logger.Logger.setRequestFilter, soup.logger.Logger.setResponseFilter, and soup.logger.Logger.setPrinter, and then attach it to a session (or multiple sessions) with soup.session.Session.addFeature.

By default, the debugging output is sent to stdout, and looks something like:

> POST /unauth HTTP/1.1
> Soup-Debug-Timestamp: 1200171744
> Soup-Debug: SoupSession 1 (0x612190), SoupMessage 1 (0x617000), GSocket 1 (0x612220)
> Host: localhost
> Content-Type: text/plain
> Connection: close

< HTTP/1.1 201 Created
< Soup-Debug-Timestamp: 1200171744
< Soup-Debug: SoupMessage 1 (0x617000)
< Date: Sun, 12 Jan 2008 21:02:24 GMT
< Content-Length: 0

The Soup-Debug-Timestamp line gives the time (as a time_t) when the request was sent, or the response fully received.

The Soup-Debug line gives further debugging information about the soup.session.Session, soup.message.Message, and gio.socket.Socket involved; the hex numbers are the addresses of the objects in question (which may be useful if you are running in a debugger). The decimal IDs are simply counters that uniquely identify objects across the lifetime of the #SoupLogger. In particular, this can be used to identify when multiple messages are sent across the same connection.

Currently, the request half of the message is logged just before the first byte of the request gets written to the network (from the soup.message.Message.starting signal).

The response is logged just after the last byte of the response body is read from the network (from the soup.message.Message.gotBody or soup.message.Message.gotInformational signal), which means that the soup.message.Message.gotHeaders signal, and anything triggered off it (such as #SoupMessage::authenticate) will be emitted before the response headers are actually logged.

If the response doesn't happen to trigger the soup.message.Message.gotBody nor soup.message.Message.gotInformational signals due to, for example, a cancellation before receiving the last byte of the response body, the response will still be logged on the event of the soup.message.Message.finished signal.

Represents an HTTP message being sent or received.

A #SoupMessage represents an HTTP message that is being sent or received.

You would create a #SoupMessage with soup.message.Message.new_ or soup.message.Message.newFromUri, set up its fields appropriately, and send it.

soup.message.Message.statusCode will normally be a soup.types.Status value, eg, soup.types.Status.Ok, though of course it might actually be an unknown status code. soup.message.Message.reasonPhrase is the actual text returned from the server, which may or may not correspond to the "standard" description of @status_code. At any rate, it is almost certainly not localized, and not very descriptive even if it is in the user's language; you should not use soup.message.Message.reasonPhrase in user-visible messages. Rather, you should look at soup.message.Message.statusCode, and determine an end-user-appropriate message based on that and on what you were trying to do.

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 #SoupMessage combines both the request and the response.

#SoupMessageBody represents the request or response body of a soup.message.Message.

Note that while @length always reflects the full length of the message body, @data is normally null, and will only be filled in after soup.message_body.MessageBody.flatten is called. For client-side messages, this automatically happens for the response body after it has been fully read. Likewise, for server-side messages, the request body is automatically filled in after being read.

As an added bonus, when @data is filled in, it is always terminated with a \0 byte (which is not reflected in @length).

The HTTP message headers associated with a request or response.

An opaque type used to iterate over a soup.message_headers.MessageHeaders structure.

After intializing the iterator with soup.message_headers_iter.MessageHeadersIter.init_, call soup.message_headers_iter.MessageHeadersIter.next to fetch data from it.

You may not modify the headers while iterating over them.

Contains metrics collected while loading a soup.message.Message either from the network or the disk cache.

Metrics are not collected by default for a soup.message.Message, you need to add the flag soup.types.MessageFlags.CollectMetrics to enable the feature.

Temporal metrics are expressed as a monotonic time and always start with a fetch start event and finish with response end. All other events are optional. An event can be 0 because it hasn't happened yet, because it's optional or because the load failed before the event reached.

Size metrics are expressed in bytes and are updated while the soup.message.Message is being loaded. You can connect to different soup.message.Message signals to get the final result of every value.

Represents a multipart HTTP message body, parsed according to the syntax of RFC 2046.

Of particular interest to HTTP are multipart/byte-ranges and multipart/form-data,

Although the headers of a #SoupMultipart body part will contain the full headers from that body part, libsoup does not interpret them according to MIME rules. For example, each body part is assumed to have "binary" Content-Transfer-Encoding, even if its headers explicitly state otherwise. In other words, don't try to use #SoupMultipart for handling real MIME multiparts.

Handles streams of multipart messages.

This adds support for the multipart responses. For handling the multiple parts the user needs to wrap the gio.input_stream.InputStream obtained by sending the request with a soup.multipart_input_stream.MultipartInputStream and use soup.multipart_input_stream.MultipartInputStream.nextPart before reading. Responses which are not wrapped will be treated like non-multipart responses.

Note that although #SoupMultipartInputStream is a gio.input_stream.InputStream, you should not read directly from it, and the results are undefined if you do.

Represents a byte range as used in the Range header.

If @end is non-negative, then @start and @end represent the bounds of of the range, counting from 0. (Eg, the first 500 bytes would be represented as @start = 0 and @end = 499.)

If @end is -1 and @start is non-negative, then this represents a range starting at @start and ending with the last byte of the requested resource body. (Eg, all but the first 500 bytes would be @start = 500, and @end = -1.)

If @end is -1 and @start is negative, then it represents a "suffix range", referring to the last -@start bytes of the resource body. (Eg, the last 500 bytes would be @start = -500 and @end = -1.)

A HTTP server.

#SoupServer implements a simple HTTP server.

To begin, create a server using soup.server.Server.new_. Add at least one handler by calling soup.server.Server.addHandler or soup.server.Server.addEarlyHandler; 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 soup.server.Server.requestStarted 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 soup.server_message.ServerMessage signals.

Once the headers have been read, #SoupServer will check if there is a soup.auth_domain.AuthDomain (qv) covering the Request-URI; if so, and if the message does not contain suitable authorization, then the soup.auth_domain.AuthDomain will set a status of soup.types.Status.Unauthorized on the message.

After checking for authorization, #SoupServer will look for "early" handlers (added with soup.server.Server.addEarlyHandler) 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.types.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.types.Status.NotFound to the client.

Otherwise (assuming no previous step assigned a status to the message) any "normal" handlers (added with soup.server.Server.addHandler) 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.types.Status.SwitchingProtocols or soup.types.Status.BadRequest accordingly.

If the message still has no status code at this point (and has not been paused with soup.server_message.ServerMessage.pause), then it will be given a status of soup.types.Status.InternalServerError (because at least one handler ran, but returned without assigning a status).

Finally, the server will emit soup.server.Server.requestFinished (or soup.server.Server.requestAborted 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 soup.server.Server.tlsCertificate property.

Once the server is set up, make one or more calls to soup.server.Server.listen, soup.server.Server.listenLocal, or soup.server.Server.listenAll 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 soup.server.Servers, 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 glib.main_context.MainContext.

An HTTP server request and response pair.

A SoupServerMessage represents an HTTP message that is being sent or received on a soup.server.Server.

soup.server.Server will create soup.server_message.ServerMessages 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.

Soup session state object.

#SoupSession is the object that controls client-side HTTP. A #SoupSession encapsulates all of the state that libsoup is keeping on behalf of your program; cached HTTP connections, authentication information, etc. It also keeps track of various global options and features that you are using.

Most applications will only need a single #SoupSession; the primary reason you might need multiple sessions is if you need to have multiple independent authentication contexts. (Eg, you are connecting to a server and authenticating as two different users at different times; the easiest way to ensure that each soup.message.Message is sent with the authentication information you intended is to use one session for the first user, and a second session for the other user.)

Additional #SoupSession functionality is provided by soup.session_feature.SessionFeature objects, which can be added to a session with soup.session.Session.addFeature or soup.session.Session.addFeatureByType For example, soup.logger.Logger provides support for logging HTTP traffic, soup.content_decoder.ContentDecoder provides support for compressed response handling, and soup.content_sniffer.ContentSniffer provides support for HTML5-style response body content sniffing. Additionally, subtypes of soup.auth.Auth can be added as features, to add support for additional authentication types.

All soup.session.Sessions are created with a soup.auth_manager.AuthManager, and support for SOUP_TYPE_AUTH_BASIC and SOUP_TYPE_AUTH_DIGEST. Additionally, sessions using the plain #SoupSession class (rather than one of its deprecated subtypes) have a soup.content_decoder.ContentDecoder by default.

Note that all async methods will invoke their callbacks on the thread-default context at the time of the function call.

Interface for miscellaneous soup.session.Session features.

#SoupSessionFeature is the interface used by classes that extend the functionality of a soup.session.Session. Some features like HTTP authentication handling are implemented internally via soup.session_feature.SessionFeatures. Other features can be added to the session by the application. (Eg, soup.logger.Logger, soup.cookie_jar.CookieJar.)

See soup.session.Session.addFeature, etc, to add a feature to a session.

The interface implemented by soup.session_feature.SessionFeatures.

The WebSocket Protocol

Provides support for the WebSocket protocol.

To connect to a WebSocket server, create a soup.session.Session and call soup.session.Session.websocketConnectAsync. To accept WebSocket connections, create a soup.server.Server and add a handler to it with soup.server.Server.addWebsocketHandler.

(Lower-level support is available via func@websocket_client_prepare_handshake and func@websocket_client_verify_handshake, for handling the client side of the WebSocket handshake, and func@websocket_server_process_handshake for handling the server side.)

#SoupWebsocketConnection handles the details of WebSocket communication. You can use soup.websocket_connection.WebsocketConnection.sendText and soup.websocket_connection.WebsocketConnection.sendBinary to send data, and the soup.websocket_connection.WebsocketConnection.message signal to receive data. (#SoupWebsocketConnection currently only supports asynchronous I/O.)

The abstract base class for soup.websocket_connection.WebsocketConnection.

A WebSocket extension

#SoupWebsocketExtension is the base class for WebSocket extension objects.

The class structure for the #SoupWebsocketExtension.

A SoupWebsocketExtensionDeflate is a soup.websocket_extension.WebsocketExtension implementing permessage-deflate (RFC 7692).

This extension is used by default in a soup.session.Session when soup.websocket_extension_manager.WebsocketExtensionManager feature is present, and always used by soup.server.Server.

SoupWebsocketExtensionManager is the soup.session_feature.SessionFeature that handles WebSockets extensions for a soup.session.Session.

A #SoupWebsocketExtensionManager is added to the session by default, and normally you don't need to worry about it at all. However, if you want to disable WebSocket extensions, you can remove the feature from the session with soup.session.Session.removeFeatureByType or disable it on individual requests with soup.message.Message.disableFeature.