From be1e23defc8c56dc0a1398b009019626f5ea0e0f Mon Sep 17 00:00:00 2001
From: Daniel-Constantin Mierla <miconda@gmail.com>
Date: Wed, 20 May 2020 21:48:29 +0200
Subject: [PATCH] dispatcher: documentation for dispatcher.hash rpc command

---
 .../dispatcher/doc/dispatcher_admin.xml       | 40 +++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/src/modules/dispatcher/doc/dispatcher_admin.xml b/src/modules/dispatcher/doc/dispatcher_admin.xml
index 30cd6a5ec1a..a255b2645d6 100644
--- a/src/modules/dispatcher/doc/dispatcher_admin.xml
+++ b/src/modules/dispatcher/doc/dispatcher_admin.xml
@@ -1960,6 +1960,46 @@ DEST: {
 &sercmd; dispatcher.remove 2 sip:127.0.0.1:5080
 &sercmd; dispatcher.remove 3 sip:127.0.0.1:5075;transport=udp
 ...
+</programlisting>
+    </section>
+		<section id="dispatcher.r.hash">
+		<title>
+		<function moreinfo="none">dispatcher.hash</function>
+		</title>
+		<para>
+		Compute the hash id corresponding to the string parameter values.
+		</para>
+		<para>
+		Return the hash id and the corresponding slot, if 'nslots' parameter
+		is not 0.
+		</para>
+		<para>
+		Name: <emphasis>dispatcher.hash</emphasis>
+		</para>
+		<para>Parameters:</para>
+		<itemizedlist>
+			<listitem><para>_nslots_: number of slots</para></listitem>
+			<listitem><para>_val1_: string value</para></listitem>
+			<listitem><para>_val2_: (optional) string value</para></listitem>
+		</itemizedlist>
+		<para>
+		It can be useful to find what address in a destination group (setid) is
+		going to be used when hashing a value or a URI. For a URI, the
+		corresponding username and domain have to be provided as _val1_ and
+		_val2_. If the URI has a port different than 5060 (or 5061 for TLS),
+		then the _val2_ has to be 'domain:port'. The _nslots_ has to be the
+		number of addresses in the group (setid). The returned 'slot' value
+		represents the index of the address to be used for routing.
+		</para>
+		<para>
+		Example:
+		</para>
+<programlisting  format="linespecific">
+...
+# prototype: &kamctl; rpc dispatcher.hash _nslots_ _val1_ [_val2_]
+&kamctl; rpc dispatcher.hash 0 alice server.com
+&kamctl; rpc dispatcher.hash 4 bob server.com
+...
 </programlisting>
     </section>