[sr-dev] git:master:8446409d: dispatcher: documentation for ds_select_routes()

Module: kamailio Branch: master Commit: 8446409d77fe82a38eec772bbcf92bea34d44e35 URL: https://github.com/kamailio/kamailio/commit/8446409d77fe82a38eec772bbcf92be… Author: Daniel-Constantin Mierla &lt;miconda(a)gmail.com&gt; Committer: Daniel-Constantin Mierla &lt;miconda(a)gmail.com&gt; Date: 2018-06-19T18:53:13+02:00 dispatcher: documentation for ds_select_routes() --- Modified: src/modules/dispatcher/doc/dispatcher_admin.xml --- Diff: https://github.com/kamailio/kamailio/commit/8446409d77fe82a38eec772bbcf92be… Patch: https://github.com/kamailio/kamailio/commit/8446409d77fe82a38eec772bbcf92be… --- diff --git a/src/modules/dispatcher/doc/dispatcher_admin.xml b/src/modules/dispatcher/doc/dispatcher_admin.xml index 19c68bf4b3..20512651ca 100644 --- a/src/modules/dispatcher/doc/dispatcher_admin.xml +++ b/src/modules/dispatcher/doc/dispatcher_admin.xml @@ -1276,6 +1276,77 @@ if(ds_select("1", "$var(a)")) { exit; } ... +</programlisting> + </example> + </section> + <section id="dispatcher.f.ds_select_routes"> + <title> + <function moreinfo="none">ds_select_routes(rules, mode [, limit])</function> + </title> + <para> + The method selects destinations following the rules combining groups add + algorithms, controlling where the first destination address is pushed, + and optionally setting a limit of selected addresses. + </para> + <para>Parameters:</para> + <itemizedlist> + <listitem> + <para><emphasis>rules</emphasis> - a string in the format + "grp1=alg1;grp2=alg2;...grpN=algN", where grpX is an integer number + identifying a dispatcher set id and algN is a dispatcher algorithm + identifier. No white spaces should be given in the parameter value. + The parameter can contain pseudo-variables. + </para> + </listitem> + <listitem> + <para><emphasis>mode</emphasis> - control where to push the first + selected target address. Valid values are: '0', 'd' or 'D' to push + the address in destination URI; '1', 'r' or 'R' to push the address + in R-URI; '2', 'x' or 'X' to push the address only in the XAVP when + failure rerouting is enabled. Note that only first character of the + parameter matters, therefore once case use a more meaningful value + such as 'ruri' instead of 'r'. The parameter can contain pseudo + variables. + </para> + </listitem> + <listitem> + <para><emphasis>limit</emphasis> - a positive integer value to + restrict the number of selected target addresses. If it is 0, then + no limit is considered. The parameter can be a static integer or + a variable holding an integer value. + </para> + </listitem> + <itemizedlist> + <para> + If the bit 2 in 'flags' is set, the rest of the addresses from the + destination groups are stored in XAVP list (limited with an optional 'limit' + parameter). You can execute 'ds_next_domain()' or 'ds_next_dst()' to use + next address to achieve serial forking to all possible destinations. + </para> + <para> + This function can be used from ANY_ROUTE. + </para> + <example> + <title><function>ds_select_routes</function> usage</title> + <programlisting format="linespecific"> +... +$var(alg) = 4; +$var(limit) = 8; +if(ds_select_routes("1=4;2=$var(alg)", "ruri", "$var(limit)")) { + t_on_failure("REROUTE"); + t_relay(); + exit; +} +failure_route[REROUTE] { + if(t_check_status("408|5[0-9][0-9]")) { + if(ds_next_domain()) { + t_on_failure("REROUTE"); + t_relay(); + exit; + } + } +} +... </programlisting> </example> </section>