[sr-dev] git:master: pdt(k): updates to documentation

[Elena-Ramona Modroiu]

Module: sip-router
Branch: master
Commit: fd494bceb1e60e6bb15b5da6820cca4fcd030222
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=fd494bceb1e60e6bb15b5da6820cca4fcd030222

Author: Elena-Ramona Modroiu <ramona at asipto.com>
Committer: Elena-Ramona Modroiu <ramona at asipto.com>
Date:   Tue Dec 20 18:09:49 2011 +0100

pdt(k): updates to documentation

- new function pd_translate(dsomain, rmode)

---

 modules_k/pdt/README            |   34 ++++++++++++++++++++++++
 modules_k/pdt/doc/pdt_admin.xml |   54 ++++++++++++++++++++++++++++++++++++++-
 2 files changed, 87 insertions(+), 1 deletions(-)

diff --git a/modules_k/pdt/README b/modules_k/pdt/README
index cc2768f..d884b6c 100644
--- a/modules_k/pdt/README
+++ b/modules_k/pdt/README
@@ -45,6 +45,7 @@ Elena-Ramona Modroiu
               4.1. prefix2domain(rewrite_mode, multidomain_mode)
               4.2. prefix2domain(rewrite_mode)
               4.3. prefix2domain()
+              4.4. pd_translate(sdomain, rewrite_mode)
 
         5. MI Commands
 
@@ -66,6 +67,7 @@ Elena-Ramona Modroiu
    1.9. Set char_list parameter
    1.10. Set check_domain parameter
    1.11. prefix2domain usage
+   1.12. pd_translate usage
 
 Chapter 1. Admin Guide
 
@@ -94,6 +96,7 @@ Chapter 1. Admin Guide
         4.1. prefix2domain(rewrite_mode, multidomain_mode)
         4.2. prefix2domain(rewrite_mode)
         4.3. prefix2domain()
+        4.4. pd_translate(sdomain, rewrite_mode)
 
    5. MI Commands
 
@@ -283,6 +286,7 @@ modparam("pdt", "check_domain", 0)
    4.1. prefix2domain(rewrite_mode, multidomain_mode)
    4.2. prefix2domain(rewrite_mode)
    4.3. prefix2domain()
+   4.4. pd_translate(sdomain, rewrite_mode)
 
 4.1.  prefix2domain(rewrite_mode, multidomain_mode)
 
@@ -344,6 +348,36 @@ prefix2domain("2");
 prefix2domain();
 ...
 
+4.4.  pd_translate(sdomain, rewrite_mode)
+
+   Translate R-URI based on source domain and longest prefix matching.
+   Returns 1 when the translation was made or there was nothing to
+   translate. Returns -1 in error cases.
+
+   The translation is done based on lookup up for an entry in the database
+   where the sdomain parameter equals the sdomain in database table.
+
+   The “sdomain” parameter specifies the source domain to be used to match
+   the longest prefix. Can be a static string or dynamic parameter with
+   variables inside.
+
+   The “rewrite_mode” parameter specifies whether to strip or not the
+   prefix from user part. The possible values are:
+     * 0: the prefix is removed along with the leading prefix.
+     * 1: only the leading prefix is removed.
+     * 2: the user part of the URI is not changed.
+     * $PV : any PV holding one of the above values.
+
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE or
+   BRANCH_ROUTE.
+
+   Example 1.12. pd_translate usage
+...
+pd_translate("$fd", "2");
+...
+pd_translate("*", "$var(a)");
+...
+
 5. MI Commands
 
    5.1. pdt_list
diff --git a/modules_k/pdt/doc/pdt_admin.xml b/modules_k/pdt/doc/pdt_admin.xml
index 8183887..a43e934 100644
--- a/modules_k/pdt/doc/pdt_admin.xml
+++ b/modules_k/pdt/doc/pdt_admin.xml
@@ -411,9 +411,61 @@ prefix2domain();
 </programlisting>
     </section>
 	
+	<section>
+	    <title>
+		<function moreinfo="none">pd_translate(sdomain, rewrite_mode)</function>
+	    </title>
+	    <para>
+		Translate R-URI based on source domain and longest prefix matching.
+		Returns 1 when the translation was made or there was nothing to translate.
+		Returns -1 in error cases.
+	    </para>
+		<para>
+		The translation is done based on lookup up for an entry in the database
+		where the sdomain parameter equals the sdomain in database table.
+		</para>
+		<para>
+		The <quote>sdomain</quote> parameter specifies the source domain to be
+		used to match the longest prefix. Can be a static string or dynamic parameter
+		with variables inside.
+		</para>
+		<para>
+		The <quote>rewrite_mode</quote> parameter specifies whether to strip or not
+		the prefix from user part. The possible values are:
+		</para>
+		<itemizedlist>
+			<listitem>
+				<para>0: the prefix is removed along with the leading prefix.</para>
+			</listitem>
+			<listitem>
+				<para>1: only the leading prefix is removed.</para> 
+			</listitem>
+			<listitem>
+				<para>2: the user part of the URI is not changed.</para>
+			</listitem>
+			<listitem>
+				<para>$PV : any PV holding one of the above values.</para>
+			</listitem>
+		</itemizedlist>
+	    <para>
+		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE or
+		BRANCH_ROUTE.
+		</para>
+		<example>
+		<title><function>pd_translate</function> usage</title>
+		<programlisting format="linespecific">
+...
+pd_translate("$fd", "2");
+...
+pd_translate("*", "$var(a)");
+...
+</programlisting>
+	    </example>
+	</section>
+
     </section>
 	
-		<section>
+	<section>
 		<title>MI Commands</title>
 		<para>
 		The database is loaded by &kamailio; at start up time.