Documenting t_lookup_cancel() script function.
authorMiklos Tirpak <miklos@iptel.org>
Tue, 20 Jan 2009 12:45:20 +0000 (12:45 +0000)
committerMiklos Tirpak <miklos@iptel.org>
Tue, 20 Jan 2009 12:45:20 +0000 (12:45 +0000)
modules/tm/README
modules/tm/doc/functions.xml

index d095d0b..87579b1 100644 (file)
@@ -76,8 +76,9 @@ Jiri Kuthan
         1.4.25. t_is_canceled() 
         1.4.26. t_is_expired() 
         1.4.27. t_relay_cancel() 
-        1.4.28. t_drop_replies() 
-        1.4.29. t_save_lumps() 
+        1.4.28. t_lookup_cancel(), t_lookup_cancel(1) 
+        1.4.29. t_drop_replies() 
+        1.4.30. t_save_lumps() 
 
    1.5. TM Module API
 
@@ -1194,14 +1195,46 @@ if (method == CANCEL) {
         # do the same as for INVITEs
 }
 
-1.4.28.  t_drop_replies()
+1.4.28.  t_lookup_cancel(), t_lookup_cancel(1)
+
+   Returns true if the corresponding INVITE transaction exists for a
+   CANCEL request. The function can be called at the beginning of the
+   script to check whether or not the CANCEL can be immediately forwarded
+   bypassing the rest of the script. Note however that t_relay_cancel
+   includes t_lookup_cancel as well, therefore it is not needed to
+   explicitly call this function unless something has to be logged for
+   example.
+
+   If the function parameter (optional) is set to 1, the message flags
+   are overwritten with the flags of the INVITE. isflagset() can be used
+   to check the flags of the previously forwarded INVITE in this case.
+
+   Example 52. t_lookup_cancel usage
+if (method == CANCEL) {
+        if (t_lookup_cancel()) {
+                log("INVITE transaction exists");
+                if (!t_relay_cancel()) {  # implicit drop if
+                                          # relaying was successful,
+                                          # nothing to do
+
+                        # corresponding INVITE transaction found
+                        # but error occurred
+                        sl_reply("500", "Internal Server Error");
+                        drop;
+                }
+        }
+        # bad luck, corresponding INVITE transaction is missing,
+        # do the same as for INVITEs
+}
+
+1.4.29.  t_drop_replies()
 
    Drops all the previously received replies in failure_route block to
    make sure that none of them is picked up again. Works only if a new
    branch is added to the transaction, or it is explicitly replied in the
    script!
 
-   Example 52. t_drop_replies() usage
+   Example 53. t_drop_replies() usage
 ...
 failure_route[0]{
         if (t_check_status("5[0-9][0-9]")){
@@ -1217,7 +1250,7 @@ failure_route[0]{
         }
 }
 
-1.4.29.  t_save_lumps()
+1.4.30.  t_save_lumps()
 
    Forces the modifications of the processed SIP message to be saved in
    shared memory before t_relay() is called. The new branches which are
@@ -1232,7 +1265,7 @@ failure_route[0]{
    The transaction must be created by t_newtran() before calling
    t_save_lumps().
 
-   Example 53. t_save_lumps() usage
+   Example 54. t_save_lumps() usage
 route {
         ...
         t_newtran();
index d171048..6571fd3 100644 (file)
@@ -900,6 +900,50 @@ if (method == CANCEL) {
        </example>
     </section>
 
+    <section id="t_lookup_cancel">
+       <title>
+           <function>t_lookup_cancel()</function>,
+           <function>t_lookup_cancel(1)</function>
+       </title>
+       <para>
+               Returns true if the corresponding INVITE transaction exists
+               for a CANCEL request. The function can be called at the beginning
+               of the script to check whether or not the CANCEL can be immediately
+               forwarded bypassing the rest of the script. Note however that
+               <function>t_relay_cancel</function> includes
+               <function>t_lookup_cancel</function> as well, therefore it is not
+               needed to explicitly call this function unless something has to be
+               logged for example.
+       </para>
+       <para>
+               If the function parameter (optional) is set to 1, the message flags
+               are overwritten with the flags of the INVITE. isflagset() can be used
+               to check the flags of the previously forwarded INVITE in this case.
+       </para>
+       <example>
+           <title><function>t_lookup_cancel</function> usage</title>
+           <programlisting>
+
+if (method == CANCEL) {
+       if (t_lookup_cancel()) {
+               log("INVITE transaction exists");
+               if (!t_relay_cancel()) {  # implicit drop if
+                                          # relaying was successful,
+                                          # nothing to do
+
+                       # corresponding INVITE transaction found
+                       # but error occurred
+                       sl_reply("500", "Internal Server Error");
+                       drop;
+               }
+       }
+       # bad luck, corresponding INVITE transaction is missing,
+       # do the same as for INVITEs
+}
+           </programlisting>
+       </example>
+    </section>
+
     <section id="t_drop_replies">
        <title>
            <function>t_drop_replies()</function>