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.
537 lines
12 KiB
537 lines
12 KiB
15 years ago
|
#LyX 2.0 created this file. For more info see http://www.lyx.org/
|
||
|
|
\lyxformat 413
|
||
|
|
\begin_document
|
||
|
|
\begin_header
|
||
|
|
\textclass article
|
||
|
|
\use_default_options true
|
||
|
|
\maintain_unincluded_children false
|
||
|
|
\language english
|
||
|
|
\language_package default
|
||
|
|
\inputencoding auto
|
||
|
|
\fontencoding global
|
||
|
|
\font_roman default
|
||
|
|
\font_sans default
|
||
|
|
\font_typewriter default
|
||
|
|
\font_default_family default
|
||
|
|
\use_non_tex_fonts false
|
||
|
|
\font_sc false
|
||
|
|
\font_osf false
|
||
|
|
\font_sf_scale 100
|
||
|
|
\font_tt_scale 100
|
||
|
|
|
||
|
|
\graphics default
|
||
|
|
\default_output_format default
|
||
|
|
\output_sync 0
|
||
|
|
\bibtex_command default
|
||
|
|
\index_command default
|
||
|
|
\paperfontsize default
|
||
|
|
\spacing single
|
||
|
|
\use_hyperref false
|
||
|
|
\papersize default
|
||
|
|
\use_geometry false
|
||
|
|
\use_amsmath 1
|
||
|
|
\use_esint 1
|
||
|
|
\use_mhchem 1
|
||
|
|
\use_mathdots 1
|
||
|
|
\cite_engine basic
|
||
|
|
\use_bibtopic false
|
||
|
|
\use_indices false
|
||
|
|
\paperorientation portrait
|
||
|
|
\suppress_date false
|
||
|
|
\use_refstyle 1
|
||
|
|
\index Index
|
||
|
|
\shortcut idx
|
||
|
|
\color #008000
|
||
|
|
\end_index
|
||
|
|
\secnumdepth 3
|
||
|
|
\tocdepth 3
|
||
|
|
\paragraph_separation indent
|
||
|
|
\paragraph_indentation default
|
||
|
|
\quotes_language english
|
||
|
|
\papercolumns 1
|
||
|
|
\papersides 1
|
||
|
|
\paperpagestyle default
|
||
|
|
\tracking_changes false
|
||
|
|
\output_changes false
|
||
|
|
\html_math_output 0
|
||
|
|
\html_css_as_file 0
|
||
|
|
\html_be_strict false
|
||
|
|
\end_header
|
||
|
|
|
||
|
|
\begin_body
|
||
|
|
|
||
|
|
\begin_layout Title
|
||
|
|
Pontarius XMPP 0.1 Manual (Third Draft)
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Author
|
||
|
|
The Pontarius Project
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Date
|
||
|
|
The 6th of July, 2011
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
\begin_inset CommandInset toc
|
||
|
|
LatexCommand tableofcontents
|
||
|
|
|
||
|
|
\end_inset
|
||
|
|
|
||
|
|
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Section
|
||
|
|
Introduction
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
Pontarius XMPP aims to be a convenient-to-use, powerful, correct, secure,
|
||
|
|
and extendable XMPP client library for Haskell.
|
||
|
|
It is written by Jon Kristensen and Mahdi Abdinejadi.
|
||
|
|
Being licensed under the GNU Lesser General Public License, Pontarius XMPP
|
||
|
|
is free and open source software.
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Section
|
||
|
|
Features and Implementation Specifics
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
Pontarius XMPP 0.1 implements the client capabilities of the XMPP Core specificat
|
||
|
|
ion (RFC 6120)
|
||
|
|
\begin_inset Foot
|
||
|
|
status open
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
http://tools.ietf.org/html/rfc6120
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\end_inset
|
||
|
|
|
||
|
|
.
|
||
|
|
Below are the specifics of our implementation.
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Itemize
|
||
|
|
The client is always the initiating entity
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Itemize
|
||
|
|
A client-of-server connection is always exactly one TCP connection
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Itemize
|
||
|
|
TLS is supported for client-to-server confidentiality
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Itemize
|
||
|
|
Only the SCRAM authentication method is supported
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Itemize
|
||
|
|
...
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
Later versions will add supports for different XMPP extensions, such as
|
||
|
|
RFC 6121 (XMPP IM), XEP-0004: Data Forms, and XEP-0077: In-Band Registration.
|
||
|
|
\begin_inset Foot
|
||
|
|
status open
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
XMPP RFCs can be found at http://xmpp.org/xmpp-protocols/rfcs/, and the so-called
|
||
|
|
XEPs at http://xmpp.org/xmpp-protocols/xmpp-extensions/.
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\end_inset
|
||
|
|
|
||
|
|
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Section
|
||
|
|
Usage
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
Working with Pontarius XMPP is mostly done asynchronously; Pontarius XMPP
|
||
|
|
``owns'' the XMPP thread, and calls different StateT s m a callback functions
|
||
|
|
in the client.
|
||
|
|
StateT is a monad transformer which allows the functions to be stateful
|
||
|
|
(being able to access and modify the arbitrary client-defined state of
|
||
|
|
type s) and to be executed on top of a MonadIO m monad (typically IO).
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Subsection
|
||
|
|
Creating the session
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
Setting up an XMPP session is done through the (blocking) session function:
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
\begin_inset listings
|
||
|
|
inline false
|
||
|
|
status open
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
session :: (MonadIO m, ClientState s m) => s ->
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
[ClientHandler s m] -> (StateT s m ()) -> m ()
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\end_inset
|
||
|
|
|
||
|
|
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
The first parameter (of type s) is an arbitrary state that is defined by
|
||
|
|
the client.
|
||
|
|
This is the initial state, and it will be passed to the stateful client
|
||
|
|
callbacks.
|
||
|
|
It will typically be modified by the client.
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
The second parameter is the list of client handlers to deal with XMPP callbacks.
|
||
|
|
The reason why we have a list is because we want to provide a ``layered''
|
||
|
|
system of XMPP event handlers.
|
||
|
|
For example, XMPP client developers may want to have a dedicated handler
|
||
|
|
to manage messages, implement a spam protection system, and so on.
|
||
|
|
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.
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
\begin_inset listings
|
||
|
|
inline false
|
||
|
|
status open
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
data MonadIO m => ClientHandler s m = ClientHandler {
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
messageReceived :: Maybe (Message ->
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
StateT s m Bool), presenceReceived :: Maybe
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
(Presence -> StateT s m Bool), iqReceived ::
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
Maybe (IQ -> StateT s m Bool),
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
sessionTerminated :: Maybe (TerminationReason ->
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
StateT s m ()) }
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\end_inset
|
||
|
|
|
||
|
|
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
ClientHandler is a record which specifies four callback functions.
|
||
|
|
The first three deals with the three XMPP stanzas, and are called once
|
||
|
|
an XMPP stanza is received.
|
||
|
|
These functions take the stanza in question, and are stateful with the
|
||
|
|
current client state.
|
||
|
|
The boolean value returned signals whether or not the message should be
|
||
|
|
blocked to clients further down the stack.
|
||
|
|
For example, a XEP-0030: Service Discovery handler may choose to hide disco#inf
|
||
|
|
o requests handlers above it in the stack.
|
||
|
|
The last function is the callback that is used when the XMPP session is
|
||
|
|
terminated.
|
||
|
|
All callbacks are optional.
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
The third argument to session is a callback function that will be called
|
||
|
|
when the session has been initialized.
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
Any function with access to the Session object can operate with the XMPP
|
||
|
|
session, such as connecting the XMPP client or sending stanzas.
|
||
|
|
More on this below.
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Subsection
|
||
|
|
Connecting the client
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
Different clients connect to XMPP in different ways.
|
||
|
|
Some secure the stream with TLS, and some authenticate with the server.
|
||
|
|
Pontarius XMPP provides a flexible function to help out with this in a
|
||
|
|
convenient way:
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
\begin_inset listings
|
||
|
|
inline false
|
||
|
|
status open
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
connect :: MonadIO m => Session s m -> HostName ->
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
PortNumber -> Maybe (Certificate, (Certificate ->
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
Bool)) -> Maybe (UserName, Password, Maybe
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
Resource) -> (ConnectResult -> StateT s m ()) ->
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
StateT s m ()
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\end_inset
|
||
|
|
|
||
|
|
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
This function simply takes the host name and port number to connect to,
|
||
|
|
an optional tuple of the certificate to use and a function evaluating certifica
|
||
|
|
tes for TLS (if Nothing is provided, the connection will not be TLS secured),
|
||
|
|
and another optional tuple with user name, password, and an optional resource
|
||
|
|
for authentication (analogously, providing Nothing here causes Pontarius
|
||
|
|
XMPP not to authenticate).
|
||
|
|
The final paramter is a callback function providing the result of the connect
|
||
|
|
action.
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
For more fine-grained control of the connection, use the openStream, secureWithT
|
||
|
|
LS, and authenticate functions.
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Subsection
|
||
|
|
Managing XMPP addresses
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
There are four functions dealing with XMPP addresses (or JIDs, as they are
|
||
|
|
also called):
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
\begin_inset listings
|
||
|
|
inline false
|
||
|
|
status open
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
fromString :: String -> Maybe Address
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
fromStrings :: Maybe String -> String ->
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
Maybe String -> Maybe Address
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
isBare :: Address -> Bool
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
isFull :: Address -> Bool
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\end_inset
|
||
|
|
|
||
|
|
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
These functions should be pretty self-explainatory to those who know the
|
||
|
|
XMPP: Core standard.
|
||
|
|
The fromString functions takes one to three strings and tries to construct
|
||
|
|
an XMPP address.
|
||
|
|
isBare and isFull checks whether or not the bare is full (has a resource
|
||
|
|
value).
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Subsection
|
||
|
|
Sending stanzas
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
Sending messages is done using this function:
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
\begin_inset listings
|
||
|
|
inline false
|
||
|
|
status open
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
sendMessage :: MonadIO m => Session s m -> Message ->
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
Maybe (Message -> StateT s m Bool) ->
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
Maybe (Timeout, StateT s m ()) ->
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
Maybe (StreamError -> StateT s m ()) ->
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
StateT s m ()
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\end_inset
|
||
|
|
|
||
|
|
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
Like in section 3.2, the first parameter is the session object.
|
||
|
|
The second is the message (check the Message record type in the API).
|
||
|
|
The third parameter is an optional callback function to be executed if
|
||
|
|
a reply to the message is received.
|
||
|
|
The fourth parameter contains a Timeout (Integer) value, and a callback
|
||
|
|
that Pontarius XMPP will call when a reply has not been received in the
|
||
|
|
window of the timeout.
|
||
|
|
The last parameter is an optional callback that is called if a stream error
|
||
|
|
occurs.
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
Presence and IQ stanzas are sent in a very similar way.
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
Stanza IDs will be set for you if you leave them out.
|
||
|
|
If, however, you want to know what ID you send, you can acquire a stanza
|
||
|
|
ID by calling the getID function:
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
\begin_inset listings
|
||
|
|
inline false
|
||
|
|
status open
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
getID :: MonadIO m => Session s m -> StateT s m String
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\end_inset
|
||
|
|
|
||
|
|
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Subsection
|
||
|
|
Concurrent usage
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
Sometimes clients will want to perform XMPP actions from more than one thread,
|
||
|
|
or in other words, they want to perform actions from code that is not a
|
||
|
|
Pontarius XMPP callback.
|
||
|
|
For these use cases, use injectAction:
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
\begin_inset listings
|
||
|
|
inline false
|
||
|
|
status open
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
injectAction :: MonadIO m => Session s m ->
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
Maybe (StateT s m Bool) -> StateT s m () ->
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Plain Layout
|
||
|
|
|
||
|
|
StateT s m ()
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\end_inset
|
||
|
|
|
||
|
|
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
The second parameter is an optional predicate callback to be executed right
|
||
|
|
before the third parameter callback is called.
|
||
|
|
If it is provided and evaluates to False, then the action will not be called.
|
||
|
|
Otherwise, the action will be called.
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Subsection
|
||
|
|
Example echo server
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\begin_layout Standard
|
||
|
|
We provide an example to further illustrate the Pontarius XMPP API and to
|
||
|
|
make it easier for developers to get started with the library.
|
||
|
|
The program illustrates how to connect, authenticate, set a presence, and
|
||
|
|
echo all messages received.
|
||
|
|
It only uses one client handler.
|
||
|
|
The contents of this example may be used freely, as if it is in the public
|
||
|
|
domain.
|
||
|
|
You find it in the Examples directory of the Pontarius XMPP source code.
|
||
|
|
\end_layout
|
||
|
|
|
||
|
|
\end_body
|
||
|
|
\end_document
|