diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/dev.html | 89 | ||||
| -rw-r--r-- | doc/dev.tex | 68 |
2 files changed, 93 insertions, 64 deletions
diff --git a/doc/dev.html b/doc/dev.html index 48a96e7a7..22ee142bb 100644 --- a/doc/dev.html +++ b/doc/dev.html @@ -4,7 +4,7 @@ <HEAD><TITLE>Ejabberd Developers Guide</TITLE> <META http-equiv="Content-Type" content="text/html; charset=ISO8859-1"> -<META name="GENERATOR" content="hevea 1.06"> +<META name="GENERATOR" content="hevea 1.07"> </HEAD> <BODY > <!--HEVEA command line is: /usr/bin/hevea -charset ISO8859-1 dev.tex --> @@ -21,7 +21,7 @@ <A HREF="mailto:alexey@sevcom.net"><TT>mailto:alexey@sevcom.net</TT></A><BR> <A HREF="xmpp:aleksey@jabber.ru"><TT>xmpp:aleksey@jabber.ru</TT></A></H3> -<H3 ALIGN=center>September 10, 2003</H3><DIV ALIGN=center> +<H3 ALIGN=center>August 21, 2005</H3><DIV ALIGN=center> <IMG SRC="logo.png"> @@ -47,11 +47,12 @@ </UL> <LI><A HREF="#htoc7">2 XML representation</A> <LI><A HREF="#htoc8">3 Module <TT>xml</TT></A> -<LI><A HREF="#htoc9">4 <TT>ejabberd</TT> modules</A> +<LI><A HREF="#htoc9">4 Module <TT>xml_stream</TT></A> +<LI><A HREF="#htoc10">5 <TT>ejabberd</TT> modules</A> <UL><LI> -<A HREF="#htoc10">4.1 <CODE>gen_mod</CODE> behaviour</A> -<LI><A HREF="#htoc11">4.2 Module <CODE>gen_iq_handler</CODE></A> -<LI><A HREF="#htoc12">4.3 Services</A> +<A HREF="#htoc11">5.1 <CODE>gen_mod</CODE> behaviour</A> +<LI><A HREF="#htoc12">5.2 Module <CODE>gen_iq_handler</CODE></A> +<LI><A HREF="#htoc13">5.3 Services</A> </UL> </UL> @@ -90,9 +91,6 @@ Works on most of popular platforms: *nix (tested on Linux, FreeBSD and <LI>Support for <A HREF="http://www.jabber.org/jeps/jep-0039.html">Statistics Gathering</A>. <LI>Support for <TT>xml:lang</TT> </UL> -<TT>ejabberd</TT> is a Free and Open Source fault-tolerant distributed Jabber -server. It is written mostly in Erlang.<BR> -<BR> <!--TOC subsection How it works--> <H3><A NAME="htoc2">1.1</A> How it works</H3><!--SEC END --> @@ -158,7 +156,7 @@ does not exist, then it is opened and registered.<BR> <H2><A NAME="htoc7">2</A> XML representation</H2><!--SEC END --> <A NAME="sec:xmlrepr"></A> -Each XML stanza represented as following tuple: +Each XML stanza is represented as the following tuple: <PRE> XMLElement = {xmlelement, Name, Attrs, [ElementOrCDATA]} Name = string() @@ -173,7 +171,7 @@ XMLElement = {xmlelement, Name, Attrs, [ElementOrCDATA]} <message to='test@conference.example.org' type='groupchat'> <body>test</body> </message> -</PRE>represented as following structure: +</PRE>is represented as the following structure: <PRE> {xmlelement, "message", [{"to", "test@conference.example.org"}, @@ -233,21 +231,34 @@ Res = string() | XMLElement get_tag_attr/2, get_tag_attr_s/2 get_subtag/2 </PRE></DL> +<!--TOC section Module <TT>xml_stream</TT>--> + +<H2><A NAME="htoc9">4</A> Module <TT>xml_stream</TT></H2><!--SEC END --> + +<A NAME="sec:xmlstreammod"></A> +<DL COMPACT=compact><DT> +<CODE><B>parse_element(Str) -> XMLElement | {error, Err}</B></CODE><DD> +<PRE> +Str = string() +Err = term() +</PRE>Parses <TT>Str</TT> using XML parser, returns either parsed element or error + tuple. +</DL> <!--TOC section <TT>ejabberd</TT> modules--> -<H2><A NAME="htoc9">4</A> <TT>ejabberd</TT> modules</H2><!--SEC END --> +<H2><A NAME="htoc10">5</A> <TT>ejabberd</TT> modules</H2><!--SEC END --> <A NAME="sec:emods"></A> <!--TOC subsection <CODE>gen_mod</CODE> behaviour--> -<H3><A NAME="htoc10">4.1</A> <CODE>gen_mod</CODE> behaviour</H3><!--SEC END --> +<H3><A NAME="htoc11">5.1</A> <CODE>gen_mod</CODE> behaviour</H3><!--SEC END --> <A NAME="sec:genmod"></A> TBD<BR> <BR> <!--TOC subsection Module <CODE>gen_iq_handler</CODE>--> -<H3><A NAME="htoc11">4.2</A> Module <CODE>gen_iq_handler</CODE></H3><!--SEC END --> +<H3><A NAME="htoc12">5.2</A> Module <CODE>gen_iq_handler</CODE></H3><!--SEC END --> <A NAME="sec:geniqhandl"></A> The module <CODE>gen_iq_handler</CODE> allows to easily write handlers for IQ packets @@ -255,23 +266,25 @@ of particular XML namespaces that addressed to server or to users bare JIDs.<BR> <BR> In this module the following functions are defined: <DL COMPACT=compact><DT> -<CODE><B>add_iq_handler(Component, NS, Module, Function, Type)</B></CODE><DD> +<CODE><B>add_iq_handler(Component, Host, NS, Module, Function, Type)</B></CODE><DD> <PRE> Component = Module = Function = atom() -NS = string() +Host = NS = string() Type = no_queue | one_queue | parallel -</PRE>Registers function <CODE>Module:Function</CODE> as handler for IQ packets that - contain child of namespace <CODE>NS</CODE> in <CODE>Component</CODE>. Queueing - discipline is <CODE>Type</CODE>. There are at least two components defined: +</PRE>Registers function <CODE>Module:Function</CODE> as handler for IQ packets on + virtual host <CODE>Host</CODE> that contain child of namespace <CODE>NS</CODE> in + <CODE>Component</CODE>. Queueing discipline is <CODE>Type</CODE>. There are at least + two components defined: <DL COMPACT=compact><DT> <CODE><B>ejabberd_local</B></CODE><DD> Handles packets that addressed to server JID; <DT><CODE><B>ejabberd_sm</B></CODE><DD> Handles packets that addressed to users bare JIDs. </DL> -<DT><CODE><B>remove_iq_handler(Component, NS)</B></CODE><DD> +<DT><CODE><B>remove_iq_handler(Component, Host, NS)</B></CODE><DD> <PRE> Component = atom() -NS = string() -</PRE>Removes IQ handler for namespace <CODE>NS</CODE> from <CODE>Component</CODE>. +Host = NS = string() +</PRE>Removes IQ handler on virtual host <CODE>Host</CODE> for namespace <CODE>NS</CODE> from + <CODE>Component</CODE>. </DL> Handler function must have the following type: <DL COMPACT=compact><DT> @@ -284,8 +297,8 @@ From = To = jid() -behaviour(gen_mod). --export([start/1, - stop/0, +-export([start/2, + stop/1, process_local_iq/3]). -include("ejabberd.hrl"). @@ -293,13 +306,13 @@ From = To = jid() -define(NS_CPUTIME, "ejabberd:cputime"). -start(Opts) -> +start(Host, Opts) -> IQDisc = gen_mod:get_opt(iqdisc, Opts, one_queue), - gen_iq_handler:add_iq_handler(ejabberd_local, ?NS_CPUTIME, + gen_iq_handler:add_iq_handler(ejabberd_local, Host, ?NS_CPUTIME, ?MODULE, process_local_iq, IQDisc). -stop() -> - gen_iq_handler:remove_iq_handler(ejabberd_local, ?NS_CPUTIME). +stop(Host) -> + gen_iq_handler:remove_iq_handler(ejabberd_local, Host, ?NS_CPUTIME). process_local_iq(From, To, {iq, ID, Type, XMLNS, SubEl}) -> case Type of @@ -317,7 +330,7 @@ process_local_iq(From, To, {iq, ID, Type, XMLNS, SubEl}) -> </PRE> <!--TOC subsection Services--> -<H3><A NAME="htoc12">4.3</A> Services</H3><!--SEC END --> +<H3><A NAME="htoc13">5.3</A> Services</H3><!--SEC END --> <A NAME="sec:services"></A> TBD<BR> @@ -328,14 +341,15 @@ TODO: use <CODE>proc_lib</CODE> -behaviour(gen_mod). --export([start/1, init/1, stop/0]). +-export([start/2, init/1, stop/1]). -include("ejabberd.hrl"). -include("jlib.hrl"). -start(Opts) -> - Host = gen_mod:get_opt(host, Opts, "echo." ++ ?MYNAME), - register(ejabberd_mod_echo, spawn(?MODULE, init, [Host])). +start(Host, Opts) -> + MyHost = gen_mod:get_opt(host, Opts, "echo." ++ Host), + register(gen_mod:get_module_proc(Host, ?PROCNAME), + spawn(?MODULE, init, [MyHost])). init(Host) -> ejabberd_router:register_local_route(Host), @@ -347,15 +361,16 @@ loop(Host) -> ejabberd_router:route(To, From, Packet), loop(Host); stop -> - ejabberd_router:unregister_local_route(Host), + ejabberd_router:unregister_route(Host), ok; _ -> loop(Host) end. -stop() -> - ejabberd_mod_echo ! stop, - ok. +stop(Host) -> + Proc = gen_mod:get_module_proc(Host, ?PROCNAME), + Proc ! stop, + {wait, Proc}. </PRE> <!--HTMLFOOT--> <!--ENDHTML--> diff --git a/doc/dev.tex b/doc/dev.tex index fcfc1ee73..26497a191 100644 --- a/doc/dev.tex +++ b/doc/dev.tex @@ -41,7 +41,7 @@ \author{Alexey Shchepin \\ \ahrefurl{mailto:alexey@sevcom.net} \\ \ahrefurl{xmpp:aleksey@jabber.ru}} -\date{September 10, 2003} +\date{August 21, 2005} \begin{document} \begin{titlepage} @@ -89,8 +89,6 @@ The main features of \ejabberd{} are: \item Support for \tjepref{0039}{Statistics Gathering}. \item Support for \ns{xml:lang} \end{itemize} -\ejabberd{} is a Free and Open Source fault-tolerant distributed \Jabber{} -server. It is written mostly in Erlang. @@ -158,7 +156,7 @@ does not exist, then it is opened and registered. \section{XML representation} \label{sec:xmlrepr} -Each XML stanza represented as following tuple: +Each XML stanza is represented as the following tuple: \begin{verbatim} XMLElement = {xmlelement, Name, Attrs, [ElementOrCDATA]} Name = string() @@ -175,7 +173,7 @@ E.\,g. this stanza: <body>test</body> </message> \end{verbatim} -represented as following structure: +is represented as the following structure: \begin{verbatim} {xmlelement, "message", [{"to", "test@conference.example.org"}, @@ -245,6 +243,18 @@ Res = string() | XMLElement \end{description} +\section{Module \texttt{xml\_stream}} +\label{sec:xmlstreammod} + +\begin{description} +\item[\verb!parse_element(Str) -> XMLElement | {error, Err}!] +\begin{verbatim} +Str = string() +Err = term() +\end{verbatim} + Parses \texttt{Str} using XML parser, returns either parsed element or error + tuple. +\end{description} \section{\ejabberd{} modules} @@ -264,25 +274,27 @@ of particular XML namespaces that addressed to server or to users bare JIDs. In this module the following functions are defined: \begin{description} -\item[\verb|add_iq_handler(Component, NS, Module, Function, Type)|] +\item[\verb|add_iq_handler(Component, Host, NS, Module, Function, Type)|] \begin{verbatim} Component = Module = Function = atom() -NS = string() +Host = NS = string() Type = no_queue | one_queue | parallel \end{verbatim} - Registers function \verb|Module:Function| as handler for IQ packets that - contain child of namespace \verb|NS| in \verb|Component|. Queueing - discipline is \verb|Type|. There are at least two components defined: + Registers function \verb|Module:Function| as handler for IQ packets on + virtual host \verb|Host| that contain child of namespace \verb|NS| in + \verb|Component|. Queueing discipline is \verb|Type|. There are at least + two components defined: \begin{description} \item[\verb|ejabberd_local|] Handles packets that addressed to server JID; \item[\verb|ejabberd_sm|] Handles packets that addressed to users bare JIDs. \end{description} -\item[\verb|remove_iq_handler(Component, NS)|] +\item[\verb|remove_iq_handler(Component, Host, NS)|] \begin{verbatim} Component = atom() -NS = string() +Host = NS = string() \end{verbatim} - Removes IQ handler for namespace \verb|NS| from \verb|Component|. + Removes IQ handler on virtual host \verb|Host| for namespace \verb|NS| from + \verb|Component|. \end{description} Handler function must have the following type: @@ -300,8 +312,8 @@ From = To = jid() -behaviour(gen_mod). --export([start/1, - stop/0, +-export([start/2, + stop/1, process_local_iq/3]). -include("ejabberd.hrl"). @@ -309,13 +321,13 @@ From = To = jid() -define(NS_CPUTIME, "ejabberd:cputime"). -start(Opts) -> +start(Host, Opts) -> IQDisc = gen_mod:get_opt(iqdisc, Opts, one_queue), - gen_iq_handler:add_iq_handler(ejabberd_local, ?NS_CPUTIME, + gen_iq_handler:add_iq_handler(ejabberd_local, Host, ?NS_CPUTIME, ?MODULE, process_local_iq, IQDisc). -stop() -> - gen_iq_handler:remove_iq_handler(ejabberd_local, ?NS_CPUTIME). +stop(Host) -> + gen_iq_handler:remove_iq_handler(ejabberd_local, Host, ?NS_CPUTIME). process_local_iq(From, To, {iq, ID, Type, XMLNS, SubEl}) -> case Type of @@ -345,14 +357,15 @@ TODO: use \verb|proc_lib| -behaviour(gen_mod). --export([start/1, init/1, stop/0]). +-export([start/2, init/1, stop/1]). -include("ejabberd.hrl"). -include("jlib.hrl"). -start(Opts) -> - Host = gen_mod:get_opt(host, Opts, "echo." ++ ?MYNAME), - register(ejabberd_mod_echo, spawn(?MODULE, init, [Host])). +start(Host, Opts) -> + MyHost = gen_mod:get_opt(host, Opts, "echo." ++ Host), + register(gen_mod:get_module_proc(Host, ?PROCNAME), + spawn(?MODULE, init, [MyHost])). init(Host) -> ejabberd_router:register_local_route(Host), @@ -364,15 +377,16 @@ loop(Host) -> ejabberd_router:route(To, From, Packet), loop(Host); stop -> - ejabberd_router:unregister_local_route(Host), + ejabberd_router:unregister_route(Host), ok; _ -> loop(Host) end. -stop() -> - ejabberd_mod_echo ! stop, - ok. +stop(Host) -> + Proc = gen_mod:get_module_proc(Host, ?PROCNAME), + Proc ! stop, + {wait, Proc}. \end{verbatim} |