Skip to content

Commit 58f2a6b

Browse files
bogdan-iancubogdan-iancu
committed
[tm] added new vars and functions to docs
1 parent a914df6 commit 58f2a6b

1 file changed

Lines changed: 180 additions & 2 deletions

File tree

‎modules/tm/doc/tm_admin.xml‎

Lines changed: 180 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1388,7 +1388,7 @@ onreply_route[3] {
13881388

13891389
<section id="func_t_new_request" xreflabel="t_new_request()">
13901390
<title>
1391-
<function moreinfo="none">t_new_request(method,RURI,from,to[,body[,ctx]])</function>
1391+
<function moreinfo="none">t_new_request( method, RURI, from, to [, body[, ctx]])</function>
13921392
</title>
13931393
<para>
13941394
This function generates and sends out a new SIP request (in a stateful way).
@@ -2023,6 +2023,44 @@ route{
20232023
</example>
20242024
</section>
20252025

2026+
<section id="func_t_get_branch_idx_by_attr" xreflabel="t_get_branch_idx_by_attr()">
2027+
<title>
2028+
<function moreinfo="none">t_get_branch_idx_by_attr(attr, [val_str], [val_int], [result_var], [offset])</function>
2029+
</title>
2030+
<para>
2031+
This function may be used to search for the index of another branch
2032+
of the current transaction. The searching is done based on the
2033+
per-branch attribute - you need to provide the name of the attribute
2034+
at least. Optionally you can provide a value (string or integer) for
2035+
the attribute used for searching. As input, the function may take an
2036+
optional branch offset (absolute value, covering all branches of the
2037+
transaction) where the search should start from.
2038+
</para>
2039+
<para>
2040+
The function returns true if a branch (having the given name and
2041+
value for the attribute) was found. The status of the branch (like
2042+
if ongoing, completed ) is not relevant. If found, the "result_var"
2043+
variable will be populated with the branch index (as integer).
2044+
</para>
2045+
<para>
2046+
This function can be used from ONREPLY_ROUTE, BRANCH_ROUTE and
2047+
FAILURE_ROUTE.
2048+
</para>
2049+
<example>
2050+
<title><function>t_get_branch_idx_by_attr</function> usage</title>
2051+
<programlisting format="linespecific">
2052+
...
2053+
# search for a branch which has the "name" attribute
2054+
# with string value "pstn"
2055+
if (t_get_branch_idx_by_attr("name", "pstn", , $var(idx))) {
2056+
xlog("found branch has index $var(idx)\n");
2057+
}
2058+
...
2059+
</programlisting>
2060+
</example>
2061+
</section>
2062+
2063+
20262064
</section>
20272065

20282066
<section id="exported_pseudo_variables" xreflabel="Exported Pseudo-Variables">
@@ -2121,7 +2159,147 @@ route{
21212159
specified, the last reply for the current branch is retrieved.
21222160
</para>
21232161
</section>
2124-
2162+
<section id="pv_tm_branch_uri" xreflabel="$tm.branch.uri">
2163+
<title>$tm.branch.uri[]</title>
2164+
<para>
2165+
<emphasis>$tm.branch.uri</emphasis> - gives read-only
2166+
access over the Request URI (as string) of a TM existing
2167+
branch. The status of the branch (completed, ongoing, etc)
2168+
is not relevant.
2169+
</para>
2170+
<para>
2171+
The TM (UAC side) branches are created when the request is
2172+
sent to new destinations via "t_relay()" or "t_inject()".
2173+
</para>
2174+
<para>
2175+
The indexing of the branches starts from 0, giving access to
2176+
all branches (past and active) of the transaction. Nevertheless
2177+
the indexing supports two optional suffixes, to simplify the
2178+
scripting:
2179+
<itemizedlist>
2180+
<listitem><para>
2181+
<emphasis>/active</emphasis> - the indexing starts also
2182+
from 0, but it is relative to the last set of branches -
2183+
the parallel branches created by the last "t_relay()"-ing.
2184+
</para></listitem>
2185+
<listitem><para>
2186+
<emphasis>/all</emphasis> - similar to "no suffix" case,
2187+
meaning it is an absolute index, covering all the
2188+
branches of the trasactions (resulted from all "t_relay()"s
2189+
performed over the transaction).
2190+
</para></listitem>
2191+
</itemizedlist>
2192+
</para>
2193+
<para>
2194+
IF no index is specified, the current branch used. This depends
2195+
on the scripting context. Like in reply route, the current
2196+
branch is the branch the reply came for; in branch route, the
2197+
current branch is the branch to be sent out; in failure route,
2198+
the current branch is the winning branch.
2199+
</para>
2200+
<para>
2201+
NOTES:
2202+
<itemizedlist>
2203+
<listitem><para>
2204+
The index ALL ( "*" ) is not supported;
2205+
</para></listitem>
2206+
<listitem><para>
2207+
In branch route, only the "$tm.branch.attr" and
2208+
"$tm.branch.flag" variables work for the current branch
2209+
(the rest of the branch related variables will return NULL)
2210+
</para></listitem>
2211+
<listitem><para>
2212+
Negative values are accepted, meaning indexing from the
2213+
end ( -1 is the latest/higher branch)
2214+
</para></listitem>
2215+
</itemizedlist>
2216+
</para>
2217+
<para>
2218+
The variable can be used in BRANCH, ONREPLY and FAILURE routes.
2219+
</para>
2220+
</section>
2221+
<section id="pv_tm_branch_duri" xreflabel="$tm.branch.duri">
2222+
<title>$tm.branch.duri[]</title>
2223+
<para>
2224+
<emphasis>$tm.branch.duri</emphasis> - 100% similar to
2225+
<emphasis role='bold'><xref linkend="pv_tm_branch_uri"/></emphasis>, but returning the Detination-URI value of the branch.
2226+
</para>
2227+
</section>
2228+
<section id="pv_tm_branch_path" xreflabel="$tm.branch.path">
2229+
<title>$tm.branch.path[]</title>
2230+
<para>
2231+
<emphasis>$tm.branch.path</emphasis> - 100% similar to
2232+
<emphasis role='bold'><xref linkend="pv_tm_branch_uri"/></emphasis>, but returning the PATH value of the branch.
2233+
</para>
2234+
</section>
2235+
<section id="pv_tm_branch_q" xreflabel="$tm.branch.q">
2236+
<title>$tm.branch.q[]</title>
2237+
<para>
2238+
<emphasis>$tm.branch.q</emphasis> - 100% similar to
2239+
<emphasis role='bold'><xref linkend="pv_tm_branch_uri"/></emphasis>, but returning the Q value of the branch.
2240+
</para>
2241+
</section>
2242+
<section id="pv_tm_branch_flags" xreflabel="$tm.branch.flags">
2243+
<title>$tm.branch.flags[]</title>
2244+
<para>
2245+
<emphasis>$tm.branch.flags</emphasis> - 100% similar to
2246+
<emphasis role='bold'><xref linkend="pv_tm_branch_uri"/></emphasis>, but returning the list (comma separated) of per-branch flags which are
2247+
set for the branch.
2248+
</para>
2249+
</section>
2250+
<section id="pv_tm_branch_socket" xreflabel="$tm.branch.socket">
2251+
<title>$tm.branch.socket[]</title>
2252+
<para>
2253+
<emphasis>$tm.branch.socket</emphasis> - 100% similar to
2254+
<emphasis role='bold'><xref linkend="pv_tm_branch_uri"/></emphasis>, but returning the socket description (proto:ip:port) used for sending the
2255+
branch out.
2256+
</para>
2257+
</section>
2258+
<section id="pv_tm_branch_flag" xreflabel="$tm.branch.flag">
2259+
<title>$tm.branch.flag()[]</title>
2260+
<para>
2261+
<emphasis>$tm.branch.flag(name)</emphasis> - similar to
2262+
<emphasis role='bold'><xref linkend="pv_tm_branch_uri"/></emphasis>, but gives read/write access to a single branch flag (by its name).
2263+
</para>
2264+
<para>
2265+
The accepted values are 0 for FALSE, pozitive non-zero for
2266+
TRUE. The returned values are 0 for FALSE and 1 for TRUE.
2267+
</para>
2268+
<para>
2269+
The flags operated here are the same as the bflags you can
2270+
operated with via the "[re]setbflag()" functions.
2271+
</para>
2272+
</section>
2273+
<section id="pv_tm_branch_attr" xreflabel="$tm.branch.attr">
2274+
<title>$tm.branch.attr()[]</title>
2275+
<para>
2276+
<emphasis>$tm.branch.attr(name)</emphasis> - similar to
2277+
<emphasis role='bold'><xref linkend="pv_tm_branch_uri"/></emphasis>, but gives read/write access to the attributed attached to the branch.
2278+
</para>
2279+
<para>
2280+
An attribute can have whatever name (no need to be
2281+
pre-defined) and it can have a single value (at a time),
2282+
string or integer.
2283+
</para>
2284+
</section>
2285+
<section id="pv_tm_branch_last_received" xreflabel="$tm.branch.last_received">
2286+
<title>$tm.branch.last_received[]</title>
2287+
<para>
2288+
<emphasis>$tm.branch.last_received</emphasis> - 100% similar to
2289+
<emphasis role='bold'><xref linkend="pv_tm_branch_uri"/></emphasis>, but returning the reply code of the last received reply (from the
2290+
network) on this branch. NULL is returned in no reply was
2291+
received so far.
2292+
</para>
2293+
</section>
2294+
<section id="pv_tm_branch_type" xreflabel="$tm.branch.type">
2295+
<title>$tm.branch.type[]</title>
2296+
<para>
2297+
<emphasis>$tm.branch.type</emphasis> - 100% similar to
2298+
<emphasis role='bold'><xref linkend="pv_tm_branch_uri"/></emphasis>, but returning the type of the current branch. This may be "phone" if it
2299+
not a real branch (has no SIP signalling, used by waiting for
2300+
branch injection) or "sip" (a real signalling branch).
2301+
</para>
2302+
</section>
21252303
</section>
21262304

21272305

0 commit comments

Comments
 (0)