Browse code

dispatcher: documentation for ds_select_routes()

Daniel-Constantin Mierla authored on 19/06/2018 16:53:13
Showing 1 changed files
... ...
@@ -1279,6 +1279,77 @@ if(ds_select("1", "$var(a)")) {
1279 1279
 </programlisting>
1280 1280
 		</example>
1281 1281
 	</section>
1282
+	<section id="dispatcher.f.ds_select_routes">
1283
+		<title>
1284
+		<function moreinfo="none">ds_select_routes(rules, mode [, limit])</function>
1285
+		</title>
1286
+		<para>
1287
+		The method selects destinations following the rules combining groups add
1288
+		algorithms, controlling where the first destination address is pushed,
1289
+		and optionally setting a limit of selected addresses.
1290
+		</para>
1291
+		<para>Parameters:</para>
1292
+		<itemizedlist>
1293
+		<listitem>
1294
+			<para><emphasis>rules</emphasis> - a string in the format
1295
+			"grp1=alg1;grp2=alg2;...grpN=algN", where grpX is an integer number
1296
+			identifying a dispatcher set id and algN is a dispatcher algorithm
1297
+			identifier. No white spaces should be given in the parameter value.
1298
+			The parameter can contain pseudo-variables.
1299
+			</para>
1300
+		</listitem>
1301
+		<listitem>
1302
+			<para><emphasis>mode</emphasis> - control where to push the first
1303
+			selected target address. Valid values are: '0', 'd' or 'D' to push
1304
+			the address in destination URI; '1', 'r' or 'R' to push the address
1305
+			in R-URI; '2', 'x' or 'X' to push the address only in the XAVP when
1306
+			failure rerouting is enabled. Note that only first character of the
1307
+			parameter matters, therefore once case use a more meaningful value
1308
+			such as 'ruri' instead of 'r'. The parameter can contain pseudo
1309
+			variables.
1310
+			</para>
1311
+		</listitem>
1312
+		<listitem>
1313
+			<para><emphasis>limit</emphasis> - a positive integer value to
1314
+			restrict the number of selected target addresses. If it is 0, then
1315
+			no limit is considered. The parameter can be a static integer or
1316
+			a variable holding an integer value.
1317
+			</para>
1318
+		</listitem>
1319
+		<itemizedlist>
1320
+		<para>
1321
+		If the bit 2 in 'flags' is set, the rest of the addresses from the
1322
+		destination groups are stored in XAVP list (limited with an optional 'limit'
1323
+		parameter). You can execute 'ds_next_domain()' or 'ds_next_dst()' to use
1324
+		next address to achieve serial forking to all possible destinations.
1325
+		</para>
1326
+		<para>
1327
+		This function can be used from ANY_ROUTE.
1328
+		</para>
1329
+		<example>
1330
+		<title><function>ds_select_routes</function> usage</title>
1331
+		<programlisting format="linespecific">
1332
+...
1333
+$var(alg) = 4;
1334
+$var(limit) = 8;
1335
+if(ds_select_routes("1=4;2=$var(alg)", "ruri", "$var(limit)")) {
1336
+    t_on_failure("REROUTE");
1337
+    t_relay();
1338
+    exit;
1339
+}
1340
+failure_route[REROUTE] {
1341
+    if(t_check_status("408|5[0-9][0-9]")) {
1342
+        if(ds_next_domain()) {
1343
+            t_on_failure("REROUTE");
1344
+            t_relay();
1345
+            exit;
1346
+        }
1347
+    }
1348
+}
1349
+...
1350
+</programlisting>
1351
+		</example>
1352
+	</section>
1282 1353
 	<section>
1283 1354
 		<title>
1284 1355
 		<function moreinfo="none">ds_next_dst()</function>