keepalive: improve documentation 1196/head
authorGuillaume Bour <guillaume@bour.cc>
Mon, 31 Jul 2017 19:59:50 +0000 (21:59 +0200)
committerGuillaume Bour <guillaume@bour.cc>
Mon, 31 Jul 2017 19:59:50 +0000 (21:59 +0200)
- documents internal API
- GH #1082

src/modules/keepalive/doc/keepalive.xml
src/modules/keepalive/doc/keepalive_admin.xml
src/modules/keepalive/doc/keepalive_devel.xml [new file with mode: 0644]

index d7c4cff..ae4d93c 100644 (file)
@@ -33,6 +33,7 @@
     <toc></toc>
     
     <xi:include href="keepalive_admin.xml"/>
+    <xi:include href="keepalive_devel.xml"/>
     
     
 </book>
index d65d4f6..a369445 100644 (file)
@@ -24,7 +24,7 @@
                <para>
                        As an example of usage by other modules, see
                        <emphasis>drouting</emphasis>, which was
-                       enahnced to use this module to monitor its gateways.
+                       enhanced to use this module to monitor its gateways.
                </para>
        </section>
 
@@ -62,7 +62,7 @@
                        <section>
                                <title><varname>ping_interval</varname> (integer)</title>
                                <para>
-                                       Interval requests are sent to destinations (in seconds)
+                                       Define the interval (in seconds) ping requests are sent to destinations
                                </para>
                                <para>
                                <emphasis>
@@ -81,7 +81,7 @@ modparam("keepalive", "ping_interval", 10)
                        <section>
                                <title><varname>destination</varname> (string)</title>
                                <para>
-                                       Allows to specify statically destinations you want to monitor
+                                       Allows to statically define destinations you want to monitor
                                </para>
                                <example>
                                        <title>Set <varname>destination</varname> parameter</title>
@@ -102,13 +102,18 @@ modparam("keepalive", "destination", "sip.provider.com")
                                        <function moreinfo="none">is_alive(destination)</function>
                            </title>
                                <para>
-                                       Get destination status
+                                       Get destination status.
                                </para>
                        <para>
-                                       Parameter <quote>destination</quote> is destination you want to check status
+                                       The Parameter <emphasis>destination</emphasis> is destination you want to check status
                        </para>
                        <para>
-                           Return value: 1 if destination is up, 2 if destination is down, -1 on error.
+                                       Returned value:
+                                       <itemizedlist>
+                                               <listitem>1 if destination is up</listitem>
+                                               <listitem>2 if destination is down</listitem>
+                                           <listitem>-1 on error</listitem>
+                                       </itemizedlist>
                        </para>
                        <para>
                                    This function can be used from ANY_ROUTE.
@@ -117,7 +122,9 @@ modparam("keepalive", "destination", "sip.provider.com")
                                        <title><function>is_alive()</function> usage</title>
                                        <programlisting format="linespecific">
 ...
-is_alive("192.168.10.20");
+if(is_alive("192.168.10.20") == 1) {
+  // do stuff
+};
 ...
                                </programlisting>
                            </example>
diff --git a/src/modules/keepalive/doc/keepalive_devel.xml b/src/modules/keepalive/doc/keepalive_devel.xml
new file mode 100644 (file)
index 0000000..ff042bb
--- /dev/null
@@ -0,0 +1,146 @@
+<?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 "../../../../doc/docbook/entities.xml">
+%docentities;
+
+]>
+<!-- Module Developer's Guide -->
+
+<chapter>
+       
+       <title>&develguide;</title>
+
+       <para>
+       The KeepAlive module provides an internal <acronym>API</acronym> to be used by 
+       other &kamailio; modules. This <acronym>API</acronym> offers support for destinations 
+       monitoring.
+       </para>
+       <para>
+       For internal (non-script) usage, the KeepAlive module offers to other module the
+       possibility to register callback functions to be executed for each destination's
+       status change.
+       </para>
+
+
+       <section>
+       <title>Available Functions</title>
+
+       <section id="dev-add_destination">
+               <title>
+               <function moreinfo="none">add_destination(uri, owner, flags, [callback, [user_attr]])</function>
+               </title>
+               <para>
+                       This function registers a new destination to monitor. 
+                       Monitoring of the destination starts as soon as it returns with success (0 value).
+               </para>
+               <para>Meaning of the parameters is as follows:</para>
+               <itemizedlist>
+               <listitem>
+                       <para>
+                               <emphasis>uri (string)</emphasis> - address of destination to monitor. Valid format is [proto:]ip[:port], with:
+                       </para>
+                       <itemizedlist>
+                               <listitem>
+                                       <emphasis>proto</emphasis> being one of <emphasis>sip</emphasis> or <emphasis>sips</emphasis> (SIP over TLS). 
+                                       If omitted, <emphasis>sip</emphasis> is used by default
+                               </listitem>
+                               <listitem>
+                                       <emphasis>port</emphasis> being optional (using default standard port, 5060 for sip and 5061 for sips)
+                               </listitem>
+                       </itemizedlist>
+               </listitem>
+               <listitem>
+                       <para>
+                               <emphasis>owner (string)</emphasis> - module name <quote>owning</quote> the destination
+                               (for information purpose)
+                       </para>
+               </listitem>
+               <listitem>
+                       <para>
+                               <emphasis>flags (integer)</emphasis> - destination flags (<emphasis>unused for now, use 0 value</emphasis>)
+                       </para>
+               </listitem>
+               <listitem>
+                       <para>
+                               <emphasis>callback (ka_statechanged_f, optional)</emphasis> - callback function, executed on destination's state change.
+                       </para>
+                       <para>
+                               The callback function is of type <code>void (*ka_statechanged_f)(str *uri, int state, void *user_attr);</code>. Use <emphasis>NULL</emphasis> to set no callback.
+                       </para>
+                       <para>
+                               destination's state value is one of:
+                       </para>
+                       <itemizedlist>
+                               <listitem>
+                                       <emphasis>0</emphasis> - unknown state (this is the destination state at first, waiting first ping replies or timeout)
+                               </listitem>
+                               <listitem>
+                                       <emphasis>1</emphasis> - destination is UP
+                               </listitem>
+                               <listitem>
+                                       <emphasis>2</emphasis> - destination is DOWN
+                               </listitem>
+                       </itemizedlist>
+               </listitem>
+               <listitem>
+                       <para>
+                               <emphasis>user_attr (void * pointer, optional)</emphasis> - If callback function is setup, this parameter will be forwarded to it, as last parameter. Use <emphasis>NULL</emphasis> to set no user_attr parameter.
+                       </para>
+               </listitem>
+               </itemizedlist>
+
+               <para>
+                       Returned values:
+               </para>
+               <itemizedlist>
+                       <listitem><emphasis>0</emphasis> if ok
+                       </listitem>
+                       <listitem><emphasis>-1</emphasis> if an error occured
+                       </listitem>
+               </itemizedlist>
+               
+       </section>
+
+
+       <section>
+               <title>Examples</title>
+               <example>
+                       <title>Loading KeepAlive module's API from another module, adding a destination to monitor &amp; registering a callback</title>
+                       <programlisting format="linespecific">
+...
+#include "../keepalive/api.h"
+...
+keepalive_api_t ka_api;
+...
+...
+/* loading keepalive API */
+if (bind_keepalive( &amp;ka_api ) != 0) {
+    LM_ERR("can't load KeepAlive API\n");
+    goto error;
+}
+...
+...
+/* callback function */
+void my_callback(str uri, int state, void *user_attr) {
+
+       printf("%.*s new state is: %d\n", uri.len, uri.str, state)
+}
+
+/* register a new destination */
+str dest  = str_init("sip:192.168.10.21:5060");
+str owner = str_init("mymodule");
+
+if (ka_api.add_destination(dest, owner, 0, my_callback, NULL) != 0) {
+    LM_ERR("can't add destination\n");
+    goto error;
+}
+...
+                       </programlisting>
+               </example>
+       </section>
+</section>
+</chapter>
+