Documenting t_lookup_cancel() script function.

modules/tm/README

@@ -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();

modules/tm/doc/functions.xml

@@ -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>