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.
536 lines
12 KiB
536 lines
12 KiB
#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
|
|
|