ipops: added dsn_int_match_ip(hostname, ipaddr)
[sip-router] / modules / ipops / doc / ipops_admin.xml
index afb03d8..9f3528d 100644 (file)
@@ -529,14 +529,17 @@ if (is_in_subnet("10.0.123.123", "10.0.123.1/24")) {
 
     </section>
 
-    <section id="ipops.f.dns_nc_match_ip">
+    <section id="ipops.f.dns_sys_match_ip">
       <title>
-        <function moreinfo="none">dns_nc_match_ip(hostname, ipaddr)</function>
+        <function moreinfo="none">dns_sys_match_ip(hostname, ipaddr)</function>
       </title>
 
       <para>
                  Returns TRUE if ipaddr is associated by DNS to hostname. FALSE otherwise. It
-                 does not use the internal DNS cache, but directly getaddrinfo(...).
+                 does not use the internal DNS resolver, but directly getaddrinfo(...). All
+                 addresses returned for the hostname are checked. Note that some hosts may
+                 return different lists of IP addresses for each query, if the DNS server
+                 is configured in that way (e.g., for providing load balancing through DNS).
       </para>
 
       <para>Parameters:</para>
@@ -550,7 +553,7 @@ if (is_in_subnet("10.0.123.123", "10.0.123.1/24")) {
         <listitem>
           <para>
                          <emphasis>hostname</emphasis> - string or pseudo-variable containing the hostname.
-                         The resulting IP addresses from DNS query are compared with ipaddress.
+                         The resulting IP addresses from DNS query are compared with ipaddr.
           </para>
         </listitem>
       </itemizedlist>
@@ -561,11 +564,60 @@ if (is_in_subnet("10.0.123.123", "10.0.123.1/24")) {
 
       <example>
         <title>
-          <function>dns_nc_match_ip</function> usage
+          <function>dns_sys_match_ip</function> usage
         </title>
         <programlisting format="linespecific">
 ...
-if (!dns_nc_match_ip("myhost.com", "1.2.3.4")) {
+if (!dns_sys_match_ip("myhost.com", "1.2.3.4")) {
+    xdbg("ip address not associated with hostname\n");
+}
+...
+        </programlisting>
+      </example>
+
+    </section>
+
+    <section id="ipops.f.dns_int_match_ip">
+      <title>
+        <function moreinfo="none">dns_int_match_ip(hostname, ipaddr)</function>
+      </title>
+
+      <para>
+                 Returns TRUE if ipaddr is associated by DNS to hostname. FALSE otherwise. It
+                 uses internal DNS resolver. At this moment, the function might not check all
+                 the IP addresses as returned by dns_sys_match_ip(), because the internal
+                 resolver targets to discover the first address to be used for relaying
+                 SIP traffic. Thus is better to use dns_sys_match_ip() if the host you want
+                 to check has many IP addresses, in different address famililies (IPv4/6).
+      </para>
+
+      <para>Parameters:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>
+            <emphasis>ipaddr</emphasis> - string or pseudo-variable containing the ip address.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+                         <emphasis>hostname</emphasis> - string or pseudo-variable containing the hostname.
+                         The resulting IP addresses from DNS query are compared with ipaddr.
+          </para>
+        </listitem>
+      </itemizedlist>
+
+      <para>
+        This function can be used from ANY_ROUTE.
+      </para>
+
+      <example>
+        <title>
+          <function>dns_int_match_ip</function> usage
+        </title>
+        <programlisting format="linespecific">
+...
+if (!dns_int_match_ip("myhost.com", "1.2.3.4")) {
     xdbg("ip address not associated with hostname\n");
 }
 ...