[sr-dev] git:master: modules/ims_icscf: updated documentation

[Richard Good]

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

Author: Richard Good <richard.good at smilecoms.com>
Committer: Richard Good <richard.good at smilecoms.com>
Date:   Tue Jun 25 15:42:44 2013 +0200

modules/ims_icscf: updated documentation
 	- updated documentation to use route blocks after async diameter

---

 modules/ims_icscf/doc/ims_icscf_admin.xml |  107 ++++++++++++++++++++---------
 1 files changed, 75 insertions(+), 32 deletions(-)

diff --git a/modules/ims_icscf/doc/ims_icscf_admin.xml b/modules/ims_icscf/doc/ims_icscf_admin.xml
index fdb0b98..aa5573d 100644
--- a/modules/ims_icscf/doc/ims_icscf_admin.xml
+++ b/modules/ims_icscf/doc/ims_icscf_admin.xml
@@ -189,7 +189,7 @@ if (I_scscf_select("0")) {
      t_relay();
 }
 ...
-</programlisting>
+        </programlisting>
       </example>
     </section>
 
@@ -215,7 +215,7 @@ I_scscf_drop();
 
     <section>
       <title><function
-      moreinfo="none">I_perform_user_authorization_request(capabalities)</function></title>
+      moreinfo="none">I_perform_user_authorization_request(route_block, capabalities)</function></title>
 
       <para>Perform a UAR on Diameter CXDX interface. This function will build
       a list of SCSCFs to be used and populate the SCSCF list for the request.
@@ -224,6 +224,9 @@ I_scscf_drop();
 
       <itemizedlist>
         <listitem>
+          <para>Route block to resume after async UAR Diameter reply.</para>
+        </listitem>
+        <listitem>
           <para>capabilities - whether to request capabilities or not "1" -
           with capabilities, "0" - no capabilities.</para>
         </listitem>
@@ -239,58 +242,98 @@ I_scscf_drop();
 
         <programlisting format="linespecific">
 ...
-            I_perform_user_authorization_request("0"); #0=REG/DEREG; 1=REG+Capabilities
-            #this is async so to know status we have to check the reply avp
-            switch ($avp(s:uaa_return_code)){
-                case 1: #success
+I_perform_user_authorization_request("REG_UAR_REPLY","0"); #0=REG/DEREG; 1=REG+Capabilities
+exit;
+...
+route[REG_UAR_REPLY]
+{
+    #this is async so to know status we have to check the reply avp
+    switch ($avp(s:uaa_return_code)){
+            case 1: #success
                     if (I_scscf_select("0")){
-                        t_on_failure("register_failure");
-                        t_on_reply("register_reply");
-                        if (!t_relay()) {
-                            t_reply("500", "Error forwarding to SCSCF");
-                        }
+                            t_on_failure("register_failure");
+                            t_on_reply("register_reply");
+                            #now relay to appropriate SCSCF
+                            if (!t_relay()) {
+                                    t_reply("500", "Error forwarding to SCSCF");
+                            }
                     } else {#select failed
-                        I_scscf_drop();
-                        t_reply("500", "Server error on SCSCF Select (UAR)");
-                    }
+                            I_scscf_drop();
+                            t_reply("500", "Server error on SCSCF Select (UAR)");
+                    }       
+                    break;          
+            case -1: #failure
+                    xlog("L_ERR", "UAR failure - error response sent from module\n");
                     break;
-                case -1: #failure
-                    xlog("L_ERR", "UAR failure - error response sent from module");
-                    break;
-                case -2: #error
-                    xlog("L_ERR", "UAR error - sending error response now");
+            case -2: #error
+                    xlog("L_ERR", "UAR error - sending error response now\n");
                     t_reply("500", "UAR failed");
                     break;
-                default:
-                    xlog("L_ERR", "Unknown return code from UAR, value is [$avp(s:uaa_return_code)]");
-                    t_reply("500", "Unknown response code from UAR"); 
+            default:
+                    xlog("L_ERR", "Unknown return code from UAR, value is [$avp(s:uaa_return_code)]\n");
+                    t_reply("500", "Unknown response code from UAR");
                     break;
-            }
-...
-</programlisting>
+    }
+}
+...          
+        </programlisting>
       </example>
     </section>
 
     <section>
       <title><function
-      moreinfo="none">I_perform_location_information_request()</function></title>
+      moreinfo="none">I_perform_location_information_request(route_block)</function></title>
+
+      <para>Perform a LIR on Diameter CXDX interface.</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>Route block to resume after async LIR Diameter reply.</para>
+        </listitem>
+      </itemizedlist>
 
       <para>This function can be used from REQUEST_ROUTE.</para>
 
+      <para>p.s. this is executed asynchronously. See example on how to
+      retrieve return value</para>
+
       <example>
-        <title>proxy_authorize usage</title>
+        <title>I_perform_location_information_request()</title>
 
         <programlisting format="linespecific">
 ...
-if (!proxy_authorize("$fd", "subscriber)) {
-proxy_challenge("$fd", "1");  # Realm will be autogenerated
-};
+I_perform_location_information_request("SESSION_LIR_REPLY","0");
+exit;
 ...
-</programlisting>
+route[SESSION_LIR_REPLY]
+{
+    if ($avp(lia_return_code) == 1) {
+            if (I_scscf_select("0")) {
+                    append_branch();
+                    t_on_reply("initial_request_reply");
+                    t_on_failure("initial_request_failure");
+                    if (!t_relay()) {
+                            t_reply("500","Error forwarding towards S-CSCF");
+                            break;
+                    }
+                    break;
+            } else {
+                    xlog("L_DBG", "dropping scscf list on initial request\n");
+                    I_scscf_drop();
+                    t_reply("500", "Server error on LIR select S-CSCF");
+                    break;
+            }
+    } else {
+            t_reply("500", "Server error on LIR");
+            break;
+    }
+    break;
+}
+...          
+        </programlisting>
       </example>
     </section>
   </section>
-
   <section>
     <title>Statistics</title>