Merge branch 'master' of https://github.com/nejla/pontarius

14 years ago · 7331147fed
5 changed files with 0 additions and 593 deletions
--- a/Documentation/Manual.lyx
+++ b/Documentation/Manual.lyx
@ -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
--- a/documentation/manual.md
+++ b/documentation/manual.md
--- a/documentation/tutorial.md
+++ b/documentation/tutorial.md
--- a/examples/EchoClient.hs
+++ b/examples/EchoClient.hs
--- a/examples/IBR.hs
+++ b/examples/IBR.hs