git:mariusbucur/dmq: Added documentation to the DMQ module - sr-dev

14 Aug 2011

Module: sip-router
Branch: mariusbucur/dmq
Commit: ba56288aad0f8dd50e60c2fb411b305aef198fb4
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=ba56288a...
Author: unknown <mariusb@.(none)>
Committer: unknown <mariusb@.(none)>
Date:   Sat Aug 13 19:02:31 2011 -0700
Added documentation to the DMQ module
---
modules_k/dmq/doc/Makefile      |    4 ++
 modules_k/dmq/doc/dmq.xml       |   44 +++++++++++++++++
 modules_k/dmq/doc/dmq_admin.xml |  103 +++++++++++++++++++++++++++++++++++++++
 modules_k/dmq/doc/dmq_devel.xml |   45 +++++++++++++++++
 4 files changed, 196 insertions(+), 0 deletions(-)

diff --git a/modules_k/dmq/doc/Makefile b/modules_k/dmq/doc/Makefile
new file mode 100644
index 0000000..d50daab
--- /dev/null
+++ b/modules_k/dmq/doc/Makefile
@@ -0,0 +1,4 @@
+docs = dmq.xml
+
+docbook_dir = ../../../docbook
+include $(docbook_dir)/Makefile.module
diff --git a/modules_k/dmq/doc/dmq.xml b/modules_k/dmq/doc/dmq.xml
new file mode 100644
index 0000000..7d9620a
--- /dev/null
+++ b/modules_k/dmq/doc/dmq.xml
@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding='ISO-8859-1'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+
+
+<!-- Include general documentation entities -->
+<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+%docentities;
+
+]>
+
+<book xmlns:xi="http://www.w3.org/2001/XInclude">
+    <bookinfo>
+	<title>Distributed Message Queue Module</title>
+	<productname class="trade">&kamailioname;</productname>
+	<authorgroup>
+	    <author>
+		<firstname>Marius Ovidiu</firstname>
+		<surname>Bucur</surname>
+		<address>
+		<email>bucur_marius_ovidiu@yahoo.com</email>
+		</address>
+	    </author>
+	    <editor>
+		<firstname>Marius Ovidiu</firstname>
+		<surname>Bucur</surname>
+		<address>
+		    <email>bucur_marius_ovidiu@yahoo.com</email>
+		</address>
+	    </editor>
+	</authorgroup>
+	<copyright>
+	    <year>2011</year>
+	    <holder>Marius Bucur</holder>
+	</copyright>
+  </bookinfo>
+    <toc></toc>
+    
+    <xi:include href="dmq_admin.xml"/>
+    <xi:include href="dmq_devel.xml"/>
+    
+</book>
+
+
diff --git a/modules_k/dmq/doc/dmq_admin.xml b/modules_k/dmq/doc/dmq_admin.xml
new file mode 100644
index 0000000..9692d4f
--- /dev/null
+++ b/modules_k/dmq/doc/dmq_admin.xml
@@ -0,0 +1,103 @@
+<?xml version="1.0" encoding='ISO-8859-1'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+
+<!-- Include general documentation entities -->
+<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+%docentities;
+
+]>
+<!-- Module User's Guide -->
+
+<chapter>
+	<title>&adminguide;</title>
+	
+	<section>
+	<title>Overview</title>
+	<para> The DMQ module implements a distributed message passing system on top of Kamailio.
+	The DMQ nodes within the system are grouped in a logical entity called DMQ bus and are able to
+	communicate with each others by sending/receiving messages (either by broadcast or sending a DMQ
+	message to a specific node).
+	The system transparently deals with node discovery, node consistency within the DMQ bus, retransmissions,
+	etc.
+	</para>
+	
+	</section>
+
+	<section>
+	<title>Dependencies</title>
+	<section>
+		<title>&kamailio; Modules</title>
+		<para>
+		The following modules must be loaded before this module:
+			<itemizedlist>
+			<listitem>
+			<para>
+				<emphasis>sl</emphasis>.
+			</para>
+			</listitem>
+			<listitem>
+			<para>
+				<emphasis>tm</emphasis>.
+			</para>
+			</listitem>
+			</itemizedlist>
+		</para>
+	</section>
+
+	<section>
+		<title>External Libraries or Applications</title>
+		<itemizedlist>
+			<listitem>
+			<para>
+				<emphasis>
+				Each peer needs to use its own serialization mechanism.
+				Some examples are libtpl, protobuf.
+				</emphasis>.
+			</para>
+			</listitem>
+		</itemizedlist>
+	</section>
+	
+	<title>Exported Parameters</title>
+	<section>
+		<title><varname>dmq_server_address</varname>(str)</title>
+		<para>
+		The local server address.
+		</para>
+		<para>
+		The modules needs it to know on which interface the DMQ engine should send and receive messages.
+		</para>
+		<para>
+		<emphasis>Default value is <quote>NULL</quote>.	
+		</emphasis>
+		</para>
+		<example>
+		<title>Set <varname>dmq_server_address</varname> parameter</title>
+		<programlisting format="linespecific">
+...
+modparam("dmq", "dmq_server_address", "&defaultdb;")
+...
+</programlisting>
+		</example>
+	</section>
+	<section>
+		<title><varname>dmq_notification_address</varname>(str)</title>
+		<para>
+		The address of the DMQ node from which the local node should retrieve initial information.
+		</para>
+		<para>
+		<emphasis>	Default value is <quote>NULL</quote>.
+		</emphasis>
+		</para>
+		<example>
+		<title>Set <varname>dmq_notification_address</varname> parameter</title>
+		<programlisting format="linespecific">
+...
+modparam("dmq", "dmq_notification_address", "&defaultdb;")
+...
+</programlisting>
+		</example>
+	</section>
+</chapter>
+
diff --git a/modules_k/dmq/doc/dmq_devel.xml b/modules_k/dmq/doc/dmq_devel.xml
new file mode 100644
index 0000000..afa561b
--- /dev/null
+++ b/modules_k/dmq/doc/dmq_devel.xml
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding='ISO-8859-1'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+
+<!-- Include general documentation entities -->
+<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+%docentities;
+
+]>
+<!-- Module Developer's Guide -->
+
+<chapter>
+    <title>&develguide;</title>
+    <para>
+		The module provides the following functions that can be used
+		in other &kamailio; modules.
+   </para>
+ 		<section>
+				<title>
+				<function moreinfo="none">dmq_load_api(dmq_api_t* api)</function>
+				</title>
+			<para>
+				This function binds the dmq modules and fills the structure 
+				with the exported functions
+				-> register_dmq_peer - registers an entity as a DMQ peer which permits receiving/sending
+				messages between nodes which support the same peer,
+				-> bcast_message - broadcast a DMQ message to all peers available in the DMQ bus,
+				-> send_message - sends a DMQ message to a specific peer in the local DMQ bus.
+			</para>
+		<example>
+		<title><function>dmq_api_t</function> structure</title>
+	<programlisting format="linespecific">
+...
+typedef struct dmq_api {
+	register_dmq_peer_t register_dmq_peer;
+	bcast_message_t bcast_message;
+	send_message_t send_message;
+} dmq_api_t;
+...
+</programlisting>
+		</example>
+
+		</section>
+</chapter>
+

    