git:master: dispatcher(k): documented the RPC commands - sr-dev

18 Apr 2011

Module: sip-router
Branch: master
Commit: 3979c5627b123d64ff95064f826523aba978bd29
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=3979c562...
Author: Daniel-Constantin Mierla miconda@gmail.com
Committer: Daniel-Constantin Mierla miconda@gmail.com
Date:   Mon Apr 18 23:21:49 2011 +0200
dispatcher(k): documented the RPC commands
---
modules_k/dispatcher/README                   |   90 +++++++++++++++++++++----
 modules_k/dispatcher/doc/dispatcher_admin.xml |   81 ++++++++++++++++++++++-
 2 files changed, 157 insertions(+), 14 deletions(-)

diff --git a/modules_k/dispatcher/README b/modules_k/dispatcher/README
index 0261325..249d5bc 100644
--- a/modules_k/dispatcher/README
+++ b/modules_k/dispatcher/README
@@ -14,7 +14,7 @@ Edited by
Carsten Bock
-   BASIS AudioNet GmbH
+   ng-voice.com
Copyright © 2004 FhG FOKUS
@@ -82,10 +82,16 @@ Carsten Bock
               5.2. ds_list
               5.3. ds_reload
-        6. Installation and Running
+        6. Exported RPC Commands
-              6.1. Destination List File
-              6.2. Kamailio config file
+              6.1. dispatcher.set_state
+              6.2. dispatcher.list
+              6.3. dispatcher.reload
+
+        7. Installation and Running
+
+              7.1. Destination List File
+              7.2. Kamailio config file
2. Frequently Asked Questions
@@ -183,10 +189,16 @@ Chapter 1. Admin Guide
         5.2. ds_list
         5.3. ds_reload
-   6. Installation and Running
+   6. Exported RPC Commands
+
+        6.1. dispatcher.set_state
+        6.2. dispatcher.list
+        6.3. dispatcher.reload
-        6.1. Destination List File
-        6.2. Kamailio config file
+   7. Installation and Running
+
+        7.1. Destination List File
+        7.2. Kamailio config file
1. Overview
@@ -751,7 +763,8 @@ ds_select_dst("1", "$var(a)");
    possible parameters:
      * "i", "I" or "0" - the last destination should be set to inactive
        and will be ignored in future requests.
-     * "a", "A" or "1" - the last destination should be set to active.
+     * "a", "A" or "1" - the last destination should be set to active and
+       the error-counter should set to "0".
      * "p", "P" or "2" - the last destination will be set to probing.
        Note: You will need to call this function "threshhold"-times,
        before it will be actually set to probing.
@@ -872,12 +885,63 @@ onreply_route {
    MI DATAGRAM Command Format:
                 ":ds_reload:\n."
-6. Installation and Running
+6. Exported RPC Commands
+
+   6.1. dispatcher.set_state
+   6.2. dispatcher.list
+   6.3. dispatcher.reload
+
+6.1.  dispatcher.set_state
+
+   Sets the state for a destination address (can be use to mark the
+   destination as active or inactive).
+
+   Name: dispatcher.set_state
+
+   Parameters:
+     * _state_ : state of the destination address
+          + “a”: active
+          + “i”: inactive
+          + “d”: disabled
+       The states “a” or “i” can be followed by “p” to set probing mode
+       (e.g. 'ap' or 'ip')
+     * _group_: destination group id
+     * _address_: address of the destination in the _group_
+
+   Example:
+                sercmd dispatcher.set_state _state_ _group_ _address_
+
+6.2.  dispatcher.list
+
+   It lists the groups and included destinations.
+
+   Name: dispatcher.list
+
+   Parameters: none
+
+   Example:
+                sercmd dispatcher.list
+
+6.3.  dispatcher.reload
+
+   It reloads the groups and included destinations. The command is
+   disabled for call load based dispatching (algorithm 10) since removal
+   of destinations may leave the list of active calls with broken
+   references.
+
+   Name: dispatcher.reload
+
+   Parameters: none
+
+   Example
+                sercmd dispatcher.reload
+
+7. Installation and Running
-   6.1. Destination List File
-   6.2. Kamailio config file
+   7.1. Destination List File
+   7.2. Kamailio config file
-6.1. Destination List File
+7.1. Destination List File
Each destination point must be on one line. First token is the set id
    (an integer value), followed by destination address (s string value in
@@ -926,7 +990,7 @@ r,opt)
...
-6.2. Kamailio config file
+7.2. Kamailio config file
Next picture displays a sample usage of dispatcher.
diff --git a/modules_k/dispatcher/doc/dispatcher_admin.xml b/modules_k/dispatcher/doc/dispatcher_admin.xml
index 47cc96c..c851db7 100644
--- a/modules_k/dispatcher/doc/dispatcher_admin.xml
+++ b/modules_k/dispatcher/doc/dispatcher_admin.xml
@@ -1091,7 +1091,86 @@ onreply_route {
     </section>
</section>
-	
+
+	<section>
+	<title>Exported RPC Commands</title>
+	<section>
+		<title>
+		<function moreinfo="none">dispatcher.set_state</function>
+		</title>
+		<para>
+		Sets the state for a destination address (can be use to mark the destination
+		as active or inactive).
+		</para>
+		<para>
+		Name: <emphasis>dispatcher.set_state</emphasis>
+		</para>
+		<para>Parameters:</para>
+		<itemizedlist>
+			<listitem><para>_state_ : state of the destination address</para>
+			      <itemizedlist>
+	                 <listitem><para> <quote>a</quote>: active</para></listitem>
+			         <listitem><para> <quote>i</quote>: inactive</para></listitem>
+			         <listitem><para> <quote>d</quote>: disabled</para></listitem>
+				  </itemizedlist>
+				  <para>The states <quote>a</quote> or <quote>i</quote> can be
+					  followed by <quote>p</quote> to set probing mode (e.g. 'ap'
+					  or 'ip')</para>
+			</listitem>
+
+			<listitem><para>_group_: destination group id</para></listitem>
+
+			<listitem><para>_address_: address of the destination in the _group_</para></listitem>
+		</itemizedlist>
+		<para>
+		Example:
+		</para>
+        <programlisting  format="linespecific">
+		sercmd dispatcher.set_state _state_ _group_ _address_
+		</programlisting>
+    </section>
+	<section>
+		<title>
+		<function moreinfo="none">dispatcher.list</function>
+		</title>
+		<para>
+		It lists the groups and included destinations.
+		</para>
+		<para>
+		Name: <emphasis>dispatcher.list</emphasis>
+		</para>
+		<para>Parameters: <emphasis>none</emphasis></para>
+		<para>
+		Example:
+		</para>
+        <programlisting  format="linespecific">
+		sercmd dispatcher.list
+		</programlisting>
+    </section>
+	<section>
+		<title>
+		<function moreinfo="none">dispatcher.reload</function>
+		</title>
+		<para>
+		It reloads the groups and included destinations. The command is
+		disabled for call load based dispatching (algorithm 10) since
+		removal of destinations may leave the list of active
+		calls with broken references.
+		</para>
+		<para>
+		Name: <emphasis>dispatcher.reload</emphasis>
+		</para>
+		<para>Parameters: <emphasis>none</emphasis></para>
+		<para>
+		Example
+		</para>
+        <programlisting  format="linespecific">
+		sercmd dispatcher.reload
+		</programlisting>
+    </section>
+
+   </section>
+
    <section>
    <title>Installation and Running</title>
    <section>

    