asakul
/
pontarius-xmpp
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Browse Source

removed lyx manual and added manual and tutorial placeholder files

master
Jon Kristensen 14 years ago
parent
c68a5275d4
commit
53a236d479
3 changed files with 0 additions and 593 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 593
      documentation/Manual.lyx
  2. 0
      documentation/manual.md
  3. 0
      documentation/tutorial.md

593
documentation/Manual.lyx
Unescape View File

@ -1,593 +0,0 @@ @@ -1,593 +0,0 @@
#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

0
documentation/manual.md
Unescape View File

0
documentation/tutorial.md
Unescape View File

Write Preview
Loading…
Cancel
Save