From c68a5275d4022d1b42563eaba666fad5a1f66d6d Mon Sep 17 00:00:00 2001 From: Jon Kristensen Date: Thu, 10 May 2012 18:10:08 +0200 Subject: [PATCH 1/2] Documentation and Examples directory lower-case --- {Documentation => documentation}/Manual.lyx | 0 {Examples => examples}/EchoClient.hs | 0 {Examples => examples}/IBR.hs | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename {Documentation => documentation}/Manual.lyx (100%) rename {Examples => examples}/EchoClient.hs (100%) rename {Examples => examples}/IBR.hs (100%) diff --git a/Documentation/Manual.lyx b/documentation/Manual.lyx similarity index 100% rename from Documentation/Manual.lyx rename to documentation/Manual.lyx diff --git a/Examples/EchoClient.hs b/examples/EchoClient.hs similarity index 100% rename from Examples/EchoClient.hs rename to examples/EchoClient.hs diff --git a/Examples/IBR.hs b/examples/IBR.hs similarity index 100% rename from Examples/IBR.hs rename to examples/IBR.hs From 53a236d479dcd526a29d08b6fe129b2a861c29f3 Mon Sep 17 00:00:00 2001 From: Jon Kristensen Date: Thu, 10 May 2012 18:12:20 +0200 Subject: [PATCH 2/2] removed lyx manual and added manual and tutorial placeholder files --- documentation/Manual.lyx | 593 -------------------------------------- documentation/manual.md | 0 documentation/tutorial.md | 0 3 files changed, 593 deletions(-) delete mode 100644 documentation/Manual.lyx create mode 100644 documentation/manual.md create mode 100644 documentation/tutorial.md diff --git a/documentation/Manual.lyx b/documentation/Manual.lyx deleted file mode 100644 index 92cf935..0000000 --- a/documentation/Manual.lyx +++ /dev/null @@ -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 diff --git a/documentation/manual.md b/documentation/manual.md new file mode 100644 index 0000000..e69de29 diff --git a/documentation/tutorial.md b/documentation/tutorial.md new file mode 100644 index 0000000..e69de29