Soup – 3.0
Description: Reference for Soup-3.0

### Namespace

# Soup – 3.0

HTTP client/server library for GNOME

Version | 3.6.6
Authors | Dan Winship, Claudio Saavedra, Patrick Griffis, and Carlos Garcia Campos
License | LGPL-2.0-or-later
Website | https://libsoup.gnome.org/
Source | https://gitlab.gnome.org/GNOME/libsoup

#### Build

C headers | `libsoup/soup.h`
pkg-config files | `libsoup-3.0`

#### Dependencies

GLib—2.0 | The base type system library
| Browse documentation
GObject—2.0 | The base type system library
| Browse documentation
Gio—2.0 | GObject Interfaces and Objects, Networking, IPC, and I/O
| Browse documentation

#### Additional documentation

- Building with libsoup
- Creating a Basic Client
- Advanced Usage
- Client thread safety
- Everything TLS Related
- Server Basics
- Migrating from libsoup 2
- Classes Hierarchy

#### Classes

Auth | The abstract base class for handling authentication.
AuthBasic | HTTP “Basic” authentication.
AuthDigest | HTTP “Digest” authentication.
AuthDomain | Server-side authentication.
AuthDomainBasic | Server-side “Basic” authentication.
AuthDomainDigest | Server-side “Digest” authentication.
AuthManager | HTTP client-side authentication handler.
AuthNegotiate | HTTP-based GSS-Negotiate authentication, as defined by RFC 4559.
AuthNTLM | HTTP-based NTLM authentication.
Cache | File-based cache for HTTP resources.
ContentDecoder | Handles decoding of HTTP messages.
ContentSniffer | Sniffs the mime type of messages.
CookieJar | Automatic cookie handling for SoupSession.
CookieJarDB | Database-based Cookie Jar.
CookieJarText | Text-file-based (“cookies.txt”) Cookie Jar.
HSTSEnforcer | Automatic HTTP Strict Transport Security enforcing for `SoupSession`.
HSTSEnforcerDB | Persistent HTTP Strict Transport Security enforcer.
Logger | Debug logging support.
Message | Represents an HTTP message being sent or received.
MultipartInputStream | Handles streams of multipart messages.
Server | `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.
ServerMessage | An HTTP server request and response pair.
Session | Soup session state object.
WebsocketConnection | The WebSocket Protocol.
WebsocketExtension | A WebSocket extension.
WebsocketExtensionDeflate | A SoupWebsocketExtensionDeflate is a `SoupWebsocketExtension` implementing permessage-deflate (RFC 7692).
WebsocketExtensionManager | SoupWebsocketExtensionManager is the `SoupSessionFeature` that handles WebSockets extensions for a `SoupSession`.

#### Interfaces

SessionFeature | Interface for miscellaneous `SoupSession` features.

#### Structs

Cookie | Implements HTTP cookies, as described by RFC 6265.
HSTSPolicy | `SoupHSTSPolicy` implements HTTP policies, as described by RFC 6797.
MessageBody | `SoupMessageBody` represents the request or response body of a `SoupMessage`.
MessageHeaders | The HTTP message headers associated with a request or response.
MessageHeadersIter | An opaque type used to iterate over a `SoupMessageHeaders` structure.
MessageMetrics | Contains metrics collected while loading a `SoupMessage` either from the network or the disk cache.
Multipart | Represents a multipart HTTP message body, parsed according to the syntax of RFC 2046.
Range | Represents a byte range as used in the Range header.

#### Enumerations

CacheType | The type of cache; this affects what kinds of responses will be saved.
CookieJarAcceptPolicy | The policy for accepting or rejecting cookies returned in responses.
DateFormat | Date formats that `soup_date_time_to_string()` can use.
Encoding | How a message body is encoded for transport.
HTTPVersion | Indicates the HTTP protocol version being used.
LoggerLogLevel | Describes the level of logging output to provide.
MemoryUse | The lifetime of the memory being passed.
MessageHeadersType | Value passed to `soup_message_headers_new()` to set certain default behaviors.
MessagePriority | Priorities that can be set on a `SoupMessage` to instruct the message queue to process it before any other message with lower priority.
SameSitePolicy | Represents the same-site policies of a cookie.
Status | These represent the known HTTP status code values, plus various network and internal errors.
URIComponent | Enum values passed to `soup_uri_copy()` to indicate the components of the URI that should be updated with the given values.
WebsocketCloseCode | Pre-defined close codes that can be passed to `soup_websocket_connection_close()` or received from `soup_websocket_connection_get_close_code()`.
WebsocketConnectionType | The type of a `SoupWebsocketConnection`.
WebsocketDataType | The type of data contained in a `SoupWebsocketConnection::message` signal.
WebsocketState | The state of the WebSocket connection.

#### Bitfields

Cacheability | Indicates if a message should or shouldn’t be cached.
Expectation | Represents the parsed value of the “Expect” header.
MessageFlags | Various flags that can be set on a `SoupMessage` to alter its behavior.
ServerListenOptions | Options to pass to `soup_server_listen()`, etc.

#### Error Domains

SessionError | A `SoupSession` error.
TLDError | Error codes for `SOUP_TLD_ERROR`.
WebsocketError | WebSocket-related errors.

#### Callbacks

AuthDomainBasicAuthCallback | Callback used by `SoupAuthDomainBasic` for authentication purposes.
AuthDomainDigestAuthCallback | Callback used by `SoupAuthDomainDigest` for authentication purposes.
AuthDomainFilter | The prototype for a `SoupAuthDomain` filter.
AuthDomainGenericAuthCallback | The prototype for a `SoupAuthDomain` generic authentication callback.
LoggerFilter | The prototype for a logging filter.
LoggerPrinter | The prototype for a custom printing callback.
MessageHeadersForeachFunc | The callback passed to `soup_message_headers_foreach()`.
ServerCallback | A callback used to handle requests to a `SoupServer`.
ServerWebsocketCallback | A callback used to handle WebSocket requests to a `SoupServer`.

#### Functions

check_version | Like `SOUP_CHECK_VERSION()`, but the check for soup_check_version is at runtime instead of compile time.
cookies_free | Frees `cookies`.
cookies_from_request | Parses `msg`‘s Cookie request header and returns a `GSList` of `SoupCookie`s.
cookies_from_response | Parses `msg`‘s Set-Cookie response headers and returns a `GSList` of `SoupCookie`s.
cookies_to_cookie_header | Serializes a `GSList` of `SoupCookie` into a string suitable for setting as the value of the “Cookie” header.
cookies_to_request | Adds the name and value of each cookie in `cookies` to `msg`‘s “Cookie” request.
cookies_to_response | Appends a “Set-Cookie” response header to `msg` for each cookie in `cookies`.
date_time_new_from_http_string | Parses `date_string` and tries to extract a date from it.
date_time_to_string | Converts `date` to a string in the format described by `format`.
form_decode | Decodes `form`.
form_decode_multipart | Decodes the “multipart/form-data” request in `multipart`.
form_encode | Encodes the given field names and values into a value of type “application/x-www-form-urlencoded”.
form_encode_datalist | Encodes `form_data_set` into a value of type “application/x-www-form-urlencoded”.
form_encode_hash | Encodes `form_data_set` into a value of type “application/x-www-form-urlencoded”.
form_encode_valist | See `soup_form_encode()`.
get_major_version | Returns the major version number of the libsoup library.
get_micro_version | Returns the micro version number of the libsoup library.
get_minor_version | Returns the minor version number of the libsoup library.
header_contains | Parses `header` to see if it contains the token `token` (matched case-insensitively).
header_free_list | Frees `list`.
header_free_param_list | Frees `param_list`.
header_g_string_append_param | Appends something like `name=value` to `string`, taking care to quote `value` if needed, and if so, to escape any quotes or backslashes in `value`.
header_g_string_append_param_quoted | Appends something like `name="value"` to `string`, taking care to escape any quotes or backslashes in `value`.
header_parse_list | Parses a header whose content is described by RFC2616 as `#something`.
header_parse_param_list | Parses a header which is a comma-delimited list of something like: `token [ "=" ( token | quoted-string ) ]`.
header_parse_param_list_strict | A strict version of `soup_header_parse_param_list()` that bails out if there are duplicate parameters.
header_parse_quality_list | Parses a header whose content is a list of items with optional “qvalue”s (eg, Accept, Accept-Charset, Accept-Encoding, Accept-Language, TE).
header_parse_semi_param_list | Parses a header which is a semicolon-delimited list of something like: `token [ "=" ( token | quoted-string ) ]`.
header_parse_semi_param_list_strict | A strict version of `soup_header_parse_semi_param_list()` that bails out if there are duplicate parameters.
headers_parse | Parses the headers of an HTTP request or response in `str` and stores the results in `dest`.
headers_parse_request | Parses the headers of an HTTP request in `str` and stores the results in `req_method`, `req_path`, `ver`, and `req_headers`.
headers_parse_response | Parses the headers of an HTTP response in `str` and stores the results in `ver`, `status_code`, `reason_phrase`, and `headers`.
headers_parse_status_line | Parses the HTTP Status-Line string in `status_line` into `ver`, `status_code`, and `reason_phrase`.
tld_domain_is_public_suffix | Looks whether the `domain` passed as argument is a public domain suffix (.org, .com, .co.uk, etc) or not.
tld_get_base_domain | Finds the base domain for a given `hostname`.
uri_copy | As of 3.4.0 this will detect the default ports of HTTP(s) and WS(S) URIs when copying and set it to the default port of the new scheme. So for example copying `http://localhost:80` while changing the scheme to https will result in `https://localhost:443`.
uri_decode_data_uri | Decodes the given data URI and returns its contents and `content_type`.
uri_equal | Tests whether or not `uri1` and `uri2` are equal in all parts.
websocket_client_prepare_handshake | Adds the necessary headers to `msg` to request a WebSocket handshake including supported WebSocket extensions.
websocket_client_verify_handshake | Looks at the response status code and headers in `msg` and determines if they contain a valid WebSocket handshake response (given the handshake request in `msg`‘s request headers).
websocket_server_check_handshake | Examines the method and request headers in `msg` and determines whether `msg` contains a valid handshake request.
websocket_server_process_handshake | Examines the method and request headers in `msg` and (assuming `msg` contains a valid handshake request), fills in the handshake response.

#### Function Macros

CHECK_VERSION | Macro to test the version of libsoup being compiled against.
DEPRECATED_FOR | Marks a symbol as deprecated in favor of another symbol.
DEPRECATED_IN_3_0_FOR | A macro used to indicate a symbol was deprecated in this version with a replacement.
DEPRECATED_IN_3_2_FOR | A macro used to indicate a symbol was deprecated in this version with a replacement.
DEPRECATED_IN_3_4_FOR | A macro used to indicate a symbol was deprecated in this version with a replacement.
DEPRECATED_IN_3_6_FOR | A macro used to indicate a symbol was deprecated in this version with a replacement.
UNAVAILABLE | Marks a symbol unavailable before the given major and minor version.

#### Constants

COOKIE_MAX_AGE_ONE_DAY | A constant corresponding to 1 day.
COOKIE_MAX_AGE_ONE_HOUR | A constant corresponding to 1 hour.
COOKIE_MAX_AGE_ONE_WEEK | A constant corresponding to 1 week.
COOKIE_MAX_AGE_ONE_YEAR | A constant corresponding to 1 year.
FORM_MIME_TYPE_MULTIPART | A macro containing the value `multipart/form-data`; the MIME type used for posting form data that contains files to be uploaded.
FORM_MIME_TYPE_URLENCODED | A macro containing the value `application/x-www-form-urlencoded`; the default MIME type for POSTing HTML form data.
HSTS_POLICY_MAX_AGE_PAST | An expiration date that is always in the past.
HTTP_URI_FLAGS | The set of `GUriFlags` libsoup expects all `GUri` to use.
MAJOR_VERSION | Like `soup_get_major_version()`, but from the headers used at application compile time, rather than from the library linked against at application run time.
MICRO_VERSION | Like `soup_get_micro_version()`, but from the headers used at application compile time, rather than from the library linked against at application run time.
MINOR_VERSION | Like `soup_get_minor_version()`, but from the headers used at application compile time, rather than from the library linked against at application run time.
VERSION_MIN_REQUIRED | A macro that should be defined by the user prior to including `libsoup.h`.