Browse code

core, lib, modules: restructured source code tree

- new folder src/ to hold the source code for main project applications
- main.c is in src/
- all core files are subfolder are in src/core/
- modules are in src/modules/
- libs are in src/lib/
- application Makefiles are in src/
- application binary is built in src/ (src/kamailio)

Daniel-Constantin Mierla authored on 07/12/2016 11:03:51
Showing 1 changed files
1 1
deleted file mode 100644
... ...
@@ -1,1202 +0,0 @@
1
-<?xml version="1.0" encoding='ISO-8859-1'?>
2
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
-
5
-<!-- Include general documentation entities -->
6
-<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
7
-%docentities;
8
-
9
-]>
10
-<!-- Module User's Guide -->
11
-
12
-<chapter>
13
-	
14
-	<title>&adminguide;</title>
15
-
16
-
17
-	<section>
18
-		<title>Overview</title>
19
-		<para>
20
-		The <acronym>UAC</acronym> (User Agent Client) module provides some basic UAC
21
-		functionalities like sending SIP requests, registering with a remote service,
22
-		From: header manipulation (anonymization) and client authentication.
23
-		</para>
24
-		<para>
25
-		The UAC module also supports sending a SIP request from the
26
-		configuration file. See variable $uac_req(name) and the function
27
-		uac_req_send().
28
-		</para>
29
-		<para>
30
-		In addition, the module supports database-driven SIP registration functionality. See
31
-		the uac_reg_lookup() function and dedicated section for remote
32
-		registration configuration.
33
-		</para>
34
-		<para>
35
-		Known limitations in this version:
36
-		</para>
37
-		<itemizedlist>
38
-			<listitem>
39
-			<para>
40
-				Authentication does not support qop auth-int, just qop auth;
41
-			</para>
42
-			</listitem>
43
-			<listitem>
44
-			<para>
45
-				CSeq is not increased automatically by uac_auth() during authentication
46
-				- the follow up request may be rejected. CSeq can be increased when
47
-				authenticating INVITE requests - dialog module has to be used, with
48
-				CSeq tracking feature enabled (see the readme of dialog module).
49
-			</para>
50
-			</listitem>
51
-			<listitem>
52
-			<para>
53
-				The <quote>uac_replace_*</quote> functions can only be run once on the same
54
-				SIP request. Try to save needed changes in a pseudovariable and
55
-				apply them once.
56
-			</para>
57
-			</listitem>
58
-		</itemizedlist>
59
-	</section>
60
-
61
-	<section>
62
-		<title>Dependencies</title>
63
-		<section>
64
-			<title>&kamailio; Modules</title>
65
-			<para>
66
-			The following modules must be loaded before this module:
67
-			<itemizedlist>
68
-			<listitem>
69
-			<para>
70
-				<emphasis>TM - Transaction Module</emphasis>
71
-			</para>
72
-			</listitem>
73
-			<listitem>
74
-			<para>
75
-				<emphasis>RR - Record-Route Module</emphasis>, but only if
76
-				restore mode for From: URI is set to <quote>auto</quote>.
77
-			</para>
78
-			</listitem>
79
-			<listitem>
80
-			<para>
81
-				<emphasis>Dialog Module</emphasis>, but only if
82
-				restore mode for From: URI is set to <quote>auto</quote> and
83
-				you want uac_replace_from or uac_replace_to to store the values
84
-				of the URIs as dialog variables.
85
-			</para>
86
-			</listitem>
87
-			</itemizedlist>
88
-			</para>
89
-		</section>
90
-		<section>
91
-			<title>External Libraries or Applications</title>
92
-			<para>
93
-				The following libraries or applications must be installed 
94
-				before running &kamailio; with this module loaded:
95
-				<itemizedlist>
96
-				<listitem>
97
-				<para>
98
-					<emphasis>None</emphasis>
99
-				</para>
100
-				</listitem>
101
-				</itemizedlist>
102
-			</para>
103
-		</section>
104
-	</section>
105
-
106
-	<section>
107
-		<title>Parameters</title>
108
-		<section id="uac.p.rr_from_store_param">
109
-			<title><varname>rr_from_store_param</varname> (string)</title>
110
-			<para>
111
-			Name of Record-Route header parameter that will be used to store 
112
-			an encoded version of the original FROM URI.
113
-			</para>
114
-			<para>
115
-				<emphasis>
116
-					This parameter is optional, it's default value being 
117
-					<quote>vsf</quote>.
118
-				</emphasis>
119
-			</para>
120
-			<example>
121
-				<title>Set <varname>rr_from_store_param</varname> parameter</title>
122
-				<programlisting format="linespecific">
123
-...
124
-modparam("uac","rr_from_store_param","my_param")
125
-...
126
-				</programlisting>
127
-			</example>
128
-		</section>
129
-		<section id="uac.p.rr_to_store_param">
130
-			<title><varname>rr_to_store_param</varname> (string)</title>
131
-			<para>
132
-			Name of Record-Route header parameter that will be used to store 
133
-			(encoded) the original TO URI.
134
-			</para>
135
-			<para>
136
-				<emphasis>
137
-					This parameter is optional, it's default value being 
138
-					<quote>vst</quote>.
139
-				</emphasis>
140
-			</para>
141
-			<example>
142
-				<title>Set <varname>rr_to_store_param</varname> parameter</title>
143
-				<programlisting format="linespecific">
144
-...
145
-modparam("uac","rr_to_store_param","my_param")
146
-...
147
-				</programlisting>
148
-			</example>
149
-		</section>
150
-		<section id="uac.p.restore_mode">
151
-			<title><varname>restore_mode</varname> (string)</title>
152
-			<para>
153
-			There are 3 modes of restoring the original FROM URI and the original TO URI:
154
-			<itemizedlist>
155
-			<listitem>
156
-				<para>
157
-				<quote>none</quote> - no information about original URI is 
158
-				stored; restoration is not possible.
159
-				</para>
160
-			</listitem>
161
-			<listitem>
162
-				<para>
163
-				<quote>manual</quote> - all following replies will be restored,
164
-				but not also the sequential requests - this must be manually 
165
-				updated based on original URI.
166
-				</para>
167
-			</listitem>
168
-			<listitem>
169
-				<para>
170
-				<quote>auto</quote> - all sequential requests and replies will 
171
-				be automatically updated based on stored original URI. For this
172
-				option you have to set <quote>modparam("rr", "append_fromtag", 1)</quote>.
173
-				</para>
174
-			</listitem>
175
-			</itemizedlist>
176
-			</para>
177
-			<para>
178
-				<emphasis>
179
-					This parameter is optional, it's default value being 
180
-					<quote>auto</quote>.
181
-				</emphasis>
182
-			</para>
183
-			<example>
184
-				<title>Set <varname>restore_mode</varname> parameter
185
-				</title>
186
-				<programlisting format="linespecific">
187
-...
188
-modparam("uac","restore_mode","auto")
189
-...
190
-				</programlisting>
191
-			</example>
192
-		</section>
193
-		<section id="uac.p.restore_dlg">
194
-			<title><varname>restore_dlg</varname> (int)</title>
195
-			<para>
196
-			If set to 1, the module uses dialog variables to store initial and
197
-			new values for From/To headers. The Dialog module has to be loaded and
198
-			all calls that involve changes to From/To headers must be tracked.
199
-			</para>
200
-			<para>
201
-				<emphasis>
202
-					Default value of this parameter is 0.
203
-				</emphasis>
204
-			</para>
205
-			<example>
206
-				<title>Set <varname>restore_dlg</varname> parameter</title>
207
-				<programlisting format="linespecific">
208
-...
209
-modparam("uac", "restore_dlg", 1)
210
-...
211
-				</programlisting>
212
-			</example>
213
-		</section>
214
-		<section id="uac.p.restore_passwd">
215
-			<title><varname>restore_passwd</varname> (string)</title>
216
-			<para>
217
-			String password to be used to encrypt the RR storing parameters. If
218
-			empty, no encryption will be used.
219
-			</para>
220
-			<para>
221
-				<emphasis>
222
-					Default value of this parameter is empty.
223
-				</emphasis>
224
-			</para>
225
-			<example>
226
-				<title>Set <varname>restore_passwd</varname> parameter</title>
227
-				<programlisting format="linespecific">
228
-...
229
-modparam("uac","restore_passwd","my_secret_passwd")
230
-...
231
-				</programlisting>
232
-			</example>
233
-		</section>
234
-		<section id="uac.p.restore_from_avp">
235
-			<title><varname>restore_from_avp</varname> (string)</title>
236
-			<para>
237
-			If defined and restore_mode is manual or auto, the avp is used to save
238
-			the original from uri in order to be able to restore it in replies.
239
-			That makes sense, if the original-uri can not be extracted from the original
240
-			request, e.g. if msg_apply_changes() was used after calling uac_replace_from()
241
-			or uac_replace_to().
242
-			</para>
243
-			<para>
244
-				If you create a dialog ( with dlg_manage() ) before calling uac_replace_from(),
245
-			this avp will not be needed. The values of the uris will be stored as dialog variables.
246
-			</para>
247
-			<para><emphasis>
248
-					Default value of this parameter is empty.
249
-				</emphasis>
250
-			</para>
251
-			<example>
252
-				<title>Set <varname>restore_from_avp</varname> parameter</title>
253
-				<programlisting format="linespecific">
254
-...
255
-modparam("uac","restore_from_avp","$avp(original_uri_from)")
256
-...
257
-				</programlisting>
258
-			</example>
259
-		</section>
260
-		<section id="uac.p.restore_to_avp">
261
-			<title><varname>restore_to_avp</varname> (string)</title>
262
-			<para>
263
-			If defined and restore_mode is manual or auto, the avp is used to save
264
-			the original To URI in order to be able to restore it in replies.
265
-			That makes sense if the original-uri can not be extracted from the original
266
-			request, e.g. if msg_apply_changes() was used after calling uac_replace_to()  
267
-			</para>
268
-			<para>
269
-				If you create a dialog ( with dlg_manage() ) before calling or uac_replace_to(),
270
-				this avp will not be needed. The values of the uris will be stored as dialog variables.
271
-			</para>
272
-			<para><emphasis>
273
-					Default value of this parameter is empty.
274
-				</emphasis>
275
-			</para>
276
-			<example>
277
-				<title>Set <varname>restore_to_avp</varname> parameter</title>
278
-				<programlisting format="linespecific">
279
-...
280
-modparam("uac","restore_to_avp","$avp(original_uri_to)")
281
-...
282
-				</programlisting>
283
-			</example>
284
-		</section>
285
-		<section id="uac.p.credential">
286
-			<title><varname>credential</varname> (string)</title>
287
-			<para>
288
-			Contains a multiple definition of credentials used to perform
289
-			authentication.
290
-			</para>
291
-			<para>
292
-				<emphasis>
293
-					This parameter is required if UAC authentication is used.
294
-				</emphasis>
295
-			</para>
296
-			<example>
297
-				<title>Set <varname>credential</varname> parameter</title>
298
-				<programlisting format="linespecific">
299
-...
300
-modparam("uac","credential","username:domain:password")
301
-...
302
-				</programlisting>
303
-			</example>
304
-		</section>
305
-		<section id="uac.p.auth-realm-avp-id">
306
-			<title><varname>auth_realm_avp</varname> (string)</title>
307
-			<para>
308
-			The definition of an PV that might contain the realm to be used
309
-			to perform authentication.
310
-			</para>
311
-			<para>
312
-			When the PV value is an empty string or NULL when uac_auth() is called,
313
-			the realm is taken from the reply and only username matching is done.
314
-			This can be used if the realm upstream will be using is not known in advance.
315
-			</para>
316
-			<para><emphasis>
317
-				If you define it, you also need to define 
318
-				<quote>auth_username_avp</quote> 
319
-				(<xref linkend="uac.p.auth-username-avp-id"/>) and 
320
-				<quote>auth_username_avp</quote> 
321
-				(<xref linkend="uac.p.auth-password-avp-id"/>).
322
-			</emphasis></para>
323
-			<example>
324
-				<title>Set <varname>auth_realm_avp</varname> parameter</title>
325
-				<programlisting format="linespecific">
326
-...
327
-modparam("uac","auth_realm_avp","$avp(i:10)")
328
-...
329
-				</programlisting>
330
-			</example>
331
-		</section>
332
-		<section id="uac.p.auth-username-avp-id">
333
-			<title><varname>auth_username_avp</varname> (string)</title>
334
-			<para>
335
-			The definition of an AVP that might contain the username to be used
336
-			to perform authentication.
337
-			</para>
338
-			<para><emphasis>
339
-				If you define it, you also need to define 
340
-				<quote>auth_realm_avp</quote> 
341
-				(<xref linkend="uac.p.auth-realm-avp-id"/>) and 
342
-				<quote>auth_username_avp</quote> 
343
-				(<xref linkend="uac.p.auth-password-avp-id"/>).
344
-			</emphasis></para>
345
-			<example>
346
-				<title>Set <varname>auth_username_avp</varname> parameter</title>
347
-				<programlisting format="linespecific">
348
-...
349
-modparam("uac","auth_username_avp","$avp(i:11)")
350
-...
351
-				</programlisting>
352
-			</example>
353
-		</section>
354
-		<section id="uac.p.auth-password-avp-id">
355
-			<title><varname>auth_password_avp</varname> (string)</title>
356
-			<para>
357
-			The definition of an AVP that might contain the password to be used
358
-			to perform authentication.
359
-			</para>
360
-			<para><emphasis>
361
-				If you define it, you also need to define 
362
-				<quote>auth_password_avp</quote> 
363
-				(<xref linkend="uac.p.auth-password-avp-id"/>) and 
364
-				<quote>auth_username_avp</quote> 
365
-				(<xref linkend="uac.p.auth-password-avp-id"/>).
366
-			</emphasis></para>
367
-			<example>
368
-				<title>Set <varname>auth_password_avp</varname> parameter</title>
369
-				<programlisting format="linespecific">
370
-...
371
-modparam("uac","auth_password_avp","$avp(i:12)")
372
-...
373
-				</programlisting>
374
-			</example>
375
-		</section>
376
-		<section id="uac.p.reg-db-url-id">
377
-			<title><varname>reg_db_url</varname> (string)</title>
378
-			<para>
379
-			DB URL to fetch account profiles for registration.
380
-			</para>
381
-			<example>
382
-				<title>Set <varname>reg_db_url</varname> parameter</title>
383
-				<programlisting format="linespecific">
384
-...
385
-modparam("uac", "reg_db_url",
386
-    "&defaultdb;")
387
-...
388
-				</programlisting>
389
-			</example>
390
-		</section>
391
-
392
-		<section id="uac.p.reg-timer-interval-id">
393
-			<title><varname>reg_timer_interval</varname> (string)</title>
394
-			<para>
395
-			Timer interval (in seconds) at which registrations are managed, e.g. renewed as needed.  
396
-			</para>
397
-			<para>
398
-				<emphasis>
399
-				The default value is 90 seconds.
400
-				</emphasis>
401
-			</para>
402
-			
403
-			<example>
404
-				<title>Set <varname>reg_timer_inteval</varname> parameter</title>
405
-				<programlisting format="linespecific">
406
-...
407
-modparam("uac", "reg_timer_interval", 60)
408
-...
409
-				</programlisting>
410
-			</example>
411
-		</section>
412
-
413
-		<section id="uac.p.reg-retry-interval-id">
414
-			<title><varname>reg_retry_interval</varname> (int)</title>
415
-			<para>
416
-			Failed registration attempts will be retried after this interval
417
-			(in seconds). The interval is not exact, retries may be
418
-			attempted as much as reg_timer_interval secs earlier.
419
-			If set to 0, failed registrations will be disabled permanently.
420
-			</para>
421
-			<para>The default value is 0 sec (disabled)</para>
422
-			<example>
423
-				<title>Set <varname>reg_retry_interval</varname> parameter</title>
424
-				<programlisting format="linespecific">
425
-...
426
-modparam("uac", "reg_retry_interval", 300)
427
-...
428
-				</programlisting>
429
-			</example>
430
-		</section>
431
-
432
-		<section id="uac.p.reg-random-delay-id">
433
-			<title><varname>reg_random_delay</varname> (int)</title>
434
-			<para>
435
-			Set a random reg_delay for each registration that has
436
-			reg_delay set to 0 in the database.
437
-			If set to 0, randomization will be disabled.
438
-			</para>
439
-			<para>The default value is 0 sec (disabled)</para>
440
-			<example>
441
-				<title>Set <varname>reg_random_delay</varname> parameter</title>
442
-				<programlisting format="linespecific">
443
-...
444
-modparam("uac", "reg_random_delay", 300)
445
-...
446
-				</programlisting>
447
-			</example>
448
-		</section>
449
-
450
-		<section id="uac.p.reg-db-table-id">
451
-			<title><varname>reg_db_table</varname> (string)</title>
452
-			<para>
453
-			DB table name to fetch user profiles for registration.
454
-			</para>
455
-			<para>
456
-				<emphasis>
457
-					This parameter is optional, it's default value being
458
-					<quote>uacreg</quote>.
459
-				</emphasis>
460
-			</para>
461
-			<example>
462
-				<title>Set <varname>reg_db_table</varname> parameter</title>
463
-				<programlisting format="linespecific">
464
-...
465
-modparam("uac", "reg_db_table", "uacreg")
466
-...
467
-				</programlisting>
468
-			</example>
469
-		</section>
470
-
471
-		<section id="uac.p.reg-contact-addr-id">
472
-			<title><varname>reg_contact_addr</varname> (string)</title>
473
-			<para>
474
-			Address to be used to build contact address. Must be at least
475
-			host part, can have port and parameters. Must not include 'sip:'.
476
-			The username part of the Contact: URI will be the L_UUID field in the database.
477
-			</para>
478
-			<example>
479
-				<title>Set <varname>reg_contact_addr</varname> parameter</title>
480
-				<programlisting format="linespecific">
481
-...
482
-modparam("uac", "reg_contact_addr", "192.168.1.2:5080")
483
-...
484
-				</programlisting>
485
-			</example>
486
-		</section>
487
-
488
-		<section id="uac.p.reg-keep-callid">
489
-			<title><varname>reg_keep_callid</varname> (string)</title>
490
-			<para>
491
-			If set to 0 (default), a new Call-Id will be generated for each
492
-			registration attempt.
493
-			If set to non-zero, the same Call-Id will be used for
494
-			re-registrations, as recommended by RFC3261 section 10.2.4.
495
-			A new Call-Id will be generated when a previous registration
496
-			had failed.
497
-			</para>
498
-			<example>
499
-				<title>Set <varname>reg_keep_callid</varname> parameter</title>
500
-				<programlisting format="linespecific">
501
-...
502
-modparam("uac", "reg_keep_callid", 1)
503
-...
504
-				</programlisting>
505
-			</example>
506
-		</section>
507
-
508
-	</section>
509
-
510
-	<section>
511
-		<title>Functions</title>
512
-		<section id="uac.f.uac_replace_from">
513
-			<title>
514
-				<function moreinfo="none">uac_replace_from(display,uri)</function>
515
-			</title>
516
-			<para>
517
-			Replace in FROM header the <emphasis>display</emphasis> name and
518
-			the <emphasis>URI</emphasis> part.
519
-			</para>
520
-			<para>
521
-			<emphasis>display</emphasis> and <emphasis>URI</emphasis> parameters
522
-			can include pseudo-variables.
523
-			</para>
524
-			<para>
525
-			This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.
526
-			</para>
527
-			<para>NOTE: Previous versions of this function added double quotes automatically to 
528
-			display variable. That is no longer the case, if you expect that behavior, you will 
529
-			have to add the quotes by yourself.
530
-			</para>
531
-			<para>
532
-			If you set restore_mode to AUTO, the URI will be modified automatically in
533
-			all subsequent requests and replies in that dialog.
534
-			</para>
535
-			<para>
536
-				There are two ways in which the AUTO mode can be achieved.
537
-			</para>
538
-			<para>
539
-				One uses the rr module and appends to the Record-Route header a parameter
540
-				containing some strings from which the original and new URI can be computed.
541
-				The problem with this mode is that it relies on the fact the parties will
542
-				send the Route exactly as it was received. In case there is a change, the
543
-				resulting URIs will not be correct.
544
-			</para>
545
-			<para>
546
-				The other one uses the dialog module to store the original and new URI.
547
-				If you already use dialog module in your configuration, this is the advisable mode.
548
-				All you need to do to use this is to call dlg_manage() before calling uac_replace_from().
549
-				It works by storing the URIs as dialog variables and registering callbacks in dialog 
550
-				module for in dialog requests.
551
-			</para>
552
-			<example>
553
-				<title><function>uac_replace_from</function> usage</title>
554
-				<programlisting format="linespecific">
555
-...
556
-# replace both display and uri
557
-uac_replace_from("$avp(s:display)","$avp(s:uri)");
558
-# replace only display and do not touch uri
559
-uac_replace_from("batman","");   # display is replaced with: batman
560
-uac_replace_from("\"batman\"","");  # display is replaced with: "batman"
561
-# remove display and replace uri
562
-uac_replace_from("","sip:robin@gotham.org");
563
-# remove display and do not touch uri
564
-uac_replace_from("","");
565
-...
566
-				</programlisting>
567
-			</example>
568
-		</section>
569
-		<section id="uac.f.uac_replace_from(uri)">
570
-			<title>
571
-				<function moreinfo="none">uac_replace_from(uri)</function>
572
-			</title>
573
-			<para>
574
-				Replace in FROM header the <emphasis>URI</emphasis> part
575
-				without altering the display name.
576
-			</para>
577
-			<para>
578
-			<emphasis>URI</emphasis> parameter can include pseudo-variables.
579
-			</para>
580
-			<para>
581
-			This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.
582
-			</para>
583
-			<example>
584
-				<title><function>uac_replace_from</function> usage</title>
585
-				<programlisting format="linespecific">
586
-...
587
-uac_replace_from("sip:batman@gotham.org");
588
-...
589
-				</programlisting>
590
-			</example>
591
-		</section>
592
-		<section id="uac.f.uac_restore_from()">
593
-			<title>
594
-				<function moreinfo="none">uac_restore_from()</function>
595
-			</title>
596
-			<para>
597
-			This function will check if the FROM URI was modified and will
598
-			use the information stored in header parameter to restore
599
-			the original FROM URI value.
600
-			</para>
601
-			<para>
602
-			This function can be used from REQUEST_ROUTE.
603
-			</para>
604
-			<example>
605
-				<title><function>uac_restore_from</function> usage</title>
606
-				<programlisting format="linespecific">
607
-...
608
-uac_restore_from();
609
-...
610
-				</programlisting>
611
-			</example>
612
-		</section>
613
-		<section id="uac.f.uac_replace_to(display,uri)">
614
-		<title>
615
-				<function moreinfo="none">uac_replace_to(display,uri)</function>
616
-			</title>
617
-			<para>
618
-			Replace in TO header the <emphasis>display</emphasis> name and
619
-			the <emphasis>URI</emphasis> part.
620
-			</para>
621
-			<para>
622
-			<emphasis>display</emphasis> and <emphasis>URI</emphasis> parameters
623
-			can include pseudo-variables.
624
-			</para>
625
-			<para>
626
-			This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.
627
-			</para>
628
-			<para>NOTE: Previous versions of this function added double quotes automatically to 
629
-			display variable. That is no longer the case, if you expect that behavior, you will 
630
-			have to add the quotes by yourself.
631
-			</para>
632
-			<example>
633
-				<title><function>uac_replace_to</function> usage</title>
634
-				<programlisting format="linespecific">
635
-...
636
-# replace both display and uri
637
-uac_replace_to("$avp(display)","$avp(uri)");
638
-# replace only display and do not touch uri
639
-uac_replace_to("batman","");   # display is replaced with: batman
640
-uac_replace_to("\"batman\"","");  # display is replaced with: "batman"
641
-# remove display and replace uri
642
-uac_replace_to("","sip:robin@gotham.org");
643
-# remove display and do not touch uri
644
-uac_replace_to("","");
645
-...
646
-				</programlisting>
647
-			</example>
648
-		</section>
649
-		<section id="uac.f.uac_replace_to(uri)">
650
-			<title>
651
-				<function moreinfo="none">uac_replace_to(uri)</function>
652
-			</title>
653
-			<para>
654
-				Replace in TO header the <emphasis>URI</emphasis> part
655
-				without altering the display name.
656
-			</para>
657
-			<para>
658
-			<emphasis>URI</emphasis> parameter can include pseudo-variables.
659
-			</para>
660
-			<para>
661
-			This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.
662
-			</para>
663
-			<para>
664
-			If you set restore_mode to AUTO, the URI will be modified automatically in
665
-			all subsequent requests and replies in that dialog.
666
-			</para>
667
-			<para>
668
-				There are two ways in which the AUTO mode can be achieved.
669
-			</para>
670
-			<para>
671
-				One uses the rr module and appends to the Record-Route header a parameter
672
-				containing some strings from which the original and new URI can be computed.
673
-				The problem with this mode is that it relies on the fact the parties will
674
-				send the Route exactly as it was received. In case there is a change, the
675
-				resulting URIs will not be correct.
676
-			</para>
677
-			<para>
678
-				The other one uses the dialog module to store the original and new URI.
679
-				If you already use dialog module in your configuration, this is the advisable mode.
680
-				All you need to do to use this is to call dlg_manage() before calling uac_replace_to().
681
-				It works by storing the URIs as dialog variables and registering callbacks in dialog 
682
-				module for in dialog requests.
683
-			</para>
684
-
685
-			<example>
686
-				<title><function>uac_replace_to</function> usage</title>
687
-				<programlisting format="linespecific">
688
-...
689
-uac_replace_to("sip:batman@gotham.org");
690
-...
691
-				</programlisting>
692
-			</example>
693
-		</section>
694
-		<section id="uac.f.uac_restore_to()">
695
-			<title>
696
-				<function moreinfo="none">uac_restore_to()</function>
697
-			</title>
698
-			<para>
699
-			This function will check if the TO URI was modified and will
700
-			use the information stored in header parameter to restore
701
-			the original TO URI value.
702
-			</para>
703
-			<para>
704
-			This function can be used from REQUEST_ROUTE.
705
-			</para>
706
-			<example>
707
-				<title><function>uac_restore_to</function> usage</title>
708
-				<programlisting format="linespecific">
709
-...
710
-uac_restore_to();
711
-...
712
-				</programlisting>
713
-			</example>
714
-		</section>
715
-		<section id="uac.f.uac_auth()">
716
-			<title>
717
-				<function moreinfo="none">uac_auth()</function>
718
-			</title>
719
-			<para>
720
-			This function can be called only from failure route and will 
721
-			build the authentication response header and insert it into the
722
-			request without sending anything.
723
-			</para>
724
-			<para>
725
-			This function can be used from FAILURE_ROUTE.
726
-			</para>
727
-			<example>
728
-				<title><function>uac_auth</function> usage</title>
729
-				<programlisting format="linespecific">
730
-...
731
-modparam("uac","auth_username_avp","$avp(auser)")
732
-modparam("uac","auth_password_avp","$avp(apass)")
733
-modparam("uac","auth_realm_avp","$avp(arealm)")
734
-
735
-request_route {
736
-   ...
737
-   if(is_method("INVITE")) {
738
-      t_on_failure("TRUNKAUTH");
739
-   }
740
-   ...
741
-}
742
-
743
-failure_route[TRUNKAUTH] {
744
-
745
-    if (t_is_canceled()) {
746
-        exit;
747
-    }
748
-    if(t_check_status("401|407")) {
749
-        $avp(auser) = "test";
750
-        $avp(apass) = "test";
751
-        uac_auth();
752
-        t_relay();
753
-        exit;
754
-    }
755
-}
756
-...
757
-				</programlisting>
758
-			</example>
759
-		</section>
760
-		<section id="uac.f.uac_req_send()">
761
-			<title>
762
-				<function moreinfo="none">uac_req_send()</function>
763
-			</title>
764
-			<para>
765
-			This function sends a SIP message from the configuration file.
766
-			The message is built out of $uac_req(...) pseudo-variable.
767
-			</para>
768
-			<para>
769
-			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
770
-			BRANCH_ROUTE, ONREPLY_ROUTE, LOCAL_ROUTE.
771
-			</para>
772
-			<example>
773
-				<title><function>uac_req_send</function> usage</title>
774
-				<programlisting format="linespecific">
775
-...
776
-$uac_req(method)="OPTIONS";
777
-$uac_req(ruri)="sip:kamailio.org";
778
-$uac_req(furi)="sip:kamailio.org";
779
-$uac_req(turi)="sip:kamailio.org";
780
-$uac_req(callid)=$(mb{s.md5});
781
-uac_req_send();
782
-...
783
-				</programlisting>
784
-			</example>
785
-		</section>
786
-		<section id="uac.f.uac_reg_lookup(uuid, dst)">
787
-			<title>
788
-				<function moreinfo="none">uac_reg_lookup(uuid, dst)</function>
789
-			</title>
790
-			<para>
791
-			This function sets the PV dst to SIP URI that correspond to uuid
792
-			in uac registations table. uuid and dst must be pseudo-variables.
793
-			</para>
794
-			<para>
795
-			This function can be used from ANY_ROUTE.
796
-			</para>
797
-			<example>
798
-				<title><function>uac_reg_lookup</function> usage</title>
799
-				<programlisting format="linespecific">
800
-...
801
-
802
-if(uac_reg_lookup("$rU", "$ru"))
803
-{
804
-    lookup("location");
805
-}
806
-...
807
-				</programlisting>
808
-			</example>
809
-		</section>
810
-		<section id="uac.f.uac_reg_status(uuid)">
811
-			<title>
812
-				<function moreinfo="none">uac_reg_status(uuid)</function>
813
-			</title>
814
-			<para>
815
-			This function returns the current registration status for the uuid.
816
-			</para>
817
-			<para>
818
-			Return values:
819
-			<itemizedlist>
820
-			<listitem>
821
-				<para>
822
-				1 - a valid registration exists.
823
-				</para>
824
-			</listitem>
825
-			<listitem>
826
-				<para>
827
-				-1 - uuid does not exist or an error occurred while executing
828
-				the function.
829
-				</para>
830
-			</listitem>
831
-			<listitem>
832
-				<para>
833
-				-2 - a registration attempt is ongoing (and currently there is
834
-				no valid registration).
835
-				</para>
836
-			</listitem>
837
-			<listitem>
838
-				<para>
839
-				-3 - registration is disabled.
840
-				</para>
841
-			</listitem>
842
-			<listitem>
843
-				<para>
844
-				-99 - no valid registration, waiting for new registration attempt.
845
-				</para>
846
-			</listitem>
847
-			</itemizedlist>
848
-			</para>
849
-			<para>
850
-			This function can be used from ANY_ROUTE.
851
-			</para>
852
-			<example>
853
-				<title><function>uac_reg_status</function> usage</title>
854
-				<programlisting format="linespecific">
855
-...
856
-$var(status) = uac_reg_status("$rU");
857
-...
858
-				</programlisting>
859
-			</example>
860
-		</section>
861
-		<section id="uac.f.uac_reg_request_to(user, mode)">
862
-			<title>
863
-				<function moreinfo="none">uac_reg_request_to(user, mode)</function>
864
-			</title>
865
-			<para>
866
-			This function can be used to send an authenticated request to a remote user in 
867
-			the uac registrations table. It sets the request-uri, dst-uri and auth_*_avp
868
-			pv's to the values that correspond to the supplied user.
869
-			</para>
870
-			<para>
871
-			The mode indicates whether the user should match the local uuid (mode=0), or the username (mode=1).
872
-			</para>
873
-			<para>
874
-			The auth_*_avp module parameters must be set to valid pv&apos;s.
875
-			</para>
876
-			<para>
877
-			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
878
-			</para>
879
-			<example>
880
-				<title><function>uac_reg_request_to</function> usage</title>
881
-				<programlisting format="linespecific">
882
-...
883
-
884
-if(uac_reg_request_to("$fU", 0))
885
-{
886
-	xlog("L_NOTICE", "Found remote user [$rU] on [$rd] via [$du]");
887
-	t_on_failure("REMOTE_AUTH");
888
-
889
-	t_relay()
890
-}
891
-...
892
-failure_route[REMOTE_AUTH] {
893
-	if ($T_reply_code == 401 or $T_reply_code == 407) {
894
-		xlog("L_NOTICE", "Remote asked for authentication");
895
-		uac_auth()
896
-	}
897