Browse code

Documenting t_lookup_cancel() script function.

Miklos Tirpak authored on 20/01/2009 12:45:20
Showing 2 changed files
... ...
@@ -76,8 +76,9 @@ Jiri Kuthan
76 76
         1.4.25. t_is_canceled() 
77 77
         1.4.26. t_is_expired() 
78 78
         1.4.27. t_relay_cancel() 
79
-        1.4.28. t_drop_replies() 
80
-        1.4.29. t_save_lumps() 
79
+        1.4.28. t_lookup_cancel(), t_lookup_cancel(1) 
80
+        1.4.29. t_drop_replies() 
81
+        1.4.30. t_save_lumps() 
81 82
 
82 83
    1.5. TM Module API
83 84
 
... ...
@@ -1194,14 +1195,46 @@ if (method == CANCEL) {
1194 1194
         # do the same as for INVITEs
1195 1195
 }
1196 1196
 
1197
-1.4.28.  t_drop_replies()
1197
+1.4.28.  t_lookup_cancel(), t_lookup_cancel(1)
1198
+
1199
+   Returns true if the corresponding INVITE transaction exists for a
1200
+   CANCEL request. The function can be called at the beginning of the
1201
+   script to check whether or not the CANCEL can be immediately forwarded
1202
+   bypassing the rest of the script. Note however that t_relay_cancel
1203
+   includes t_lookup_cancel as well, therefore it is not needed to
1204
+   explicitly call this function unless something has to be logged for
1205
+   example.
1206
+
1207
+   If the function parameter (optional) is set to 1, the message flags
1208
+   are overwritten with the flags of the INVITE. isflagset() can be used
1209
+   to check the flags of the previously forwarded INVITE in this case.
1210
+
1211
+   Example 52. t_lookup_cancel usage
1212
+if (method == CANCEL) {
1213
+        if (t_lookup_cancel()) {
1214
+                log("INVITE transaction exists");
1215
+                if (!t_relay_cancel()) {  # implicit drop if
1216
+                                          # relaying was successful,
1217
+                                          # nothing to do
1218
+
1219
+                        # corresponding INVITE transaction found
1220
+                        # but error occurred
1221
+                        sl_reply("500", "Internal Server Error");
1222
+                        drop;
1223
+                }
1224
+        }
1225
+        # bad luck, corresponding INVITE transaction is missing,
1226
+        # do the same as for INVITEs
1227
+}
1228
+
1229
+1.4.29.  t_drop_replies()
1198 1230
 
1199 1231
    Drops all the previously received replies in failure_route block to
1200 1232
    make sure that none of them is picked up again. Works only if a new
1201 1233
    branch is added to the transaction, or it is explicitly replied in the
1202 1234
    script!
1203 1235
 
1204
-   Example 52. t_drop_replies() usage
1236
+   Example 53. t_drop_replies() usage
1205 1237
 ...
1206 1238
 failure_route[0]{
1207 1239
         if (t_check_status("5[0-9][0-9]")){
... ...
@@ -1217,7 +1250,7 @@ failure_route[0]{
1217 1217
         }
1218 1218
 }
1219 1219
 
1220
-1.4.29.  t_save_lumps()
1220
+1.4.30.  t_save_lumps()
1221 1221
 
1222 1222
    Forces the modifications of the processed SIP message to be saved in
1223 1223
    shared memory before t_relay() is called. The new branches which are
... ...
@@ -1232,7 +1265,7 @@ failure_route[0]{
1232 1232
    The transaction must be created by t_newtran() before calling
1233 1233
    t_save_lumps().
1234 1234
 
1235
-   Example 53. t_save_lumps() usage
1235
+   Example 54. t_save_lumps() usage
1236 1236
 route {
1237 1237
         ...
1238 1238
         t_newtran();
... ...
@@ -900,6 +900,50 @@ if (method == CANCEL) {
900 900
 	</example>
901 901
     </section>
902 902
 
903
+    <section id="t_lookup_cancel">
904
+	<title>
905
+	    <function>t_lookup_cancel()</function>,
906
+	    <function>t_lookup_cancel(1)</function>
907
+	</title>
908
+	<para>
909
+		Returns true if the corresponding INVITE transaction exists
910
+		for a CANCEL request. The function can be called at the beginning
911
+		of the script to check whether or not the CANCEL can be immediately
912
+		forwarded bypassing the rest of the script. Note however that
913
+		<function>t_relay_cancel</function> includes
914
+		<function>t_lookup_cancel</function> as well, therefore it is not
915
+		needed to explicitly call this function unless something has to be
916
+		logged for example.
917
+	</para>
918
+	<para>
919
+		If the function parameter (optional) is set to 1, the message flags
920
+		are overwritten with the flags of the INVITE. isflagset() can be used
921
+		to check the flags of the previously forwarded INVITE in this case.
922
+	</para>
923
+	<example>
924
+	    <title><function>t_lookup_cancel</function> usage</title>
925
+	    <programlisting>
926
+
927
+if (method == CANCEL) {
928
+	if (t_lookup_cancel()) {
929
+		log("INVITE transaction exists");
930
+		if (!t_relay_cancel()) {  # implicit drop if
931
+                                          # relaying was successful,
932
+                                          # nothing to do
933
+
934
+			# corresponding INVITE transaction found
935
+			# but error occurred
936
+			sl_reply("500", "Internal Server Error");
937
+			drop;
938
+		}
939
+	}
940
+	# bad luck, corresponding INVITE transaction is missing,
941
+	# do the same as for INVITEs
942
+}
943
+	    </programlisting>
944
+	</example>
945
+    </section>
946
+
903 947
     <section id="t_drop_replies">
904 948
 	<title>
905 949
 	    <function>t_drop_replies()</function>