Network.XMPP.Session

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.

Documentation

data MonadIO m => ClientHandler s m

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.

Constructors

ClientHandler

Fields

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

Methods

putSession :: s -> Session s m -> s

data ConnectResult

Constructors

ConnectSuccess StreamProperties StreamFeatures (Maybe Resource)

ConnectOpenStreamFailure

ConnectSecureWithTLSFailure

ConnectAuthenticateFailure

data Session s m

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

TerminationReason contains information on why the XMPP session was terminated.

data OpenStreamResult

Constructors

OpenStreamSuccess StreamProperties StreamFeatures

OpenStreamFailure

data SecureWithTLSResult

Constructors

SecureWithTLSSuccess StreamProperties StreamFeatures

SecureWithTLSFailure

data AuthenticateResult

Constructors

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

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 ClientHandlers; 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.

injectAction :: MonadIO m => Session s m -> Maybe (StateT s m Bool) -> StateT s m () -> StateT s m ()