pontarius-xmpp/Documentation/Manual.lyx

#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 1.0 Manual (Fifth Draft)
\end_layout

\begin_layout Author
Nejla
\end_layout

\begin_layout Date
March 25, 2012
\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 is a work in progress of a minimal XMPP client implementation
 with all the required client features and behaviours of the RFC 6120 ("XMPP
 Core") specification
\begin_inset Foot
status open

\begin_layout Plain Layout
http://tools.ietf.org/html/rfc6120
\end_layout

\end_inset

.
 Pontarius has been developed by the Pontarius project (mainly by Jon Kristensen
), and has now been taken over by Nejla.

\series bold
 
\series default
Being licensed under the Apache License (Version 2), Pontarius is free and
 open source software.
\end_layout

\begin_layout Section
Features and Implementation Specifics
\end_layout

\begin_layout Standard
Pontarius 1.0 will implement the XMPP Core specification (RFC 6120).
 Features include the following:
\end_layout

\begin_layout Itemize
Connecting and disconnecting from an XMPP server
\end_layout

\begin_layout Itemize
Opening the XMPP streams
\end_layout

\begin_layout Itemize
Securing XMPP streams with TLS
\end_layout

\begin_layout Itemize
Authenticate using SASL
\end_layout

\begin_layout Itemize
Perform resource binding
\end_layout

\begin_layout Itemize
Send and receive stanzas (message, presence, and IQ) and stanza errors
\end_layout

\begin_layout Itemize
Send and receive stream errors
\end_layout

\begin_layout Standard
Below are the specifics of our implementation:
\end_layout

\begin_layout Itemize
Pontarius XMPP is a client library; the application using Pontarius XMPP
 is always the 
\begin_inset Quotes eld
\end_inset

initiating entity
\begin_inset Quotes erd
\end_inset


\end_layout

\begin_layout Itemize
A client-to-server connection always consists of exactly one TCP connection
\end_layout

\begin_layout Itemize
For stream security through TLS, only the TLS_RSA_WITH_AES_128_CBC_SHA cipher
 suite is supported
\end_layout

\begin_layout Itemize
TLS renegotiation is not supported
\end_layout

\begin_layout Itemize
TLS channel binding is not supported
\end_layout

\begin_layout Itemize
For (SASL) authentication, the SHA-1 variant of SASL Salted Challenge Response
 Authentication Mechanism (SCRAM-SHA-1) is the only supported mechanism
\end_layout

\begin_layout Section
Future Development
\end_layout

\begin_layout Standard
The current goal for Pontarius XMPP 2.0 is to serve as a library for an XMPP
 server.
\end_layout

\begin_layout Section
Usage
\end_layout

\begin_layout Standard

\noun on
Note that the information provided below is out-of-date.
 It will be updated before the next release.
\end_layout

\begin_layout Standard
Working with Pontarius 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
As with email, XMPP uses globally unique addresses (or JIDs, as they are
 also called) in order to route and deliver messages over the network.
 All XMPP entities are addressable on the local network.
\end_layout

\begin_layout Standard
There are four functions dealing with XMPP addresses:
\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