You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
76 lines
2.9 KiB
76 lines
2.9 KiB
13 years ago
|
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")](http://tools.ietf.org/html/rfc6120).
|
||
|
|
|
||
|
|
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](http://hackage.haskell.org/package/pontarius-xmpp/).
|
||
|
|
|
||
|
|
_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 <code>Network.Xmpp</code> module.
|
||
|
|
|
||
|
|
import Network.Xmpp
|
||
|
|
|
||
|
|
When this is done, a <code>Session</code> object can be acquired by calling
|
||
|
|
<code>session</code>. 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
|
||
|
|
<code>Data.Text</code> 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).
|
||
|
|
<code>session</code> 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 <code>Session</code> object.
|
||
|
|
|
||
|
|
The return type of <code>session</code> is <code>IO (Either XmppFailure
|
||
|
|
(Session, Maybe AuthFailure))</code>. As <code>XmppFailure</code> is an
|
||
|
|
<code>Control.Monad.Error</code> instance, you can utilize the
|
||
|
|
<code>ErrorT</code> 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 <code>dupSession</code> and
|
||
|
|
<code>forkIO</code>.
|
||
|
|
|
||
|
|
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](http://www.jonkri.com/contact/) if you
|
||
|
|
have any questions or comments.
|