pontarius-xmpp- A (prototyped) secure and easy to use XMPP library




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

class ClientState s m whereSource


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

data Session s m Source

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 

data SecureWithTLSResult Source


SecureWithTLSSuccess StreamProperties StreamFeatures 

data AuthenticateResult Source


AuthenticateSuccess StreamProperties StreamFeatures Resource 

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

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