Portability | portable |
---|---|
Stability | unstable |
Maintainer | info@pontarius.org |
This module provides the functions used by XMPP clients to manage their XMPP sessions.
Working with Pontarius XMPP is mostly done asynchronously with callbacks;
Pontarius XMPP owns the XMPP thread and carries the client state with it. A
client consists of a list of client handlers to handle XMPP events. This is
all set up through a Session
object, which a client can create by calling
the (blocking) function createSession
.
The Pontarius XMPP functions operate in an arbitrary MonadIO monad. Typically, clients will use the IO monad.
For more information, see the Pontarius XMPP Manual.
- data MonadIO m => ClientHandler s m = ClientHandler {
- messageReceived :: Maybe (Message -> StateT s m Bool)
- presenceReceived :: Maybe (Presence -> StateT s m Bool)
- iqReceived :: Maybe (IQ -> StateT s m Bool)
- sessionTerminated :: Maybe (TerminationReason -> StateT s m ())
- class ClientState s m where
- putSession :: s -> Session s m -> s
- data ConnectResult
- = ConnectSuccess StreamProperties StreamFeatures (Maybe Resource)
- | ConnectOpenStreamFailure
- | ConnectSecureWithTLSFailure
- | ConnectAuthenticateFailure
- data Session s m
- data TerminationReason
- data OpenStreamResult
- = OpenStreamSuccess StreamProperties StreamFeatures
- | OpenStreamFailure
- data SecureWithTLSResult
- = SecureWithTLSSuccess StreamProperties StreamFeatures
- | SecureWithTLSFailure
- data AuthenticateResult
- = AuthenticateSuccess StreamProperties StreamFeatures Resource
- | AuthenticateFailure
- sendPresence :: MonadIO m => Session s m -> Presence -> Maybe (Presence -> StateT s m Bool) -> Maybe (Timeout, StateT s m ()) -> Maybe (StreamError -> StateT s m ()) -> StateT s m ()
- sendIQ :: MonadIO m => Session s m -> IQ -> Maybe (IQ -> StateT s m Bool) -> Maybe (Timeout, StateT s m ()) -> Maybe (StreamError -> StateT s m ()) -> StateT s m ()
- sendMessage :: MonadIO m => Session s m -> Message -> Maybe (Message -> StateT s m Bool) -> Maybe (Timeout, StateT s m ()) -> Maybe (StreamError -> StateT s m ()) -> StateT s m ()
- connect :: MonadIO m => Session s m -> HostName -> PortNumber -> Maybe (Certificate, Certificate -> Bool) -> Maybe (UserName, Password, Maybe Resource) -> (ConnectResult -> StateT s m ()) -> StateT s m ()
- openStream :: MonadIO m => Session s m -> HostName -> PortNumber -> (OpenStreamResult -> StateT s m ()) -> StateT s m ()
- secureWithTLS :: MonadIO m => Session s m -> Certificate -> (Certificate -> Bool) -> (SecureWithTLSResult -> StateT s m ()) -> StateT s m ()
- authenticate :: MonadIO m => Session s m -> UserName -> Password -> Maybe Resource -> (AuthenticateResult -> StateT s m ()) -> StateT s m ()
- session :: (MonadIO m, ClientState s m) => s -> [ClientHandler s m] -> StateT s m () -> m ()
- injectAction :: MonadIO m => Session s m -> Maybe (StateT s m Bool) -> StateT s m () -> StateT s m ()
Documentation
data MonadIO m => ClientHandler s m Source
A client typically needs one or more ClientHandler
objects to interact
with Pontarius XMPP. Each client handler may provide four callback
functions; the first three callbacks deals with received stanzas, and the
last one is used when the session is terminated.
These stanza functions takes the current client state and an object containing the details of the stanza in question. The boolean returned along with the possibly updated state signals whether or not the message should be blocked to client handlerss further down the stack. For example, an XEP-0030: Service Discovery handler may choose to hide disco#info requests to handlers above it in the stack.
The sessionTerminated
callback function takes a TerminationReason
value
along with the state and will be sent to all client handlers.
ClientHandler | |
|
class ClientState s m whereSource
putSession :: s -> Session s m -> sSource
data ConnectResult Source
ConnectSuccess StreamProperties StreamFeatures (Maybe Resource) | |
ConnectOpenStreamFailure | |
ConnectSecureWithTLSFailure | |
ConnectAuthenticateFailure |
The Session
object is used by clients when interacting with Pontarius
XMPP. It holds information needed by Pontarius XMPP; its content is not
accessible from the client.
data TerminationReason Source
TerminationReason
contains information on why the XMPP session was
terminated.
data OpenStreamResult Source
OpenStreamSuccess StreamProperties StreamFeatures | |
OpenStreamFailure |
data SecureWithTLSResult Source
SecureWithTLSSuccess StreamProperties StreamFeatures | |
SecureWithTLSFailure |
data AuthenticateResult Source
AuthenticateSuccess StreamProperties StreamFeatures Resource | |
AuthenticateFailure |
sendPresence :: MonadIO m => Session s m -> Presence -> Maybe (Presence -> StateT s m Bool) -> Maybe (Timeout, StateT s m ()) -> Maybe (StreamError -> StateT s m ()) -> StateT s m ()Source
sendIQ :: MonadIO m => Session s m -> IQ -> Maybe (IQ -> StateT s m Bool) -> Maybe (Timeout, StateT s m ()) -> Maybe (StreamError -> StateT s m ()) -> StateT s m ()Source
sendMessage :: MonadIO m => Session s m -> Message -> Maybe (Message -> StateT s m Bool) -> Maybe (Timeout, StateT s m ()) -> Maybe (StreamError -> StateT s m ()) -> StateT s m ()Source
connect :: MonadIO m => Session s m -> HostName -> PortNumber -> Maybe (Certificate, Certificate -> Bool) -> Maybe (UserName, Password, Maybe Resource) -> (ConnectResult -> StateT s m ()) -> StateT s m ()Source
openStream :: MonadIO m => Session s m -> HostName -> PortNumber -> (OpenStreamResult -> StateT s m ()) -> StateT s m ()Source
secureWithTLS :: MonadIO m => Session s m -> Certificate -> (Certificate -> Bool) -> (SecureWithTLSResult -> StateT s m ()) -> StateT s m ()Source
authenticate :: MonadIO m => Session s m -> UserName -> Password -> Maybe Resource -> (AuthenticateResult -> StateT s m ()) -> StateT s m ()Source
session :: (MonadIO m, ClientState s m) => s -> [ClientHandler s m] -> StateT s m () -> m ()Source
Creates an XMPP session. Blocks the current thread. The first parameter,
s
, is an arbitrary state that is defined by the client. This is the
initial state, and it will be passed to the client (handlers) as XMPP
events are emitted. The second parameter is the list of ClientHandler
s;
this is a way to provide a layered system of XMPP event handlers. For
example, a client may have a dedicated handler to manage messages,
implement a spam protection system, etc. Messages are piped through these
handlers one by one, and any handler may block the message from being sent
to the next handler(s) above in the stack. The third argument is a callback
function that will be called when the session has been initialized, and
this function should be used by the client to store the Session object in
its state.