GI.Soup.Objects.Session

No description available in the introspection data.

Exported types

newtype Session

Memory-managed wrapper type.

Constructors

Session (ManagedPtr Session)

Instances

Eq Session

Defined in GI.Soup.Objects.Session

Methods

(==) :: Session -> Session -> Bool

(/=) :: Session -> Session -> Bool

GObject Session

Defined in GI.Soup.Objects.Session

ManagedPtrNewtype Session

Defined in GI.Soup.Objects.Session

Methods

toManagedPtr :: Session -> ManagedPtr Session

TypedObject Session

Defined in GI.Soup.Objects.Session

Methods

glibType :: IO GType

HasParentTypes Session

Defined in GI.Soup.Objects.Session

IsGValue (Maybe Session)

Convert Session to and from GValue. See toGValue and fromGValue.

Defined in GI.Soup.Objects.Session

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe Session -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe Session)

type ParentTypes Session

Defined in GI.Soup.Objects.Session

type ParentTypes Session = '[Object]

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

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

Instances

(GObject o, IsDescendantOf Session o) => IsSession o

Defined in GI.Soup.Objects.Session

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

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

Methods

Click to display all available methods, including inherited ones

Methods

abort, addFeature, addFeatureByType, bindProperty, bindPropertyFull, cancelMessage, connectAsync, connectFinish, forceFloating, freezeNotify, getv, hasFeature, isFloating, notify, notifyByPspec, pauseMessage, prefetchDns, prepareForUri, queueMessage, redirectMessage, ref, refSink, removeFeature, removeFeatureByType, request, requestHttp, requestHttpUri, requestUri, requeueMessage, runDispose, send, sendAsync, sendFinish, sendMessage, stealConnection, stealData, stealQdata, thawNotify, unpauseMessage, unref, watchClosure, websocketConnectAsync, websocketConnectFinish, wouldRedirect.

Getters

getAsyncContext, getData, getFeature, getFeatureForMessage, getFeatures, getProperty, getQdata.

Setters

setData, setDataFull, setProperty.

abort

sessionAbort

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.

addFeature

sessionAddFeature

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

addFeatureByType

sessionAddFeatureByType

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

sessionCancelMessage

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

sessionConnectAsync

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

sessionConnectFinish

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

sessionGetAsyncContext

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

sessionGetFeature

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

sessionGetFeatureForMessage

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

sessionGetFeatures

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

sessionHasFeature

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

sessionNew

Arguments

:: (HasCallStack, MonadIO m)

=> m Session

Returns: the new session.

Creates a Session with the default options.

Since: 2.42

pauseMessage

sessionPauseMessage

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

sessionPrefetchDns

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

sessionPrepareForUri

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

sessionQueueMessage

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

sessionRedirectMessage

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

sessionRemoveFeature

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

sessionRemoveFeatureByType

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

sessionRequest

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

sessionRequestHttp

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

sessionRequestHttpUri

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

sessionRequestUri

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

sessionRequeueMessage

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

sessionSend

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

sessionSendAsync

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

sessionSendFinish

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

sessionSendMessage

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

sessionStealConnection

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

sessionUnpauseMessage

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

sessionWebsocketConnectAsync

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

sessionWebsocketConnectFinish

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

sessionWouldRedirect

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 Messages sent from this session.

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

Since: 2.30

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

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

clear #acceptLanguage

constructSessionAcceptLanguage :: (IsSession o, MonadIO m) => Text -> m (GValueConstruct o)

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)

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 ()

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

constructSessionAcceptLanguageAuto :: (IsSession o, MonadIO m) => Bool -> m (GValueConstruct o)

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

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 ()

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.

constructSessionAsyncContext :: (IsSession o, MonadIO m) => Ptr () -> m (GValueConstruct 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 ())

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 ()

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

clear #httpAliases

constructSessionHttpAliases :: (IsSession o, MonadIO m) => [Text] -> m (GValueConstruct o)

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])

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 ()

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 ()

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

clear #httpsAliases

constructSessionHttpsAliases :: (IsSession o, MonadIO m) => [Text] -> m (GValueConstruct o)

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])

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 ()

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

constructSessionIdleTimeout :: (IsSession o, MonadIO m) => Word32 -> m (GValueConstruct o)

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

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 ()

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

set session [ #idleTimeout := value ]

localAddress

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, MonadIO m, IsAddress a) => a -> m (GValueConstruct o)

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

getSessionLocalAddress :: (MonadIO m, IsSession o) => o -> m (Maybe Address)

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.

constructSessionMaxConns :: (IsSession o, MonadIO m) => Int32 -> m (GValueConstruct o)

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

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 ()

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.

constructSessionMaxConnsPerHost :: (IsSession o, MonadIO m) => Int32 -> m (GValueConstruct o)

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

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 ()

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 ()

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

clear #proxyResolver

constructSessionProxyResolver :: (IsSession o, MonadIO m, IsProxyResolver a) => a -> m (GValueConstruct o)

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)

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 ()

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 ()

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

clear #proxyUri

constructSessionProxyUri :: (IsSession o, MonadIO m) => URI -> m (GValueConstruct o)

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)

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 ()

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 ()

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

clear #sslCaFile

constructSessionSslCaFile :: (IsSession o, MonadIO m) => Text -> m (GValueConstruct o)

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)

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 ()

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 (tSessionAsync 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

constructSessionSslStrict :: (IsSession o, MonadIO m) => Bool -> m (GValueConstruct o)

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

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 ()

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.

If you are using SessionAsync or SessionSync, on libsoup older than 2.74.0, the default value is False, for backward compatibility.

Since: 2.38

constructSessionSslUseSystemCaFile :: (IsSession o, MonadIO m) => Bool -> m (GValueConstruct o)

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

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 ()

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).

constructSessionTimeout :: (IsSession o, MonadIO m) => Word32 -> m (GValueConstruct o)

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

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 ()

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, on libsoup older than 2.74.0, this property will be Nothing by default.

Since: 2.38

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

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

clear #tlsDatabase

constructSessionTlsDatabase :: (IsSession o, MonadIO m, IsTlsDatabase a) => a -> m (GValueConstruct o)

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)

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 ()

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 ()

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

clear #tlsInteraction

constructSessionTlsInteraction :: (IsSession o, MonadIO m, IsTlsInteraction a) => a -> m (GValueConstruct o)

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)

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 ()

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.

constructSessionUseNtlm :: (IsSession o, MonadIO m) => Bool -> m (GValueConstruct o)

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

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 ()

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

set session [ #useNtlm := value ]

useThreadContext

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

constructSessionUseThreadContext :: (IsSession o, MonadIO m) => Bool -> m (GValueConstruct o)

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

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 ()

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 Messages 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 ()

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

clear #userAgent

constructSessionUserAgent :: (IsSession o, MonadIO m) => Text -> m (GValueConstruct o)

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)

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 ()

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

set session [ #userAgent := value ]

Signals

authenticate

type SessionAuthenticateCallback

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.

afterSessionAuthenticate :: (IsSession a, MonadIO m) => a -> ((?self :: a) => SessionAuthenticateCallback) -> m SignalHandlerId

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

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onSessionAuthenticate :: (IsSession a, MonadIO m) => a -> ((?self :: a) => SessionAuthenticateCallback) -> m SignalHandlerId

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

connectionCreated

type SessionConnectionCreatedCallback

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

afterSessionConnectionCreated :: (IsSession a, MonadIO m) => a -> ((?self :: a) => SessionConnectionCreatedCallback) -> m SignalHandlerId

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

after session #connectionCreated callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onSessionConnectionCreated :: (IsSession a, MonadIO m) => a -> ((?self :: a) => SessionConnectionCreatedCallback) -> m SignalHandlerId

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

on session #connectionCreated callback

requestQueued

type SessionRequestQueuedCallback

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 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 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 finished (and all of the other Message signals) may be invoked multiple times for a given message.

Since: 2.24

afterSessionRequestQueued :: (IsSession a, MonadIO m) => a -> ((?self :: a) => SessionRequestQueuedCallback) -> m SignalHandlerId

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

after session #requestQueued callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onSessionRequestQueued :: (IsSession a, MonadIO m) => a -> ((?self :: a) => SessionRequestQueuedCallback) -> m SignalHandlerId

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

on session #requestQueued callback

requestStarted

type SessionRequestStartedCallback

Arguments

 = Message

msg: the request being sent

-> Socket

socket: the socket the request is being sent on

-> IO ()

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

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

afterSessionRequestStarted :: (IsSession a, MonadIO m) => a -> ((?self :: a) => SessionRequestStartedCallback) -> m SignalHandlerId

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

after session #requestStarted callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onSessionRequestStarted :: (IsSession a, MonadIO m) => a -> ((?self :: a) => SessionRequestStartedCallback) -> m SignalHandlerId

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

on session #requestStarted callback

requestUnqueued

type SessionRequestUnqueuedCallback

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

afterSessionRequestUnqueued :: (IsSession a, MonadIO m) => a -> ((?self :: a) => SessionRequestUnqueuedCallback) -> m SignalHandlerId

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

after session #requestUnqueued callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onSessionRequestUnqueued :: (IsSession a, MonadIO m) => a -> ((?self :: a) => SessionRequestUnqueuedCallback) -> m SignalHandlerId

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

on session #requestUnqueued callback

tunneling

type SessionTunnelingCallback

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

afterSessionTunneling :: (IsSession a, MonadIO m) => a -> ((?self :: a) => SessionTunnelingCallback) -> m SignalHandlerId

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

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onSessionTunneling :: (IsSession a, MonadIO m) => a -> ((?self :: a) => SessionTunnelingCallback) -> m SignalHandlerId

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