Welcome to Pontarius XMPP!

Pontarius XMPP is an active work in progress to build a Haskell XMPP library that implements the client capabilities of RFC 6120 ("XMPP Core").

Getting started

The latest release of Pontarius XMPP, as well as its module API pages, can always be found at the Pontarius XMPP Hackage page.

Note: Pontarius XMPP is still in its Alpha phase. Pontarius XMPP is not yet feature-complete, it may contain bugs, and its API may change between versions.

The first thing to do is to import the Network.Xmpp module.

import Network.Xmpp

When this is done, a Session object can be acquired by calling session. This object will be used for interacting with the library.

result <- session
             "example.com"
              def
              (Just ([scramSha1 "user" Nothing "Password"], Nothing))

Tip: Note that the first parameter actually is a Text value. Import Data.Text and use the OverloadedStrings LANGUAGE pragma.

The three parameters above are the XMPP server realm, the session configuration settings (set to the default settings), and a SASL handler (for authentication). session will perform the necessary DNS queries to find the address of the realm, connect, establish the XMPP stream, attempt to secure the stream with TLS, authenticate, establish a concurrent interface for interacting with the stream, and return the Session object.

The return type of session is IO (Either XmppFailure (Session, Maybe AuthFailure)). As XmppFailure is an Control.Monad.Error instance, you can utilize the ErrorT monad transformer for error handling. A more simple way of doing it could be doing something like this:

sess <- case result of
            Right (sess, Nothing) -> sess
            Right (_sess, e) -> error "AuthFailure: " ++ (show e)
            Left e -> error "XmppFailure: " ++ (show e)

Next, let us set our status to Online.

sendPresence presenceOnline sess

Now, let's say that we want to receive all message stanzas, and echo the stanzas back to the recipient. This can be done like so:

forever $ do
    msg <- getMessage sess
    sendMessage (answerIM (bodies msg) [] msg) sess
    let sender = show . fromJust $ messageFrom msg
    let contents = maybe "nothing" Text.unpack $ body msg
    printf "%s says \"%s\"\n" sender contents

Additional XMPP threads can be created using dupSession and forkIO.

For a public domain example of a simple Pontarius XMPP (Cabal) project, refer to the examples/echoclient directory.

More information

Feel free to contact Jon Kristensen if you have any questions or comments.