modules/ims_auth: updated documentation

	- updated documentation to use route blocks after async diameter

modules/ims_auth/doc/ims_auth_admin.xml

@@ -274,8 +274,6 @@ modparam("ims_auth", "max_nonce_reuse", 1)
       </example>
     </section>
 
-  </section>
-
     <section>
       <title><varname>add_authinfo_hdr</varname> (integer)</title>
 
@@ -404,8 +402,8 @@ modparam("ims_auth", "av_check_only_impu", 1)
         <programlisting format="linespecific">
 ...
 if (!www_authorize("kamailio.org", "subscriber")) {
-	www_challenge("kamailio.org", "1");
-};
+	www_challenge(""REG_MAR_REPLY"", "kamailio.org", "1");
+};         
 ...
 </programlisting>
       </example>
@@ -421,7 +419,7 @@ if (!www_authorize("kamailio.org", "subscriber")) {
     </section>
 
     <section>
-      <title><function moreinfo="none">ims_www_challenge(realm,
+      <title><function moreinfo="none">ims_www_challenge(route_block, realm,
       table)</function></title>
 
       <para>Name alias: proxy_authorize(realm, table)</para>
@@ -441,6 +439,9 @@ if (!www_authorize("kamailio.org", "subscriber")) {
       <para>Meaning of the parameters is as follows:</para>
 
       <itemizedlist>
+        <listitem>
+          <para>Route block to resume after async MAR Diameter reply.</para>
+        </listitem>
         <listitem>
           <para><emphasis>realm</emphasis> - Realm is a opaque string that the
           user agent should present to the user so he can decide what username
@@ -472,15 +473,39 @@ if (!www_authorize("kamailio.org", "subscriber")) {
         <programlisting format="linespecific">
 ...
 if (!proxy_authorize("$fd", "subscriber)) {
-	proxy_challenge("$fd", "1");  # Realm will be autogenerated
+	proxy_challenge(""REG_MAR_REPLY","$fd");  # Realm will be autogenerated
 };
 ...
+            ...
+route[REG_MAR_REPLY]
+{
+     #this is async so to know status we have to check the reply avp
+     xlog("L_DBG","maa_return code is $avp(s:maa_return_code)\n");   
+
+     switch ($avp(s:maa_return_code)){
+             case 1: #success
+                     xlog("L_DBG", "MAR success - 401/407 response sent from module\n");
+                     break;
+             case -1: #failure
+                     xlog("L_ERR", "MAR failure - error response sent from module\n");
+                     break;
+             case -2: #error
+                     xlog("L_ERR", "MAR error - sending error response now\n");
+                     t_reply("500", "MAR failed");
+                     break;
+             default:
+                     xlog("L_ERR", "Unknown return code from MAR, value is [$avp(s:uaa_return_code)]\n");
+                     t_reply("500", "Unknown response code from MAR");
+                     break;
+     }
+     exit;           
+}               
 </programlisting>
       </example>
     </section>
 
     <section>
-      <title><function moreinfo="none">ims_proxy_challenge(realm,
+      <title><function moreinfo="none">ims_proxy_challenge(route_block, realm,
       table)</function></title>
 
       <para>Name alias: proxy_authorize(realm, table)</para>
@@ -500,6 +525,9 @@ if (!proxy_authorize("$fd", "subscriber)) {
       <para>Meaning of the parameters is as follows:</para>
 
       <itemizedlist>
+        <listitem>
+          <para>Route block to resume after async MAR Diameter reply.</para>
+        </listitem>
         <listitem>
           <para><emphasis>realm</emphasis> - Realm is a opaque string that the
           user agent should present to the user so he can decide what username
@@ -531,9 +559,33 @@ if (!proxy_authorize("$fd", "subscriber)) {
         <programlisting format="linespecific">
 ...
 if (!proxy_authorize("$fd", "subscriber)) {
-	proxy_challenge("$fd", "1");  # Realm will be autogenerated
+	proxy_challenge("REG_MAR_REPLY","$fd", "1");  # Realm will be autogenerated
 };
 ...
+route[REG_MAR_REPLY]
+{
+     #this is async so to know status we have to check the reply avp
+     xlog("L_DBG","maa_return code is $avp(s:maa_return_code)\n");   
+
+     switch ($avp(s:maa_return_code)){
+             case 1: #success
+                     xlog("L_DBG", "MAR success - 401/407 response sent from module\n");
+                     break;
+             case -1: #failure
+                     xlog("L_ERR", "MAR failure - error response sent from module\n");
+                     break;
+             case -2: #error
+                     xlog("L_ERR", "MAR error - sending error response now\n");
+                     t_reply("500", "MAR failed");
+                     break;
+             default:
+                     xlog("L_ERR", "Unknown return code from MAR, value is [$avp(s:uaa_return_code)]\n");
+                     t_reply("500", "Unknown response code from MAR");
+                     break;
+     }
+     exit;           
+}            
+...
 </programlisting>
       </example>
     </section>