Browse code

- improved documentation system - documentation makefiles - proper documentation dependency tracking in makefiles - XML-based dialect of docbook used with xi:include inclusions

Jan Janak authored on 23/07/2005 23:30:26
Showing 9 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,29 @@
1
+#
2
+# The list of documents to build (without extensions)
3
+#
4
+DOCUMENTS = tm
5
+
6
+#
7
+# The root directory containing Makefile.doc
8
+#
9
+ROOT_DIR=../../..
10
+
11
+#
12
+# Validate docbook documents before generating output
13
+# (may be slow)
14
+#
15
+#VALIDATE=1
16
+
17
+#
18
+# You can override the stylesheet used to generate
19
+# xhtml documents here
20
+#
21
+#XHTML_XSL=$(ROOT_DIR)/doc/stylesheets/xhtml.xsl
22
+
23
+#
24
+# You can override the stylesheet used to generate
25
+# plain text documents here
26
+#
27
+#TXT_XSL=$(XHTML_XSL)
28
+
29
+include $(ROOT_DIR)/Makefile.doc
0 30
new file mode 100644
... ...
@@ -0,0 +1,160 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
3
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
4
+
5
+<section id="tm.api" xmlns:xi="http://www.w3.org/2001/XInclude">
6
+    <sectioninfo>
7
+	<revhistory>
8
+	    <revision>
9
+		<revnumber>$Revision$</revnumber>
10
+		<date>$Date$</date>
11
+	    </revision>
12
+	</revhistory>
13
+    </sectioninfo>
14
+
15
+    <title>TM Module API</title>
16
+    <para>
17
+	There are applications which would like to generate SIP transactions
18
+	without too big involvement in SIP stack, transaction management,
19
+	etc. An example of such an application is sending instant messages from
20
+	a website. To address needs of such apps, SER accepts requests for
21
+	new transactions via fifo pipes too. If you want to enable this
22
+	feature, start <acronym>FIFO</acronym> server with configuration
23
+	option.
24
+    </para>
25
+    <para>
26
+	fifo="/tmp/ser_fifo"
27
+    </para>
28
+    <para>
29
+	Then, an application can easily launch a new transaction by writing a
30
+	transaction request to this named pipe. The request must follow very
31
+	simple format, which is
32
+    </para>
33
+    <programlisting>
34
+ :t_uac_from:[&lt;file_name&gt;]\n
35
+ &lt;method&gt;\n
36
+ &lt;sender's uri&gt;\n
37
+ &lt;dst uri&gt;\n
38
+ &lt;CR_separated_headers&gt;\n
39
+ &lt;body&gt;\n
40
+ .\n
41
+ \n
42
+</programlisting>
43
+    <para>
44
+	(Filename is to where a report will be dumped. ser assumes /tmp as
45
+	file's directory.)
46
+    </para>
47
+    <para>
48
+	Note the the request write must be atomic, otherwise it might get
49
+	intermixed with writes from other writers. You can easily use it via
50
+	Unix command-line tools, see the following example:
51
+    </para>
52
+    <screen>
53
+[jiri@bat jiri]$ cat &gt; /tmp/ser_fifo
54
+:t_uac_from:xxx
55
+MESSAGE
56
+sip:sender@iptel.org
57
+sip:mrx@iptel.org
58
+header:value
59
+foo:bar
60
+bznk:hjhjk
61
+p_header: p_value
62
+
63
+body body body
64
+yet body
65
+end of body
66
+.
67
+
68
+    </screen>
69
+    <para>
70
+	or cat test/transaction.fifo &gt; /tmp/ser_fifo
71
+    </para>
72
+
73
+    <section id="defines">
74
+	<title>Defines</title>
75
+	<itemizedlist>
76
+	    <listitem>
77
+		<para>
78
+		    ACK_TAG enables stricter matching of acknowledgments
79
+		    including to-tags. Without it, to-tags are ignored. It is
80
+		    disabled by default for two reasons:
81
+		</para>
82
+		<itemizedlist>
83
+		    <listitem>
84
+			<para>
85
+			    It eliminates an unlikely race condition in which
86
+			    transaction's to-tag is being rewritten by a 200 OK
87
+			    whereas an ACK is being looked up by to-tag.
88
+			</para>
89
+		    </listitem>
90
+		</itemizedlist>
91
+		<itemizedlist>
92
+		    <listitem>
93
+			<para>
94
+			    It makes UACs happy who set wrong to-tags.
95
+			</para>
96
+		    </listitem>
97
+		</itemizedlist>
98
+		<para>
99
+		    It should not make a difference, as there may be only one
100
+		    negative reply sent upstream and 200/ACKs are not matched
101
+		    as they constitute another transaction. It will make no
102
+		    difference at all when the new magic cookie matching is
103
+		    enabled anyway.
104
+		</para>
105
+	    </listitem>
106
+	    <listitem>
107
+		<para>
108
+		    CANCEL_TAG similarly enables strict matching of CANCELs 
109
+		    including to-tags--act of mercy to UACs, who screw up
110
+		    the to-tags (however, it still depends on how forgiving
111
+		    the downstream UAS is). Like with ACK_TAG, all this
112
+		    complex transactions matching goes with <ulink
113
+			url="http://www.ietf.org/rfc/rfc3261.txt">RFC3261</ulink>'s
114
+		    magic cookie away anyway.
115
+		</para>
116
+	    </listitem>
117
+	</itemizedlist>
118
+    </section>
119
+    <section>
120
+	<title>Functions</title>
121
+	<section>
122
+	    <title>
123
+		<function>register_tmcb(cb_type, cb_func)</function>
124
+	    </title>
125
+	    <para>
126
+		For programmatic use only--register a function to be called
127
+		back on an event. See t_hooks.h for more details.
128
+	    </para>
129
+	    <para>Meaning of the parameters is as follows:</para>
130
+	    <itemizedlist>
131
+		<listitem>
132
+		    <para><emphasis>cb_type</emphasis> - Callback type.
133
+		    </para>
134
+		</listitem>
135
+		<listitem>
136
+		    <para><emphasis>cb_func</emphasis> - Callback function.
137
+		    </para>
138
+		</listitem>
139
+	    </itemizedlist>
140
+	</section>
141
+	
142
+	<section id="load_tm">
143
+	    <title>
144
+		<function>load_tm(*import_structure)</function>
145
+	    </title>
146
+	    <para>
147
+		For programmatic use only--import exported <acronym>TM</acronym> functions.
148
+		See the acc module for an example of use.
149
+	    </para>
150
+	    <para>Meaning of the parameters is as follows:</para>
151
+	    <itemizedlist>
152
+		<listitem>
153
+		    <para><emphasis>import_structure</emphasis> - Pointer to the import structure.
154
+		    </para>
155
+		</listitem>
156
+	    </itemizedlist>
157
+	</section>
158
+    </section>
159
+    
160
+</section>
0 161
new file mode 100644
... ...
@@ -0,0 +1,288 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
3
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
4
+
5
+<section id="tm.functions" xmlns:xi="http://www.w3.org/2001/XInclude">
6
+    <sectioninfo>
7
+	<revhistory>
8
+	    <revision>
9
+		<revnumber>$Revision$</revnumber>
10
+		<date>$Date$</date>
11
+	    </revision>
12
+	</revhistory>
13
+    </sectioninfo>
14
+
15
+    <title>Functions</title>
16
+
17
+    <section id="t_relay_to_udp">
18
+	<title>
19
+	    <function>t_relay_to_udp(ip, port)</function>,
20
+	    <function>t_relay_to_tcp(ip, port)</function>
21
+	</title>
22
+	<para>
23
+	    Relay a message statefully to a fixed destination. This along with
24
+	    <function>t_relay</function> is the function most users want to
25
+	    use--all other are mostly for programming. Programmers interested
26
+	    in writing <acronym>TM</acronym> logic should review how t_relay is
27
+	    implemented in tm.c and how <acronym>TM</acronym> callbacks work.
28
+	</para>
29
+	<para>Meaning of the parameters is as follows:</para>
30
+	<itemizedlist>
31
+	    <listitem>
32
+		<para><emphasis>ip</emphasis> - IP address where the message should be sent.
33
+		</para>
34
+	    </listitem>
35
+	    <listitem>
36
+		<para><emphasis>port</emphasis> - Port number.
37
+		</para>
38
+	    </listitem>
39
+	</itemizedlist>
40
+	<example>
41
+	    <title><function>t_relay_to_udp</function> usage</title>
42
+	    <programlisting>
43
+...
44
+t_relay_to_udp("1.2.3.4", "5060");
45
+...
46
+	    </programlisting>
47
+	</example>
48
+    </section>
49
+
50
+    <section id="t_relay">
51
+	<title>
52
+	    <function>t_relay()</function>
53
+	</title>
54
+	<para>
55
+	    Relay a message statefully to destination indicated in current URI. (If the
56
+	    original URI was rewritten by UsrLoc, RR, strip/prefix, etc., the new URI will
57
+	    be taken). Returns a negative value on failure--you may still want to send a
58
+	    negative reply upstream statelessly not to leave upstream UAC in lurch.
59
+	</para>
60
+	<example>
61
+	    <title><function>t_relay</function> usage</title>
62
+	    <programlisting>
63
+...
64
+if (!t_relay()) 
65
+{ 
66
+    sl_reply_error(); 
67
+    break; 
68
+};
69
+...
70
+	    </programlisting>
71
+	</example>
72
+    </section>
73
+    
74
+    <section id="t_on_negative">
75
+	<title>
76
+	    <function>t_on_negative(reply_route)</function>
77
+	</title>
78
+	<para>
79
+	    Sets reply routing block, to which control is passed after a
80
+	    transaction completed with a negative result but before sending a
81
+	    final reply. In the referred block, you can either start a new
82
+	    branch (good for services such as forward_on_no_reply) or send a
83
+	    final reply on your own (good for example for message silo, which
84
+	    received a negative reply from upstream and wants to tell upstream
85
+	    "202 I will take care of it"). Note that the set of
86
+	    command which are usable within reply_routes is strictly limited to
87
+	    rewriting URI, initiating new branches, logging, and sending
88
+	    stateful replies (<function>t_reply</function>). Any other commands
89
+	    may result in unpredictable behavior and possible server
90
+	    failure. Note that whenever reply_route is entered, uri is reset to
91
+	    value which it had on relaying. If it temporarily changed during a
92
+	    reply_route processing, subsequent reply_route will ignore the
93
+	    changed value and use again the original one.
94
+	</para>
95
+	<para>Meaning of the parameters is as follows:</para>
96
+	<itemizedlist>
97
+	    <listitem>
98
+		<para><emphasis>reply_route</emphasis> - Reply route block to be called.
99
+		</para>
100
+	    </listitem>
101
+	</itemizedlist>
102
+	<example>
103
+	    <title><function>t_on_negative</function> usage</title>
104
+	    <programlisting>
105
+...
106
+route { 
107
+    t_on_negative("1"); 
108
+    t_relay(); 
109
+} 
110
+
111
+reply_route[1] {
112
+    revert_uri(); 
113
+    setuser("voicemail"); 
114
+    append_branch(); 
115
+}
116
+...
117
+	    </programlisting>
118
+	</example>
119
+	<para>
120
+	    See <filename>test/onr.cfg</filename> for a more complex example of
121
+	    combination of serial with parallel forking.
122
+	</para>
123
+    </section>
124
+    
125
+    <section id="append_branch">
126
+	<title>
127
+	    <function>append_branch()</function>
128
+	</title>
129
+	<para>
130
+	    Similarly to <function>t_fork_to</function>, it extends destination
131
+	    set by a new entry. The difference is that current URI is taken
132
+	    as new entry.
133
+	</para>
134
+	<example>
135
+	    <title><function>append_branch</function> usage</title>
136
+	    <programlisting>
137
+...
138
+set_user("john"); 
139
+t_fork(); 
140
+set_user("alice");
141
+t_fork(); 
142
+t_relay();
143
+...
144
+	    </programlisting>
145
+	</example>
146
+    </section>
147
+
148
+    <section id="t_newtran">
149
+	<title>
150
+	    <function>t_newtran()</function>
151
+	</title>
152
+	<para>
153
+	    Creates a new transaction, returns a negative value on error. This
154
+	    is the only way a script can add a new transaction in an atomic
155
+	    way. Typically, it is used to deploy a UAS.
156
+	</para>
157
+	<example>
158
+	    <title><function>t_newtran</function> usage</title>
159
+	    <programlisting>
160
+...
161
+if (t_newtran()) { 
162
+    log("UAS logic"); 
163
+    t_reply("999","hello"); 
164
+} else sl_reply_error();
165
+...
166
+	    </programlisting>
167
+	</example>
168
+	<para>
169
+	    See test/uas.cfg for more examples.
170
+	</para>
171
+    </section>
172
+
173
+    <section id="t_reply">
174
+	<title>
175
+	    <function>t_reply(code, reason_phrase)</function>
176
+	</title>
177
+	<para>
178
+	    Sends a stateful reply after a transaction has been
179
+	    established. See <function>t_newtran</function> for usage.
180
+	</para>
181
+	<para>Meaning of the parameters is as follows:</para>
182
+	<itemizedlist>
183
+	    <listitem>
184
+		<para><emphasis>code</emphasis> - Reply code number.
185
+		</para>
186
+	    </listitem>
187
+	    <listitem>
188
+		<para><emphasis>reason_phrase</emphasis> - Reason string.
189
+		</para>
190
+	    </listitem>
191
+	</itemizedlist>
192
+	<example>
193
+	    <title><function>t_reply</function> usage</title>
194
+	    <programlisting>
195
+...
196
+t_reply("404", "Not found");
197
+...
198
+	    </programlisting>
199
+	</example>
200
+    </section>
201
+
202
+    <section id="t_lookup_request">
203
+	<title>
204
+	    <function>t_lookup_request()</function>
205
+	</title>
206
+	<para>
207
+	    Checks if a transaction exists. Returns a positive value if so,
208
+	    negative otherwise.  Most likely you will not want to use it, as a
209
+	    typical application of a looku-up is to introduce a new transaction
210
+	    if none was found. However this is safely (atomically) done using
211
+	    <function>t_newtran</function>.
212
+	</para>
213
+	<example>
214
+	    <title><function>t_lookup_request</function> usage</title>
215
+	    <programlisting>
216
+...
217
+if (t_lookup_request()) {
218
+    ...
219
+};
220
+...
221
+	    </programlisting>
222
+	</example>
223
+    </section>
224
+
225
+    <section id="t_retransmit_reply">
226
+	<title>
227
+	    <function>t_retransmit_reply()</function>
228
+	</title>
229
+	<para>
230
+	    Retransmits a reply sent previously by UAS transaction.
231
+	</para>
232
+	<example>
233
+	    <title><function>t_retransmit_reply</function> usage</title>
234
+	    <programlisting>
235
+...
236
+t_retransmit_reply();
237
+...
238
+	    </programlisting>
239
+	</example>
240
+    </section>
241
+
242
+    <section id="t_release">
243
+	<title>
244
+	    <function>t_release()</function>
245
+	</title>
246
+	<para>
247
+	    Remove transaction from memory (it will be first put on a wait
248
+	    timer to absorb delayed messages).
249
+	</para>
250
+	<example>
251
+	    <title><function>t_release</function> usage</title>
252
+	    <programlisting>
253
+...
254
+t_release();
255
+...
256
+	    </programlisting>
257
+	</example>
258
+    </section>
259
+
260
+    <section id="t_forward_nonack">
261
+	<title>
262
+	    <function>t_forward_nonack(ip, port)</function>
263
+	</title>
264
+	<para>
265
+	    mainly for internal usage--forward a non-ACK request statefully.
266
+	</para>
267
+	<para>Meaning of the parameters is as follows:</para>
268
+	<itemizedlist>
269
+	    <listitem>
270
+		<para><emphasis>ip</emphasis> - IP address where the message should be sent.
271
+		</para>
272
+	    </listitem>
273
+	    <listitem>
274
+		<para><emphasis>port</emphasis> - Port number.
275
+		</para>
276
+	    </listitem>
277
+	</itemizedlist>
278
+	<example>
279
+	    <title><function>t_forward_nonack</function> usage</title>
280
+	    <programlisting>
281
+...
282
+t_forward_nonack("1.2.3.4", "5060");
283
+...
284
+	    </programlisting>
285
+	</example>
286
+    </section>
287
+
288
+</section>
0 289
new file mode 100644
... ...
@@ -0,0 +1,191 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
3
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
4
+
5
+<section id="tm.parameters" xmlns:xi="http://www.w3.org/2001/XInclude">
6
+    <sectioninfo>
7
+	<revhistory>
8
+	    <revision>
9
+		<revnumber>$Revision$</revnumber>
10
+		<date>$Date$</date>
11
+	    </revision>
12
+	</revhistory>
13
+    </sectioninfo>
14
+
15
+    <title>Parameters</title>
16
+
17
+    <section id="fr_timer">
18
+	<title><varname>fr_timer</varname> (integer)</title>
19
+	<para>
20
+	    Timer which hits if no final reply for a request or ACK for a
21
+	    negative INVITE reply arrives (in seconds).
22
+	</para>
23
+	<para>
24
+	    Default value is 30 seconds.
25
+	</para>
26
+	<example>
27
+	    <title>Set <varname>fr_timer</varname> parameter</title>
28
+	    <programlisting>
29
+...
30
+modparam("tm", "fr_timer", 10)
31
+...
32
+	    </programlisting>
33
+	</example>
34
+    </section>
35
+
36
+    <section id="fr_inv_timer">
37
+	<title><varname>fr_inv_timer</varname> (integer)</title>
38
+	<para>
39
+	    Timer which hits if no final reply for an INVITE arrives after a
40
+	    provisional message was received (in seconds).
41
+	</para>
42
+	<para>
43
+	    Default value is 120 seconds.
44
+	</para>
45
+	<example>
46
+	    <title>Set <varname>fr_inv_timer</varname> parameter</title>
47
+	    <programlisting>
48
+...
49
+modparam("tm", "fr_inv_timer", 200)
50
+...
51
+	    </programlisting>
52
+	</example>
53
+    </section>
54
+
55
+    <section id="wt_timer">
56
+	<title><varname>wt_timer</varname> (integer)</title>
57
+	<para>
58
+	    Time for which a transaction stays in memory to absorb delayed
59
+	    messages after it completed; also, when this timer hits,
60
+	    retransmission of local cancels is stopped (a puristic but complex
61
+	    behavior would be not to enter wait state until local branches are
62
+	    finished by a final reply or FR timer--we simplified).
63
+	</para>
64
+	<para>
65
+	    Default value is 5 seconds.
66
+	</para>
67
+	<example>
68
+	    <title>Set <varname>wt_timer</varname> parameter</title>
69
+	    <programlisting>
70
+...
71
+modparam("tm", "wt_timer", 10)
72
+...
73
+	    </programlisting>
74
+	</example>
75
+    </section>
76
+
77
+    <section id="delete_timer">
78
+	<title><varname>delete_timer</varname> (integer)</title>
79
+	<para>
80
+	    Time after which a to-be-deleted transaction currently ref-ed by a
81
+	    process will be tried to be deleted again.
82
+	</para>
83
+	<para>
84
+	    Default value is 2 seconds.
85
+	</para>
86
+	<example>
87
+	    <title>Set <varname>delete_timer</varname> parameter</title>
88
+	    <programlisting>
89
+...
90
+modparam("tm", "delete_timer", 5)
91
+...
92
+	    </programlisting>
93
+	</example>
94
+    </section>
95
+    
96
+    <section id="retr_timer1p1">
97
+	<title><varname>retr_timer1p1</varname> (integer)</title>
98
+	<para>
99
+	    Retransmission period.
100
+	</para>
101
+	<para>
102
+	    Default value is 1 second.
103
+	</para>
104
+	<example>
105
+	    <title>Set <varname>retr_timer1p1</varname> parameter</title>
106
+	    <programlisting>
107
+...
108
+modparam("tm", "retr_timer1p1", 2)
109
+...
110
+	    </programlisting>
111
+	</example>
112
+    </section>
113
+
114
+    <section id="retr_timer1p2">
115
+	<title><varname>retr_timer1p2</varname> (integer)</title>
116
+	<para>
117
+	    Retransmission period.
118
+	</para>
119
+	<para>
120
+	    Default value is 2 * <varname>retr_timer1p1</varname> second.
121
+	</para>
122
+	<example>
123
+	    <title>Set <varname>retr_timer1p2</varname> parameter</title>
124
+	    <programlisting>
125
+...
126
+modparam("tm", "retr_timer1p2", 4)
127
+...
128
+	    </programlisting>
129
+	</example>
130
+    </section>
131
+
132
+    <section id="retr_timer1p3">
133
+	<title><varname>retr_timer1p3</varname> (integer)</title>
134
+	<para>
135
+	    Retransmission period.
136
+	</para>
137
+	<para>
138
+	    Default value is 4 * <varname>retr_timer1p1</varname> second.
139
+	</para>
140
+	<example>
141
+	    <title>Set <varname>retr_timer1p4</varname> parameter</title>
142
+	    <programlisting>
143
+...
144
+modparam("tm", "retr_timer1p3", 8)
145
+...
146
+	    </programlisting>
147
+	</example>
148
+    </section>
149
+
150
+    <section id="retr_timer2">
151
+	<title><varname>retr_timer2</varname> (integer)</title>
152
+	<para>
153
+	    Maximum retransmission period.
154
+	</para>
155
+	<para>
156
+	    Default value is 4 seconds.
157
+	</para>
158
+	<example>
159
+	    <title>Set <varname>retr_timer2</varname> parameter</title>
160
+	    <programlisting>
161
+...
162
+modparam("tm", "retr_timer2", 8)
163
+...
164
+	    </programlisting>
165
+	</example>
166
+    </section>
167
+
168
+    <section id="noisy_ctimer">
169
+	<title><varname>noisy_ctimer</varname> (integer)</title>
170
+	<para>
171
+	    If set, on FR timer INVITE transactions will be explicitly canceled
172
+	    if possible, silently dropped otherwise. Preferably, it is turned
173
+	    off to allow very long ringing.  This behavior is overridden if a
174
+	    request is forked, or some functionality explicitly turned it off
175
+	    for a transaction (like acc does to avoid unaccounted transactions
176
+	    due to expired timer).
177
+	</para>
178
+	<para>
179
+	    Default value is 0 (false).
180
+	</para>
181
+	<example>
182
+	    <title>Set <varname>noisy_ctimer</varname> parameter</title>
183
+	    <programlisting>
184
+...
185
+modparam("tm", "noisy_ctimer", 1)
186
+...
187
+	    </programlisting>
188
+	</example>
189
+    </section>
190
+
191
+</section>
0 192
deleted file mode 100644
... ...
@@ -1,52 +0,0 @@
1
-<!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
2
-
3
-
4
-<!ENTITY user SYSTEM "tm_user.sgml">
5
-<!ENTITY devel SYSTEM "tm_devel.sgml">
6
-<!ENTITY faq SYSTEM "tm_faq.sgml">
7
-
8
-<!-- Include general SER documentation entities -->
9
-<!ENTITY % serentities SYSTEM "../../../doc/ser_entities.sgml">
10
-%serentities;
11
-
12
-]>
13
-
14
-<book>
15
-    <bookinfo>
16
-	<title>tm Module</title>
17
-	<productname class="trade">&sername;</productname>
18
-	<authorgroup>
19
-	    <author>
20
-		<firstname>Jiri</firstname>
21
-		<surname>Kuthan</surname>
22
-		<affiliation><orgname>&fhg;</orgname></affiliation>
23
-		<address>
24
-		    <email>jiri@iptel.org</email>
25
-		</address>
26
-	    </author>
27
-	    <editor>
28
-		<firstname>Jiri</firstname>
29
-		<surname>Kuthan</surname>
30
-		<address>
31
-		    <email>jiri@iptel.org</email>
32
-		</address>
33
-	    </editor>
34
-	</authorgroup>
35
-	<copyright>
36
-	    <year>2003</year>
37
-	    <holder>&fhg;</holder>
38
-	</copyright>
39
-	<revhistory>
40
-	    <revision>
41
-		<revnumber>$Revision$</revnumber>
42
-		<date>$Date$</date>
43
-	    </revision>
44
-	</revhistory>
45
-    </bookinfo>
46
-    <toc></toc>
47
-    
48
-    &user;
49
-    &devel;
50
-    &faq;
51
-    
52
-</book>
53 0
new file mode 100644
... ...
@@ -0,0 +1,154 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
3
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
4
+
5
+<section id="tm" xmlns:xi="http://www.w3.org/2001/XInclude">
6
+    <sectioninfo>
7
+	<authorgroup>
8
+	    <author>
9
+		<firstname>Jiri</firstname>
10
+		<surname>Kuthan</surname>
11
+		<affiliation><orgname>FhG FOKUS</orgname></affiliation>
12
+		<address>
13
+		    <email>jiri@iptel.org</email>
14
+		</address>
15
+	    </author>
16
+	</authorgroup>
17
+	<copyright>
18
+	    <year>2003</year>
19
+	    <holder>FhG FOKUS</holder>
20
+	</copyright>
21
+	<revhistory>
22
+	    <revision>
23
+		<revnumber>$Revision$</revnumber>
24
+		<date>$Date$</date>
25
+	    </revision>
26
+	</revhistory>
27
+    </sectioninfo>
28
+
29
+    <title>TM Module</title>
30
+
31
+    <section>
32
+	<title>Overview</title>
33
+	<para>
34
+	    <acronym>TM</acronym> module enables stateful processing of SIP
35
+	    transactions. The main use of stateful logic, which is costly in
36
+	    terms of memory and <acronym>CPU</acronym>, is some services
37
+	    inherently need state. For example, transaction-based accounting
38
+	    (module acc) needs to process transaction state as opposed to
39
+	    individual messages, and any kinds of forking must be implemented
40
+	    statefully. Other use of stateful processing is it trading
41
+	    <acronym>CPU</acronym> caused by retransmission processing for
42
+	    memory. That makes however only sense if <acronym>CPU</acronym>
43
+	    consumption per request is huge. For example, if you want to avoid
44
+	    costly <acronym>DNS</acronym> resolution for every retransmission
45
+	    of a request to an unresolvable destination, use stateful
46
+	    mode. Then, only the initial message burdens server by
47
+	    <acronym>DNS</acronym> queries, subsequent retransmissions will be
48
+	    dropped and will not result in more processes blocked by
49
+	    <acronym>DNS</acronym> resolution. The price is more memory
50
+	    consumption and higher processing latency.
51
+	</para>
52
+	<para>
53
+	    From user's perspective, there are these major functions : t_relay,
54
+	    t_relay_to_udp and t_relay_to_tcp. All of them setup transaction
55
+	    state, absorb retransmissions from upstream, generate downstream
56
+	    retransmissions and correlate replies to requests. t_relay forwards
57
+	    to current URI (be it original request's URI or a URI changed by
58
+	    some of URI-modifying functions, such as sethost). t_relay_to_udp
59
+	    and t_relay_to_tcp forward to a specific address over UDP or TCP
60
+	    respectively.
61
+	</para>
62
+	<para>
63
+	    In general, if <acronym>TM</acronym> is used, it copies clones of
64
+	    received SIP messages in shared memory. That costs the memory and
65
+	    also <acronym>CPU</acronym> time (memcpys, lookups, shmem locks,
66
+	    etc.)  Note that non-<acronym>TM</acronym> functions operate over
67
+	    the received message in private memory, that means that any core
68
+	    operations will have no effect on statefully processed messages
69
+	    after creating the transactional state. For example, calling
70
+	    record_route <emphasis>after</emphasis> t_relay is pretty useless,
71
+	    as the <acronym>RR</acronym> is added to privately held message
72
+	    whereas its <acronym>TM</acronym> clone is being forwarded.
73
+	</para>
74
+	<para>
75
+	    <acronym>TM</acronym> is quite big and uneasy to program--lot of
76
+	    mutexes, shared memory access, malloc and free, timers--you really
77
+	    need to be careful when you do anything. To simplify
78
+	    <acronym>TM</acronym> programming, there is the instrument of
79
+	    callbacks. The callback mechanisms allow programmers to register
80
+	    their functions to specific event. See t_hooks.h for a list of
81
+	    possible events.
82
+	</para>
83
+	<para>
84
+	    Other things programmers may want to know is UAC--it is a very
85
+	    simplistic code which allows you to generate your own
86
+	    transactions. Particularly useful for things like NOTIFYs or
87
+	    <acronym>IM</acronym> gateways. The UAC takes care of all the
88
+	    transaction machinery: retransmissions , FR timeouts, forking, etc.
89
+	    See t_uac prototype in uac.h for more details. Who wants to see the
90
+	    transaction result may register for a callback.
91
+	</para>
92
+    </section>
93
+    
94
+    <section id="known_issues">
95
+	<title>Known Issues</title>
96
+	<itemizedlist>
97
+	    <listitem>
98
+		<para>
99
+		    We don't have authentication merging on forking.
100
+		</para>
101
+	    </listitem>
102
+	    <listitem>
103
+		<para>
104
+		    Local ACK/CANCELs copy'n'pastes Route and ignores deleted
105
+		    Routes.
106
+		</para>
107
+	    </listitem>
108
+	    <listitem>
109
+		<para>
110
+		    6xx should be delayed.
111
+		</para>
112
+	    </listitem>
113
+	    <listitem>
114
+		<para>
115
+		    Possibly, performance could be improved by not parsing
116
+		    non-INVITEs, as they do not be replied with 100, and do not
117
+		    result in ACK/CANCELs, and other things which take
118
+		    parsing. However, we need to rethink whether we don't need
119
+		    parsed headers later for something else. Remember, when we
120
+		    now conserver a request in sh_mem, we can't apply any
121
+		    pkg_mem operations to it any more. (that might be
122
+		    redesigned too).
123
+		</para>
124
+	    </listitem>
125
+	    <listitem>
126
+		<para>
127
+		    Another performance improvement may be achieved by not
128
+		    parsing CSeq in replies until reply branch matches branch
129
+		    of an INVITE/CANCEL in transaction table.
130
+		</para>
131
+	    </listitem>
132
+	    <listitem>
133
+		<para>
134
+		    <function>t_replicate</function> should be done more
135
+		    cleanly--Vias, Routes, etc. should be removed from a
136
+		    message prior to replicating it (well, does not matter any
137
+		    longer so much as there is a new replication module).
138
+		</para>
139
+	    </listitem>
140
+	    <listitem>
141
+		<para>
142
+		    <acronym>SNMP</acronym> support (as nobody cares about
143
+		    <acronym>SNMP</acronym>, in particular for
144
+		    <acronym>TM</acronym>, I will drop this item soon).
145
+		</para>
146
+	    </listitem>
147
+	</itemizedlist>
148
+    </section>
149
+    
150
+    <xi:include href="params.xml"/>
151
+    <xi:include href="functions.xml"/>
152
+    <xi:include href="api.xml"/>
153
+
154
+</section>
0 155
deleted file mode 100644
... ...
@@ -1,106 +0,0 @@
1
-<!-- Module Developer's Guide -->
2
-
3
-<chapter>
4
-    <chapterinfo>
5
-	<revhistory>
6
-	    <revision>
7
-		<revnumber>$Revision$</revnumber>
8
-		<date>$Date$</date>
9
-	    </revision>
10
-	</revhistory>
11
-    </chapterinfo>
12
-    <title>Developer's Guide</title>
13
-    <para>
14
-	The module does not provide any sort of <acronym>API</acronym> to use in other &ser; modules.	
15
-    </para>
16
-    <section>
17
-	<title>Defines</title>
18
-	<itemizedlist>
19
-	    <listitem>
20
-		<para>
21
-		    ACK_TAG enables stricter matching of acknowledgments including to-tags. Without
22
-		    it, to-tags are ignored. It is disabled by default for two reasons: 
23
-		</para>
24
-		<itemizedlist>
25
-		    <listitem>
26
-			<para>
27
-			    It eliminates an unlikely race condition in which transaction's to-tag
28
-			    is being rewritten by a 200 OK whereas an ACK is being looked up by
29
-			    to-tag.
30
-			</para>
31
-		    </listitem>
32
-		</itemizedlist>
33
-		<itemizedlist>
34
-		    <listitem>
35
-			<para>
36
-			    It makes &uac;s happy who set wrong to-tags.
37
-			</para>
38
-		    </listitem>
39
-		</itemizedlist>
40
-		<para>
41
-		    It should not make a difference, as there may be only one
42
-		    negative reply sent upstream and 200/ACKs are not matched
43
-		    as they constitute another transaction. It will make no
44
-		    difference at all when the new magic cookie matching is
45
-		    enabled anyway.
46
-		</para>
47
-	    </listitem>
48
-	    <listitem>
49
-		<para>
50
-		    CANCEL_TAG similarly enables strict matching of CANCELs 
51
-		    including to-tags--act of mercy to &uac;s, who screw up
52
-		    the to-tags (however, it still depends on how forgiving
53
-		    the downstream UAS is). Like with ACK_TAG, all this
54
-		    complex transactions matching goes with &rfc3261;'s
55
-		    magic cookie away anyway.
56
-		</para>
57
-	    </listitem>
58
-	</itemizedlist>
59
-    </section>
60
-    <section>
61
-	<title>Functions</title>
62
-	<section>
63
-	    <title>
64
-		<function moreinfo="none">register_tmcb(cb_type, cb_func)</function>
65
-	    </title>
66
-	    <para>
67
-		For programmatic use only--register a function to be called back on an event. See
68
-		t_hooks.h for more details.
69
-	    </para>
70
-	    <para>Meaning of the parameters is as follows:</para>
71
-	    <itemizedlist>
72
-		<listitem>
73
-		    <para><emphasis>cb_type</emphasis> - Callback type.
74
-		    </para>
75
-		</listitem>
76
-		<listitem>
77
-		    <para><emphasis>cb_func</emphasis> - Callback function.
78
-		    </para>
79
-		</listitem>
80
-	    </itemizedlist>
81
-	</section>
82
-
83
-	<section>
84
-	    <title>
85
-		<function moreinfo="none">load_tm(*import_structure)</function>
86
-	    </title>
87
-	    <para>
88
-		For programmatic use only--import exported <acronym>TM</acronym> functions.
89
-		See the acc module for an example of use.
90
-	    </para>
91
-	    <para>Meaning of the parameters is as follows:</para>
92
-	    <itemizedlist>
93
-		<listitem>
94
-		    <para><emphasis>import_structure</emphasis> - Pointer to the import structure.
95
-		    </para>
96
-		</listitem>
97
-	    </itemizedlist>
98
-	</section>
99
-    </section>
100
-</chapter>
101
-
102
-<!-- Keep this element at the end of the file
103
-Local Variables:
104
-sgml-parent-document: ("tm.sgml" "book" "chapter")
105
-End:
106 0
deleted file mode 100644
... ...
@@ -1,67 +0,0 @@
1
-<!-- Module FAQ -->
2
-
3
-<chapter>
4
-    <chapterinfo>
5
-	<revhistory>
6
-	    <revision>
7
-		<revnumber>$Revision$</revnumber>
8
-		<date>$Date$</date>
9
-	    </revision>
10
-	</revhistory>
11
-    </chapterinfo>
12
-    <title>Frequently Asked Questions</title>
13
-    <qandaset defaultlabel="number">
14
-	<qandaentry>
15
-	    <question>
16
-		<para>Where can I find more about &ser;?</para>
17
-	    </question>
18
-	    <answer>
19
-		<para>
20
-		    Take a look at &serhomelink;.
21
-		</para>
22
-	    </answer>
23
-	</qandaentry>
24
-	<qandaentry>
25
-	    <question>
26
-		<para>Where can I post a question about this module?</para>
27
-	    </question>
28
-	    <answer>
29
-		<para>
30
-		    First at all check if your question was already answered on one of
31
-		    our mailing lists: 
32
-		</para>
33
-		<itemizedlist>
34
-		    <listitem>
35
-			<para>&seruserslink;</para>
36
-		    </listitem>
37
-		    <listitem>
38
-			<para>&serdevlink;</para>
39
-		    </listitem>
40
-		</itemizedlist>
41
-		<para>
42
-		    E-mails regarding any stable version should be sent to &serusersmail; and e-mail
43
-		    regarding development versions or CVS snapshots should be send to &serdevmail;.
44
-		</para>
45
-		<para>
46
-		    If you want to keep the mail private, send it to &serhelpmail;.
47
-		</para>
48
-	    </answer>
49
-	</qandaentry>
50
-	<qandaentry>
51
-	    <question>
52
-		<para>How can I report a bug?</para>
53
-	    </question>
54
-	    <answer>
55
-		<para>
56
-		    Please follow the guidelines provided at: &serbugslink;
57
-		</para>
58
-	    </answer>
59
-	</qandaentry>
60
-    </qandaset>
61
-</chapter>
62
-
63
-<!-- Keep this element at the end of the file
64
-Local Variables:
65
-sgml-parent-document: ("tm.sgml" "Book" "chapter")
66
-End:
67 0
deleted file mode 100644
... ...
@@ -1,669 +0,0 @@
1
-<!-- Module User's Guide -->
2
-
3
-<chapter>
4
-    <chapterinfo>
5
-	<revhistory>
6
-	    <revision>
7
-		<revnumber>$Revision$</revnumber>
8
-		<date>$Date$</date>
9
-	    </revision>
10
-	</revhistory>
11
-    </chapterinfo>
12
-    <title>User's Guide</title>
13
-    
14
-    <section>
15
-	<title>Overview</title>
16
-	<para>
17
-	    <acronym>TM</acronym> module enables stateful processing of &sip; transactions. The main
18
-	    use of stateful logic, which is costly in terms of memory and <acronym>CPU</acronym>, is
19
-	    some services inherently need state. For example, transaction-based accounting (module
20
-	    acc) needs to process transaction state as opposed to individual messages, and any kinds
21
-	    of forking must be implemented statefully. Other use of stateful processing is it trading
22
-	    <acronym>CPU</acronym> caused by retransmission processing for memory. That makes
23
-	    however only sense if <acronym>CPU</acronym> consumption per request is huge. For
24
-	    example, if you want to avoid costly <acronym>DNS</acronym> resolution for every
25
-	    retransmission of a request to an unresolvable destination, use stateful mode. Then,
26
-	    only the initial message burdens server by <acronym>DNS</acronym> queries, subsequent
27
-	    retransmissions will be dropped and will not result in more processes blocked by
28
-	    <acronym>DNS</acronym> resolution. The price is more memory consumption and higher
29
-	    processing latency.
30
-	</para>
31
-	<para>
32
-	    From user's perspective, there are these major functions : t_relay, t_relay_to_udp
33
-		and t_relay_to_tcp. All of them
34
-	    setup transaction state, absorb retransmissions from upstream, generate downstream
35
-	    retransmissions and correlate replies to requests. t_relay forwards to current &uri; (be
36
-	    it original request's &uri; or a &uri; changed by some of &uri;-modifying functions,
37
-	    such as sethost). t_relay_to_udp and t_relay_to_tcp forward to a specific address
38
-		over UDP or TCP respectively.
39
-	</para>
40
-	<para>
41
-	    In general, if <acronym>TM</acronym> is used, it copies clones of received &sip;
42
-	    messages in shared memory. That costs the memory and also <acronym>CPU</acronym> time
43
-	    (memcpys, lookups, shmem locks, etc.)  Note that non-<acronym>TM</acronym> functions
44
-	    operate over the received message in private memory, that means that any core operations
45
-	    will have no effect on statefully processed messages after creating the transactional
46
-	    state. For example, calling record_route <emphasis>after</emphasis> t_relay is pretty
47
-	    useless, as the <acronym>RR</acronym> is added to privately held message whereas its
48
-	    <acronym>TM</acronym> clone is being forwarded.
49
-	</para>
50
-	<para>
51
-	    <acronym>TM</acronym> is quite big and uneasy to program--lot of mutexes, shared memory
52
-	    access, malloc & free, timers--you really need to be careful when you do anything. To
53
-	    simplify <acronym>TM</acronym> programming, there is the instrument of callbacks. The
54
-	    callback mechanisms allow programmers to register their functions to specific event. See
55
-	    t_hooks.h for a list of possible events.
56
-	</para>
57
-	<para>
58
-	    Other things programmers may want to know is &uac;--it is a very simplistic code which
59
-	    allows you to generate your own transactions. Particularly useful for things like
60
-	    NOTIFYs or <acronym>IM</acronym> gateways. The &uac; takes care of all the transaction
61
-	    machinery: retransmissions , FR timeouts, forking, etc.  See t_uac prototype in uac.h
62
-	    for more details. Who wants to see the transaction result may register for a callback.
63
-	</para>
64
-    </section>
65
-    <section>
66
-	<title>Dependencies</title>
67
-	<section>
68
-	    <title>&ser; Modules</title>
69
-	    <para>
70
-		The following modules must be loaded before this module:
71
-	    	<itemizedlist>
72
-		    <listitem>
73
-			<para>
74
-			    <emphasis>No dependencies on other &ser; modules</emphasis>.
75
-			</para>
76
-		    </listitem>
77
-	    	</itemizedlist>
78
-	    </para>
79
-	</section>
80
-	<section>
81
-	    <title>External Libraries or Applications</title>
82
-	    <para>
83
-		The following libraries or applications must be installed before running
84
-		&ser; with this module loaded:
85
-	    	<itemizedlist>
86
-		    <listitem>
87
-			<para>
88
-			    <emphasis>None</emphasis>.
89
-			</para>
90
-		    </listitem>
91
-	    	</itemizedlist>
92
-	    </para>
93
-	</section>
94
-    </section>
95
-    <section>
96
-	<title>Exported Parameters</title>
97
-	<section>
98
-	    <title><varname>fr_timer</varname> (integer)</title>
99
-	    <para>
100
-		Timer which hits if no final reply for a request or ACK for a negative INVITE reply
101
-		arrives (in seconds).
102
-	    </para>
103
-	    <para>
104
-		<emphasis>
105
-		    Default value is 30 seconds.
106
-		</emphasis>
107
-	    </para>
108
-	    <example>
109
-		<title>Set <varname>fr_timer</varname> parameter</title>
110
-		<programlisting format="linespecific">
111
-...
112
-modparam("tm", "fr_timer", 10)
113
-...
114
-</programlisting>
115
-	    </example>
116
-	</section>
117
-
118
-	<section>
119
-	    <title><varname>fr_inv_timer</varname> (integer)</title>
120
-	    <para>
121
-		Timer which hits if no final reply for an INVITE arrives after a provisional message
122
-		was received (in seconds).
123
-	    </para>
124
-	    <para>
125
-		<emphasis>
126
-		    Default value is 120 seconds.
127
-		</emphasis>
128
-	    </para>
129
-	    <example>
130
-		<title>Set <varname>fr_inv_timer</varname> parameter</title>
131
-		<programlisting format="linespecific">
132
-...
133
-modparam("tm", "fr_inv_timer", 200)
134
-...
135
-</programlisting>
136
-	    </example>
137
-	</section>
138
-
139
-	<section>
140
-	    <title><varname>wt_timer</varname> (integer)</title>
141
-	    <para>
142
-		Time for which a transaction stays in memory to absorb delayed messages after it
143
-		completed; also, when this timer hits, retransmission of local cancels is stopped (a
144
-		puristic but complex behavior would be not to enter wait state until local branches
145
-		are finished by a final reply or FR timer--we simplified).
146
-	    </para>
147
-	    <para>
148
-		<emphasis>
149
-		    Default value is 5 seconds.
150
-		</emphasis>
151
-	    </para>
152
-	    <example>
153
-		<title>Set <varname>wt_timer</varname> parameter</title>
154
-		<programlisting format="linespecific">
155
-...
156
-modparam("tm", "wt_timer", 10)
157
-...
158
-</programlisting>
159
-	    </example>
160
-	</section>
161
-
162
-	<section>
163
-	    <title><varname>delete_timer</varname> (integer)</title>
164
-	    <para>
165
-		Time after which a to-be-deleted transaction currently ref-ed by a process will be
166
-		tried to be deleted again.
167
-	    </para>
168
-	    <para>
169
-		<emphasis>
170
-		    Default value is 2 seconds.
171
-		</emphasis>
172
-	    </para>
173
-	    <example>
174
-		<title>Set <varname>delete_timer</varname> parameter</title>
175
-		<programlisting format="linespecific">
176
-...
177
-modparam("tm", "delete_timer", 5)
178
-...
179
-</programlisting>
180
-	    </example>
181
-	</section>
182
-
183
-	<section>
184
-	    <title><varname>retr_timer1p1</varname> (integer)</title>
185
-	    <para>
186
-		Retransmission period.
187
-	    </para>
188
-	    <para>
189
-		<emphasis>
190
-		    Default value is 1 second.
191
-		</emphasis>
192
-	    </para>
193
-	    <example>
194
-		<title>Set <varname>retr_timer1p1</varname> parameter</title>
195
-		<programlisting format="linespecific">
196
-...
197
-modparam("tm", "retr_timer1p1", 2)
198
-...
199
-</programlisting>
200
-	    </example>
201
-	</section>
202
-
203
-	<section>
204
-	    <title><varname>retr_timer1p2</varname> (integer)</title>
205
-	    <para>
206
-		Retransmission period.
207
-	    </para>
208
-	    <para>
209
-		<emphasis>
210
-		    Default value is 2 * <varname>retr_timer1p1</varname> second.
211
-		</emphasis>
212
-	    </para>
213
-	    <example>
214
-		<title>Set <varname>retr_timer1p2</varname> parameter</title>
215
-		<programlisting format="linespecific">
216
-...
217
-modparam("tm", "retr_timer1p2", 4)
218
-...
219
-</programlisting>
220
-	    </example>
221
-	</section>
222
-
223
-	<section>
224
-	    <title><varname>retr_timer1p3</varname> (integer)</title>
225
-	    <para>
226
-		Retransmission period.
227
-	    </para>
228
-	    <para>
229
-		<emphasis>
230
-		    Default value is 4 * <varname>retr_timer1p1</varname> second.
231
-		</emphasis>
232
-	    </para>
233
-	    <example>
234
-		<title>Set <varname>retr_timer1p4</varname> parameter</title>
235
-		<programlisting format="linespecific">
236
-...
237
-modparam("tm", "retr_timer1p3", 8)
238
-...
239
-</programlisting>
240
-	    </example>
241
-	</section>
242
-
243
-	<section>
244
-	    <title><varname>retr_timer2</varname> (integer)</title>
245
-	    <para>
246
-		Maximum retransmission period.
247
-	    </para>
248
-	    <para>
249
-		<emphasis>
250
-		    Default value is 4 seconds.
251
-		</emphasis>
252
-	    </para>
253
-	    <example>
254
-		<title>Set <varname>retr_timer2</varname> parameter</title>
255
-		<programlisting format="linespecific">
256
-...
257
-modparam("tm", "retr_timer2", 8)
258
-...
259
-</programlisting>
260
-	    </example>
261
-	</section>
262
-
263
-	<section>
264
-	    <title><varname>noisy_ctimer</varname> (integer)</title>
265
-	    <para>
266
-		If set, on FR timer INVITE transactions will be explicitly canceled if possible,
267
-		silently dropped otherwise. Preferably, it is turned off to allow very long ringing.
268
-		This behavior is overridden if a request is forked, or some functionality
269
-		explicitly turned it off for a transaction (like acc does to avoid unaccounted
270
-		transactions due to expired timer).
271
-	    </para>
272
-	    <para>
273
-		<emphasis>
274
-		    Default value is 0 (false).
275
-		</emphasis>
276
-	    </para>
277
-	    <example>
278
-		<title>Set <varname>noisy_ctimer</varname> parameter</title>
279
-		<programlisting format="linespecific">
280
-...
281
-modparam("tm", "noisy_ctimer", 1)
282
-...
283
-</programlisting>
284
-	    </example>
285
-	</section>
286
-
287
-
288
-
289
-    </section>
290
-    <section>
291
-	<title>Exported Functions</title>
292
-	<section>
293
-	    <title>
294
-		<function moreinfo="none">t_relay_to_udp(ip, port)</function>,
295
-		<function moreinfo="none">t_relay_to_tcp(ip, port)</function>
296
-	    </title>
297
-	    <para>
298
-		Relay a message statefully to a fixed destination. This along with <function
299
-		    moreinfo="none">t_relay</function> is the function most users want to use--all
300
-		other are mostly for programming. Programmers interested in writing
301
-		<acronym>TM</acronym> logic should review how t_relay is implemented in tm.c and
302
-		how <acronym>TM</acronym> callbacks work.
303
-	    </para>
304
-	    <para>Meaning of the parameters is as follows:</para>
305
-	    <itemizedlist>
306
-		<listitem>
307
-		    <para><emphasis>ip</emphasis> - &ip address where the message should be sent.
308
-		    </para>
309
-		</listitem>
310
-		<listitem>
311
-		    <para><emphasis>port</emphasis> - Port number.
312
-		    </para>
313
-		</listitem>
314
-	    </itemizedlist>
315
-	    <example>
316
-		<title><function>t_relay_to_udp</function> usage</title>
317
-		<programlisting format="linespecific">
318
-...
319
-t_relay_to_udp("1.2.3.4", "5060");
320
-...
321
-</programlisting>
322
-	    </example>
323
-	</section>
324
-
325
-	<section>
326
-	    <title>
327
-		<function moreinfo="none">t_relay()</function>
328
-	    </title>
329
-	    <para>
330
-		Relay a message statefully to destination indicated in current &uri;. (If the
331
-		original &uri; was rewritten by UsrLoc, RR, strip/prefix, etc., the new &uri; will
332
-		be taken). Returns a negative value on failure--you may still want to send a
333
-		negative reply upstream statelessly not to leave upstream &uac; in lurch.
334
-	    </para>
335
-	    <example>
336
-		<title><function>t_relay</function> usage</title>
337
-		<programlisting format="linespecific">
338
-...
339
-if (!t_relay()) { sl_reply_error(); break; };
340
-...
341
-</programlisting>
342
-	    </example>
343