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 |
- Exported types
- Methods
- 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
- Signals
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 SoupSession
s 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
Memory-managed wrapper type.
Instances
Eq Session Source # | |
GObject Session Source # | |
Defined in GI.Soup.Objects.Session | |
ManagedPtrNewtype Session Source # | |
Defined in GI.Soup.Objects.Session toManagedPtr :: Session -> ManagedPtr Session | |
TypedObject Session Source # | |
Defined in GI.Soup.Objects.Session | |
HasParentTypes Session Source # | |
Defined in GI.Soup.Objects.Session | |
IsGValue (Maybe Session) Source # | Convert |
Defined in GI.Soup.Objects.Session gvalueGType_ :: IO GType gvalueSet_ :: Ptr GValue -> Maybe Session -> IO () gvalueGet_ :: Ptr GValue -> IO (Maybe Session) | |
type ParentTypes Session Source # | |
Defined in GI.Soup.Objects.Session type ParentTypes Session = '[Object] |
class (GObject o, IsDescendantOf Session o) => IsSession o Source #
Instances
(GObject o, IsDescendantOf Session o) => IsSession o Source # | |
Defined in GI.Soup.Objects.Session |
Methods
Click to display all available methods, including inherited ones
Methods
abort, addFeature, addFeatureByType, bindProperty, bindPropertyFull, forceFloating, freezeNotify, getv, hasFeature, isFloating, notify, notifyByPspec, preconnectAsync, preconnectFinish, ref, refSink, removeFeature, removeFeatureByType, runDispose, send, sendAndRead, sendAndReadAsync, sendAndReadFinish, sendAndSplice, sendAndSpliceAsync, sendAndSpliceFinish, sendAsync, sendFinish, stealData, stealQdata, thawNotify, unref, watchClosure, websocketConnectAsync, websocketConnectFinish.
Getters
getAcceptLanguage, getAcceptLanguageAuto, getAsyncResultMessage, getData, getFeature, getFeatureForMessage, getIdleTimeout, getLocalAddress, getMaxConns, getMaxConnsPerHost, getProperty, getProxyResolver, getQdata, getRemoteConnectable, getTimeout, getTlsDatabase, getTlsInteraction, getUserAgent.
Setters
setAcceptLanguage, setAcceptLanguageAuto, setData, setDataFull, setIdleTimeout, setProperty, setProxyResolver, setTimeout, setTlsDatabase, setTlsInteraction, setUserAgent.
abort
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> m () |
Cancels all pending requests in session
and closes all idle
persistent connections.
addFeature
:: (HasCallStack, MonadIO m, IsSession a, IsSessionFeature b) | |
=> a |
|
-> b |
|
-> 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 #
:: (HasCallStack, MonadIO m, IsSession a) | |
=> 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 #
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> 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 #
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> m Bool | Returns: |
Gets whether session
automatically sets the "Accept-Language" header on new
requests.
getAsyncResultMessage
sessionGetAsyncResultMessage Source #
:: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b) | |
=> a |
|
-> b |
|
-> m (Maybe Message) | Returns: a |
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
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> GType |
|
-> m (Maybe SessionFeature) | Returns: a |
Gets the feature in session
of type featureType
.
getFeatureForMessage
sessionGetFeatureForMessage Source #
:: (HasCallStack, MonadIO m, IsSession a, IsMessage b) | |
=> a |
|
-> GType |
|
-> b |
|
-> m (Maybe SessionFeature) | Returns: a |
Gets the feature in session
of type featureType
, provided
that it is not disabled for msg
.
getIdleTimeout
sessionGetIdleTimeout Source #
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> m Word32 | Returns: the timeout in seconds |
Get the timeout in seconds for idle connection lifetime currently used by
session
.
getLocalAddress
sessionGetLocalAddress Source #
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> m (Maybe InetSocketAddress) | Returns: a |
Get the InetSocketAddress
to use for the client side of
connections in session
.
getMaxConns
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> m Word32 | Returns: the maximum number of connections |
Get the maximum number of connections that session
can open at once.
getMaxConnsPerHost
sessionGetMaxConnsPerHost Source #
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> 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 #
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> m (Maybe ProxyResolver) | Returns: a |
Get the ProxyResolver
currently used by session
.
getRemoteConnectable
sessionGetRemoteConnectable Source #
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> m (Maybe SocketConnectable) | Returns: the |
Gets the remote connectable if one set.
getTimeout
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> m Word32 | Returns: the timeout in seconds |
Get the timeout in seconds for socket I/O operations currently used by
session
.
getTlsDatabase
sessionGetTlsDatabase Source #
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> m (Maybe TlsDatabase) | Returns: a |
Get the TlsDatabase
currently used by session
.
getTlsInteraction
sessionGetTlsInteraction Source #
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> m (Maybe TlsInteraction) | Returns: a |
Get the TlsInteraction
currently used by session
.
getUserAgent
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> m (Maybe Text) | Returns: the user agent string |
Get the value used by session
for the "User-Agent" header on new requests.
hasFeature
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> GType |
|
-> m Bool |
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
:: (HasCallStack, MonadIO m) | |
=> m Session | Returns: the new session. |
Creates a Session
with the default options.
preconnectAsync
sessionPreconnectAsync Source #
:: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c) | |
=> a |
|
-> b |
|
-> Int32 |
|
-> Maybe c |
|
-> Maybe AsyncReadyCallback |
|
-> 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 #
:: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b) | |
=> a |
|
-> b |
|
-> m () | (Can throw |
Complete a preconnect async operation started with [methodsession
.preconnect_async].
removeFeature
:: (HasCallStack, MonadIO m, IsSession a, IsSessionFeature b) | |
=> a |
|
-> b |
|
-> m () |
Removes feature
's functionality from session
.
removeFeatureByType
sessionRemoveFeatureByType Source #
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> GType |
|
-> m () |
Removes all features of type featureType
(or any subclass of
featureType
) from session
.
send
:: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c) | |
=> a |
|
-> b |
|
-> Maybe c |
|
-> m InputStream | Returns: a |
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
:: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c) | |
=> a |
|
-> b |
|
-> Maybe c |
|
-> m Bytes |
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 #
:: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c) | |
=> a |
|
-> b |
|
-> Int32 |
|
-> Maybe c |
|
-> Maybe AsyncReadyCallback |
|
-> 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 #
:: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b) | |
=> a |
|
-> b |
|
-> m Bytes |
Gets the response to a [methodsession
.send_and_read_async].
If successful, returns a [structgLib
.Bytes] with the response body.
sendAndSplice
:: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsOutputStream c, IsCancellable d) | |
=> a |
|
-> b |
|
-> c |
|
-> [OutputStreamSpliceFlags] |
|
-> Maybe d |
|
-> m Int64 | Returns: a |
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 #
:: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsOutputStream c, IsCancellable d) | |
=> a |
|
-> b |
|
-> c |
|
-> [OutputStreamSpliceFlags] |
|
-> Int32 |
|
-> Maybe d |
|
-> Maybe AsyncReadyCallback |
|
-> 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 #
:: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b) | |
=> a |
|
-> b |
|
-> m Int64 | Returns: a |
Gets the response to a [methodsession
.send_and_splice_async].
Since: 3.4
sendAsync
:: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c) | |
=> a |
|
-> b |
|
-> Int32 |
|
-> Maybe c |
|
-> Maybe AsyncReadyCallback |
|
-> 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
:: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b) | |
=> a |
|
-> b |
|
-> m InputStream | Returns: a |
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 #
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> Text |
|
-> 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 #
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> Bool |
|
-> 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 #
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> Word32 |
|
-> 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 #
:: (HasCallStack, MonadIO m, IsSession a, IsProxyResolver b) | |
=> a |
|
-> Maybe b |
|
-> 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
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> Word32 |
|
-> 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 #
:: (HasCallStack, MonadIO m, IsSession a, IsTlsDatabase b) | |
=> a |
|
-> Maybe b |
|
-> 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 #
:: (HasCallStack, MonadIO m, IsSession a, IsTlsInteraction b) | |
=> a |
|
-> Maybe b |
|
-> 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
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> Text |
|
-> 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 #
:: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c) | |
=> a |
|
-> b |
|
-> Maybe Text |
|
-> Maybe [Text] |
|
-> Int32 |
|
-> Maybe c |
|
-> Maybe AsyncReadyCallback |
|
-> 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 #
:: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b) | |
=> a |
|
-> b |
|
-> m WebsocketConnection | Returns: a new |
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
TlsConnection
s 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 #
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 #
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