tm_user.sgml

sip server服务器

		<title><function>t_relay</function> usage</title>
		<programlisting format="linespecific">
...
if (!t_relay()) { sl_reply_error(); break; };
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title>
		<function moreinfo="none">t_on_negative(reply_route)</function>
	    </title>
	    <para>
		Sets reply routing block, to which control is passed after a transaction completed
		with a negative result but before sending a final reply. In the referred block, you
		can either start a new branch (good for services such as forward_on_no_reply) or
		send a final reply on your own (good for example for message silo, which received a
		negative reply from upstream and wants to tell upstream <quote>202 I will take care
		of it</quote>). Note that the set of command which are usable within reply_routes
		is strictly limited to rewriting &uri;, initiating new branches, logging, and
		sending stateful replies (<function>t_reply</function>). Any other commands may
		result in unpredictable behavior and possible server failure. Note that whenever
		reply_route is entered, uri is reset to value which it had on relaying. If it
		temporarily changed during a reply_route processing, subsequent reply_route will
		ignore the changed value and use again the original one.
	    </para>
	    <para>Meaning of the parameters is as follows:</para>
	    <itemizedlist>
		<listitem>
		    <para><emphasis>reply_route</emphasis> - Reply route block to be called.
		    </para>
		</listitem>
	    </itemizedlist>
	    <example>
		<title><function>t_on_negative</function> usage</title>
		<programlisting format="linespecific">
...
route { 
    t_on_negative("1"); 
    t_relay(); 
} 

reply_route[1] {
    revert_uri(); 
    setuser("voicemail"); 
    append_branch(); 
}
...
</programlisting>
	    </example>
	    <para>
		See test/onr.cfg for a more complex example of combination
		of serial with parallel forking.
	    </para>
	</section>

	<section>
	    <title>
		<function moreinfo="none">append_branch()</function>
	    </title>
	    <para>
		Similarly to <function>t_fork_to</function>, it extends destination set by a new
		entry. The difference is that current &uri; is taken as new entry.
	    </para>
	    <example>
		<title><function>append_branch</function> usage</title>
		<programlisting format="linespecific">
...
set_user("john"); 
t_fork(); 
set_user("alice");
t_fork(); 
t_relay();
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title>
		<function moreinfo="none">t_newtran()</function>
	    </title>
	    <para>
		Creates a new transaction, returns a negative value on error. This is the only way a
		script can add a new transaction in an atomic way. Typically, it is used to deploy a
		&uas;.
	    </para>
	    <example>
		<title><function>t_newtran</function> usage</title>
		<programlisting format="linespecific">
...
if (t_newtran()) { 
    log("UAS logic"); 
    t_reply("999","hello"); 
} else sl_reply_error();
...
</programlisting>
	    </example>
	    <para>
		See test/uas.cfg for more examples.
	    </para>
	</section>

	<section>
	    <title>
		<function moreinfo="none">t_reply(code, reason_phrase)</function>
	    </title>
	    <para>
		Sends a stateful reply after a transaction has been established. See
		<function>t_newtran</function> for usage.
	    </para>
	    <para>Meaning of the parameters is as follows:</para>
	    <itemizedlist>
		<listitem>
		    <para><emphasis>code</emphasis> - Reply code number.
		    </para>
		</listitem>
		<listitem>
		    <para><emphasis>reason_phrase</emphasis> - Reason string.
		    </para>
		</listitem>
	    </itemizedlist>
	    <example>
		<title><function>t_reply</function> usage</title>
		<programlisting format="linespecific">
...
t_reply("404", "Not found");
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title>
		<function moreinfo="none">t_lookup_request()</function>
	    </title>
	    <para>
		Checks if a transaction exists. Returns a positive value if so, negative otherwise.
		Most likely you will not want to use it, as a typical application of a looku-up is
		to introduce a new transaction if none was found. However this is safely
		(atomically) done using <function>t_newtran</function>.
	    </para>
	    <example>
		<title><function>t_lookup_request</function> usage</title>
		<programlisting format="linespecific">
...
if (t_lookup_request()) {
    ...
};
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title>
		<function moreinfo="none">t_retransmit_reply()</function>
	    </title>
	    <para>
		Retransmits a reply sent previously by &uas; transaction.
	    </para>
	    <example>
		<title><function>t_retransmit_reply</function> usage</title>
		<programlisting format="linespecific">
...
t_retransmit_reply();
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title>
		<function moreinfo="none">t_release()</function>
	    </title>
	    <para>
		Remove transaction from memory (it will be first put on a wait timer to absorb
		delayed messages).
	    </para>
	    <example>
		<title><function>t_release</function> usage</title>
		<programlisting format="linespecific">
...
t_release();
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title>
		<function moreinfo="none">t_forward_nonack(ip, port)</function>
	    </title>
	    <para>
		mainly for internal usage--forward a non-ACK request statefully.
	    </para>
	    <para>Meaning of the parameters is as follows:</para>
	    <itemizedlist>
		<listitem>
		    <para><emphasis>ip</emphasis> - &ip address where the message should be sent.
		    </para>
		</listitem>
		<listitem>
		    <para><emphasis>port</emphasis> - Port number.
		    </para>
		</listitem>
	    </itemizedlist>
	    <example>
		<title><function>t_forward_nonack</function> usage</title>
		<programlisting format="linespecific">
...
t_forward_nonack("1.2.3.4", "5060");
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title>External Usage of <acronym>TM</acronym></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, &ser; accepts requests for new transactions via fifo pipes too. If you want to
		enable this feature, start <acronym>FIFO</acronym> server with configuration option.
	    </para>
	    <para>
		fifo=<quote>/tmp/ser_fifo</quote>
	    </para>
	    <para>
		Then, an application can easily launch a new transaction by writing a transaction
		request to this named pipe. The request must follow very simple format, which is
	    </para>
	    <programlisting format="linespecific">
 :t_uac_from:[&lt;file_name&gt;]\n
 &lt;method&gt;\n
 &lt;sender's uri&gt;\n
 &lt;dst uri&gt;\n
 &lt;CR_separated_headers&gt;\n
 &lt;body&gt;\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 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 format="linespecific">
[jiri@bat jiri]$ cat &gt; /tmp/ser_fifo
:t_uac_from:xxx
MESSAGE
sip:[e-mail]
sip:[e-mail]
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 &gt; /tmp/ser_fifo
	    </para>
	</section>
	<section>
	    <title>Known Issues</title>
	    <itemizedlist>
		<listitem>
		    <para>
			We don't have authentication merging on forking.
		    </para>
		</listitem>
		<listitem>
		    <para>
			Local ACK/CANCELs copy'n'pastes Route and ignores deleted
			Routes.
		    </para>
		</listitem>
		<listitem>
		    <para>
			6xx should be delayed.
		    </para>
		</listitem>
		<listitem>
		    <para>
			Possibly, performance could be improved by not parsing non-INVITEs, as they
			do not be replied with 100, and do not result in ACK/CANCELs, and other
			things which take parsing. However, we need to rethink whether we don't need
			parsed headers later for something else. Remember, when we now conserver a
			request in sh_mem, we can't apply any pkg_mem operations to it any
			more. (that might be redesigned too).
		    </para>
		</listitem>
		<listitem>
		    <para>
			Another performance improvement may be achieved by not parsing
			CSeq in replies until reply branch matches branch of an INVITE/CANCEL
			in transaction table.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<function>t_replicate</function> should be done more cleanly--Vias, Routes,
			etc. should be removed from a message prior to replicating it (well, does
			not matter any longer so much as there is a new replication module).
		    </para>
		</listitem>
		<listitem>
		    <para>
			<acronym>SNMP</acronym> support (as nobody cares about
			<acronym>SNMP</acronym>, in particular for <acronym>TM</acronym>, I will drop this item soon).
		    </para>
		</listitem>
	    </itemizedlist>
	</section>
    </section>
</chapter>

<!-- Keep this element at the end of the file
Local Variables:
sgml-parent-document: ("tm.sgml" "Book" "chapter")
End:
-->