ipops: added documentation for new function and pv

kamailio · Apr 3, 2015 · 9ac723b · 9ac723b
1 parent 7e89554
commit 9ac723b
Show file tree

Hide file tree

Showing 2 changed files with 130 additions and 0 deletions.
diff --git a/modules/ipops/README b/modules/ipops/README
@@ -39,6 +39,7 @@ I
               4.11. dns_sys_match_ip(hostname, ipaddr)
               4.12. dns_int_match_ip(hostname, ipaddr)
               4.13. dns_query(hostname, pvid)
+              4.14. srv_query(srvcname, pvid)
 
    List of Examples
 
@@ -55,6 +56,7 @@ I
    1.11. dns_sys_match_ip usage
    1.12. dns_int_match_ip usage
    1.13. dns_query usage
+   1.14. srv_query usage
 
 Chapter 1. Admin Guide
 
@@ -82,6 +84,7 @@ Chapter 1. Admin Guide
         4.11. dns_sys_match_ip(hostname, ipaddr)
         4.12. dns_int_match_ip(hostname, ipaddr)
         4.13. dns_query(hostname, pvid)
+        4.14. srv_query(srvcname, pvid)
 
 1. Overview
 
@@ -136,6 +139,7 @@ Chapter 1. Admin Guide
    4.11. dns_sys_match_ip(hostname, ipaddr)
    4.12. dns_int_match_ip(hostname, ipaddr)
    4.13. dns_query(hostname, pvid)
+   4.14. srv_query(srvcname, pvid)
 
 4.1. is_ip (ip)
 
@@ -416,3 +420,44 @@ if(dns_query("test.com", "xyz"))
     }
 }
 ...
+
+4.14. srv_query(srvcname, pvid)
+
+   Queries DNS SRV records to resolve a service/protocol name into a list
+   of priorities, weights, ports, and targets sorted by priority and
+   weight as outlined in RFC 2782.
+
+   Parameters:
+     * srvcname - string or pseudo-variable containing the
+       service/protocol. For example, "_sip._tcp.example.com".
+     * pvid - container id for script variable.
+
+   Output:
+
+   Returns a positive number indicating success or a negative number when
+   an error is encountered. It can be used from ANY_ROUTE.
+
+   The $srvquery pseudo-variable (PV) is loaded with the results of the
+   query. Multiple queries can be stored in the PV using the pvid key.
+   Each query contains zero-indexed arrays sorted by priority and weight
+   that contain:
+     * count - number of records found
+     * port [index] - port number
+     * priority [index] - priority number as defined by RFC 2782
+     * target [index] - target host name
+     * weight [index] - weight number as defined by RFC 2782
+
+   Example 1.14. srv_query usage
+...
+if (srv_query ("_sip._udp.example.com", "udp") > 0) {
+  $var(cnt) = $srvquery(udp=>count);
+  $var(i) = 0;
+  while ($var(i) < $var(cnt)) {
+    xlog ("port[$var(i)] $srvquery(udp=>port[$var(i)])\n)";
+    xlog ("priority[$var(i)] $srvquery(udp=>priority[$var(i)])\n)";
+    xlog ("target[$var(i)] $srvquery(udp=>target[$var(i)])\n)";
+    xlog ("weight[$var(i)] $srvquery(udp=>weight[$var(i)])\n)";
+    $var(i) = $var(i) + 1;
+  }
+}
+...
diff --git a/modules/ipops/doc/ipops_admin.xml b/modules/ipops/doc/ipops_admin.xml
@@ -674,6 +674,91 @@ if(dns_query("test.com", "xyz"))
         $var(i) = $var(i) + 1;
     }
 }
+...
+        </programlisting>
+      </example>
+
+    </section>
+
+    <section id="ipops.f.srv_query">
+      <title>
+        <function moreinfo="none">srv_query(srvcname, pvid)</function>
+      </title>
+
+      <para>
+Queries DNS SRV records to resolve a service/protocol name into a list of priorities, weights, ports, and targets sorted by priority and weight as outlined in <ulink url="http://tools.ietf.org/html/rfc2782">RFC 2782</ulink>.
+      </para>
+
+      <para>Parameters:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>
+			  <emphasis>srvcname</emphasis> - string or pseudo-variable containing the service/protocol. For example, "_sip._tcp.example.com".
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <emphasis>pvid</emphasis> - container id for script variable.
+          </para>
+        </listitem>
+      </itemizedlist>
+
+      <para>Output:</para>
+
+      <para>
+        Returns a positive number indicating success or a negative number when an error is encountered. It can be used from ANY_ROUTE.
+      </para>
+
+      <para>
+        The $srvquery pseudo-variable (PV) is loaded with the results of the query. Multiple queries can be stored in the PV using the pvid key. Each query contains zero-indexed arrays sorted by priority and weight that contain:
+      </para>
+
+      <itemizedlist>
+        <listitem>
+          <para>
+            <emphasis>count</emphasis> - number of records found
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <emphasis>port [index]</emphasis> - port number
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <emphasis>priority [index]</emphasis> - priority number as defined by <ulink url="http://tools.ietf.org/html/rfc2782">RFC 2782</ulink>
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <emphasis>target [index]</emphasis> - target host name
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <emphasis>weight [index]</emphasis> - weight number as defined by <ulink url="http://tools.ietf.org/html/rfc2782">RFC 2782</ulink>
+          </para>
+        </listitem>
+      </itemizedlist>
+
+      <example>
+        <title>
+          <function>srv_query</function> usage
+        </title>
+        <programlisting format="linespecific">
+...
+if (srv_query ("_sip._udp.example.com", "udp") > 0) {
+  $var(cnt) = $srvquery(udp=>count);
+  $var(i) = 0;
+  while ($var(i) &lt; $var(cnt)) {
+    xlog ("port[$var(i)] $srvquery(udp=>port[$var(i)])\n)";
+    xlog ("priority[$var(i)] $srvquery(udp=>priority[$var(i)])\n)";
+    xlog ("target[$var(i)] $srvquery(udp=>target[$var(i)])\n)";
+    xlog ("weight[$var(i)] $srvquery(udp=>weight[$var(i)])\n)";
+    $var(i) = $var(i) + 1;
+  }
+}
 ...
         </programlisting>
       </example>