Copyright	Will Thompson and Iñaki García Etxebarria
License	LGPL-2.1
Maintainer	Iñaki García Etxebarria
Safe Haskell	Safe-Inferred
Language	Haskell2010

GI.Soup.Objects.Session

Contents

Exported types
Methods
Properties
Signals
- requestQueued
- requestUnqueued

Description

Soup session state object.

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

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

Additional Session functionality is provided by [ifacesessionFeature] objects, which can be added to a session with [methodsession.add_feature] or [methodsession.add_feature_by_type] For example, [classlogger] provides support for logging HTTP traffic, [classcontentDecoder] provides support for compressed response handling, and [classcontentSniffer] provides support for HTML5-style response body content sniffing. Additionally, subtypes of [classauth] can be added as features, to add support for additional authentication types.

All SoupSessions are created with a [classauthManager], and support for SOUP_TYPE_AUTH_BASIC and SOUP_TYPE_AUTH_DIGEST. Additionally, sessions using the plain Session class (rather than one of its deprecated subtypes) have a [classcontentDecoder] by default.

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

Synopsis

newtype Session = Session (ManagedPtr Session)
class (GObject o, IsDescendantOf Session o) => IsSession o
toSession :: (MonadIO m, IsSession o) => o -> m Session
sessionAbort :: (HasCallStack, MonadIO m, IsSession a) => a -> m ()
sessionAddFeature :: (HasCallStack, MonadIO m, IsSession a, IsSessionFeature b) => a -> b -> m ()
sessionAddFeatureByType :: (HasCallStack, MonadIO m, IsSession a) => a -> GType -> m ()
sessionGetAcceptLanguage :: (HasCallStack, MonadIO m, IsSession a) => a -> m (Maybe Text)
sessionGetAcceptLanguageAuto :: (HasCallStack, MonadIO m, IsSession a) => a -> m Bool
sessionGetAsyncResultMessage :: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b) => a -> b -> m (Maybe Message)
sessionGetFeature :: (HasCallStack, MonadIO m, IsSession a) => a -> GType -> m (Maybe SessionFeature)
sessionGetFeatureForMessage :: (HasCallStack, MonadIO m, IsSession a, IsMessage b) => a -> GType -> b -> m (Maybe SessionFeature)
sessionGetIdleTimeout :: (HasCallStack, MonadIO m, IsSession a) => a -> m Word32
sessionGetLocalAddress :: (HasCallStack, MonadIO m, IsSession a) => a -> m (Maybe InetSocketAddress)
sessionGetMaxConns :: (HasCallStack, MonadIO m, IsSession a) => a -> m Word32
sessionGetMaxConnsPerHost :: (HasCallStack, MonadIO m, IsSession a) => a -> m Word32
sessionGetProxyResolver :: (HasCallStack, MonadIO m, IsSession a) => a -> m (Maybe ProxyResolver)
sessionGetRemoteConnectable :: (HasCallStack, MonadIO m, IsSession a) => a -> m (Maybe SocketConnectable)
sessionGetTimeout :: (HasCallStack, MonadIO m, IsSession a) => a -> m Word32
sessionGetTlsDatabase :: (HasCallStack, MonadIO m, IsSession a) => a -> m (Maybe TlsDatabase)
sessionGetTlsInteraction :: (HasCallStack, MonadIO m, IsSession a) => a -> m (Maybe TlsInteraction)
sessionGetUserAgent :: (HasCallStack, MonadIO m, IsSession a) => a -> m (Maybe Text)
sessionHasFeature :: (HasCallStack, MonadIO m, IsSession a) => a -> GType -> m Bool
sessionNew :: (HasCallStack, MonadIO m) => m Session
sessionPreconnectAsync :: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c) => a -> b -> Int32 -> Maybe c -> Maybe AsyncReadyCallback -> m ()
sessionPreconnectFinish :: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b) => a -> b -> m ()
sessionRemoveFeature :: (HasCallStack, MonadIO m, IsSession a, IsSessionFeature b) => a -> b -> m ()
sessionRemoveFeatureByType :: (HasCallStack, MonadIO m, IsSession a) => a -> GType -> m ()
sessionSend :: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c) => a -> b -> Maybe c -> m InputStream
sessionSendAndRead :: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c) => a -> b -> Maybe c -> m Bytes
sessionSendAndReadAsync :: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c) => a -> b -> Int32 -> Maybe c -> Maybe AsyncReadyCallback -> m ()
sessionSendAndReadFinish :: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b) => a -> b -> m Bytes
sessionSendAndSplice :: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsOutputStream c, IsCancellable d) => a -> b -> c -> [OutputStreamSpliceFlags] -> Maybe d -> m Int64
sessionSendAndSpliceAsync :: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsOutputStream c, IsCancellable d) => a -> b -> c -> [OutputStreamSpliceFlags] -> Int32 -> Maybe d -> Maybe AsyncReadyCallback -> m ()
sessionSendAndSpliceFinish :: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b) => a -> b -> m Int64
sessionSendAsync :: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c) => a -> b -> Int32 -> Maybe c -> Maybe AsyncReadyCallback -> m ()
sessionSendFinish :: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b) => a -> b -> m InputStream
sessionSetAcceptLanguage :: (HasCallStack, MonadIO m, IsSession a) => a -> Text -> m ()
sessionSetAcceptLanguageAuto :: (HasCallStack, MonadIO m, IsSession a) => a -> Bool -> m ()
sessionSetIdleTimeout :: (HasCallStack, MonadIO m, IsSession a) => a -> Word32 -> m ()
sessionSetProxyResolver :: (HasCallStack, MonadIO m, IsSession a, IsProxyResolver b) => a -> Maybe b -> m ()
sessionSetTimeout :: (HasCallStack, MonadIO m, IsSession a) => a -> Word32 -> m ()
sessionSetTlsDatabase :: (HasCallStack, MonadIO m, IsSession a, IsTlsDatabase b) => a -> Maybe b -> m ()
sessionSetTlsInteraction :: (HasCallStack, MonadIO m, IsSession a, IsTlsInteraction b) => a -> Maybe b -> m ()
sessionSetUserAgent :: (HasCallStack, MonadIO m, IsSession a) => a -> Text -> m ()
sessionWebsocketConnectAsync :: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c) => a -> b -> Maybe Text -> Maybe [Text] -> Int32 -> Maybe c -> Maybe AsyncReadyCallback -> m ()
sessionWebsocketConnectFinish :: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b) => a -> b -> m WebsocketConnection
constructSessionAcceptLanguage :: (IsSession o, MonadIO m) => Text -> m (GValueConstruct o)
getSessionAcceptLanguage :: (MonadIO m, IsSession o) => o -> m (Maybe Text)
setSessionAcceptLanguage :: (MonadIO m, IsSession o) => o -> Text -> m ()
constructSessionAcceptLanguageAuto :: (IsSession o, MonadIO m) => Bool -> m (GValueConstruct o)
getSessionAcceptLanguageAuto :: (MonadIO m, IsSession o) => o -> m Bool
setSessionAcceptLanguageAuto :: (MonadIO m, IsSession o) => o -> Bool -> m ()
constructSessionIdleTimeout :: (IsSession o, MonadIO m) => Word32 -> m (GValueConstruct o)
getSessionIdleTimeout :: (MonadIO m, IsSession o) => o -> m Word32
setSessionIdleTimeout :: (MonadIO m, IsSession o) => o -> Word32 -> m ()
constructSessionLocalAddress :: (IsSession o, MonadIO m, IsInetSocketAddress a) => a -> m (GValueConstruct o)
getSessionLocalAddress :: (MonadIO m, IsSession o) => o -> m (Maybe InetSocketAddress)
constructSessionMaxConns :: (IsSession o, MonadIO m) => Int32 -> m (GValueConstruct o)
getSessionMaxConns :: (MonadIO m, IsSession o) => o -> m Int32
constructSessionMaxConnsPerHost :: (IsSession o, MonadIO m) => Int32 -> m (GValueConstruct o)
getSessionMaxConnsPerHost :: (MonadIO m, IsSession o) => o -> m Int32
clearSessionProxyResolver :: (MonadIO m, IsSession o) => o -> m ()
constructSessionProxyResolver :: (IsSession o, MonadIO m, IsProxyResolver a) => a -> m (GValueConstruct o)
getSessionProxyResolver :: (MonadIO m, IsSession o) => o -> m (Maybe ProxyResolver)
setSessionProxyResolver :: (MonadIO m, IsSession o, IsProxyResolver a) => o -> a -> m ()
constructSessionRemoteConnectable :: (IsSession o, MonadIO m, IsSocketConnectable a) => a -> m (GValueConstruct o)
getSessionRemoteConnectable :: (MonadIO m, IsSession o) => o -> m (Maybe SocketConnectable)
constructSessionTimeout :: (IsSession o, MonadIO m) => Word32 -> m (GValueConstruct o)
getSessionTimeout :: (MonadIO m, IsSession o) => o -> m Word32
setSessionTimeout :: (MonadIO m, IsSession o) => o -> Word32 -> m ()
clearSessionTlsDatabase :: (MonadIO m, IsSession o) => o -> m ()
constructSessionTlsDatabase :: (IsSession o, MonadIO m, IsTlsDatabase a) => a -> m (GValueConstruct o)
getSessionTlsDatabase :: (MonadIO m, IsSession o) => o -> m (Maybe TlsDatabase)
setSessionTlsDatabase :: (MonadIO m, IsSession o, IsTlsDatabase a) => o -> a -> m ()
clearSessionTlsInteraction :: (MonadIO m, IsSession o) => o -> m ()
constructSessionTlsInteraction :: (IsSession o, MonadIO m, IsTlsInteraction a) => a -> m (GValueConstruct o)
getSessionTlsInteraction :: (MonadIO m, IsSession o) => o -> m (Maybe TlsInteraction)
setSessionTlsInteraction :: (MonadIO m, IsSession o, IsTlsInteraction a) => o -> a -> m ()
constructSessionUserAgent :: (IsSession o, MonadIO m) => Text -> m (GValueConstruct o)
getSessionUserAgent :: (MonadIO m, IsSession o) => o -> m (Maybe Text)
setSessionUserAgent :: (MonadIO m, IsSession o) => o -> Text -> m ()
type SessionRequestQueuedCallback = Message -> IO ()
afterSessionRequestQueued :: (IsSession a, MonadIO m) => a -> ((?self :: a) => SessionRequestQueuedCallback) -> m SignalHandlerId
onSessionRequestQueued :: (IsSession a, MonadIO m) => a -> ((?self :: a) => SessionRequestQueuedCallback) -> m SignalHandlerId
type SessionRequestUnqueuedCallback = Message -> IO ()
afterSessionRequestUnqueued :: (IsSession a, MonadIO m) => a -> ((?self :: a) => SessionRequestUnqueuedCallback) -> m SignalHandlerId
onSessionRequestUnqueued :: (IsSession a, MonadIO m) => a -> ((?self :: a) => SessionRequestUnqueuedCallback) -> m SignalHandlerId

Exported types

newtype Session Source #

Memory-managed wrapper type.

Constructors

Session (ManagedPtr Session)

Instances

Instances details

Eq Session Source #
Instance details Defined in GI.Soup.Objects.Session Methods (==) :: Session -> Session -> Bool # (/=) :: Session -> Session -> Bool #
GObject Session Source #
Instance details Defined in GI.Soup.Objects.Session
ManagedPtrNewtype Session Source #
Instance details Defined in GI.Soup.Objects.Session Methods toManagedPtr :: Session -> ManagedPtr Session
TypedObject Session Source #
Instance details Defined in GI.Soup.Objects.Session Methods glibType :: IO GType
HasParentTypes Session Source #
Instance details Defined in GI.Soup.Objects.Session
IsGValue (Maybe Session) Source #	Convert `Session` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details 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 Source #
Instance details Defined in GI.Soup.Objects.Session type ParentTypes Session = '[Object]

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

Instances details

(GObject o, IsDescendantOf Session o) => IsSession o Source #
Instance details Defined 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.

Methods

Click to display all available methods, including inherited ones

Expand

abort

sessionAbort Source #

Arguments

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

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

addFeature

sessionAddFeature Source #

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 cannot add multiple features of the same [aliasgLib.Type] to a session.

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

addFeatureByType

sessionAddFeatureByType Source #

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 [ifacesessionFeature], this creates a new feature of that type and adds it to session as with [methodsession.add_feature]. You can use this when you don't need to customize the new feature in any way. Adding multiple features of the same featureType is not allowed.

If featureType is not a [ifacesessionFeature] type, this gives each existing feature on session the chance to accept featureType as a "subfeature". This can be used to add new [classauth] types, for instance.

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

getAcceptLanguage

sessionGetAcceptLanguage Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a)
=> a	`session`: a `Session`
-> m (Maybe Text)	Returns: the accept language string

Get the value used by session for the "Accept-Language" header on new requests.

getAcceptLanguageAuto

sessionGetAcceptLanguageAuto Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a)
=> a	`session`: a `Session`
-> m Bool	Returns: `True` if `session` sets "Accept-Language" header automatically, or `False` otherwise.

Gets whether session automatically sets the "Accept-Language" header on new requests.

getAsyncResultMessage

sessionGetAsyncResultMessage Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b)
=> a	`session`: a `Session`
-> b	`result`: the `AsyncResult` passed to your callback
-> m (Maybe Message)	Returns: a `Message` or `Nothing` if `result` is not a valid `session` async operation result.

Gets the [classmessage] of the result asynchronous operation This is useful to get the [classmessage] of an asynchronous operation started by session from its [callbackgio.AsyncReadyCallback].

getFeature

sessionGetFeature Source #

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 feature in session of type featureType.

getFeatureForMessage

sessionGetFeatureForMessage Source #

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`. The feature is owned by `session`.

Gets the feature in session of type featureType, provided that it is not disabled for msg.

getIdleTimeout

sessionGetIdleTimeout Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a)
=> a	`session`: a `Session`
-> m Word32	Returns: the timeout in seconds

Get the timeout in seconds for idle connection lifetime currently used by session.

getLocalAddress

sessionGetLocalAddress Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a)
=> a	`session`: a `Session`
-> m (Maybe InetSocketAddress)	Returns: a `InetSocketAddress`

Get the InetSocketAddress to use for the client side of connections in session.

getMaxConns

sessionGetMaxConns Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a)
=> a	`session`: a `Session`
-> m Word32	Returns: the maximum number of connections

Get the maximum number of connections that session can open at once.

getMaxConnsPerHost

sessionGetMaxConnsPerHost Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a)
=> a	`session`: a `Session`
-> m Word32	Returns: the maximum number of connections per host

Get the maximum number of connections that session can open at once to a given host.

getProxyResolver

sessionGetProxyResolver Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a)
=> a	`session`: a `Session`
-> m (Maybe ProxyResolver)	Returns: a `ProxyResolver` or `Nothing` if proxies are disabled in `session`

Get the ProxyResolver currently used by session.

getRemoteConnectable

sessionGetRemoteConnectable Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a)
=> a	`session`: a `Session`
-> m (Maybe SocketConnectable)	Returns: the `SocketConnectable`

Gets the remote connectable if one set.

getTimeout

sessionGetTimeout Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a)
=> a	`session`: a `Session`
-> m Word32	Returns: the timeout in seconds

Get the timeout in seconds for socket I/O operations currently used by session.

getTlsDatabase

sessionGetTlsDatabase Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a)
=> a	`session`: a `Session`
-> m (Maybe TlsDatabase)	Returns: a `TlsDatabase`

Get the TlsDatabase currently used by session.

getTlsInteraction

sessionGetTlsInteraction Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a)
=> a	`session`: a `Session`
-> m (Maybe TlsInteraction)	Returns: a `TlsInteraction`

Get the TlsInteraction currently used by session.

getUserAgent

sessionGetUserAgent Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a)
=> a	`session`: a `Session`
-> m (Maybe Text)	Returns: the user agent string

Get the value used by session for the "User-Agent" header on new requests.

hasFeature

sessionHasFeature Source #

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 [ifacesessionFeature], or else a subtype of some class managed by another feature, such as [classauth]).

new

sessionNew Source #

Arguments

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

Creates a Session with the default options.

preconnectAsync

sessionPreconnectAsync Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c)
=> a	`session`: a `Session`
-> b	`msg`: a `Message`
-> Int32	`ioPriority`: the I/O priority of the request
-> Maybe c	`cancellable`: a `Cancellable`
-> Maybe AsyncReadyCallback	`callback`: the callback to invoke when the operation finishes
-> m ()

Start a preconnection to msg.

Once the connection is done, it will remain in idle state so that it can be reused by future requests. If there's already an idle connection for the given msg host, the operation finishes successfully without creating a new connection. If a new request for the given msg host is made while the preconnect is still ongoing, the request will take the ownership of the connection and the preconnect operation will finish successfully (if there's a connection error it will be handled by the request).

The operation finishes when the connection is done or an error occurred.

preconnectFinish

sessionPreconnectFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b)
=> a	`session`: a `Session`
-> b	`result`: the `AsyncResult` passed to your callback
-> m ()	(Can throw `GError`)

Complete a preconnect async operation started with [methodsession.preconnect_async].

removeFeature

sessionRemoveFeature Source #

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.

removeFeatureByType

sessionRemoveFeatureByType Source #

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.

send

sessionSend Source #

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; [methodsession.send] will return a IOErrorEnumCancelled error. Note that with requests that have side effects (eg, POST, PUT, DELETE) 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 [methodsession.send] will only return once a final response has been received.

sendAndRead

sessionSendAndRead Source #

Arguments

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

Synchronously sends msg and reads the response body.

On success, a [structgLib.Bytes] will be returned with the response body. This function should only be used when the resource to be retrieved is not too long and can be stored in memory.

See [methodsession.send] for more details on the general semantics.

sendAndReadAsync

sessionSendAndReadAsync Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c)
=> a	`session`: a `Session`
-> b	`msg`: a `Message`
-> Int32	`ioPriority`: the I/O priority of the request
-> Maybe c	`cancellable`: a `Cancellable`
-> Maybe AsyncReadyCallback	`callback`: the callback to invoke
-> m ()

Asynchronously sends msg and reads the response body.

When callback is called, then either msg has been sent, and its response body read, or else an error has occurred. This function should only be used when the resource to be retrieved is not too long and can be stored in memory. Call [methodsession.send_and_read_finish] to get a [structgLib.Bytes] with the response body.

See [methodsession.send] for more details on the general semantics.

sendAndReadFinish

sessionSendAndReadFinish Source #

Arguments

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

Gets the response to a [methodsession.send_and_read_async].

If successful, returns a [structgLib.Bytes] with the response body.

sendAndSplice

sessionSendAndSplice Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsOutputStream c, IsCancellable d)
=> a	`session`: a `Session`
-> b	`msg`: a `Message`
-> c	`outStream`: a `OutputStream`
-> [OutputStreamSpliceFlags]	`flags`: a set of `OutputStreamSpliceFlags`
-> Maybe d	`cancellable`: a `Cancellable`
-> m Int64	Returns: a `gssize` containing the size of the data spliced, or -1 if an error occurred. (Can throw `GError`)

Synchronously sends msg and splices the response body stream into outStream.

See [methodsession.send] for more details on the general semantics.

Since: 3.4

sendAndSpliceAsync

sessionSendAndSpliceAsync Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsOutputStream c, IsCancellable d)
=> a	`session`: a `Session`
-> b	`msg`: a `Message`
-> c	`outStream`: a `OutputStream`
-> [OutputStreamSpliceFlags]	`flags`: a set of `OutputStreamSpliceFlags`
-> Int32	`ioPriority`: the I/O priority of the request
-> Maybe d	`cancellable`: a `Cancellable`
-> Maybe AsyncReadyCallback	`callback`: the callback to invoke
-> m ()

Asynchronously sends msg and splices the response body stream into outStream. When callback is called, then either msg has been sent and its response body spliced, or else an error has occurred.

See [methodsession.send] for more details on the general semantics.

Since: 3.4

sendAndSpliceFinish

sessionSendAndSpliceFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b)
=> a	`session`: a `Session`
-> b	`result`: the `AsyncResult` passed to your callback
-> m Int64	Returns: a `gssize` containing the size of the data spliced, or -1 if an error occurred. (Can throw `GError`)

Gets the response to a [methodsession.send_and_splice_async].

Since: 3.4

sendAsync

sessionSendAsync Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c)
=> a	`session`: a `Session`
-> b	`msg`: a `Message`
-> Int32	`ioPriority`: the I/O priority of the request
-> 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 [methodsession.send_finish] to get a InputStream for reading the response body.

See [methodsession.send] for more details on the general semantics.

sendFinish

sessionSendFinish Source #

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 [methodsession.send_async] call.

If successful returns a InputStream that can be used to read the response body.

setAcceptLanguage

sessionSetAcceptLanguage Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a)
=> a	`session`: a `Session`
-> Text	`acceptLanguage`: the languages string
-> m ()

Set the value to use for the "Accept-Language" header on [classmessage]s sent from session.

If acceptLanguage is Nothing then no "Accept-Language" will be included in requests. See [propertysession:accept-language] for more information.

setAcceptLanguageAuto

sessionSetAcceptLanguageAuto Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a)
=> a	`session`: a `Session`
-> Bool	`acceptLanguageAuto`: the value to set
-> m ()

Set whether session will automatically set the "Accept-Language" header on requests using a value generated from system languages based on getLanguageNames.

See [propertysession:accept-language-auto] for more information.

setIdleTimeout

sessionSetIdleTimeout Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a)
=> a	`session`: a `Session`
-> Word32	`timeout`: a timeout in seconds
-> m ()

Set a timeout in seconds for idle connection lifetime to be used by session on new connections.

See [propertysession:idle-timeout] for more information.

setProxyResolver

sessionSetProxyResolver Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a, IsProxyResolver b)
=> a	`session`: a `Session`
-> Maybe b	`proxyResolver`: a `ProxyResolver` or `Nothing`
-> m ()

Set a ProxyResolver to be used by session on new connections.

If proxyResolver is Nothing then no proxies will be used. See [propertysession:proxy-resolver] for more information.

setTimeout

sessionSetTimeout Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a)
=> a	`session`: a `Session`
-> Word32	`timeout`: a timeout in seconds
-> m ()

Set a timeout in seconds for socket I/O operations to be used by session on new connections.

See [propertysession:timeout] for more information.

setTlsDatabase

sessionSetTlsDatabase Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a, IsTlsDatabase b)
=> a	`session`: a `Session`
-> Maybe b	`tlsDatabase`: a `TlsDatabase`
-> m ()

Set a GIo.TlsDatabase to be used by session on new connections.

If tlsDatabase is Nothing then certificate validation will always fail. See [propertysession:tls-database] for more information.

setTlsInteraction

sessionSetTlsInteraction Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a, IsTlsInteraction b)
=> a	`session`: a `Session`
-> Maybe b	`tlsInteraction`: a `TlsInteraction`
-> m ()

Set a TlsInteraction to be used by session on new connections.

If tlsInteraction is Nothing then client certificate validation will always fail.

See [propertysession:tls-interaction] for more information.

setUserAgent

sessionSetUserAgent Source #

Arguments

:: (HasCallStack, MonadIO m, IsSession a)
=> a	`session`: a `Session`
-> Text	`userAgent`: the user agent string
-> m ()

Set the value to use for the "User-Agent" header on [classmessage]s sent from session.

If userAgent has trailing whitespace, session will append its own product token (eg, libsoup/3.0.0) to the end of the header for you. If userAgent is Nothing then no "User-Agent" will be included in requests. See [propertysession:user-agent] for more information.

websocketConnectAsync

sessionWebsocketConnectAsync Source #

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
-> Int32	`ioPriority`: the I/O priority of the request
-> Maybe c	`cancellable`: a `Cancellable`
-> Maybe AsyncReadyCallback	`callback`: the callback to invoke
-> m ()

Asynchronously creates a [classwebsocketConnection] 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, [methodsession.websocket_connect_finish] will return a new [classwebsocketConnection]. 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 [methodsession.websocket_connect_finish] will return WebsocketErrorNotWebsocket.

websocketConnectFinish

sessionWebsocketConnectFinish Source #

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 [classwebsocketConnection] response to a [methodsession.websocket_connect_async] call.

If successful, returns a [classwebsocketConnection] that can be used to communicate with the server.

Properties

acceptLanguage

If non-Nothing, the value to use for the "Accept-Language" header on [classmessage]s sent from this session.

Setting this will disable [propertysession:accept-language-auto].

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

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 [classmessage] sent, based on the return value of getLanguageNames.

Setting this will override any previous value of [propertysession:accept-language].

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

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 ]

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 [methodsession.abort] after setting this if you want to ensure that all future connections will have this timeout value.

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

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 ]

localAddress

Sets the InetSocketAddress 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.

constructSessionLocalAddress :: (IsSession o, MonadIO m, IsInetSocketAddress a) => a -> m (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.

getSessionLocalAddress :: (MonadIO m, IsSession o) => o -> m (Maybe InetSocketAddress) Source #

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

get session #localAddress

maxConns

The maximum number of connections that the session can open at once.

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

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

maxConnsPerHost

The maximum number of connections that the session can open at once to a given host.

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

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

proxyResolver

A ProxyResolver to use with this session.

If no proxy resolver is set, then the default proxy resolver will be used. See [funcgio.ProxyResolver.get_default]. 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.

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

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

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 ]

remoteConnectable

Sets a socket to make outgoing connections on. This will override the default behaviour of opening TCP/IP sockets to the hosts specified in the URIs.

This function is not required for common HTTP usage, but only when connecting to a HTTP service that is not using standard TCP/IP sockets. An example of this is a local service that uses HTTP over UNIX-domain sockets, in that case a UnixSocketAddress can be passed to this function.

constructSessionRemoteConnectable :: (IsSession o, MonadIO m, IsSocketConnectable a) => a -> m (GValueConstruct o) Source #

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

getSessionRemoteConnectable :: (MonadIO m, IsSession o) => o -> m (Maybe SocketConnectable) Source #

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

get session #remoteConnectable

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 [methodsession.abort] after setting this if you want to ensure that all future connections will have this timeout value.

Not to be confused with [propertysession: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) Source #

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.

If no certificate database is set, then the default database will be used. See tlsBackendGetDefaultDatabase.

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, MonadIO m, IsTlsDatabase a) => a -> m (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 TlsConnections created by the session.

This can be used to provide client-side certificates, for example.

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

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

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 ]

userAgent

User-Agent string.

If non-Nothing, the value to use for the "User-Agent" header on [classmessage]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 [propertysession:user-agent] property that has trailing whitespace, Session will append its own product token (eg, libsoup/2.3.2) to the end of the header for you.

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

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

requestQueued

type SessionRequestQueuedCallback Source #

Arguments

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

Emitted when a request is queued on session.

When sending a request, first signalsession[requestQueued] is emitted, indicating that the session has become aware of the request.

After a connection is available to send the request various [classmessage] signals are emitted as the message is processed. If the message is requeued, it will emit signalmessage[restarted], which will then be followed by other [classmessage] signals when the message is re-sent.

Eventually, the message will emit signalmessage[finished]. Normally, this signals the completion of message processing. However, it is possible that the application will requeue the message from the "finished" handler. In that case the process will loop back.

Eventually, a message will reach "finished" and not be requeued. At that point, the session will emit signalsession[requestUnqueued] to indicate that it is done with the message.

To sum up: signalsession[requestQueued] and signalsession[requestUnqueued] are guaranteed to be emitted exactly once, but signalmessage[finished] (and all of the other [classmessage] signals) may be invoked multiple times for a given message.

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

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 Source #

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

requestUnqueued

type SessionRequestUnqueuedCallback Source #

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 signalsession[requestQueued] for a detailed description of the message lifecycle within a session.

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

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 Source #

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

Exported types

Instances

Instances

Methods

Click to display all available methods, including inherited ones

Methods

Getters

Setters

abort

addFeature

addFeatureByType

getAcceptLanguage

getAcceptLanguageAuto

getAsyncResultMessage

getFeature

getFeatureForMessage

getIdleTimeout

getLocalAddress

getMaxConns

getMaxConnsPerHost

getProxyResolver

getRemoteConnectable

getTimeout

getTlsDatabase

getTlsInteraction

getUserAgent

hasFeature

new

preconnectAsync

preconnectFinish

removeFeature

removeFeatureByType

send

sendAndRead

sendAndReadAsync

sendAndReadFinish

sendAndSplice

sendAndSpliceAsync

sendAndSpliceFinish

sendAsync

sendFinish

setAcceptLanguage

setAcceptLanguageAuto

setIdleTimeout

setProxyResolver

setTimeout

setTlsDatabase

setTlsInteraction

setUserAgent

websocketConnectAsync

websocketConnectFinish

Properties

acceptLanguage

acceptLanguageAuto

idleTimeout

localAddress

maxConns

maxConnsPerHost

proxyResolver

remoteConnectable

timeout

tlsDatabase

tlsInteraction

userAgent

Signals

requestQueued

requestUnqueued