gi-soup-2.4.18: Libsoup bindings

Copyright Will Thompson Iñaki García Etxebarria and Jonas Platte LGPL-2.1 Iñaki García Etxebarria (inaki@blueleaf.cc) None Haskell2010

GI.Soup.Objects.Session

Description

No description available in the introspection data.

Synopsis

# Exported types

newtype Session Source #

Memory-managed wrapper type.

Constructors

 Session (ManagedPtr Session)
Instances
 Source # Instance detailsDefined in GI.Soup.Objects.Session Methods Source # Instance detailsDefined in GI.Soup.Objects.Session Source # Instance detailsDefined in GI.Soup.Objects.Session type ParentTypes Session = Object ': ([] :: [Type])

class (GObject o, IsDescendantOf Session o) => IsSession o Source #

Type class for types which can be safely cast to Session, for instance with toSession.

Instances
 Source # Instance detailsDefined in GI.Soup.Objects.Session

toSession :: (MonadIO m, IsSession o) => o -> m Session Source #

Cast to Session, for types for which this is known to be safe. For general casts, use castTo.

A convenience alias for Nothing :: Maybe Session.

# Methods

## abort

Arguments

 :: (HasCallStack, MonadIO m, IsSession a) => a session: the session -> m ()

Cancels all pending requests in session and closes all idle persistent connections.

The message cancellation has the same semantics as with sessionCancelMessage; asynchronous requests on a SessionAsync will have their callback called before sessionAbort returns. Requests on a plain Session will not.

Arguments

 :: (HasCallStack, MonadIO m, IsSession a, IsSessionFeature b) => a session: a Session -> b feature: an object that implements SessionFeature -> m ()

Adds feature's functionality to session. You can also add a feature to the session at construct time by using the SOUP_SESSION_ADD_FEATURE property.

See the main Session documentation for information on what features are present in sessions by default.

Since: 2.24

Arguments

 :: (HasCallStack, MonadIO m, IsSession a) => a session: a Session -> GType featureType: a GType -> m ()

If featureType is the type of a class that implements SessionFeature, this creates a new feature of that type and adds it to session as with sessionAddFeature. You can use this when you don't need to customize the new feature in any way.

If featureType is not a SessionFeature type, this gives each existing feature on session the chance to accept featureType as a "subfeature". This can be used to add new Auth or Request types, for instance.

You can also add a feature to the session at construct time by using the SOUP_SESSION_ADD_FEATURE_BY_TYPE property.

See the main Session documentation for information on what features are present in sessions by default.

Since: 2.24

## cancelMessage

Arguments

 :: (HasCallStack, MonadIO m, IsSession a, IsMessage b) => a session: a Session -> b msg: the message to cancel -> Word32 statusCode: status code to set on msg (generally StatusCancelled) -> m ()

Causes session to immediately finish processing msg (regardless of its current state) with a final status_code of statusCode. You may call this at any time after handing msg off to session; if session has started sending the request but has not yet received the complete response, then it will close the request's connection. Note that with requests that have side effects (eg, <literal>POST</literal>, <literal>PUT</literal>, <literal>DELETE</literal>) it is possible that you might cancel the request after the server acts on it, but before it returns a response, leaving the remote resource in an unknown state.

If the message is cancelled while its response body is being read, then the response body in msg will be left partially-filled-in. The response headers, on the other hand, will always be either empty or complete.

Beware that with the deprecated SessionAsync, messages queued with sessionQueueMessage will have their callbacks invoked before sessionCancelMessage returns. The plain Session does not have this behavior; cancelling an asynchronous message will merely queue its callback to be run after returning to the main loop.

## connectAsync

Arguments

 :: (HasCallStack, MonadIO m, IsSession a, IsCancellable b) => a session: a Session -> URI uri: a URI to connect to -> Maybe b cancellable: a Cancellable -> Maybe SessionConnectProgressCallback progressCallback: a SessionConnectProgressCallback which will be called for every network event that occurs during the connection. -> Maybe AsyncReadyCallback callback: the callback to invoke when the operation finishes -> m ()

Start a connection to uri. The operation can be monitored by providing a progressCallback and finishes when the connection is done or an error ocurred.

Call sessionConnectFinish to get the IOStream to communicate with the server.

Since: 2.62

## connectFinish

Arguments

 :: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b) => a session: a Session -> b result: the AsyncResult passed to your callback -> m IOStream Returns: a new IOStream, or Nothing on error. (Can throw GError)

Gets the IOStream created for the connection to communicate with the server.

Since: 2.62

## getAsyncContext

Arguments

 :: (HasCallStack, MonadIO m, IsSession a) => a session: a Session -> m (Maybe MainContext) Returns: session's MainContext, which may be Nothing

Gets session's Session:async-context. This does not add a ref to the context, so you will need to ref it yourself if you want it to outlive its session.

For a modern Session, this will always just return the thread-default MainContext, and so is not especially useful.

## getFeature

Arguments

 :: (HasCallStack, MonadIO m, IsSession a) => a session: a Session -> GType featureType: the GType of the feature to get -> m (Maybe SessionFeature) Returns: a SessionFeature, or Nothing. The feature is owned by session.

Gets the first feature in session of type featureType. For features where there may be more than one feature of a given type, use sessionGetFeatures.

Since: 2.26

## getFeatureForMessage

Arguments

 :: (HasCallStack, MonadIO m, IsSession a, IsMessage b) => a session: a Session -> GType featureType: the GType of the feature to get -> b msg: a Message -> m (Maybe SessionFeature) Returns: a SessionFeature, or Nothing. The feature is owned by session.

Gets the first feature in session of type featureType, provided that it is not disabled for msg. As with sessionGetFeature, this should only be used for features where featureType is only expected to match a single feature. In particular, if there are two matching features, and the first is disabled on msg, and the second is not, then this will return Nothing, not the second feature.

Since: 2.28

## getFeatures

Arguments

 :: (HasCallStack, MonadIO m, IsSession a) => a session: a Session -> GType featureType: the GType of the class of features to get -> m [SessionFeature] Returns: a list of features. You must free the list, but not its contents

Generates a list of session's features of type featureType. (If you want to see all features, you can pass SOUP_TYPE_SESSION_FEATURE for featureType.)

Since: 2.26

## hasFeature

Arguments

 :: (HasCallStack, MonadIO m, IsSession a) => a session: a Session -> GType featureType: the GType of the class of features to check for -> m Bool Returns: True or False

Tests if session has at a feature of type featureType (which can be the type of either a SessionFeature, or else a subtype of some class managed by another feature, such as Auth or Request).

Since: 2.42

## new

Arguments

 :: (HasCallStack, MonadIO m) => m Session Returns: the new session.

Creates a Session with the default options.

Since: 2.42

## pauseMessage

Arguments

 :: (HasCallStack, MonadIO m, IsSession a, IsMessage b) => a session: a Session -> b msg: a Message currently running on session -> m ()

Pauses HTTP I/O on msg. Call sessionUnpauseMessage to resume I/O.

This may only be called for asynchronous messages (those sent on a SessionAsync or using sessionQueueMessage).

## prefetchDns

Arguments

 :: (HasCallStack, MonadIO m, IsSession a, IsCancellable b) => a session: a Session -> Text hostname: a hostname to be resolved -> Maybe b cancellable: a Cancellable object, or Nothing -> Maybe AddressCallback callback: callback to call with the result, or Nothing -> m ()

Tells session that an URI from the given hostname may be requested shortly, and so the session can try to prepare by resolving the domain name in advance, in order to work more quickly once the URI is actually requested.

If cancellable is non-Nothing, it can be used to cancel the resolution. callback will still be invoked in this case, with a status of StatusCancelled.

Since: 2.38

## prepareForUri

Arguments

 :: (HasCallStack, MonadIO m, IsSession a) => a session: a Session -> URI uri: a URI which may be required -> m ()

Deprecated: (Since version 2.38)use sessionPrefetchDns instead

Tells session that uri may be requested shortly, and so the session can try to prepare (resolving the domain name, obtaining proxy address, etc.) in order to work more quickly once the URI is actually requested.

Since: 2.30

## queueMessage

Arguments

 :: (HasCallStack, MonadIO m, IsSession a, IsMessage b) => a session: a Session -> b msg: the message to queue -> Maybe SessionCallback callback: a SessionCallback which will be called after the message completes or when an unrecoverable error occurs. -> m ()

Queues the message msg for asynchronously sending the request and receiving a response in the current thread-default MainContext. If msg has been processed before, any resources related to the time it was last sent are freed.

Upon message completion, the callback specified in callback will be invoked. If after returning from this callback the message has not been requeued, msg will be unreffed.

(The behavior above applies to a plain Session; if you are using SessionAsync or SessionSync, then the MainContext that is used depends on the settings of Session:async-context and Session:use-thread-context, and for SessionSync, the message will actually be sent and processed in another thread, with only the final callback occurring in the indicated MainContext.)

Contrast this method with sessionSendAsync, which also asynchronously sends a message, but returns before reading the response body, and allows you to read the response via a InputStream.

## redirectMessage

Arguments

 :: (HasCallStack, MonadIO m, IsSession a, IsMessage b) => a session: the session -> b msg: a Message that has received a 3xx response -> m Bool Returns: True if a redirection was applied, False if not (eg, because there was no Location header, or it could not be parsed).

Updates msg's URI according to its status code and "Location" header, and requeues it on session. Use this when you have set MessageFlagsNoRedirect on a message, but have decided to allow a particular redirection to occur, or if you want to allow a redirection that Session will not perform automatically (eg, redirecting a non-safe method such as DELETE).

If msg's status code indicates that it should be retried as a GET request, then msg will be modified accordingly.

If msg has already been redirected too many times, this will cause it to fail with StatusTooManyRedirects.

Since: 2.38

## removeFeature

Arguments

 :: (HasCallStack, MonadIO m, IsSession a, IsSessionFeature b) => a session: a Session -> b feature: a feature that has previously been added to session -> m ()

Removes feature's functionality from session.

Since: 2.24

## removeFeatureByType

Arguments

 :: (HasCallStack, MonadIO m, IsSession a) => a session: a Session -> GType featureType: a GType -> m ()

Removes all features of type featureType (or any subclass of featureType) from session. You can also remove standard features from the session at construct time by using the SOUP_SESSION_REMOVE_FEATURE_BY_TYPE property.

Since: 2.24

## request

Arguments

 :: (HasCallStack, MonadIO m, IsSession a) => a session: a Session -> Text uriString: a URI, in string form -> m Request Returns: a new Request, or Nothing on error. (Can throw GError)

Creates a Request for retrieving uriString.

Since: 2.42

## requestHttp

Arguments

 :: (HasCallStack, MonadIO m, IsSession a) => a session: a Session -> Text method: an HTTP method -> Text uriString: a URI, in string form -> m RequestHTTP Returns: a new RequestHTTP, or Nothing on error. (Can throw GError)

Creates a Request for retrieving uriString, which must be an "http" or "https" URI (or another protocol listed in session's Session:http-aliases or Session:https-aliases).

Since: 2.42

## requestHttpUri

Arguments

 :: (HasCallStack, MonadIO m, IsSession a) => a session: a Session -> Text method: an HTTP method -> URI uri: a URI representing the URI to retrieve -> m RequestHTTP Returns: a new RequestHTTP, or Nothing on error. (Can throw GError)

Creates a Request for retrieving uri, which must be an "http" or "https" URI (or another protocol listed in session's Session:http-aliases or Session:https-aliases).

Since: 2.42

## requestUri

Arguments

 :: (HasCallStack, MonadIO m, IsSession a) => a session: a Session -> URI uri: a URI representing the URI to retrieve -> m Request Returns: a new Request, or Nothing on error. (Can throw GError)

Creates a Request for retrieving uri.

Since: 2.42

## requeueMessage

Arguments

 :: (HasCallStack, MonadIO m, IsSession a, IsMessage b) => a session: a Session -> b msg: the message to requeue -> m ()

This causes msg to be placed back on the queue to be attempted again.

## send

Arguments

 :: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c) => a session: a Session -> b msg: a Message -> Maybe c cancellable: a Cancellable -> m InputStream Returns: a InputStream for reading the response body, or Nothing on error. (Can throw GError)

Synchronously sends msg and waits for the beginning of a response. On success, a InputStream will be returned which you can use to read the response body. ("Success" here means only that an HTTP response was received and understood; it does not necessarily mean that a 2xx class status code was received.)

If non-Nothing, cancellable can be used to cancel the request; sessionSend will return a IOErrorEnumCancelled error. Note that with requests that have side effects (eg, <literal>POST</literal>, <literal>PUT</literal>, <literal>DELETE</literal>) it is possible that you might cancel the request after the server acts on it, but before it returns a response, leaving the remote resource in an unknown state.

If msg is requeued due to a redirect or authentication, the initial (3xx/401/407) response body will be suppressed, and sessionSend will only return once a final response has been received.

Contrast this method with sessionSendMessage, which also synchronously sends a Message, but doesn't return until the response has been completely read.

(Note that this method cannot be called on the deprecated SessionAsync subclass.)

Since: 2.42

## sendAsync

Arguments

 :: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c) => a session: a Session -> b msg: a Message -> Maybe c cancellable: a Cancellable -> Maybe AsyncReadyCallback callback: the callback to invoke -> m ()

Asynchronously sends msg and waits for the beginning of a response. When callback is called, then either msg has been sent, and its response headers received, or else an error has occurred. Call sessionSendFinish to get a InputStream for reading the response body.

See sessionSend for more details on the general semantics.

Contrast this method with sessionQueueMessage, which also asynchronously sends a Message, but doesn't invoke its callback until the response has been completely read.

(Note that this method cannot be called on the deprecated SessionSync subclass, and can only be called on SessionAsync if you have set the Session:use-thread-context property.)

Since: 2.42

## sendFinish

Arguments

 :: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b) => a session: a Session -> b result: the AsyncResult passed to your callback -> m InputStream Returns: a InputStream for reading the response body, or Nothing on error. (Can throw GError)

Gets the response to a sessionSendAsync call and (if successful), returns a InputStream that can be used to read the response body.

Since: 2.42

## sendMessage

Arguments

 :: (HasCallStack, MonadIO m, IsSession a, IsMessage b) => a session: a Session -> b msg: the message to send -> m Word32 Returns: the HTTP status code of the response

Synchronously send msg. This call will not return until the transfer is finished successfully or there is an unrecoverable error.

Unlike with sessionQueueMessage, msg is not freed upon return.

(Note that if you call this method on a SessionAsync, it will still use asynchronous I/O internally, running the glib main loop to process the message, which may also cause other events to be processed.)

Contrast this method with sessionSend, which also synchronously sends a message, but returns before reading the response body, and allows you to read the response via a InputStream.

## stealConnection

Arguments

 :: (HasCallStack, MonadIO m, IsSession a, IsMessage b) => a session: a Session -> b msg: the message whose connection is to be stolen -> m IOStream Returns: the IOStream formerly associated with msg (or Nothing if msg was no longer associated with a connection). No guarantees are made about what kind of IOStream is returned.

"Steals" the HTTP connection associated with msg from session. This happens immediately, regardless of the current state of the connection, and msg's callback will not be called. You can steal the connection from a Message signal handler if you need to wait for part or all of the response to be received first.

Calling this function may cause msg to be freed if you are not holding any other reference to it.

Since: 2.50

## unpauseMessage

Arguments

 :: (HasCallStack, MonadIO m, IsSession a, IsMessage b) => a session: a Session -> b msg: a Message currently running on session -> m ()

Resumes HTTP I/O on msg. Use this to resume after calling sessionPauseMessage.

If msg is being sent via blocking I/O, this will resume reading or writing immediately. If msg is using non-blocking I/O, then reading or writing won't resume until you return to the main loop.

This may only be called for asynchronous messages (those sent on a SessionAsync or using sessionQueueMessage).

## websocketConnectAsync

Arguments

 :: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c) => a session: a Session -> b msg: Message indicating the WebSocket server to connect to -> Maybe Text origin: origin of the connection -> Maybe [Text] protocols: a Nothing-terminated array of protocols supported -> Maybe c cancellable: a Cancellable -> Maybe AsyncReadyCallback callback: the callback to invoke -> m ()

Asynchronously creates a WebsocketConnection to communicate with a remote server.

All necessary WebSocket-related headers will be added to msg, and it will then be sent and asynchronously processed normally (including handling of redirection and HTTP authentication).

If the server returns "101 Switching Protocols", then msg's status code and response headers will be updated, and then the WebSocket handshake will be completed. On success, sessionWebsocketConnectFinish will return a new WebsocketConnection. On failure it will return a GError.

If the server returns a status other than "101 Switching Protocols", then msg will contain the complete response headers and body from the server's response, and sessionWebsocketConnectFinish will return WebsocketErrorNotWebsocket.

Since: 2.50

## websocketConnectFinish

Arguments

 :: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b) => a session: a Session -> b result: the AsyncResult passed to your callback -> m WebsocketConnection Returns: a new WebsocketConnection, or Nothing on error. (Can throw GError)

Gets the WebsocketConnection response to a sessionWebsocketConnectAsync call and (if successful), returns a WebsocketConnection that can be used to communicate with the server.

Since: 2.50

## wouldRedirect

Arguments

 :: (HasCallStack, MonadIO m, IsSession a, IsMessage b) => a session: a Session -> b msg: a Message that has response headers -> m Bool Returns: whether msg would be redirected

Checks if msg contains a response that would cause session to redirect it to a new URL (ignoring msg's MessageFlagsNoRedirect flag, and the number of times it has already been redirected).

Since: 2.38

# Properties

## acceptLanguage

If non-Nothing, the value to use for the "Accept-Language" header on Message<!-- -->s sent from this session.

Setting this will disable Session:accept-language-auto.

Since: 2.30

clearSessionAcceptLanguage :: (MonadIO m, IsSession o) => o -> m () Source #

Set the value of the “accept-language” property to Nothing. When overloading is enabled, this is equivalent to

clear #acceptLanguage


Construct a GValueConstruct with valid value for the “accept-language” property. This is rarely needed directly, but it is used by new.

getSessionAcceptLanguage :: (MonadIO m, IsSession o) => o -> m (Maybe Text) Source #

Get the value of the “accept-language” property. When overloading is enabled, this is equivalent to

get session #acceptLanguage


setSessionAcceptLanguage :: (MonadIO m, IsSession o) => o -> Text -> m () Source #

Set the value of the “accept-language” property. When overloading is enabled, this is equivalent to

set session [ #acceptLanguage := value ]


## acceptLanguageAuto

If True, Session will automatically set the string for the "Accept-Language" header on every Message sent, based on the return value of getLanguageNames.

Setting this will override any previous value of Session:accept-language.

Since: 2.30

Construct a GValueConstruct with valid value for the “accept-language-auto” property. This is rarely needed directly, but it is used by new.

getSessionAcceptLanguageAuto :: (MonadIO m, IsSession o) => o -> m Bool Source #

Get the value of the “accept-language-auto” property. When overloading is enabled, this is equivalent to

get session #acceptLanguageAuto


setSessionAcceptLanguageAuto :: (MonadIO m, IsSession o) => o -> Bool -> m () Source #

Set the value of the “accept-language-auto” property. When overloading is enabled, this is equivalent to

set session [ #acceptLanguageAuto := value ]


## asyncContext

The MainContext that miscellaneous session-related asynchronous callbacks are invoked on. (Eg, setting Session:idle-timeout will add a timeout source on this context.)

For a plain Session, this property is always set to the MainContext that is the thread-default at the time the session was created, and cannot be overridden. For the deprecated Session subclasses, the default value is Nothing, meaning to use the global default MainContext.

If Session:use-thread-context is False, this context will also be used for asynchronous HTTP I/O.

Construct a GValueConstruct with valid value for the “async-context” property. This is rarely needed directly, but it is used by new.

getSessionAsyncContext :: (MonadIO m, IsSession o) => o -> m (Ptr ()) Source #

Get the value of the “async-context” property. When overloading is enabled, this is equivalent to

get session #asyncContext


## httpAliases

A Nothing-terminated array of URI schemes that should be considered to be aliases for "http". Eg, if this included <literal>"dav"</literal>, than a URI of <literal>dav://example.com/path</literal> would be treated identically to <literal>http://example.com/path</literal>.

In a plain Session, the default value is Nothing, meaning that only "http" is recognized as meaning "http". In SessionAsync and SessionSync, for backward compatibility, the default value is an array containing the single element <literal>"*"</literal>, a special value which means that any scheme except "https" is considered to be an alias for "http".

See also Session:https-aliases.

Since: 2.38

clearSessionHttpAliases :: (MonadIO m, IsSession o) => o -> m () Source #

Set the value of the “http-aliases” property to Nothing. When overloading is enabled, this is equivalent to

clear #httpAliases


Construct a GValueConstruct with valid value for the “http-aliases” property. This is rarely needed directly, but it is used by new.

getSessionHttpAliases :: (MonadIO m, IsSession o) => o -> m (Maybe [Text]) Source #

Get the value of the “http-aliases” property. When overloading is enabled, this is equivalent to

get session #httpAliases


setSessionHttpAliases :: (MonadIO m, IsSession o) => o -> [Text] -> m () Source #

Set the value of the “http-aliases” property. When overloading is enabled, this is equivalent to

set session [ #httpAliases := value ]


## httpsAliases

A comma-delimited list of URI schemes that should be considered to be aliases for "https". See Session:http-aliases for more information.

The default value is Nothing, meaning that no URI schemes are considered aliases for "https".

Since: 2.38

clearSessionHttpsAliases :: (MonadIO m, IsSession o) => o -> m () Source #

Set the value of the “https-aliases” property to Nothing. When overloading is enabled, this is equivalent to

clear #httpsAliases


Construct a GValueConstruct with valid value for the “https-aliases” property. This is rarely needed directly, but it is used by new.

getSessionHttpsAliases :: (MonadIO m, IsSession o) => o -> m (Maybe [Text]) Source #

Get the value of the “https-aliases” property. When overloading is enabled, this is equivalent to

get session #httpsAliases


setSessionHttpsAliases :: (MonadIO m, IsSession o) => o -> [Text] -> m () Source #

Set the value of the “https-aliases” property. When overloading is enabled, this is equivalent to

set session [ #httpsAliases := value ]


## idleTimeout

Connection lifetime (in seconds) when idle. Any connection left idle longer than this will be closed.

Although you can change this property at any time, it will only affect newly-created connections, not currently-open ones. You can call sessionAbort after setting this if you want to ensure that all future connections will have this timeout value.

Note that the default value of 60 seconds only applies to plain SoupSessions. If you are using SessionAsync or SessionSync, the default value is 0 (meaning idle connections will never time out).

Since: 2.24

Construct a GValueConstruct with valid value for the “idle-timeout” property. This is rarely needed directly, but it is used by new.

getSessionIdleTimeout :: (MonadIO m, IsSession o) => o -> m Word32 Source #

Get the value of the “idle-timeout” property. When overloading is enabled, this is equivalent to

get session #idleTimeout


setSessionIdleTimeout :: (MonadIO m, IsSession o) => o -> Word32 -> m () Source #

Set the value of the “idle-timeout” property. When overloading is enabled, this is equivalent to

set session [ #idleTimeout := value ]


Sets the Address to use for the client side of the connection.

Use this property if you want for instance to bind the local socket to a specific IP address.

Since: 2.42

constructSessionLocalAddress :: (IsSession o, IsAddress a) => a -> IO (GValueConstruct o) Source #

Construct a GValueConstruct with valid value for the “local-address” property. This is rarely needed directly, but it is used by new.

Get the value of the “local-address” property. When overloading is enabled, this is equivalent to

get session #localAddress


## maxConns

No description available in the introspection data.

Construct a GValueConstruct with valid value for the “max-conns” property. This is rarely needed directly, but it is used by new.

getSessionMaxConns :: (MonadIO m, IsSession o) => o -> m Int32 Source #

Get the value of the “max-conns” property. When overloading is enabled, this is equivalent to

get session #maxConns


setSessionMaxConns :: (MonadIO m, IsSession o) => o -> Int32 -> m () Source #

Set the value of the “max-conns” property. When overloading is enabled, this is equivalent to

set session [ #maxConns := value ]


## maxConnsPerHost

No description available in the introspection data.

Construct a GValueConstruct with valid value for the “max-conns-per-host” property. This is rarely needed directly, but it is used by new.

getSessionMaxConnsPerHost :: (MonadIO m, IsSession o) => o -> m Int32 Source #

Get the value of the “max-conns-per-host” property. When overloading is enabled, this is equivalent to

get session #maxConnsPerHost


setSessionMaxConnsPerHost :: (MonadIO m, IsSession o) => o -> Int32 -> m () Source #

Set the value of the “max-conns-per-host” property. When overloading is enabled, this is equivalent to

set session [ #maxConnsPerHost := value ]


## proxyResolver

A ProxyResolver to use with this session. Setting this will clear the Session:proxy-uri property, and remove any <type>SoupProxyURIResolver</type> features that have been added to the session.

By default, in a plain Session, this is set to the default ProxyResolver, but you can set it to Nothing if you don't want to use proxies, or set it to your own ProxyResolver if you want to control what proxies get used.

Since: 2.42

clearSessionProxyResolver :: (MonadIO m, IsSession o) => o -> m () Source #

Set the value of the “proxy-resolver” property to Nothing. When overloading is enabled, this is equivalent to

clear #proxyResolver


Construct a GValueConstruct with valid value for the “proxy-resolver” property. This is rarely needed directly, but it is used by new.

getSessionProxyResolver :: (MonadIO m, IsSession o) => o -> m (Maybe ProxyResolver) Source #

Get the value of the “proxy-resolver” property. When overloading is enabled, this is equivalent to

get session #proxyResolver


setSessionProxyResolver :: (MonadIO m, IsSession o, IsProxyResolver a) => o -> a -> m () Source #

Set the value of the “proxy-resolver” property. When overloading is enabled, this is equivalent to

set session [ #proxyResolver := value ]


## proxyUri

A proxy to use for all http and https requests in this session. Setting this will clear the Session:proxy-resolver property, and remove any <type>SoupProxyURIResolver</type> features that have been added to the session. Setting this property will also cancel all currently pending messages.

Note that Session will normally handle looking up the user's proxy settings for you; you should only use Session:proxy-uri if you need to override the user's normal proxy settings.

Also note that this proxy will be used for <emphasis>all</emphasis> requests; even requests to <literal>localhost</literal>. If you need more control over proxies, you can create a SimpleProxyResolver and set the Session:proxy-resolver property.

clearSessionProxyUri :: (MonadIO m, IsSession o) => o -> m () Source #

Set the value of the “proxy-uri” property to Nothing. When overloading is enabled, this is equivalent to

clear #proxyUri


Construct a GValueConstruct with valid value for the “proxy-uri” property. This is rarely needed directly, but it is used by new.

getSessionProxyUri :: (MonadIO m, IsSession o) => o -> m (Maybe URI) Source #

Get the value of the “proxy-uri” property. When overloading is enabled, this is equivalent to

get session #proxyUri


setSessionProxyUri :: (MonadIO m, IsSession o) => o -> URI -> m () Source #

Set the value of the “proxy-uri” property. When overloading is enabled, this is equivalent to

set session [ #proxyUri := value ]


## sslCaFile

File containing SSL CA certificates.

If the specified file does not exist or cannot be read, then libsoup will print a warning, and then behave as though it had read in a empty CA file, meaning that all SSL certificates will be considered invalid.

clearSessionSslCaFile :: (MonadIO m, IsSession o) => o -> m () Source #

Set the value of the “ssl-ca-file” property to Nothing. When overloading is enabled, this is equivalent to

clear #sslCaFile


Construct a GValueConstruct with valid value for the “ssl-ca-file” property. This is rarely needed directly, but it is used by new.

getSessionSslCaFile :: (MonadIO m, IsSession o) => o -> m (Maybe Text) Source #

Get the value of the “ssl-ca-file” property. When overloading is enabled, this is equivalent to

get session #sslCaFile


setSessionSslCaFile :: (MonadIO m, IsSession o) => o -> Text -> m () Source #

Set the value of the “ssl-ca-file” property. When overloading is enabled, this is equivalent to

set session [ #sslCaFile := value ]


## sslStrict

Normally, if Session:tls-database is set (including if it was set via Session:ssl-use-system-ca-file or Session:ssl-ca-file), then libsoup will reject any certificate that is invalid (ie, expired) or that is not signed by one of the given CA certificates, and the Message will fail with the status StatusSslFailed.

If you set Session:ssl-strict to False, then all certificates will be accepted, and you will need to call messageGetHttpsStatus to distinguish valid from invalid certificates. (This can be used, eg, if you want to accept invalid certificates after giving some sort of warning.)

For a plain Session, if the session has no CA file or TLS database, and this property is True, then all certificates will be rejected. However, beware that the deprecated Session subclasses (SessionAsync and SessionSync) have the opposite behavior: if there is no CA file or TLS database, then all certificates are always accepted, and this property has no effect.

Since: 2.30

Construct a GValueConstruct with valid value for the “ssl-strict” property. This is rarely needed directly, but it is used by new.

getSessionSslStrict :: (MonadIO m, IsSession o) => o -> m Bool Source #

Get the value of the “ssl-strict” property. When overloading is enabled, this is equivalent to

get session #sslStrict


setSessionSslStrict :: (MonadIO m, IsSession o) => o -> Bool -> m () Source #

Set the value of the “ssl-strict” property. When overloading is enabled, this is equivalent to

set session [ #sslStrict := value ]


## sslUseSystemCaFile

Setting this to True is equivalent to setting Session:tls-database to the default system CA database. (and likewise, setting Session:tls-database to the default database by hand will cause this property to become True).

Setting this to False (when it was previously True) will clear the Session:tls-database field.

See Session:ssl-strict for more information on how https certificate validation is handled.

Note that the default value of True only applies to plain SoupSessions. If you are using SessionAsync or SessionSync, the default value is False, for backward compatibility.

Since: 2.38

Construct a GValueConstruct with valid value for the “ssl-use-system-ca-file” property. This is rarely needed directly, but it is used by new.

getSessionSslUseSystemCaFile :: (MonadIO m, IsSession o) => o -> m Bool Source #

Get the value of the “ssl-use-system-ca-file” property. When overloading is enabled, this is equivalent to

get session #sslUseSystemCaFile


setSessionSslUseSystemCaFile :: (MonadIO m, IsSession o) => o -> Bool -> m () Source #

Set the value of the “ssl-use-system-ca-file” property. When overloading is enabled, this is equivalent to

set session [ #sslUseSystemCaFile := value ]


## timeout

The timeout (in seconds) for socket I/O operations (including connecting to a server, and waiting for a reply to an HTTP request).

Although you can change this property at any time, it will only affect newly-created connections, not currently-open ones. You can call sessionAbort after setting this if you want to ensure that all future connections will have this timeout value.

Note that the default value of 60 seconds only applies to plain SoupSessions. If you are using SessionAsync or SessionSync, the default value is 0 (meaning socket I/O will not time out).

Not to be confused with Session:idle-timeout (which is the length of time that idle persistent connections will be kept open).

Construct a GValueConstruct with valid value for the “timeout” property. This is rarely needed directly, but it is used by new.

getSessionTimeout :: (MonadIO m, IsSession o) => o -> m Word32 Source #

Get the value of the “timeout” property. When overloading is enabled, this is equivalent to

get session #timeout


setSessionTimeout :: (MonadIO m, IsSession o) => o -> Word32 -> m () Source #

Set the value of the “timeout” property. When overloading is enabled, this is equivalent to

set session [ #timeout := value ]


## tlsDatabase

Sets the TlsDatabase to use for validating SSL/TLS certificates.

Note that setting the Session:ssl-ca-file or Session:ssl-use-system-ca-file property will cause this property to be set to a TlsDatabase corresponding to the indicated file or system default.

See Session:ssl-strict for more information on how https certificate validation is handled.

If you are using a plain Session then Session:ssl-use-system-ca-file will be True by default, and so this property will be a copy of the system CA database. If you are using SessionAsync or SessionSync, this property will be Nothing by default.

Since: 2.38

clearSessionTlsDatabase :: (MonadIO m, IsSession o) => o -> m () Source #

Set the value of the “tls-database” property to Nothing. When overloading is enabled, this is equivalent to

clear #tlsDatabase


constructSessionTlsDatabase :: (IsSession o, IsTlsDatabase a) => a -> IO (GValueConstruct o) Source #

Construct a GValueConstruct with valid value for the “tls-database” property. This is rarely needed directly, but it is used by new.

getSessionTlsDatabase :: (MonadIO m, IsSession o) => o -> m (Maybe TlsDatabase) Source #

Get the value of the “tls-database” property. When overloading is enabled, this is equivalent to

get session #tlsDatabase


setSessionTlsDatabase :: (MonadIO m, IsSession o, IsTlsDatabase a) => o -> a -> m () Source #

Set the value of the “tls-database” property. When overloading is enabled, this is equivalent to

set session [ #tlsDatabase := value ]


## tlsInteraction

A TlsInteraction object that will be passed on to any GTlsConnections created by the session. (This can be used to provide client-side certificates, for example.)

Since: 2.48

clearSessionTlsInteraction :: (MonadIO m, IsSession o) => o -> m () Source #

Set the value of the “tls-interaction” property to Nothing. When overloading is enabled, this is equivalent to

clear #tlsInteraction


Construct a GValueConstruct with valid value for the “tls-interaction” property. This is rarely needed directly, but it is used by new.

getSessionTlsInteraction :: (MonadIO m, IsSession o) => o -> m (Maybe TlsInteraction) Source #

Get the value of the “tls-interaction” property. When overloading is enabled, this is equivalent to

get session #tlsInteraction


setSessionTlsInteraction :: (MonadIO m, IsSession o, IsTlsInteraction a) => o -> a -> m () Source #

Set the value of the “tls-interaction” property. When overloading is enabled, this is equivalent to

set session [ #tlsInteraction := value ]


## useNtlm

Whether or not to use NTLM authentication.

Construct a GValueConstruct with valid value for the “use-ntlm” property. This is rarely needed directly, but it is used by new.

getSessionUseNtlm :: (MonadIO m, IsSession o) => o -> m Bool Source #

Get the value of the “use-ntlm” property. When overloading is enabled, this is equivalent to

get session #useNtlm


setSessionUseNtlm :: (MonadIO m, IsSession o) => o -> Bool -> m () Source #

Set the value of the “use-ntlm” property. When overloading is enabled, this is equivalent to

set session [ #useNtlm := value ]


If True (which it always is on a plain Session), asynchronous HTTP requests in this session will run in whatever the thread-default MainContext is at the time they are started, rather than always occurring in Session:async-context.

Since: 2.38

Construct a GValueConstruct with valid value for the “use-thread-context” property. This is rarely needed directly, but it is used by new.

getSessionUseThreadContext :: (MonadIO m, IsSession o) => o -> m Bool Source #

Get the value of the “use-thread-context” property. When overloading is enabled, this is equivalent to

get session #useThreadContext


setSessionUseThreadContext :: (MonadIO m, IsSession o) => o -> Bool -> m () Source #

Set the value of the “use-thread-context” property. When overloading is enabled, this is equivalent to

set session [ #useThreadContext := value ]


## userAgent

If non-Nothing, the value to use for the "User-Agent" header on Message<!-- -->s sent from this session.

RFC 2616 says: "The User-Agent request-header field contains information about the user agent originating the request. This is for statistical purposes, the tracing of protocol violations, and automated recognition of user agents for the sake of tailoring responses to avoid particular user agent limitations. User agents SHOULD include this field with requests."

The User-Agent header contains a list of one or more product tokens, separated by whitespace, with the most significant product token coming first. The tokens must be brief, ASCII, and mostly alphanumeric (although "-", "_", and "." are also allowed), and may optionally include a "/" followed by a version string. You may also put comments, enclosed in parentheses, between or after the tokens.

If you set a Session:user_agent property that has trailing whitespace, Session will append its own product token (eg, "<literal>libsoup/2.3.2</literal>") to the end of the header for you.

clearSessionUserAgent :: (MonadIO m, IsSession o) => o -> m () Source #

Set the value of the “user-agent” property to Nothing. When overloading is enabled, this is equivalent to

clear #userAgent


Construct a GValueConstruct with valid value for the “user-agent” property. This is rarely needed directly, but it is used by new.

getSessionUserAgent :: (MonadIO m, IsSession o) => o -> m (Maybe Text) Source #

Get the value of the “user-agent” property. When overloading is enabled, this is equivalent to

get session #userAgent


setSessionUserAgent :: (MonadIO m, IsSession o) => o -> Text -> m () Source #

Set the value of the “user-agent” property. When overloading is enabled, this is equivalent to

set session [ #userAgent := value ]


# Signals

## authenticate

type C_SessionAuthenticateCallback = Ptr () -> Ptr Message -> Ptr Auth -> CInt -> Ptr () -> IO () Source #

Type for the callback on the (unwrapped) C side.

Arguments

 = Message msg: the Message being sent -> Auth auth: the Auth to authenticate -> Bool retrying: True if this is the second (or later) attempt -> IO ()

Emitted when the session requires authentication. If credentials are available call authAuthenticate on auth. If these credentials fail, the signal will be emitted again, with retrying set to True, which will continue until you return without calling authAuthenticate on auth.

Note that this may be emitted before msg's body has been fully read.

If you call sessionPauseMessage on msg before returning, then you can authenticate auth asynchronously (as long as you objectRef it to make sure it doesn't get destroyed), and then unpause msg when you are ready for it to continue.

Connect a signal handler for the “authenticate” signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after session #authenticate callback


Wrap the callback into a GClosure.

Generate a function pointer callable from C code, from a C_SessionAuthenticateCallback.

A convenience synonym for Nothing :: Maybe SessionAuthenticateCallback.

Connect a signal handler for the “authenticate” signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on session #authenticate callback


Wrap a SessionAuthenticateCallback into a C_SessionAuthenticateCallback.

## connectionCreated

type C_SessionConnectionCreatedCallback = Ptr () -> Ptr Object -> Ptr () -> IO () Source #

Type for the callback on the (unwrapped) C side.

Arguments

 = Object connection: the connection -> IO ()

Emitted when a new connection is created. This is an internal signal intended only to be used for debugging purposes, and may go away in the future.

Since: 2.30

Connect a signal handler for the “connection-created” signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after session #connectionCreated callback


Wrap the callback into a GClosure.

Generate a function pointer callable from C code, from a C_SessionConnectionCreatedCallback.

A convenience synonym for Nothing :: Maybe SessionConnectionCreatedCallback.

Connect a signal handler for the “connection-created” signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on session #connectionCreated callback


Wrap a SessionConnectionCreatedCallback into a C_SessionConnectionCreatedCallback.

## requestQueued

type C_SessionRequestQueuedCallback = Ptr () -> Ptr Message -> Ptr () -> IO () Source #

Type for the callback on the (unwrapped) C side.

Arguments

 = Message msg: the request that was queued -> IO ()

Emitted when a request is queued on session. (Note that "queued" doesn't just mean sessionQueueMessage; sessionSendMessage implicitly queues the message as well.)

When sending a request, first Session::request_queued is emitted, indicating that the session has become aware of the request.

Once a connection is available to send the request on, the session emits Session::request_started. Then, various Message signals are emitted as the message is processed. If the message is requeued, it will emit Message::restarted, which will then be followed by another Session::request_started and another set of Message signals when the message is re-sent.

Eventually, the message will emit Message::finished. Normally, this signals the completion of message processing. However, it is possible that the application will requeue the message from the "finished" handler (or equivalently, from the sessionQueueMessage callback). In that case, the process will loop back to Session::request_started.

Eventually, a message will reach "finished" and not be requeued. At that point, the session will emit Session::request_unqueued to indicate that it is done with the message.

To sum up: Session::request_queued and Session::request_unqueued are guaranteed to be emitted exactly once, but Session::request_started and Message::finished (and all of the other Message signals) may be invoked multiple times for a given message.

Since: 2.24

Connect a signal handler for the “request-queued” signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after session #requestQueued callback


Wrap the callback into a GClosure.

Generate a function pointer callable from C code, from a C_SessionRequestQueuedCallback.

A convenience synonym for Nothing :: Maybe SessionRequestQueuedCallback.

Connect a signal handler for the “request-queued” signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on session #requestQueued callback


Wrap a SessionRequestQueuedCallback into a C_SessionRequestQueuedCallback.

## requestStarted

type C_SessionRequestStartedCallback = Ptr () -> Ptr Message -> Ptr Socket -> Ptr () -> IO () Source #

Type for the callback on the (unwrapped) C side.

Arguments

 = Message msg: the request being sent -> Socket socket: the socket the request is being sent on -> IO ()

Deprecated: (Since version 2.50.)Use Message::starting instead.

Emitted just before a request is sent. See Session::request_queued for a detailed description of the message lifecycle within a session.

Connect a signal handler for the “request-started” signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after session #requestStarted callback


Wrap the callback into a GClosure.

Generate a function pointer callable from C code, from a C_SessionRequestStartedCallback.

A convenience synonym for Nothing :: Maybe SessionRequestStartedCallback.

Connect a signal handler for the “request-started” signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on session #requestStarted callback


Wrap a SessionRequestStartedCallback into a C_SessionRequestStartedCallback.

## requestUnqueued

type C_SessionRequestUnqueuedCallback = Ptr () -> Ptr Message -> Ptr () -> IO () Source #

Type for the callback on the (unwrapped) C side.

Arguments

 = Message msg: the request that was unqueued -> IO ()

Emitted when a request is removed from session's queue, indicating that session is done with it. See Session::request_queued for a detailed description of the message lifecycle within a session.

Since: 2.24

Connect a signal handler for the “request-unqueued” signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after session #requestUnqueued callback


Wrap the callback into a GClosure.

Generate a function pointer callable from C code, from a C_SessionRequestUnqueuedCallback.

A convenience synonym for Nothing :: Maybe SessionRequestUnqueuedCallback.

Connect a signal handler for the “request-unqueued” signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on session #requestUnqueued callback


Wrap a SessionRequestUnqueuedCallback into a C_SessionRequestUnqueuedCallback.

## tunneling

type C_SessionTunnelingCallback = Ptr () -> Ptr Object -> Ptr () -> IO () Source #

Type for the callback on the (unwrapped) C side.

Arguments

 = Object connection: the connection -> IO ()

Emitted when an SSL tunnel is being created on a proxy connection. This is an internal signal intended only to be used for debugging purposes, and may go away in the future.

Since: 2.30

Connect a signal handler for the “tunneling” signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after session #tunneling callback


Wrap the callback into a GClosure.

Generate a function pointer callable from C code, from a C_SessionTunnelingCallback.

A convenience synonym for Nothing :: Maybe SessionTunnelingCallback.

onSessionTunneling :: (IsSession a, MonadIO m) => a -> SessionTunnelingCallback -> m SignalHandlerId Source #

Connect a signal handler for the “tunneling” signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on session #tunneling callback


Wrap a SessionTunnelingCallback into a C_SessionTunnelingCallback.