mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
267 lines
8.6 KiB
267 lines
8.6 KiB
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<section id="tm.api" xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<sectioninfo>
|
|
</sectioninfo>
|
|
|
|
<title>TM Module API</title>
|
|
<para>
|
|
There are applications which would like to generate SIP transactions
|
|
without too big involvement in SIP stack, transaction management,
|
|
etc. An example of such an application is sending instant messages from
|
|
a website. To address needs of such apps, SIP-router accepts requests for
|
|
new transactions via the management interface. If you want to enable this
|
|
feature, start the management interface server by configuring the proper
|
|
modules.
|
|
</para>
|
|
<para>
|
|
An application can easily launch a new transaction by writing a
|
|
transaction request to this interface. The request must follow very
|
|
simple format, which for the basic FIFO interface is
|
|
</para>
|
|
<programlisting>
|
|
:t_uac_from:[<file_name>]\n
|
|
<method>\n
|
|
<sender's uri>\n
|
|
<dst uri>\n
|
|
<CR_separated_headers>\n
|
|
<body>\n
|
|
.\n
|
|
\n
|
|
</programlisting>
|
|
<para>
|
|
(Filename is to where a report will be dumped. ser assumes /tmp as
|
|
file's directory.)
|
|
</para>
|
|
<para>
|
|
Note the request write must be atomic, otherwise it might get
|
|
intermixed with writes from other writers. You can easily use it via
|
|
Unix command-line tools, see the following example:
|
|
</para>
|
|
<screen>
|
|
[jiri@bat jiri]$ cat > /tmp/ser_fifo
|
|
:t_uac_from:xxx
|
|
MESSAGE
|
|
sip:sender@iptel.org
|
|
sip:mrx@iptel.org
|
|
header:value
|
|
foo:bar
|
|
bznk:hjhjk
|
|
p_header: p_value
|
|
|
|
body body body
|
|
yet body
|
|
end of body
|
|
.
|
|
|
|
</screen>
|
|
<para>
|
|
or cat test/transaction.fifo > /tmp/ser_fifo
|
|
</para>
|
|
|
|
<section id="defines">
|
|
<title>Defines</title>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
ACK_TAG enables stricter matching of acknowledgments
|
|
including to-tags. Without it, to-tags are ignored. It is
|
|
disabled by default for two reasons:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
It eliminates an unlikely race condition in which
|
|
transaction's to-tag is being rewritten by a 200 OK
|
|
whereas an ACK is being looked up by to-tag.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
It makes UACs happy who set wrong to-tags.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
It should not make a difference, as there may be only one
|
|
negative reply sent upstream and 200/ACKs are not matched
|
|
as they constitute another transaction. It will make no
|
|
difference at all when the new magic cookie matching is
|
|
enabled anyway.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
CANCEL_TAG similarly enables strict matching of CANCELs
|
|
including to-tags--act of mercy to UACs, who screw up
|
|
the to-tags (however, it still depends on how forgiving
|
|
the downstream UAS is). Like with ACK_TAG, all this
|
|
complex transactions matching goes with <ulink
|
|
url="http://www.ietf.org/rfc/rfc3261.txt">RFC3261</ulink>'s
|
|
magic cookie away anyway.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section>
|
|
<title>Functions</title>
|
|
<section>
|
|
<title>
|
|
<function>register_tmcb(cb_type, cb_func)</function>
|
|
</title>
|
|
<para>
|
|
For programmatic use only--register a function to be called
|
|
back on an event. See t_hooks.h for more details.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>cb_type</emphasis> - Callback type.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>cb_func</emphasis> - Callback function.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section id="load_tm">
|
|
<title>
|
|
<function>load_tm(*import_structure)</function>
|
|
</title>
|
|
<para>
|
|
For programmatic use only--import exported <acronym>TM</acronym> functions.
|
|
See the acc module for an example of use.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>import_structure</emphasis> - Pointer to the import structure.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section id="t_suspend">
|
|
<title>
|
|
<function>int t_suspend(struct sip_msg *msg,
|
|
unsigned int *hash_index, unsigned int *label)</function>
|
|
</title>
|
|
<para>
|
|
For programmatic use only.
|
|
This function together with t_continue() can be used to
|
|
implement asynchronous actions: t_suspend() saves the transaction,
|
|
returns its identifiers, and t_continue() continues the
|
|
SIP request/response processing. (The request/response processing does not continue
|
|
from the same point in the script, a separate route block defined
|
|
by the parameter of t_continue() is executed instead. The reply lock
|
|
is held during the route block execution.)
|
|
FR timer is ticking while the transaction is suspended, and the
|
|
transaction's failure route is executed if t_continue() is not
|
|
called in time.
|
|
</para>
|
|
<para>
|
|
Missing: message lumps are saved by t_suspend() and are not updated by
|
|
the subsequent t_relay(). This means that the modifications made
|
|
between them are lost.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>msg</emphasis> - SIP message pointer.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>hash_index</emphasis> - transaction identifier.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>label</emphasis> - transaction identifier.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>Return value: 0 - success, <0 - error.</para>
|
|
<para>
|
|
Usage: Allocate a memory block for storing the transaction identifiers
|
|
(hash_index and label), and for storing also any variable related to
|
|
the async query. Before calling t_suspend(), register for the following
|
|
callbacks, and pass the pointer to the allocated shared memory as
|
|
a parameter: TMCB_ON_FAILURE, TMCB_DESTROY, and TMCB_E2ECANCEL_IN
|
|
(in case of INVITE transaction). The async operation can be
|
|
cancelled, if it is still pending, when TMCB_ON_FAILURE or
|
|
TMCB_E2ECANCEL_IN is called. TMCB_DESTROY is suitable to free
|
|
the shared memory allocated for the async and SIP transaction identifiers.
|
|
Once the async query result is available call t_continue(), see below.
|
|
The SIP transaction must exist before calling t_suspend(), and the module
|
|
function calling t_suspend() should return 0 to make sure that the script
|
|
processing does not continue.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="t_continue">
|
|
<title>
|
|
<function>int t_continue(unsigned int hash_index, unsigned int label,
|
|
struct action *route)</function>
|
|
</title>
|
|
<para>
|
|
For programmatic use only.
|
|
This function is the pair of t_suspend(), and is supposed
|
|
to be called when the asynchronous query result is available.
|
|
The function executes a route block with the saved SIP message.
|
|
It is possible to add more branches to the transaction, or send
|
|
a reply from the route block.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>hash_index</emphasis> - transaction identifier.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>label</emphasis> - transaction identifier.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>route</emphasis> - route block to execute.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>Return value: 0 - success, <0 - error.</para>
|
|
</section>
|
|
|
|
<section id="t_cancel_suspend">
|
|
<title>
|
|
<function>int t_cancel_suspend(unsigned int hash_index, unsigned int label)</function>
|
|
</title>
|
|
<para>
|
|
For programmatic use only.
|
|
This function is for revoking t_suspend() from the
|
|
same process as it was executed before. t_cancel_suspend() can be
|
|
used when something fails after t_suspend() has already been executed
|
|
and it turns out that the transcation should not have been
|
|
suspended. The function cancels the FR timer of the transacation.
|
|
</para>
|
|
<para>
|
|
The message lumps are saved by t_suspend() which cannot be restored.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>hash_index</emphasis> - transaction identifier.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>label</emphasis> - transaction identifier.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>Return value: 0 - success, <0 - error.</para>
|
|
</section>
|
|
</section>
|
|
</section>
|