Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria (inaki@blueleaf.cc) |
Safe Haskell | None |
Language | Haskell2010 |
- Exported types
- Methods
- abort
- addFeature
- addFeatureByType
- cancelMessage
- connectAsync
- connectFinish
- getAsyncContext
- getFeature
- getFeatureForMessage
- getFeatures
- hasFeature
- new
- pauseMessage
- prefetchDns
- prepareForUri
- queueMessage
- redirectMessage
- removeFeature
- removeFeatureByType
- request
- requestHttp
- requestHttpUri
- requestUri
- requeueMessage
- send
- sendAsync
- sendFinish
- sendMessage
- stealConnection
- unpauseMessage
- websocketConnectAsync
- websocketConnectFinish
- wouldRedirect
- Properties
- Signals
No description available in the introspection data.
Synopsis
- newtype Session = Session (ManagedPtr Session)
- class (GObject o, IsDescendantOf Session o) => IsSession o
- toSession :: (MonadIO m, IsSession o) => o -> m Session
- noSession :: Maybe 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 ()
- sessionCancelMessage :: (HasCallStack, MonadIO m, IsSession a, IsMessage b) => a -> b -> Word32 -> m ()
- sessionConnectAsync :: (HasCallStack, MonadIO m, IsSession a, IsCancellable b) => a -> URI -> Maybe b -> Maybe SessionConnectProgressCallback -> Maybe AsyncReadyCallback -> m ()
- sessionConnectFinish :: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b) => a -> b -> m IOStream
- sessionGetAsyncContext :: (HasCallStack, MonadIO m, IsSession a) => a -> m (Maybe MainContext)
- 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)
- sessionGetFeatures :: (HasCallStack, MonadIO m, IsSession a) => a -> GType -> m [SessionFeature]
- sessionHasFeature :: (HasCallStack, MonadIO m, IsSession a) => a -> GType -> m Bool
- sessionNew :: (HasCallStack, MonadIO m) => m Session
- sessionPauseMessage :: (HasCallStack, MonadIO m, IsSession a, IsMessage b) => a -> b -> m ()
- sessionPrefetchDns :: (HasCallStack, MonadIO m, IsSession a, IsCancellable b) => a -> Text -> Maybe b -> Maybe AddressCallback -> m ()
- sessionPrepareForUri :: (HasCallStack, MonadIO m, IsSession a) => a -> URI -> m ()
- sessionQueueMessage :: (HasCallStack, MonadIO m, IsSession a, IsMessage b) => a -> b -> Maybe SessionCallback -> m ()
- sessionRedirectMessage :: (HasCallStack, MonadIO m, IsSession a, IsMessage b) => a -> b -> m Bool
- sessionRemoveFeature :: (HasCallStack, MonadIO m, IsSession a, IsSessionFeature b) => a -> b -> m ()
- sessionRemoveFeatureByType :: (HasCallStack, MonadIO m, IsSession a) => a -> GType -> m ()
- sessionRequest :: (HasCallStack, MonadIO m, IsSession a) => a -> Text -> m Request
- sessionRequestHttp :: (HasCallStack, MonadIO m, IsSession a) => a -> Text -> Text -> m RequestHTTP
- sessionRequestHttpUri :: (HasCallStack, MonadIO m, IsSession a) => a -> Text -> URI -> m RequestHTTP
- sessionRequestUri :: (HasCallStack, MonadIO m, IsSession a) => a -> URI -> m Request
- sessionRequeueMessage :: (HasCallStack, MonadIO m, IsSession a, IsMessage b) => a -> b -> m ()
- sessionSend :: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c) => a -> b -> Maybe c -> m InputStream
- sessionSendAsync :: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c) => a -> b -> Maybe c -> Maybe AsyncReadyCallback -> m ()
- sessionSendFinish :: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b) => a -> b -> m InputStream
- sessionSendMessage :: (HasCallStack, MonadIO m, IsSession a, IsMessage b) => a -> b -> m Word32
- sessionStealConnection :: (HasCallStack, MonadIO m, IsSession a, IsMessage b) => a -> b -> m IOStream
- sessionUnpauseMessage :: (HasCallStack, MonadIO m, IsSession a, IsMessage b) => a -> b -> m ()
- sessionWebsocketConnectAsync :: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c) => a -> b -> Maybe Text -> Maybe [Text] -> Maybe c -> Maybe AsyncReadyCallback -> m ()
- sessionWebsocketConnectFinish :: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b) => a -> b -> m WebsocketConnection
- sessionWouldRedirect :: (HasCallStack, MonadIO m, IsSession a, IsMessage b) => a -> b -> m Bool
- clearSessionAcceptLanguage :: (MonadIO m, IsSession o) => o -> m ()
- constructSessionAcceptLanguage :: IsSession o => Text -> IO (GValueConstruct o)
- getSessionAcceptLanguage :: (MonadIO m, IsSession o) => o -> m (Maybe Text)
- setSessionAcceptLanguage :: (MonadIO m, IsSession o) => o -> Text -> m ()
- constructSessionAcceptLanguageAuto :: IsSession o => Bool -> IO (GValueConstruct o)
- getSessionAcceptLanguageAuto :: (MonadIO m, IsSession o) => o -> m Bool
- setSessionAcceptLanguageAuto :: (MonadIO m, IsSession o) => o -> Bool -> m ()
- constructSessionAsyncContext :: IsSession o => Ptr () -> IO (GValueConstruct o)
- getSessionAsyncContext :: (MonadIO m, IsSession o) => o -> m (Ptr ())
- clearSessionHttpAliases :: (MonadIO m, IsSession o) => o -> m ()
- constructSessionHttpAliases :: IsSession o => [Text] -> IO (GValueConstruct o)
- getSessionHttpAliases :: (MonadIO m, IsSession o) => o -> m (Maybe [Text])
- setSessionHttpAliases :: (MonadIO m, IsSession o) => o -> [Text] -> m ()
- clearSessionHttpsAliases :: (MonadIO m, IsSession o) => o -> m ()
- constructSessionHttpsAliases :: IsSession o => [Text] -> IO (GValueConstruct o)
- getSessionHttpsAliases :: (MonadIO m, IsSession o) => o -> m (Maybe [Text])
- setSessionHttpsAliases :: (MonadIO m, IsSession o) => o -> [Text] -> m ()
- constructSessionIdleTimeout :: IsSession o => Word32 -> IO (GValueConstruct o)
- getSessionIdleTimeout :: (MonadIO m, IsSession o) => o -> m Word32
- setSessionIdleTimeout :: (MonadIO m, IsSession o) => o -> Word32 -> m ()
- constructSessionLocalAddress :: (IsSession o, IsAddress a) => a -> IO (GValueConstruct o)
- getSessionLocalAddress :: (MonadIO m, IsSession o) => o -> m (Maybe Address)
- constructSessionMaxConns :: IsSession o => Int32 -> IO (GValueConstruct o)
- getSessionMaxConns :: (MonadIO m, IsSession o) => o -> m Int32
- setSessionMaxConns :: (MonadIO m, IsSession o) => o -> Int32 -> m ()
- constructSessionMaxConnsPerHost :: IsSession o => Int32 -> IO (GValueConstruct o)
- getSessionMaxConnsPerHost :: (MonadIO m, IsSession o) => o -> m Int32
- setSessionMaxConnsPerHost :: (MonadIO m, IsSession o) => o -> Int32 -> m ()
- clearSessionProxyResolver :: (MonadIO m, IsSession o) => o -> m ()
- constructSessionProxyResolver :: (IsSession o, IsProxyResolver a) => a -> IO (GValueConstruct o)
- getSessionProxyResolver :: (MonadIO m, IsSession o) => o -> m (Maybe ProxyResolver)
- setSessionProxyResolver :: (MonadIO m, IsSession o, IsProxyResolver a) => o -> a -> m ()
- clearSessionProxyUri :: (MonadIO m, IsSession o) => o -> m ()
- constructSessionProxyUri :: IsSession o => URI -> IO (GValueConstruct o)
- getSessionProxyUri :: (MonadIO m, IsSession o) => o -> m (Maybe URI)
- setSessionProxyUri :: (MonadIO m, IsSession o) => o -> URI -> m ()
- clearSessionSslCaFile :: (MonadIO m, IsSession o) => o -> m ()
- constructSessionSslCaFile :: IsSession o => Text -> IO (GValueConstruct o)
- getSessionSslCaFile :: (MonadIO m, IsSession o) => o -> m (Maybe Text)
- setSessionSslCaFile :: (MonadIO m, IsSession o) => o -> Text -> m ()
- constructSessionSslStrict :: IsSession o => Bool -> IO (GValueConstruct o)
- getSessionSslStrict :: (MonadIO m, IsSession o) => o -> m Bool
- setSessionSslStrict :: (MonadIO m, IsSession o) => o -> Bool -> m ()
- constructSessionSslUseSystemCaFile :: IsSession o => Bool -> IO (GValueConstruct o)
- getSessionSslUseSystemCaFile :: (MonadIO m, IsSession o) => o -> m Bool
- setSessionSslUseSystemCaFile :: (MonadIO m, IsSession o) => o -> Bool -> m ()
- constructSessionTimeout :: IsSession o => Word32 -> IO (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, IsTlsDatabase a) => a -> IO (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, IsTlsInteraction a) => a -> IO (GValueConstruct o)
- getSessionTlsInteraction :: (MonadIO m, IsSession o) => o -> m (Maybe TlsInteraction)
- setSessionTlsInteraction :: (MonadIO m, IsSession o, IsTlsInteraction a) => o -> a -> m ()
- constructSessionUseNtlm :: IsSession o => Bool -> IO (GValueConstruct o)
- getSessionUseNtlm :: (MonadIO m, IsSession o) => o -> m Bool
- setSessionUseNtlm :: (MonadIO m, IsSession o) => o -> Bool -> m ()
- constructSessionUseThreadContext :: IsSession o => Bool -> IO (GValueConstruct o)
- getSessionUseThreadContext :: (MonadIO m, IsSession o) => o -> m Bool
- setSessionUseThreadContext :: (MonadIO m, IsSession o) => o -> Bool -> m ()
- clearSessionUserAgent :: (MonadIO m, IsSession o) => o -> m ()
- constructSessionUserAgent :: IsSession o => Text -> IO (GValueConstruct o)
- getSessionUserAgent :: (MonadIO m, IsSession o) => o -> m (Maybe Text)
- setSessionUserAgent :: (MonadIO m, IsSession o) => o -> Text -> m ()
- type C_SessionAuthenticateCallback = Ptr () -> Ptr Message -> Ptr Auth -> CInt -> Ptr () -> IO ()
- type SessionAuthenticateCallback = Message -> Auth -> Bool -> IO ()
- afterSessionAuthenticate :: (IsSession a, MonadIO m) => a -> SessionAuthenticateCallback -> m SignalHandlerId
- genClosure_SessionAuthenticate :: MonadIO m => SessionAuthenticateCallback -> m (GClosure C_SessionAuthenticateCallback)
- mk_SessionAuthenticateCallback :: C_SessionAuthenticateCallback -> IO (FunPtr C_SessionAuthenticateCallback)
- noSessionAuthenticateCallback :: Maybe SessionAuthenticateCallback
- onSessionAuthenticate :: (IsSession a, MonadIO m) => a -> SessionAuthenticateCallback -> m SignalHandlerId
- wrap_SessionAuthenticateCallback :: SessionAuthenticateCallback -> C_SessionAuthenticateCallback
- type C_SessionConnectionCreatedCallback = Ptr () -> Ptr Object -> Ptr () -> IO ()
- type SessionConnectionCreatedCallback = Object -> IO ()
- afterSessionConnectionCreated :: (IsSession a, MonadIO m) => a -> SessionConnectionCreatedCallback -> m SignalHandlerId
- genClosure_SessionConnectionCreated :: MonadIO m => SessionConnectionCreatedCallback -> m (GClosure C_SessionConnectionCreatedCallback)
- mk_SessionConnectionCreatedCallback :: C_SessionConnectionCreatedCallback -> IO (FunPtr C_SessionConnectionCreatedCallback)
- noSessionConnectionCreatedCallback :: Maybe SessionConnectionCreatedCallback
- onSessionConnectionCreated :: (IsSession a, MonadIO m) => a -> SessionConnectionCreatedCallback -> m SignalHandlerId
- wrap_SessionConnectionCreatedCallback :: SessionConnectionCreatedCallback -> C_SessionConnectionCreatedCallback
- type C_SessionRequestQueuedCallback = Ptr () -> Ptr Message -> Ptr () -> IO ()
- type SessionRequestQueuedCallback = Message -> IO ()
- afterSessionRequestQueued :: (IsSession a, MonadIO m) => a -> SessionRequestQueuedCallback -> m SignalHandlerId
- genClosure_SessionRequestQueued :: MonadIO m => SessionRequestQueuedCallback -> m (GClosure C_SessionRequestQueuedCallback)
- mk_SessionRequestQueuedCallback :: C_SessionRequestQueuedCallback -> IO (FunPtr C_SessionRequestQueuedCallback)
- noSessionRequestQueuedCallback :: Maybe SessionRequestQueuedCallback
- onSessionRequestQueued :: (IsSession a, MonadIO m) => a -> SessionRequestQueuedCallback -> m SignalHandlerId
- wrap_SessionRequestQueuedCallback :: SessionRequestQueuedCallback -> C_SessionRequestQueuedCallback
- type C_SessionRequestStartedCallback = Ptr () -> Ptr Message -> Ptr Socket -> Ptr () -> IO ()
- type SessionRequestStartedCallback = Message -> Socket -> IO ()
- afterSessionRequestStarted :: (IsSession a, MonadIO m) => a -> SessionRequestStartedCallback -> m SignalHandlerId
- genClosure_SessionRequestStarted :: MonadIO m => SessionRequestStartedCallback -> m (GClosure C_SessionRequestStartedCallback)
- mk_SessionRequestStartedCallback :: C_SessionRequestStartedCallback -> IO (FunPtr C_SessionRequestStartedCallback)
- noSessionRequestStartedCallback :: Maybe SessionRequestStartedCallback
- onSessionRequestStarted :: (IsSession a, MonadIO m) => a -> SessionRequestStartedCallback -> m SignalHandlerId
- wrap_SessionRequestStartedCallback :: SessionRequestStartedCallback -> C_SessionRequestStartedCallback
- type C_SessionRequestUnqueuedCallback = Ptr () -> Ptr Message -> Ptr () -> IO ()
- type SessionRequestUnqueuedCallback = Message -> IO ()
- afterSessionRequestUnqueued :: (IsSession a, MonadIO m) => a -> SessionRequestUnqueuedCallback -> m SignalHandlerId
- genClosure_SessionRequestUnqueued :: MonadIO m => SessionRequestUnqueuedCallback -> m (GClosure C_SessionRequestUnqueuedCallback)
- mk_SessionRequestUnqueuedCallback :: C_SessionRequestUnqueuedCallback -> IO (FunPtr C_SessionRequestUnqueuedCallback)
- noSessionRequestUnqueuedCallback :: Maybe SessionRequestUnqueuedCallback
- onSessionRequestUnqueued :: (IsSession a, MonadIO m) => a -> SessionRequestUnqueuedCallback -> m SignalHandlerId
- wrap_SessionRequestUnqueuedCallback :: SessionRequestUnqueuedCallback -> C_SessionRequestUnqueuedCallback
- type C_SessionTunnelingCallback = Ptr () -> Ptr Object -> Ptr () -> IO ()
- type SessionTunnelingCallback = Object -> IO ()
- afterSessionTunneling :: (IsSession a, MonadIO m) => a -> SessionTunnelingCallback -> m SignalHandlerId
- genClosure_SessionTunneling :: MonadIO m => SessionTunnelingCallback -> m (GClosure C_SessionTunnelingCallback)
- mk_SessionTunnelingCallback :: C_SessionTunnelingCallback -> IO (FunPtr C_SessionTunnelingCallback)
- noSessionTunnelingCallback :: Maybe SessionTunnelingCallback
- onSessionTunneling :: (IsSession a, MonadIO m) => a -> SessionTunnelingCallback -> m SignalHandlerId
- wrap_SessionTunnelingCallback :: SessionTunnelingCallback -> C_SessionTunnelingCallback
Exported types
Memory-managed wrapper type.
Instances
GObject Session Source # | |
Defined in GI.Soup.Objects.Session gobjectType :: IO GType # | |
HasParentTypes Session Source # | |
Defined in GI.Soup.Objects.Session | |
type ParentTypes Session Source # | |
Defined in GI.Soup.Objects.Session |
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
abort
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> 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
:: (HasCallStack, MonadIO m, IsSession a, IsSessionFeature b) | |
=> a |
|
-> b |
|
-> 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 Source #
:: (HasCallStack, MonadIO m, IsSession a) | |
=> 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
:: (HasCallStack, MonadIO m, IsSession a, IsMessage b) | |
=> a |
|
-> b |
|
-> Word32 |
|
-> 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
:: (HasCallStack, MonadIO m, IsSession a, IsCancellable b) | |
=> a |
|
-> URI |
|
-> Maybe b |
|
-> Maybe SessionConnectProgressCallback |
|
-> Maybe AsyncReadyCallback |
|
-> 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
:: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b) | |
=> a |
|
-> b |
|
-> m IOStream | Returns: a new |
Gets the IOStream
created for the connection to communicate with the server.
Since: 2.62
getAsyncContext
sessionGetAsyncContext Source #
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> m (Maybe MainContext) | Returns: |
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
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> GType |
|
-> m (Maybe SessionFeature) | Returns: a |
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 Source #
:: (HasCallStack, MonadIO m, IsSession a, IsMessage b) | |
=> a |
|
-> GType |
|
-> b |
|
-> m (Maybe SessionFeature) | Returns: a |
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
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> GType |
|
-> 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
:: (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 SessionFeature
, or else a subtype of
some class managed by another feature, such as Auth
or
Request
).
Since: 2.42
new
:: (HasCallStack, MonadIO m) | |
=> m Session | Returns: the new session. |
Creates a Session
with the default options.
Since: 2.42
pauseMessage
:: (HasCallStack, MonadIO m, IsSession a, IsMessage b) | |
=> a |
|
-> b |
|
-> 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
:: (HasCallStack, MonadIO m, IsSession a, IsCancellable b) | |
=> a |
|
-> Text |
|
-> Maybe b |
|
-> Maybe AddressCallback |
|
-> 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
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> URI |
|
-> 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
:: (HasCallStack, MonadIO m, IsSession a, IsMessage b) | |
=> a |
|
-> b |
|
-> Maybe SessionCallback |
|
-> 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 Source #
:: (HasCallStack, MonadIO m, IsSession a, IsMessage b) | |
=> a |
|
-> b |
|
-> m Bool | Returns: |
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
:: (HasCallStack, MonadIO m, IsSession a, IsSessionFeature b) | |
=> a |
|
-> b |
|
-> m () |
Removes feature
's functionality from session
.
Since: 2.24
removeFeatureByType
sessionRemoveFeatureByType Source #
:: (HasCallStack, MonadIO m, IsSession a) | |
=> 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
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> Text |
|
-> m Request | Returns: a new |
Creates a Request
for retrieving uriString
.
Since: 2.42
requestHttp
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> Text |
|
-> Text |
|
-> m RequestHTTP | Returns: a new |
requestHttpUri
sessionRequestHttpUri Source #
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> Text |
|
-> URI |
|
-> m RequestHTTP | Returns: a new |
requestUri
:: (HasCallStack, MonadIO m, IsSession a) | |
=> a |
|
-> URI |
|
-> m Request | Returns: a new |
Creates a Request
for retrieving uri
.
Since: 2.42
requeueMessage
sessionRequeueMessage Source #
:: (HasCallStack, MonadIO m, IsSession a, IsMessage b) | |
=> a |
|
-> b |
|
-> m () |
This causes msg
to be placed back on the queue to be attempted
again.
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;
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
:: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c) | |
=> a |
|
-> b |
|
-> 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 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
:: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b) | |
=> a |
|
-> b |
|
-> m InputStream | Returns: a |
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
:: (HasCallStack, MonadIO m, IsSession a, IsMessage b) | |
=> a |
|
-> b |
|
-> 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 Source #
:: (HasCallStack, MonadIO m, IsSession a, IsMessage b) | |
=> a |
|
-> b |
|
-> m IOStream | Returns: the |
"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 Source #
:: (HasCallStack, MonadIO m, IsSession a, IsMessage b) | |
=> a |
|
-> b |
|
-> 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 Source #
:: (HasCallStack, MonadIO m, IsSession a, IsMessage b, IsCancellable c) | |
=> a |
|
-> b |
|
-> Maybe Text |
|
-> Maybe [Text] |
|
-> Maybe c |
|
-> Maybe AsyncReadyCallback |
|
-> 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 Source #
:: (HasCallStack, MonadIO m, IsSession a, IsAsyncResult b) | |
=> a |
|
-> b |
|
-> m WebsocketConnection | Returns: a new |
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
:: (HasCallStack, MonadIO m, IsSession a, IsMessage b) | |
=> a |
|
-> b |
|
-> m Bool | Returns: whether |
Checks if msg
contains a response that would cause session
to
redirect it to a new URL (ignoring msg
's MessageFlagsNoRedirect
flag, and the number of times it has already been redirected).
Since: 2.38
Properties
acceptLanguage
If non-Nothing
, the value to use for the "Accept-Language" header
on Message
<!-- -->s sent from this session.
Setting this will disable
Session
:accept-language-auto
.
Since: 2.30
clearSessionAcceptLanguage :: (MonadIO m, IsSession o) => o -> m () Source #
Set the value of the “accept-language
” property to Nothing
.
When overloading is enabled, this is equivalent to
clear
#acceptLanguage
constructSessionAcceptLanguage :: IsSession o => Text -> IO (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 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 => Bool -> IO (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 ]
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 => Ptr () -> IO (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “async-context
” property. This is rarely needed directly, but it is used by new
.
getSessionAsyncContext :: (MonadIO m, IsSession o) => o -> m (Ptr ()) Source #
Get the value of the “async-context
” property.
When overloading is enabled, this is equivalent to
get
session #asyncContext
httpAliases
A Nothing
-terminated array of URI schemes that should be
considered to be aliases for "http". Eg, if this included
<literal>"dav"</literal>, than a URI of
<literal>dav://example.com/path</literal> would be treated
identically to <literal>http://example.com/path</literal>.
In a plain Session
, the default value is Nothing
,
meaning that only "http" is recognized as meaning "http".
In SessionAsync
and SessionSync
, for backward
compatibility, the default value is an array containing the
single element <literal>"*"</literal>, a special value
which means that any scheme except "https" is considered to
be an alias for "http".
See also Session
:https-aliases
.
Since: 2.38
clearSessionHttpAliases :: (MonadIO m, IsSession o) => o -> m () Source #
Set the value of the “http-aliases
” property to Nothing
.
When overloading is enabled, this is equivalent to
clear
#httpAliases
constructSessionHttpAliases :: IsSession o => [Text] -> IO (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “http-aliases
” property. This is rarely needed directly, but it is used by new
.
getSessionHttpAliases :: (MonadIO m, IsSession o) => o -> m (Maybe [Text]) Source #
Get the value of the “http-aliases
” property.
When overloading is enabled, this is equivalent to
get
session #httpAliases
setSessionHttpAliases :: (MonadIO m, IsSession o) => o -> [Text] -> m () Source #
Set the value of the “http-aliases
” property.
When overloading is enabled, this is equivalent to
set
session [ #httpAliases:=
value ]
httpsAliases
A comma-delimited list of URI schemes that should be
considered to be aliases for "https". See
Session
:http-aliases
for more information.
The default value is Nothing
, meaning that no URI schemes
are considered aliases for "https".
Since: 2.38
clearSessionHttpsAliases :: (MonadIO m, IsSession o) => o -> m () Source #
Set the value of the “https-aliases
” property to Nothing
.
When overloading is enabled, this is equivalent to
clear
#httpsAliases
constructSessionHttpsAliases :: IsSession o => [Text] -> IO (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “https-aliases
” property. This is rarely needed directly, but it is used by new
.
getSessionHttpsAliases :: (MonadIO m, IsSession o) => o -> m (Maybe [Text]) Source #
Get the value of the “https-aliases
” property.
When overloading is enabled, this is equivalent to
get
session #httpsAliases
setSessionHttpsAliases :: (MonadIO m, IsSession o) => o -> [Text] -> m () Source #
Set the value of the “https-aliases
” property.
When overloading is enabled, this is equivalent to
set
session [ #httpsAliases:=
value ]
idleTimeout
Connection lifetime (in seconds) when idle. Any connection left idle longer than this will be closed.
Although you can change this property at any time, it will
only affect newly-created connections, not currently-open
ones. You can call sessionAbort
after setting this
if you want to ensure that all future connections will have
this timeout value.
Note that the default value of 60 seconds only applies to
plain SoupSessions
. If you are using SessionAsync
or
SessionSync
, the default value is 0 (meaning idle
connections will never time out).
Since: 2.24
constructSessionIdleTimeout :: IsSession o => Word32 -> IO (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 Address
to use for the client side of
the connection.
Use this property if you want for instance to bind the local socket to a specific IP address.
Since: 2.42
constructSessionLocalAddress :: (IsSession o, IsAddress a) => a -> IO (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “local-address
” property. This is rarely needed directly, but it is used by new
.
getSessionLocalAddress :: (MonadIO m, IsSession o) => o -> m (Maybe Address) Source #
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 => Int32 -> IO (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
setSessionMaxConns :: (MonadIO m, IsSession o) => o -> Int32 -> m () Source #
Set the value of the “max-conns
” property.
When overloading is enabled, this is equivalent to
set
session [ #maxConns:=
value ]
maxConnsPerHost
No description available in the introspection data.
constructSessionMaxConnsPerHost :: IsSession o => Int32 -> IO (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
setSessionMaxConnsPerHost :: (MonadIO m, IsSession o) => o -> Int32 -> m () Source #
Set the value of the “max-conns-per-host
” property.
When overloading is enabled, this is equivalent to
set
session [ #maxConnsPerHost:=
value ]
proxyResolver
A ProxyResolver
to use with this session. Setting this
will clear the Session
:proxy-uri
property, and remove
any <type>SoupProxyURIResolver</type> features that have
been added to the session.
By default, in a plain Session
, this is set to the
default ProxyResolver
, but you can set it to Nothing
if you
don't want to use proxies, or set it to your own
ProxyResolver
if you want to control what proxies get
used.
Since: 2.42
clearSessionProxyResolver :: (MonadIO m, IsSession o) => o -> m () Source #
Set the value of the “proxy-resolver
” property to Nothing
.
When overloading is enabled, this is equivalent to
clear
#proxyResolver
constructSessionProxyResolver :: (IsSession o, IsProxyResolver a) => a -> IO (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 ]
proxyUri
A proxy to use for all http and https requests in this
session. Setting this will clear the
Session
:proxy-resolver
property, and remove any
<type>SoupProxyURIResolver</type> features that have been
added to the session. Setting this property will also
cancel all currently pending messages.
Note that Session
will normally handle looking up the
user's proxy settings for you; you should only use
Session
:proxy-uri
if you need to override the user's
normal proxy settings.
Also note that this proxy will be used for
<emphasis>all</emphasis> requests; even requests to
<literal>localhost</literal>. If you need more control over
proxies, you can create a SimpleProxyResolver
and set the
Session
:proxy-resolver
property.
clearSessionProxyUri :: (MonadIO m, IsSession o) => o -> m () Source #
Set the value of the “proxy-uri
” property to Nothing
.
When overloading is enabled, this is equivalent to
clear
#proxyUri
constructSessionProxyUri :: IsSession o => URI -> IO (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “proxy-uri
” property. This is rarely needed directly, but it is used by new
.
getSessionProxyUri :: (MonadIO m, IsSession o) => o -> m (Maybe URI) Source #
Get the value of the “proxy-uri
” property.
When overloading is enabled, this is equivalent to
get
session #proxyUri
setSessionProxyUri :: (MonadIO m, IsSession o) => o -> URI -> m () Source #
Set the value of the “proxy-uri
” property.
When overloading is enabled, this is equivalent to
set
session [ #proxyUri:=
value ]
sslCaFile
File containing SSL CA certificates.
If the specified file does not exist or cannot be read, then libsoup will print a warning, and then behave as though it had read in a empty CA file, meaning that all SSL certificates will be considered invalid.
clearSessionSslCaFile :: (MonadIO m, IsSession o) => o -> m () Source #
Set the value of the “ssl-ca-file
” property to Nothing
.
When overloading is enabled, this is equivalent to
clear
#sslCaFile
constructSessionSslCaFile :: IsSession o => Text -> IO (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “ssl-ca-file
” property. This is rarely needed directly, but it is used by new
.
getSessionSslCaFile :: (MonadIO m, IsSession o) => o -> m (Maybe Text) Source #
Get the value of the “ssl-ca-file
” property.
When overloading is enabled, this is equivalent to
get
session #sslCaFile
setSessionSslCaFile :: (MonadIO m, IsSession o) => o -> Text -> m () Source #
Set the value of the “ssl-ca-file
” property.
When overloading is enabled, this is equivalent to
set
session [ #sslCaFile:=
value ]
sslStrict
Normally, if Session
:tls-database
is set (including if
it was set via Session
:ssl-use-system-ca-file
or
Session
:ssl-ca-file
), then libsoup will reject any
certificate that is invalid (ie, expired) or that is not
signed by one of the given CA certificates, and the
Message
will fail with the status
StatusSslFailed
.
If you set Session
:ssl-strict
to False
, then all
certificates will be accepted, and you will need to call
messageGetHttpsStatus
to distinguish valid from
invalid certificates. (This can be used, eg, if you want to
accept invalid certificates after giving some sort of
warning.)
For a plain Session
, if the session has no CA file or
TLS database, and this property is True
, then all
certificates will be rejected. However, beware that the
deprecated Session
subclasses (SessionAsync
and
SessionSync
) have the opposite behavior: if there is
no CA file or TLS database, then all certificates are always
accepted, and this property has no effect.
Since: 2.30
constructSessionSslStrict :: IsSession o => Bool -> IO (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “ssl-strict
” property. This is rarely needed directly, but it is used by new
.
getSessionSslStrict :: (MonadIO m, IsSession o) => o -> m Bool Source #
Get the value of the “ssl-strict
” property.
When overloading is enabled, this is equivalent to
get
session #sslStrict
setSessionSslStrict :: (MonadIO m, IsSession o) => o -> Bool -> m () Source #
Set the value of the “ssl-strict
” property.
When overloading is enabled, this is equivalent to
set
session [ #sslStrict:=
value ]
sslUseSystemCaFile
Setting this to True
is equivalent to setting
Session
:tls-database
to the default system CA database.
(and likewise, setting Session
:tls-database
to the
default database by hand will cause this property to
become True
).
Setting this to False
(when it was previously True
) will
clear the Session
:tls-database
field.
See Session
:ssl-strict
for more information on how
https certificate validation is handled.
Note that the default value of True
only applies to plain
SoupSessions
. If you are using SessionAsync
or
SessionSync
, the default value is False
, for backward
compatibility.
Since: 2.38
constructSessionSslUseSystemCaFile :: IsSession o => Bool -> IO (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “ssl-use-system-ca-file
” property. This is rarely needed directly, but it is used by new
.
getSessionSslUseSystemCaFile :: (MonadIO m, IsSession o) => o -> m Bool Source #
Get the value of the “ssl-use-system-ca-file
” property.
When overloading is enabled, this is equivalent to
get
session #sslUseSystemCaFile
setSessionSslUseSystemCaFile :: (MonadIO m, IsSession o) => o -> Bool -> m () Source #
Set the value of the “ssl-use-system-ca-file
” property.
When overloading is enabled, this is equivalent to
set
session [ #sslUseSystemCaFile:=
value ]
timeout
The timeout (in seconds) for socket I/O operations (including connecting to a server, and waiting for a reply to an HTTP request).
Although you can change this property at any time, it will
only affect newly-created connections, not currently-open
ones. You can call sessionAbort
after setting this
if you want to ensure that all future connections will have
this timeout value.
Note that the default value of 60 seconds only applies to
plain SoupSessions
. If you are using SessionAsync
or
SessionSync
, the default value is 0 (meaning socket I/O
will not time out).
Not to be confused with Session
:idle-timeout
(which is
the length of time that idle persistent connections will be
kept open).
constructSessionTimeout :: IsSession o => Word32 -> IO (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.
Note that setting the Session
:ssl-ca-file
or
Session
:ssl-use-system-ca-file
property will cause
this property to be set to a TlsDatabase
corresponding to
the indicated file or system default.
See Session
:ssl-strict
for more information on how
https certificate validation is handled.
If you are using a plain Session
then
Session
:ssl-use-system-ca-file
will be True
by
default, and so this property will be a copy of the system
CA database. If you are using SessionAsync
or
SessionSync
, this property will be Nothing
by default.
Since: 2.38
clearSessionTlsDatabase :: (MonadIO m, IsSession o) => o -> m () Source #
Set the value of the “tls-database
” property to Nothing
.
When overloading is enabled, this is equivalent to
clear
#tlsDatabase
constructSessionTlsDatabase :: (IsSession o, IsTlsDatabase a) => a -> IO (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “tls-database
” property. This is rarely needed directly, but it is used by new
.
getSessionTlsDatabase :: (MonadIO m, IsSession o) => o -> m (Maybe TlsDatabase) Source #
Get the value of the “tls-database
” property.
When overloading is enabled, this is equivalent to
get
session #tlsDatabase
setSessionTlsDatabase :: (MonadIO m, IsSession o, IsTlsDatabase a) => o -> a -> m () Source #
Set the value of the “tls-database
” property.
When overloading is enabled, this is equivalent to
set
session [ #tlsDatabase:=
value ]
tlsInteraction
A TlsInteraction
object that will be passed on to any
GTlsConnections
created by the session. (This can be used to
provide client-side certificates, for example.)
Since: 2.48
clearSessionTlsInteraction :: (MonadIO m, IsSession o) => o -> m () Source #
Set the value of the “tls-interaction
” property to Nothing
.
When overloading is enabled, this is equivalent to
clear
#tlsInteraction
constructSessionTlsInteraction :: (IsSession o, IsTlsInteraction a) => a -> IO (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 ]
useNtlm
Whether or not to use NTLM authentication.
constructSessionUseNtlm :: IsSession o => Bool -> IO (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “use-ntlm
” property. This is rarely needed directly, but it is used by new
.
getSessionUseNtlm :: (MonadIO m, IsSession o) => o -> m Bool Source #
Get the value of the “use-ntlm
” property.
When overloading is enabled, this is equivalent to
get
session #useNtlm
setSessionUseNtlm :: (MonadIO m, IsSession o) => o -> Bool -> m () Source #
Set the value of the “use-ntlm
” property.
When overloading is enabled, this is equivalent to
set
session [ #useNtlm:=
value ]
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 => Bool -> IO (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “use-thread-context
” property. This is rarely needed directly, but it is used by new
.
getSessionUseThreadContext :: (MonadIO m, IsSession o) => o -> m Bool Source #
Get the value of the “use-thread-context
” property.
When overloading is enabled, this is equivalent to
get
session #useThreadContext
setSessionUseThreadContext :: (MonadIO m, IsSession o) => o -> Bool -> m () Source #
Set the value of the “use-thread-context
” property.
When overloading is enabled, this is equivalent to
set
session [ #useThreadContext:=
value ]
userAgent
If non-Nothing
, the value to use for the "User-Agent" header
on Message
<!-- -->s sent from this session.
RFC 2616 says: "The User-Agent request-header field contains information about the user agent originating the request. This is for statistical purposes, the tracing of protocol violations, and automated recognition of user agents for the sake of tailoring responses to avoid particular user agent limitations. User agents SHOULD include this field with requests."
The User-Agent header contains a list of one or more product tokens, separated by whitespace, with the most significant product token coming first. The tokens must be brief, ASCII, and mostly alphanumeric (although "-", "_", and "." are also allowed), and may optionally include a "/" followed by a version string. You may also put comments, enclosed in parentheses, between or after the tokens.
If you set a Session
:user_agent
property that has trailing
whitespace, Session
will append its own product token
(eg, "<literal>libsoup/2.3.2</literal>") to the end of the
header for you.
clearSessionUserAgent :: (MonadIO m, IsSession o) => o -> m () Source #
Set the value of the “user-agent
” property to Nothing
.
When overloading is enabled, this is equivalent to
clear
#userAgent
constructSessionUserAgent :: IsSession o => Text -> IO (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
authenticate
type C_SessionAuthenticateCallback = Ptr () -> Ptr Message -> Ptr Auth -> CInt -> Ptr () -> IO () Source #
Type for the callback on the (unwrapped) C side.
type SessionAuthenticateCallback Source #
= Message |
|
-> Auth |
|
-> Bool |
|
-> 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 -> SessionAuthenticateCallback -> m SignalHandlerId Source #
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
genClosure_SessionAuthenticate :: MonadIO m => SessionAuthenticateCallback -> m (GClosure C_SessionAuthenticateCallback) Source #
Wrap the callback into a GClosure
.
mk_SessionAuthenticateCallback :: C_SessionAuthenticateCallback -> IO (FunPtr C_SessionAuthenticateCallback) Source #
Generate a function pointer callable from C code, from a C_SessionAuthenticateCallback
.
noSessionAuthenticateCallback :: Maybe SessionAuthenticateCallback Source #
A convenience synonym for
.Nothing
:: Maybe
SessionAuthenticateCallback
onSessionAuthenticate :: (IsSession a, MonadIO m) => a -> SessionAuthenticateCallback -> m SignalHandlerId Source #
Connect a signal handler for the “authenticate
” signal, to be run before the default handler.
When overloading is enabled, this is equivalent to
on
session #authenticate callback
wrap_SessionAuthenticateCallback :: SessionAuthenticateCallback -> C_SessionAuthenticateCallback Source #
Wrap a SessionAuthenticateCallback
into a C_SessionAuthenticateCallback
.
connectionCreated
type C_SessionConnectionCreatedCallback = Ptr () -> Ptr Object -> Ptr () -> IO () Source #
Type for the callback on the (unwrapped) C side.
type SessionConnectionCreatedCallback Source #
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 -> SessionConnectionCreatedCallback -> m SignalHandlerId Source #
Connect a signal handler for the “connection-created
” signal, to be run after the default handler.
When overloading is enabled, this is equivalent to
after
session #connectionCreated callback
genClosure_SessionConnectionCreated :: MonadIO m => SessionConnectionCreatedCallback -> m (GClosure C_SessionConnectionCreatedCallback) Source #
Wrap the callback into a GClosure
.
mk_SessionConnectionCreatedCallback :: C_SessionConnectionCreatedCallback -> IO (FunPtr C_SessionConnectionCreatedCallback) Source #
Generate a function pointer callable from C code, from a C_SessionConnectionCreatedCallback
.
noSessionConnectionCreatedCallback :: Maybe SessionConnectionCreatedCallback Source #
A convenience synonym for
.Nothing
:: Maybe
SessionConnectionCreatedCallback
onSessionConnectionCreated :: (IsSession a, MonadIO m) => a -> SessionConnectionCreatedCallback -> m SignalHandlerId Source #
Connect a signal handler for the “connection-created
” signal, to be run before the default handler.
When overloading is enabled, this is equivalent to
on
session #connectionCreated callback
wrap_SessionConnectionCreatedCallback :: SessionConnectionCreatedCallback -> C_SessionConnectionCreatedCallback Source #
requestQueued
type C_SessionRequestQueuedCallback = Ptr () -> Ptr Message -> Ptr () -> IO () Source #
Type for the callback on the (unwrapped) C side.
type SessionRequestQueuedCallback Source #
Emitted when a request is queued on session
. (Note that
"queued" doesn't just mean sessionQueueMessage
;
sessionSendMessage
implicitly queues the message
as well.)
When sending a request, first Session
::request_queued
is emitted, indicating that the session has become aware of
the request.
Once a connection is available to send the request on, the
session emits Session
::request_started
. Then, various
Message
signals are emitted as the message is
processed. If the message is requeued, it will emit
Message
::restarted
, which will then be followed by
another Session
::request_started
and another set of
Message
signals when the message is re-sent.
Eventually, the message will emit Message
::finished
.
Normally, this signals the completion of message
processing. However, it is possible that the application
will requeue the message from the "finished" handler (or
equivalently, from the sessionQueueMessage
callback). In that case, the process will loop back to
Session
::request_started
.
Eventually, a message will reach "finished" and not be
requeued. At that point, the session will emit
Session
::request_unqueued
to indicate that it is done
with the message.
To sum up: Session
::request_queued
and
Session
::request_unqueued
are guaranteed to be emitted
exactly once, but Session
::request_started
and
Message
::finished
(and all of the other Message
signals) may be invoked multiple times for a given message.
Since: 2.24
afterSessionRequestQueued :: (IsSession a, MonadIO m) => a -> SessionRequestQueuedCallback -> m SignalHandlerId Source #
Connect a signal handler for the “request-queued
” signal, to be run after the default handler.
When overloading is enabled, this is equivalent to
after
session #requestQueued callback
genClosure_SessionRequestQueued :: MonadIO m => SessionRequestQueuedCallback -> m (GClosure C_SessionRequestQueuedCallback) Source #
Wrap the callback into a GClosure
.
mk_SessionRequestQueuedCallback :: C_SessionRequestQueuedCallback -> IO (FunPtr C_SessionRequestQueuedCallback) Source #
Generate a function pointer callable from C code, from a C_SessionRequestQueuedCallback
.
noSessionRequestQueuedCallback :: Maybe SessionRequestQueuedCallback Source #
A convenience synonym for
.Nothing
:: Maybe
SessionRequestQueuedCallback
onSessionRequestQueued :: (IsSession a, MonadIO m) => a -> SessionRequestQueuedCallback -> m SignalHandlerId Source #
Connect a signal handler for the “request-queued
” signal, to be run before the default handler.
When overloading is enabled, this is equivalent to
on
session #requestQueued callback
wrap_SessionRequestQueuedCallback :: SessionRequestQueuedCallback -> C_SessionRequestQueuedCallback Source #
Wrap a SessionRequestQueuedCallback
into a C_SessionRequestQueuedCallback
.
requestStarted
type C_SessionRequestStartedCallback = Ptr () -> Ptr Message -> Ptr Socket -> Ptr () -> IO () Source #
Type for the callback on the (unwrapped) C side.
afterSessionRequestStarted :: (IsSession a, MonadIO m) => a -> SessionRequestStartedCallback -> m SignalHandlerId Source #
Connect a signal handler for the “request-started
” signal, to be run after the default handler.
When overloading is enabled, this is equivalent to
after
session #requestStarted callback
genClosure_SessionRequestStarted :: MonadIO m => SessionRequestStartedCallback -> m (GClosure C_SessionRequestStartedCallback) Source #
Wrap the callback into a GClosure
.
mk_SessionRequestStartedCallback :: C_SessionRequestStartedCallback -> IO (FunPtr C_SessionRequestStartedCallback) Source #
Generate a function pointer callable from C code, from a C_SessionRequestStartedCallback
.
noSessionRequestStartedCallback :: Maybe SessionRequestStartedCallback Source #
A convenience synonym for
.Nothing
:: Maybe
SessionRequestStartedCallback
onSessionRequestStarted :: (IsSession a, MonadIO m) => a -> SessionRequestStartedCallback -> m SignalHandlerId Source #
Connect a signal handler for the “request-started
” signal, to be run before the default handler.
When overloading is enabled, this is equivalent to
on
session #requestStarted callback
wrap_SessionRequestStartedCallback :: SessionRequestStartedCallback -> C_SessionRequestStartedCallback Source #
Wrap a SessionRequestStartedCallback
into a C_SessionRequestStartedCallback
.
requestUnqueued
type C_SessionRequestUnqueuedCallback = Ptr () -> Ptr Message -> Ptr () -> IO () Source #
Type for the callback on the (unwrapped) C side.
type SessionRequestUnqueuedCallback Source #
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 -> SessionRequestUnqueuedCallback -> m SignalHandlerId Source #
Connect a signal handler for the “request-unqueued
” signal, to be run after the default handler.
When overloading is enabled, this is equivalent to
after
session #requestUnqueued callback
genClosure_SessionRequestUnqueued :: MonadIO m => SessionRequestUnqueuedCallback -> m (GClosure C_SessionRequestUnqueuedCallback) Source #
Wrap the callback into a GClosure
.
mk_SessionRequestUnqueuedCallback :: C_SessionRequestUnqueuedCallback -> IO (FunPtr C_SessionRequestUnqueuedCallback) Source #
Generate a function pointer callable from C code, from a C_SessionRequestUnqueuedCallback
.
noSessionRequestUnqueuedCallback :: Maybe SessionRequestUnqueuedCallback Source #
A convenience synonym for
.Nothing
:: Maybe
SessionRequestUnqueuedCallback
onSessionRequestUnqueued :: (IsSession a, MonadIO m) => a -> SessionRequestUnqueuedCallback -> m SignalHandlerId Source #
Connect a signal handler for the “request-unqueued
” signal, to be run before the default handler.
When overloading is enabled, this is equivalent to
on
session #requestUnqueued callback
wrap_SessionRequestUnqueuedCallback :: SessionRequestUnqueuedCallback -> C_SessionRequestUnqueuedCallback Source #
Wrap a SessionRequestUnqueuedCallback
into a C_SessionRequestUnqueuedCallback
.
tunneling
type C_SessionTunnelingCallback = Ptr () -> Ptr Object -> Ptr () -> IO () Source #
Type for the callback on the (unwrapped) C side.
type SessionTunnelingCallback Source #
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 -> SessionTunnelingCallback -> m SignalHandlerId Source #
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
genClosure_SessionTunneling :: MonadIO m => SessionTunnelingCallback -> m (GClosure C_SessionTunnelingCallback) Source #
Wrap the callback into a GClosure
.
mk_SessionTunnelingCallback :: C_SessionTunnelingCallback -> IO (FunPtr C_SessionTunnelingCallback) Source #
Generate a function pointer callable from C code, from a C_SessionTunnelingCallback
.
noSessionTunnelingCallback :: Maybe SessionTunnelingCallback Source #
A convenience synonym for
.Nothing
:: Maybe
SessionTunnelingCallback
onSessionTunneling :: (IsSession a, MonadIO m) => a -> SessionTunnelingCallback -> m SignalHandlerId Source #
Connect a signal handler for the “tunneling
” signal, to be run before the default handler.
When overloading is enabled, this is equivalent to
on
session #tunneling callback