4ce4a6b99558bc5c263b947d1d3ba26f5c76a143
[sip-router] / src / modules / registrar / doc / registrar_admin.xml
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 "../../../../doc/docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter>
13         
14         <title>&adminguide;</title>
15         
16         <section id="rergistrar.overview">
17         <title>Overview</title>
18         <para>The module contains REGISTER processing logic. The actual location
19                 database is managed by the USRLOC module.
20         </para>
21         <section>
22                 <title>PATH support</title>
23                 <para>
24                 The Register module includes Path support (according to RFC 3327) 
25                 for usage in registrars and home-proxies.
26                 </para>
27                 <para>
28                 If path support is enabled in the registrar module, a call to save(...)
29                 stores the values of the Path Header(s) along with the contact into usrloc. 
30                 There are three modes regarding the reply to a REGISTER including
31                 one or more Path HFs:
32                 </para>
33                 <itemizedlist>
34                         <listitem>
35                         <para>
36                                 <emphasis>off</emphasis> - stores the value of the 
37                                 Path headers into usrloc without passing it back to 
38                                 the UAC in the reply.
39                         </para>
40                         </listitem>
41                         <listitem>
42                         <para>
43                                 <emphasis>lazy</emphasis> - stores the Path header and 
44                                 passes it back to the UAC if Path-support is indicated 
45                                 by the <quote>path</quote> param in the Supported HF.
46                         </para>
47                         </listitem>
48                         <listitem>
49                         <para>
50                                 <emphasis>strict</emphasis> - rejects the registration 
51                                 with <quote>420 Bad Extension</quote> if there's a Path 
52                                 header but no support for it is indicated by the UAC. 
53                                 Otherwise it's stored and passed back to the UAC.
54                         </para>
55                         </listitem>
56                 </itemizedlist>
57                 <para>
58                 A call to lookup(...) always uses the path header if
59                 found, and inserts it as Route HF either in front of
60                 the first Route HF, or after the last Via HF if no
61                 Route is present. It also sets the destination uri to
62                 the first Path uri, thus overwriting the received-uri,
63                 because NAT has to be handled at the outbound-proxy of
64                 the UAC (the first hop after client's NAT).
65                 </para>
66                 <para>
67                 The whole process is transparent to the user, so no
68                 config changes are required beside setting the
69                 registrar-parameters <quote>use_path</quote> and 
70                 <quote>path_mode</quote>.
71                 </para>
72         </section>
73         <section>
74                 <title>GRUU Support</title>
75                 <para>
76                         GRUU (RFC5627) is supported with both public and temporary
77                         addresses.
78                 </para>
79                 <para>
80                         The public GRUU is build based on the '+sip.instance'
81                         UUID parameter as recommended by RFC.
82                 </para>
83                 <para>
84                         The temporary GRUU is built based on internal SRUID (unique
85                         id generator) and it is kept the same for the duration of
86                         contact validity.
87                 </para>
88         </section>
89         
90         </section>
91
92
93         <section>
94         <title>Dependencies</title>
95         <section>
96                 <title>&kamailio; Modules</title>
97                 <para>
98                 The following modules must be loaded before this module:
99                         <itemizedlist>
100                         <listitem>
101                         <para>
102                                 <emphasis>usrloc - User Location Module</emphasis>.
103                         </para>
104                         </listitem>
105                         <listitem>
106                         <para>
107                                 <emphasis>sl - Stateless Replies</emphasis>.
108                         </para>
109                         </listitem>
110                         </itemizedlist>
111                 </para>
112         </section>
113         <section>
114                 <title>External Libraries or Applications</title>
115                 <para>
116                 The following libraries or applications must be installed before 
117                 running &kamailio; with this module loaded:
118                         <itemizedlist>
119                         <listitem>
120                         <para>
121                                 <emphasis>None</emphasis>.
122                         </para>
123                         </listitem>
124                         </itemizedlist>
125                 </para>
126         </section>
127         </section>
128         <section>
129         <title>Parameters</title>
130         <section id="registrar.p.default_expires">
131                 <title><varname>default_expires</varname> (integer)</title>
132                 <para>
133                 If the processed message contains neither Expires 
134                 <acronym>HFs</acronym> nor expires contact parameters, this value 
135                 will be used for newly created usrloc records. The parameter contains 
136                 number of second to expire (for example use 3600 for one hour). If it
137                 is set to a lower value than the <quote>min_expires</quote> parameter
138                 then it will be ignored. This parameter can be modified via ser config framework.
139                 A random value in a specific interval can be selected by using the default_expires_range
140                 parameter
141                 </para>
142                 <para>
143                 <emphasis>
144                         Default value is 3600.
145                 </emphasis>
146                 </para>
147                 <example>
148                 <title>Set <varname>default_expires</varname> parameter</title>
149                 <programlisting format="linespecific">
150 ...
151 modparam("registrar", "default_expires", 1800)
152 ...
153 </programlisting>
154                 </example>
155         </section>
156         <section id="registrar.p.default_expires_range">
157                 <title><varname>default_expires_range</varname> (integer)</title>
158                 <para>
159                 This parameter specifies that the expiry used for newly created usrloc records
160                 are not fixed, but a random value in the interval <quote>[default_expires-default_expires_range%, default_expires]</quote>.
161                 The value is between 0 and 100 and represent the maximum percentage from expires that
162                 will be subtracted when computing the value. Default is 0, meaning default_expires
163                 is left unmodified. This parameter can be modified via the &kamailio; config framework.
164                 </para>
165                 <para>
166                 <emphasis>
167                         Default value is 0.
168                 </emphasis>
169                 </para>
170                 <example>
171                 <title>Set <varname>default_expires_range</varname> parameter</title>
172                 <programlisting format="linespecific">
173 ...
174 modparam("registrar", "default_expires_range", 30) # +- 30% from default_expires
175 ...
176 </programlisting>
177                 </example>
178         </section>
179         <section id="registrar.p.expires_range">
180                 <title><varname>expires_range</varname> (integer)</title>
181                 <para>
182                 Similar to default_expires_range, but it applies to the incoming expires
183                 value. Default in 0, meaning the expires is left unmodified. 
184                 This parameter can be modified via the &kamailio; config framework.
185                 </para>
186                 <para>
187                 <emphasis>
188                         Default value is 0.
189                 </emphasis>
190                 </para>
191                 <example>
192                 <title>Set <varname>expires_range</varname> parameter</title>
193                 <programlisting format="linespecific">
194 ...
195 modparam("registrar", "expires_range", 30) # expires within [0.7*expires .. expires]
196 ...
197 </programlisting>
198                 </example>
199         </section>
200
201         <section id="registrar.p.min_expires">
202                 <title><varname>min_expires</varname> (integer)</title>
203                 <para>
204                 The minimum expires value of a <quote>Contact</quote>. Values lower than this 
205                 minimum will be automatically set to the minimum. Value 0 disables 
206                 the checking. This parameter can be modified via the &kamailio; config framework.
207                 </para>
208                 <para>
209                 <emphasis>
210                         Default value is 60.
211                 </emphasis>
212                 </para>
213                 <example>
214                 <title>Set <varname>min_expires</varname> parameter</title>
215                 <programlisting format="linespecific">
216 ...
217 modparam("registrar", "min_expires", 60)
218 ...
219 </programlisting>
220                 </example>
221         </section>
222         <section id="registrar.p.max_expires">
223                 <title><varname>max_expires</varname> (integer)</title>
224                 <para>
225                 The maximum accepted expires value of a <quote>Contact</quote>, values higher than this 
226                 maximum will be automatically set to the maximum. Value 0 disables 
227                 the checking. This parameter can be modified via the &kamailio; config framework.
228                 </para>
229                 <para>
230                 <emphasis>
231                         Default value is 0.
232                 </emphasis>
233                 </para>
234                 <example>
235                 <title>Set <varname>max_expires</varname> parameter</title>
236                 <programlisting format="linespecific">
237 ...
238 modparam("registrar", "max_expires", 120)
239 ...
240 </programlisting>
241                 </example>
242         </section>
243
244         <section id="registrar.p.default_q">
245                 <title><varname>default_q</varname> (integer)</title>
246                 <para>
247                 The parameter represents default <quote>q</quote> value for new contacts. Because 
248                 &kamailio; doesn't support float parameter types, the value in the parameter 
249                 is divided by 1000 and stored as float. For example, if you want 
250                 default_q to be 0.38, use value 380 here. This parameter can be modified via 
251                 the &kamailio; config framework.
252                 </para>
253                 <para>
254                 <emphasis>
255                         Default value is 0.
256                 </emphasis>
257                 </para>
258                 <example>
259                 <title>Set <varname>default_q</varname> parameter</title>
260                 <programlisting format="linespecific">
261 ...
262 modparam("registrar", "default_q", 1000)
263 ...
264 </programlisting>
265                 </example>
266         </section>
267
268         <section id="registrar.p.realm_prefix">
269                 <title><varname>realm_prefix</varname> (string)</title>
270                 <para>
271                  Prefix to be automatically stripped from realm. As an alternative to 
272                  SRV records (not all SIP clients support SRV lookup), a subdomain of 
273                  the master domain can be defined for SIP purposes (like 
274                  sip.mydomain.net pointing to same IP address as the SRV record for 
275                  mydomain.net). By ignoring the realm_prefix "sip.", at registration,
276                  sip.mydomain.net will be equivalent to mydomain.net. This parameter 
277                  can be modified via the &kamailio; config framework.
278                 </para>
279                 <para>
280                 <emphasis>
281                         Default value is NULL (none).
282                 </emphasis>
283                 </para>
284                 <example>
285                 <title>Set <varname>realm_prefix</varname> parameter</title>
286                 <programlisting format="linespecific">
287 ...
288 modparam("registrar", "realm_prefix", "sip.")
289 ...
290 </programlisting>
291                 </example>
292         </section>
293
294
295         <section>
296                 <title><varname>append_branches</varname> (integer)</title>
297                 <para>
298                 The parameter controls how lookup function processes multiple 
299                 contacts.  If there are multiple contacts for the given username in 
300                 usrloc and this parameter is set to 1, Request-URI will be 
301                 overwritten with the highest-q rated contact and the rest will be 
302                 appended to sip_msg structure and can be later used by tm for forking.
303                 If the parameter is set to 0, only Request-URI will be overwritten 
304                 with the highest-q rated contact and the rest will be left unprocessed.
305                 This parameter can be modified via &kamailio; config framework.
306                 </para>
307                 <para>
308                 <emphasis>
309                         Default value is 1.
310                 </emphasis>
311                 </para>
312                 <example>
313                 <title>Set <varname>append_branches</varname> parameter</title>
314                 <programlisting format="linespecific">
315 ...
316 modparam("registrar", "append_branches", 0)
317 ...
318 </programlisting>
319                 </example>
320         </section>
321
322         <section id="registrar.p.aor_avp">
323                 <title><varname>aor_avp</varname> (str)</title>
324                 <para>
325                 This module parameter has been removed. Use the 'uri' parameter from
326                 functions (e.g., save, lookup, registered).
327                 </para>
328         </section>
329
330         <section id="registrar.p.case_sensitive">
331                 <title><varname>case_sensitive</varname> (integer)</title>
332                 <para>
333                 If set to 1 then <acronym>AOR</acronym> comparison and also
334                 storing will be case sensitive, if set to 0 then <acronym>AOR</acronym>
335                 comparison and storing will be case insensitive. This is recommended.
336                 This parameter can be modified via &kamailio; config framework.
337                 </para>
338                 <para>
339                 <emphasis>
340                         Default value is 0.
341                 </emphasis>
342                 </para>
343                 <example>
344                 <title>Set <varname>case_sensitive</varname> parameter</title>
345                 <programlisting format="linespecific">
346 ...
347 modparam("registrar", "case_sensitive", 1)
348 ...
349 </programlisting>
350                 </example>
351         </section>
352
353         <section id="registrar.p.received_avp">
354                 <title><varname>received_avp</varname> (str)</title>
355                 <para>
356                 Registrar will store the value of the AVP configured by this 
357                 parameter in the received column in the user location database. 
358                 It will leave the column empty if the AVP is empty. The AVP should 
359                 contain a SIP URI consisting of the source IP, port,
360                 and transport protocol of the REGISTER message being processed.
361                 </para>
362                 <note>
363                 <para>
364                         The value of this parameter should be the same as the value of 
365                         corresponding parameter of nathelper module.
366                 </para>
367                 </note>
368                 <para>
369                 <emphasis>
370                         Default value is "NULL" (disabled).
371                 </emphasis>
372                 </para>
373                 <example>
374                 <title>Set <varname>received_avp</varname> parameter</title>
375                 <programlisting format="linespecific">
376 ...
377 modparam("registrar", "received_avp", "$avp(s:rcv)")
378 ...
379 </programlisting>
380                 </example>
381         </section>
382
383         <section id="registrar.p.received_param">
384                 <title><varname>received_param</varname> (string)</title>
385                 <para>
386                 The name of the parameter that will be appended to Contact URI's of 
387                 200 OK when the received URI was set by the <quote>nathelper</quote> module. If the
388                 value is an empty string, then the parameter is not appended anymore.
389                 </para>
390                 <para>
391                 <emphasis>
392                         Default value is "received".
393                 </emphasis>
394                 </para>
395                 <example>
396                 <title>Set <varname>received_param</varname> parameter</title>
397                 <programlisting format="linespecific">
398 ...
399 modparam("registrar", "received_param", "rcv")
400 ...
401 </programlisting>
402                 </example>
403         </section>
404
405         <section id="registrar.p.max_contacts">
406                 <title><varname>max_contacts</varname> (integer)</title>
407                 <para>
408                 The parameter can be used to limit the number of contacts per 
409                 AOR (Address of Record) in the user location database.
410                 If the maximum number of contacts is exceeded, &kamailio; will not
411                 accept the registration and send an error response. 
412                 Value 0 disables the check. This parameter can be modified via 
413                 the &kamailio; config framework.
414                 (Please also check the flag for <function>save()</function> if you only want
415                 only one active registration).
416                 </para>
417                 <para>
418                 <emphasis>
419                         Default value is 0.
420                 </emphasis>
421                 </para>
422                 <example>
423                 <title>Set <varname>max_contacts</varname> parameter</title>
424                 <programlisting format="linespecific">
425 ...
426 # Allow no more than 10 contacts per AOR
427 modparam("registrar", "max_contacts", 10)
428 ...
429                 </programlisting>
430                 </example>
431         </section>
432
433         <section id="registrar.p.retry_after">
434                 <title><varname>retry_after</varname> (integer)</title>
435                 <para>
436                 The registrar can generate a 5xx reply to REGISTER requests in various 
437                 situations. It can, for example, happen when the 
438                 <varname>max_contacts</varname> parameter is set and the
439                 processing of REGISTER request would exceed the limit. In this case 
440                 the registrar would generate "503 Service Unavailable" response.
441                 This parameter can be modified via the &kamailio; config framework.
442                 </para>
443                 <para>
444                 If you want to add the Retry-After header field in 5xx replies, set 
445                 this parameter to a value grater than zero (0 means do not add the 
446                 header field). See section 20.33 of RFC3261 for more details.
447                 </para>
448                 <para>
449                 <emphasis>
450                         Default value is 0 (disabled).
451                 </emphasis>
452                 </para>
453                 <example>
454                 <title>Set <varname>retry_after</varname> parameter</title>
455                 <programlisting format="linespecific">
456 ...
457 modparam("registrar", "retry_after", 30)
458 ...
459                 </programlisting>
460                 </example>
461         </section>
462
463         <section id="registrar.p.sock_flag">
464                 <title><varname>sock_flag</varname> (integer)</title>
465                 <para>
466                 Message flag to signal to the registrar module to look into REGISTER 
467                 request for a header which contains a socket description (IP:port). 
468                 This socket info will be stored by registrar instead of the received 
469                 socket info.
470                 </para>
471                 <para>
472                 This makes sense only in multiple replicated servers scenarios.
473                 </para>
474                 <para>
475                 <emphasis>
476                         Default value is -1 (no flag).
477                 </emphasis>
478                 </para>
479                 <example>
480                 <title>Set <varname>sock_flag</varname> parameter</title>
481                 <programlisting format="linespecific">
482 ...
483 modparam("registrar", "sock_flag", 18)
484 ...
485                 </programlisting>
486                 </example>
487         </section>
488
489         <section id="registrar.p.sock_hdr_name">
490                 <title><varname>sock_hdr_name</varname> (string)</title>
491                 <para>
492                 Header which contains a socket description (proto:IP:port) to override
493                 the received socket info. The header will be read only if the
494                 flag sock_flag is set.
495                 </para>
496                 <para>
497                 This makes sense only in multiple replicated servers scenarios.
498                 </para>
499                 <para>
500                 <emphasis>
501                         Default value is NULL.
502                 </emphasis>
503                 </para>
504                 <example>
505                 <title>Set <varname>sock_hdr_name</varname> parameter</title>
506                 <programlisting format="linespecific">
507 ...
508 modparam("registrar", "sock_hdr_name", "Sock-Info")
509 ...
510                 </programlisting>
511                 </example>
512         </section>
513
514         <section id="registrar.p.method_filtering">
515                 <title><varname>method_filtering</varname> (integer)</title>
516                 <para>
517                 Tells if the contact filtering based on supported methods should be
518                 performed during lookup on initial requests without to-tag.
519         It's enabled only if it has a non zero 
520                 value. Supported methods are listed in the <quote>Allow:</quote> 
521                 header in the REGISTER message and stored in the location database.
522                 </para>
523                 <para>
524                 <emphasis>
525                         Default value is 0 (disabled).
526                 </emphasis>
527                 </para>
528                 <example>
529                 <title>Set <varname>method_filtering</varname> parameter</title>
530                 <programlisting format="linespecific">
531 ...
532 modparam("registrar", "method_filtering", 1)
533 ...
534                 </programlisting>
535                 </example>
536         </section>
537
538         <section id="registrar.p.use_path">
539                 <title><varname>use_path</varname> (integer)</title>
540                 <para>
541                 If set to 1, the <quote>Path:</quote> header is handled according to the parameter 
542                 This parameter can be modified via &kamailio; config framework.
543                 <quote>path_mode</quote>.
544                 </para>
545                 <para>
546                 <emphasis>
547                         Default value is 0 (disabled).
548                 </emphasis>
549                 </para>
550                 <example>
551                 <title>Set <varname>use_path</varname> parameter</title>
552                 <programlisting format="linespecific">
553 ...
554 modparam("registrar", "use_path", 1)
555 ...
556                 </programlisting>
557                 </example>
558         </section>
559
560         <section id="registrar.p.path_mode">
561                 <title><varname>path_mode</varname> (integer)</title>
562                 <para>
563                 The registrar module implements three different modes regarding the 
564                 response to a registration which includes one or more Path headers:
565                 </para>
566                 <itemizedlist>
567                 <listitem>
568                         <para>
569                         0 - The Path header is saved into usrloc, but is not included in 
570                         the reply.
571                         </para>
572                 </listitem>
573                 <listitem>
574                         <para>
575                         1 - The Path header is saved into usrloc, but is only included in 
576                         the reply if path support is indicated in the registration request 
577                         by the <quote>path</quote> option in the 
578                         <quote>Supported:</quote> header.
579                         </para>
580                 </listitem>
581                 <listitem>
582                         <para>
583                         2 - The path header is only saved into usrloc, if path support is 
584                         indicated in the registration request by the <quote>path</quote> 
585                         option of the <quote>Supported</quote> header. If no path support 
586                         is indicated, the request is rejected with 
587                         <quote>420 - Bad Extension</quote> and the header 
588                         <quote>Unsupported: path</quote> is included in the reply along 
589                         with the received <quote>Path</quote> header. This mode is the 
590                         one recommended by RFC-3327.
591                         </para>
592                 </listitem>
593                 </itemizedlist>
594                 <para>
595                 <emphasis>
596                         Default value is 2.
597                 </emphasis>
598                 </para>
599                 <example>
600                 <title>Set <varname>path_mode</varname> parameter</title>
601                 <programlisting format="linespecific">
602 ...
603 modparam("registrar", "path_mode", 0)
604 ...
605                 </programlisting>
606                 </example>
607         </section>
608
609         <section id="registrar.p.path_use_received">
610                 <title><varname>path_use_received</varname> (integer)</title>
611                 <para>
612                 If set to 1, the <quote>received</quote> parameter of the first Path 
613                 URI of a registration is set as received-uri and the NAT branch flag is
614                 set for this contact. This is useful if the registrar is placed
615                 behind a SIP loadbalancer, which passes the nat'ed UAC address as 
616                 <quote>received</quote> parameter
617                 in it's Path uri.
618                 </para>
619                 <para>
620                 <emphasis>
621                         Default value is 0 (disabled).
622                 </emphasis>
623                 </para>
624                 <example>
625                 <title>Set <varname>path_use_received</varname> parameter</title>
626                 <programlisting format="linespecific">
627 ...
628 modparam("registrar", "path_use_received", 1)
629 ...
630                 </programlisting>
631                 </example>
632         </section>
633
634         <section id="registrar.p.path_check_local">
635                 <title><varname>path_check_local</varname> (integer)</title>
636                 <para>
637                 If set to 1, when performing a lookup the Path (if present) is evaluated
638                 and if the first hop is local (according to <quote>myself</quote> test), we
639                 skip it to avoid unnecessary looping.
640                 </para>
641                 <para>
642                 This is useful if multiple servers are sharing a common location database,
643                 each saving contacts with their local address as the Path.
644                 </para>
645                 <para>
646                 <emphasis>
647                 Default value is 0 (disabled).
648                 </emphasis>
649                 </para>
650                 <example>
651                 <title>Set <varname>path_check_local</varname> parameter</title>
652                 <programlisting format="linespecific">
653 ...
654 modparam("registrar", "path_check_local", 1)
655 ...
656                 </programlisting>
657                 </example>
658         </section>
659
660         <section id="registrar.p.reg_callid_avp">
661                 <title><varname>reg_callid_avp</varname> (string)</title>
662                 <para>
663                         <emphasis>
664                                 obsolete. use match_option in registered function
665                         </emphasis>
666                 </para>
667                 <para>
668                 If reg_callid_avp is defined and populated when the
669                 <function>registered()</function> is invoked, the result is 
670                 TRUE only if an active registration with
671                 the specified callID is found.
672                 </para>
673                 <para>
674                 <emphasis>
675                         Default value is NULL (disabled).
676                 </emphasis>
677                 </para>
678                 <example>
679                 <title>Set <varname>reg_callid_avp</varname> parameter</title>
680                 <programlisting format="linespecific">
681 ...
682 modparam("registrar", "reg_callid_avp", "$avp(s:avp)")
683 ...
684                 </programlisting>
685                 </example>
686         </section>
687
688         <section id="registrar.p.xavp_cfg">
689                 <title><varname>xavp_cfg</varname> (string)</title>
690                 <para>
691                         Defines the name of XAVP class to store runtime module config
692                         values. The values are stored as inner XAVPs, like
693                         $xavp(class=&gt;attribute). Valid inner XAVP names:
694                 </para>
695                 <itemizedlist>
696                 <listitem>
697                         <para>
698                                 <emphasis>max_contacts</emphasis> - the number of maximum
699                                 contacts to be stored for the current registration AoR. It
700                                 overwrites the 'max_contacts' module parameter value.
701                         </para>
702                 </listitem>
703                 <listitem>
704                         <para>
705                                 <emphasis>socket</emphasis> - the string representing the
706                                 socket on which the register request was received, as alternative
707                                 to using the sock_hdr.
708                         </para>
709                 </listitem>
710                 <listitem>
711                         <para>
712                                 <emphasis>q</emphasis> - q value of contact
713                                 (integer 0-1000). It
714                                 overrides q value given in contact header and
715                                 default_q parameter.
716                         </para>
717                 </listitem>
718                 </itemizedlist>
719                 <para>
720                         For example. if this parameter is set to 'reg', then the number
721                         of maximum contacts can be set in $xavp(reg=&gt;max_contacts).
722                 </para>
723                 <para>
724                 <emphasis>
725                         Default value is NULL (disabled).
726                 </emphasis>
727                 </para>
728                 <example>
729                 <title>Set <varname>xavp_cfg</varname> parameter</title>
730                 <programlisting format="linespecific">
731 ...
732 modparam("registrar", "xavp_cfg", "reg")
733 ...
734 request_route {
735     ...
736     $xavp(reg=&gt;max_contacts) = 4;
737     save("location");
738     ...
739 }
740 ...
741                 </programlisting>
742                 </example>
743         </section>
744
745         <section id="registrar.p.xavp_rcd">
746                 <title><varname>xavp_rcd</varname> (string)</title>
747                 <para>
748                         Defines the name of XAVP class to store details from the
749                         location records. The values are stored as inner XAVPs, like
750                         $xavp(class[0]=&gt;attribute). Valid inner XAVP names:
751                 </para>
752                 <itemizedlist>
753                 <listitem>
754                         <para>
755                                 <emphasis>ruid</emphasis> - the record's internal unique
756                                 id.
757                         </para>
758                 </listitem>
759                 <listitem>
760                         <para>
761                                 <emphasis>contact</emphasis> - the record's contact value.
762                         </para>
763                 </listitem>
764                 <listitem>
765                         <para>
766                                 <emphasis>expires</emphasis> - the record's expires value.
767                         </para>
768                 </listitem>
769                 <listitem>
770                         <para>
771                                 <emphasis>received</emphasis> - the record's received value.
772                         </para>
773                 </listitem>
774                 </itemizedlist>
775                 <para>
776                         For example. if this parameter is set to 'ulrcd', then values are set in:
777                 </para>
778                 <itemizedlist>
779                 <listitem>
780                         <para><emphasis>$xavp(ulrcd[0]=&gt;ruid)</emphasis></para>
781                 </listitem>
782                 <listitem>
783                         <para><emphasis>$xavp(ulrcd[0]=&gt;contact)</emphasis></para>
784                 </listitem>
785                 <listitem>
786                         <para><emphasis>$xavp(ulrcd[0]=&gt;received)</emphasis></para>
787                 </listitem>
788                 </itemizedlist>
789                 <para>
790                 <emphasis>
791                         Default value is NULL (disabled).
792                 </emphasis>
793                 </para>
794                 <example>
795                 <title>Set <varname>xavp_rcd</varname> parameter</title>
796                 <programlisting format="linespecific">
797 ...
798 modparam("registrar", "xavp_rcd", "ulrcd")
799 ...
800                 </programlisting>
801                 </example>
802         </section>
803
804         <section id="registrar.p.gruu_enabled">
805                 <title><varname>gruu_enabled</varname> (integer)</title>
806                 <para>
807                 If set to 1 and the <quote>+sip.instance</quote> parameter to
808                 Contact header of REGISTER is present, then the value of the
809                 parameter is saved to location and pub-gruu and temp-gruu addresses
810                 are generated.
811                 </para>
812                 <para>
813                 Set it to 0 if you want to ignore GRUU extensions in REGISTER.
814                 </para>
815                 <para>
816                 <emphasis>
817                         Default value is 1 (enabled).
818                 </emphasis>
819                 </para>
820                 <example>
821                 <title>Set <varname>gruu_enabled</varname> parameter</title>
822                 <programlisting format="linespecific">
823 ...
824 modparam("registrar", "gruu_enabled", 0)
825 ...
826                 </programlisting>
827                 </example>
828         </section>
829
830         <section id="registrar.p.outbound_mode">
831                 <title><varname>outbound_mode</varname> (integer)</title>
832                 <para>
833                 If set to 0 this module will accept REGISTER requests that do
834                 not contain a <quote>Supported:</quote> header with the outbound options-tag.
835                 The 200 OK response to REGISTER requests that this module
836                 generates will not contain <quote>Require:</quote> or 
837                 <quote>Supported:</quote> headers with
838                 the outbound options-tag. If the client has a <quote>Require:</quote> header
839                 with the outbound options tag the REGISTER will be rejected
840                 with a <quote>420 Bad Extension</quote> response.
841                 </para>
842                 <para>
843                 If set to 1 this module will accept REGISTER requests that
844                 do not contain a <quote>Supported:</quote> header with the outbound
845                 options-tag and REGISTER requests that do contain a Supported:
846                 or Requires: header with the outbound options-tag. When the
847                 client supports <emphasis>outbound</emphasis> the appropriate
848                 RFC5626 procedures will be followed.
849                 </para>
850                 <para>
851                 If set to 2 this module will reject REGISTER requests that
852                 do not contain a <quote>Supported:</quote> header with the outbound
853                 options-tag. When the client supports outbound the appropriate
854                 RFC5626 procedures will be followed.
855                 </para>
856                 <para>
857                 <emphasis>
858                         Default value is 0.
859                 </emphasis>
860                 </para>
861                 <example>
862                 <title>Set <varname>outbound_mode</varname> parameter</title>
863                 <programlisting format="linespecific">
864 ...
865 modparam("registrar", "outbound_mode", 2)
866 ...
867                 </programlisting>
868                 </example>
869         </section>
870
871         <section id="registrar.p.regid_mode">
872                 <title><varname>regid_mode</varname> (integer)</title>
873                 <para>
874                 If set to 0 this module will ignore the <quote>regid</quote> contact param
875                 when saving REGISTER request if the request does not
876                 indicate support for outbound.
877                 </para>
878                 <para>
879                 If set to 1 this module will use <quote>regid</quote> contact param
880                 (if present) when saving REGISTER request even if 
881                 REGISTER request does not indicate support for outbound.
882                 </para>
883                 <para>
884                 <emphasis>
885                         Default value is 0.
886                 </emphasis>
887                 </para>
888                 <example>
889                 <title>Set <varname>regid_mode</varname> parameter</title>
890                 <programlisting format="linespecific">
891 ...
892 modparam("registrar", "regid_mode", 1)
893 ...
894                 </programlisting>
895                 </example>
896         </section>
897
898         <section id="registrar.p.flow_timer">
899                 <title><varname>flow_timer</varname> (integer)</title>
900                 <para>
901                 If set to 0 then this module will not add a <quote>Flow-Timer:</quote> header
902                 to 200 OK responses to REGISTER requests.
903                 </para>
904                 <para>
905                 If set to > 0 then this module will add a <quote>Flow-Timer:</quote> header
906                 containing this value to 200 OK responses to REGISTER requests.
907                 This parameter may only be set to a value > 0 when
908                 <emphasis>outbound_mode</emphasis> is set to 1 or 2.
909                 </para>
910                 <para>
911                 When set to a value greater than 0 this parameter should be set to slightly
912                 less than the connection timeout value between the UAC and the
913                 network (this corresponds to the core
914                 <emphasis>tcp_connection_lifetime</emphasis> option and
915                 <emphasis>websocket</emphasis>
916                 <emphasis>keepalive_timeout</emphasis> modparam). This
917                 parameter is most useful when you have a single edge
918                 proxy/registrar or if you have an edge proxy that cannot modify
919                 responses. If you are using a separate edge proxy you should
920                 consider leaving this parameter set to 0 and adding the
921                 <quote>Flow-Timer:</quote> header on the edge proxy as this allows you to
922                 keep all of the timer values for a specific flow in one
923                 configuration.
924                 </para>
925                 <para>
926                 <emphasis>
927                         Default value is 0.
928                 </emphasis>
929                 </para>
930                 <example>
931                 <title>Set <varname>flow_timer</varname> parameter</title>
932                 <programlisting format="linespecific">
933 ...
934 modparam("registrar", "flow_timer", 25)
935 ...
936                 </programlisting>
937                 </example>
938         </section>
939
940         <section id="registrar.p.contact_max_size">
941                 <title><varname>contact_max_size</varname> (integer)</title>
942                 <para>
943                 Max size of URIs in <quote>Contact:</quote> header.
944                 </para>
945                 <para>
946                 The size of URIs in <quote>Contact:</quote> headers are checked to be
947                 lower or equal to this value.
948                 A warning is logged and a 400 Bad Request is sent in response to REGISTER
949                 requests with contact URIs that are longer than this value.
950                 </para>
951                 <para>
952                 If a database is used then you must make sure that your database model supports
953                 strings of the configured size in the column <quote>contact</quote> of the table
954                 specified in <quote>save()</quote> function.
955                 </para>
956                 <para>
957                 <emphasis>
958                         Default value is 512.
959                 </emphasis>
960                 </para>
961                 <example>
962                 <title>Set <varname>contact_max_size</varname> parameter</title>
963                 <programlisting format="linespecific">
964 ...
965 modparam("registrar", "contact_max_size", 1024)
966 ...
967                 </programlisting>
968                 </example>
969         </section>
970
971         <section id="registrar.p.event_callback">
972                 <title><varname>event_callback</varname> (str)</title>
973                 <para>
974                         The name of the function in the KEMI configuration file (embedded
975                         scripting language such as Lua, Python, ...) to be executed instead
976                         of event_route[...] blocks.
977                 </para>
978                 <para>
979                         The function receives a string parameter with the name of the event.
980             The only possible value currently is 'usrloc:contact-expired'.
981                 </para>
982                 <para>
983                 <emphasis>
984                         Default value is 'empty' (no function is executed for events).
985                 </emphasis>
986                 </para>
987                 <example>
988                 <title>Set <varname>event_callback</varname> parameter</title>
989                 <programlisting format="linespecific">
990 ...
991 modparam("registrar", "event_callback", "ksr_registrar_event")
992 ...
993 -- event callback function implemented in Lua
994 function ksr_registrar_event(evname)
995     KSR.info( "Expired contact for " .. KSR.pv.getw("$ulc(exp=>aor)") .. "\n");
996         return 1;
997 end
998 ...
999         </programlisting>
1000                 </example>
1001         </section>
1002         <section id="registrar.p.lookup_filter_mode">
1003                 <title><varname>lookup_filter_mode</varname> (int)</title>
1004                 <para>
1005                         Control what filters should be applied to lookup(...) operations.
1006                         It can be a combination (sum) of the next values:
1007                 </para>
1008                 <itemizedlist>
1009                 <listitem>
1010                         <para>
1011                                 <emphasis>1</emphasis> - apply the branch flags filter - return
1012                                 only contact records with branch flags matching at least one set
1013                                 inside xavp specified by xavp_cfg parameter with inner name
1014                                 rlf_bflags - e.g., $xavp(reg=&gt;rlf_bflags).
1015                         </para>
1016                 </listitem>
1017         </itemizedlist>
1018                 <para>
1019                 <emphasis>
1020                         Default value is NULL (disabled).
1021                 </emphasis>
1022                 </para>
1023                 <example>
1024                 <title>Set <varname>xavp_cfg</varname> parameter</title>
1025                 <programlisting format="linespecific">
1026 ...
1027 modparam("registrar", "xavp_cfg", "reg")
1028 modparam("registrar", "lookup_filter_mode", 1)
1029 ...
1030 request_route {
1031     ...
1032     $xavp(reg=&gt;rlf_bflags) = 8;
1033     if(lookup("location")) { ... }
1034     ...
1035 }
1036 ...
1037                 </programlisting>
1038                 </example>
1039         </section>
1040         </section>
1041
1042         
1043         <section>
1044         <title>Functions</title>
1045         <section id="registrar.f.save">
1046                 <title>
1047                 <function moreinfo="none">save(domain, [, flags [, uri]])</function>
1048                 </title>
1049                 <para>
1050                 The function processes a <emphasis>REGISTER</emphasis> message. It can add, remove or 
1051                 modify location records (in usrloc) depending on Contact and Expires HFs in the 
1052                 REGISTER message. On success and when called from the REQUEST_ROUTE, 
1053                 <quote>200 OK</quote> will be returned listing all contacts that are currently in 
1054                 the location database. On an error, an error message will be sent with a short
1055                 description in reason phrase.
1056                 </para>
1057                 <para>Meaning of the parameters is as follows:</para>
1058                 <itemizedlist>
1059                 <listitem>
1060                         <para>
1061                         <emphasis>domain</emphasis> - Logical domain within the registrar. 
1062                         If a database is used then this must be name of the table which 
1063                         stores the contacts.
1064                         </para>
1065                 </listitem>
1066                 <listitem>
1067                         <para>
1068                         <emphasis>flags</emphasis> (optional) - the value may be a bitwise
1069                         OR of the following flags:
1070                         </para>
1071                         <itemizedlist>
1072                                 <listitem>
1073                                         <para><emphasis>0x01</emphasis> - save the contacts only
1074                                         in memory cache without no DB operation;
1075                                         </para>
1076                                 </listitem>
1077                                 <listitem>
1078                                         <para><emphasis>0x02</emphasis> - do not generate a SIP 
1079                                                 reply to the current REGISTER request. When used in
1080                                                 ONREPLY_ROUTE, this parameter is obsolete.</para>
1081                                 </listitem>
1082                                 <listitem>
1083                                         <para><emphasis>0x04</emphasis> - store and maintain one
1084                                         contact per AoR. If there are other contact addresses for
1085                                         AoR not matching current registration, remove them.
1086                                         This mode ensures one contact per AoR (user).</para>
1087                                 </listitem>
1088                                 <listitem>
1089                                         <para><emphasis>0x08</emphasis> - Do not apply
1090                                         <emphasis>expires_range</emphasis> or 
1091                                         <emphasis>default_expires_range</emphasis> to this
1092                                         registration.
1093                                         </para>
1094                                 </listitem>
1095                         </itemizedlist>
1096                         <para>The flags may be given in decimal or hexadecimal format.</para>
1097                 </listitem>
1098                 <listitem>
1099                         <para>
1100                         <emphasis>uri</emphasis> (optional - flags param has to be set and
1101                         can be 0 for default behavior) - SIP URI to do be used instead of To
1102                         header URI. It can be a dynamic string with pseudo-variables.
1103                         </para>
1104                 </listitem>
1105                 </itemizedlist>
1106                 <para>Return codes:</para>
1107                 <itemizedlist>
1108                 <listitem>
1109                         <para>
1110                         <emphasis>-2</emphasis> - error, too many contacts for AOR.
1111                         </para>
1112                         <para>
1113                         <emphasis>-1</emphasis> - error.
1114                         </para>
1115                         <para>
1116                         <emphasis>1</emphasis> - contacts inserted.
1117                         </para>
1118                         <para>
1119                         <emphasis>2</emphasis> - contacts updated.
1120                         </para>
1121                         <para>
1122                         <emphasis>3</emphasis> - contacts deleted.
1123                         </para>
1124                         <para>
1125                         <emphasis>4</emphasis> - contacts returned.
1126                         </para>
1127                 </listitem>
1128                 </itemizedlist>
1129                 <para>
1130                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE and REPLY_ROUTE.
1131                 </para>
1132                 <example>
1133                 <title><function>save</function> usage</title>
1134                 <programlisting format="linespecific">
1135 ...
1136 save("location");
1137 save("location", "0x01");
1138 save("location", "0x00", "sip:test@kamailio.org");
1139 ...
1140 </programlisting>
1141                 </example>
1142         </section>
1143
1144         <section id="registrar.f.lookup">
1145                 <title>
1146                 <function moreinfo="none">lookup(domain [, uri])</function>
1147                 </title>
1148                 <para>
1149                 The lookup function extracts username and/or domain from Request-URI and tries to find 
1150                 all contacts for the username in usrloc. If there are no such 
1151                 contacts, -1 will be returned.  If there are such contacts, 
1152                 Request-URI will be overwritten with the contact that has
1153                 the highest q value and optionally the rest will be appended to 
1154                 the message (depending on append_branches parameter value).
1155                 </para>
1156                 <para>
1157                 If the <varname>method_filtering</varname> option is enabled and
1158         request is initial request without to-tag, the
1159         <function>lookup</function> function 
1160                 will return only the contacts that support the method of the
1161                 processed request.
1162                 </para>
1163                 <para>Meaning of the parameters is as follows:</para>
1164                 <itemizedlist>
1165                 <listitem>
1166                         <para>
1167                         <emphasis>domain</emphasis> - Name of table that should be used 
1168                         for the lookup.
1169                         </para>
1170                 </listitem>
1171                 <listitem>
1172                         <para>
1173                         <emphasis>uri</emphasis> (optional) - SIP URI to do be used instead
1174                         of R-URI. It can be a dynamic string with pseudo-variables.
1175                         </para>
1176                 </listitem>
1177                 </itemizedlist>
1178                 <para>Return codes:</para>
1179                 <itemizedlist>
1180                 <listitem>
1181                         <para>
1182                         <emphasis>1</emphasis> - contacts found and returned.
1183                         </para>
1184                         <para>
1185                         <emphasis>-1</emphasis> - no contact found.
1186                         </para>
1187                         <para>
1188                         <emphasis>-2</emphasis> - contacts found, but method not supported.
1189                         </para>
1190                         <para>
1191                         <emphasis>-3</emphasis> - internal error during processing.
1192                         </para>
1193                 </listitem>
1194                 </itemizedlist>
1195
1196                 <para>
1197                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1198                 </para>
1199                 <example>
1200                 <title><function>lookup</function> usage</title>
1201                 <programlisting format="linespecific">
1202 ...
1203 lookup("location");
1204 switch ($retcode) {
1205     case -1:
1206     case -3:
1207         sl_send_reply("404", "Not Found");
1208         exit;
1209     case -2:
1210         sl_send_reply("405", "Not Found");
1211         exit;
1212 };
1213 ...
1214 </programlisting>
1215                 </example>
1216         </section>
1217
1218         <section id="registrar.f.lookup_branches">
1219                 <title>
1220                 <function moreinfo="none">lookup_branches(domain)</function>
1221                 </title>
1222                 <para>
1223                 The function performs lookup(domain) on r-uri and additional
1224                 branches (only branches that have no other attributes set than uri).
1225                 </para>
1226                 <para>Meaning of the parameters is as follows:</para>
1227                 <itemizedlist>
1228                 <listitem>
1229                         <para>
1230                         <emphasis>domain</emphasis> - Name of table that should be used 
1231                         for the lookup.
1232                         </para>
1233                 </listitem>
1234                 </itemizedlist>
1235                 <para>Return codes are propagated from the <function>lookup(domain)</function> function.
1236                 </para>
1237
1238                 <para>
1239                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1240                 </para>
1241                 <example>
1242                 <title><function>lookup_branches</function> usage</title>
1243                 <programlisting format="linespecific">
1244 ...
1245 lookup_branches("location");
1246 ...
1247 </programlisting>
1248                 </example>
1249         </section>
1250
1251         <section id="registrar.f.registered">
1252                 <title>
1253                 <function moreinfo="none">registered(domain [, uri [, match_option [, match_action]]])</function>
1254                 </title>
1255                 <para>
1256                 The function returns true if the AOR in the URI is 
1257                 registered, false otherwise.  The function does not modify the 
1258                 message being process, it neither rewrites the Request-URI if a 
1259                 contact is found nor append branches. If uri parameter is not
1260                 provided, then it considered to be the Request-URI for SIP requests
1261                 and To-URI for SIP replies.
1262                 </para>
1263                 <para>Meaning of the parameters is as follows:</para>
1264                 <itemizedlist>
1265                 <listitem>
1266                         <para>
1267                         <emphasis>domain</emphasis> - Name of table that should be 
1268                         used for the lookup.
1269                         </para>
1270                 </listitem>
1271                 <listitem>
1272                         <para>
1273                         <emphasis>uri</emphasis> (optional) - SIP URI to do be used instead
1274                         of Request/To-URI. It can be a dynamic string with pseudo-variables.
1275                         </para>
1276                 </listitem>
1277                 <listitem>
1278                         <para>
1279                         <emphasis>match_option</emphasis> (optional) - flag parameter to restrict
1280                         contact search. use reg_xavp_cfg to set the values to compare to.
1281                         </para>
1282             <para>flag values is as follows:</para>
1283                         <itemizedlist>
1284                                 <listitem>
1285                                         <para>1 - match_callid</para>
1286                                 </listitem>
1287                                 <listitem>
1288                                         <para>2 - match_received</para>
1289                                 </listitem>
1290                                 <listitem>
1291                                         <para>4 - match_contact</para>
1292                                 </listitem>
1293                         </itemizedlist>
1294                 </listitem>
1295                 <listitem>
1296                         <para>
1297                         <emphasis>match_action</emphasis> (optional) - actions to perform when match is positive.
1298                         </para>
1299             <para>flag values is as follows:</para>
1300                         <itemizedlist>
1301                                 <listitem>
1302                                         <para>1 - restore the xavps associated with the matched contact</para>
1303                                 </listitem>
1304                                 <listitem>
1305                                         <para>2 - skip adding the matched location record attributes to xavp_rcd
1306                                         (e.g., the ruid, contact, received, ...)</para>
1307                                 </listitem>
1308                         </itemizedlist>
1309                 </listitem>
1310                 </itemizedlist>
1311                 <para>
1312                 This function can be used from ANY_ROUTE.
1313                 </para>
1314                 <example>
1315                 <title><function>registered</function> usage</title>
1316                 <programlisting format="linespecific">
1317 ...
1318 if (registered("location")) {
1319         sl_send_reply("100", "Trying");
1320         ...
1321 };
1322 ...
1323 $xavp(regcfg=>match_received) = $su;
1324 if (registered("location","$rz:$Au", 2)) {
1325         sl_send_reply("100", "Trying");
1326         ...
1327 };
1328 ...
1329
1330 </programlisting>
1331                 </example>
1332         </section>
1333
1334         <section id="registrar.f.add_sock_hdr">
1335                 <title>
1336                 <function moreinfo="none">add_sock_hdr(hdr_name)</function>
1337                 </title>
1338                 <para>
1339                 Adds a new header to the current REGISTER request with 
1340                 <quote>hdr_name</quote> which contains the description of the
1341                 received socket (proto:ip:port)
1342                 </para>
1343                 <para>
1344                 This makes sense only in multiple replicated servers scenarios.
1345                 </para>
1346                 <para>Meaning of the parameters is as follows:</para>
1347                 <itemizedlist>
1348                 <listitem>
1349                         <para>
1350                         <emphasis>hdr_name</emphasis> - header name to be used, it can be
1351                         a static string or contain variables.
1352                         </para>
1353                 </listitem>
1354                 </itemizedlist>
1355                 <para>
1356                 This function can be used from REQUEST_ROUTE.
1357                 </para>
1358                 <example>
1359                 <title><function>add_sock_hdr</function> usage</title>
1360                 <programlisting format="linespecific">
1361 ...
1362 add_sock_hdr("Sock-Info");
1363 ...
1364 </programlisting>
1365                 </example>
1366         </section>
1367         <section id="registrar.f.unregister">
1368                 <title>
1369                 <function moreinfo="none">unregister(domain, uri[, ruid])</function>
1370                 </title>
1371                 <para>
1372                 The function removes contacts associated with 'uri' from the location
1373                 database. If 'ruid' is provided a specific contact is removed,
1374                 if 'ruid' is not provided all the current contacts are removed. 
1375                 If 'ruid' is provided and the <quote>usrloc</quote> module is
1376                 using <quote>db_mode=3</quote>, 'uri' does not need to be given and can be
1377                 empty string.
1378                 </para>
1379                 <para>Meaning of the parameters is as follows:</para>
1380                 <itemizedlist>
1381                 <listitem>
1382                         <para>
1383                         <emphasis>domain</emphasis> - Name of table that should be 
1384                         used for the lookup or contact addresses.
1385                         </para>
1386                 </listitem>
1387                 <listitem>
1388                         <para>
1389                         <emphasis>uri</emphasis> - The SIP URI address of the user
1390                         which to remove the contact addresses for. It can contain
1391                         pseudo-variables that are evaluated at runtime.
1392                         </para>
1393                 </listitem>
1394                 <listitem>
1395                         <para>
1396                         <emphasis>ruid</emphasis> - The record unique ID for a
1397                         a specific contact to be removed. It can contain
1398                         pseudo-variables that are evaluated at runtime.
1399                         </para>
1400                 </listitem>
1401                 </itemizedlist>
1402                 <para>
1403                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1404                 </para>
1405                 <para>
1406                 Return values:
1407                 </para>
1408                 <itemizedlist>
1409                 <listitem>
1410                         <para>
1411                         <emphasis>0</emphasis> - Successfully deleted contact(s)
1412                         </para>
1413                 </listitem>
1414                 <listitem>
1415                         <para>
1416                         <emphasis>-1</emphasis> - Failed to extract or parse address of record from argument
1417                         </para>
1418                 </listitem>
1419                 <listitem>
1420                         <para>
1421                         <emphasis>-2</emphasis> - Error in unregistering user
1422                         </para>
1423                 </listitem>
1424                 <listitem>
1425                         <para>
1426                         <emphasis>-3</emphasis> - Contacts for AOR not found
1427                         </para>
1428                 </listitem>
1429                 </itemizedlist>
1430                 <example>
1431                 <title><function>unregister</function> usage</title>
1432                 <programlisting format="linespecific">
1433 ...
1434 unregister("location", "$ru");
1435 unregister("location", "sip:user@kamailio.org");
1436 unregister("location", "$ru", "$ulc(caller=>ruid)");
1437 unregister("location", "", "$ruid");
1438 ...
1439 </programlisting>
1440                 </example>
1441         </section>
1442         <section id="registrar.f.reg_fetch_contacts">
1443                 <title>
1444                 <function moreinfo="none">reg_fetch_contacts(domain, uri, profile)</function>
1445                 </title>
1446                 <para>
1447                         The function fetches the contacts for 'uri' from table 'domain'
1448                         to pseudo-variable $ulc(profile).
1449                 </para>
1450                 <para>Meaning of the parameters is as follows:</para>
1451                 <itemizedlist>
1452                 <listitem>
1453                         <para>
1454                         <emphasis>domain</emphasis> - Name of table that should be 
1455                         used for the lookup of contact addresses.
1456                         </para>
1457                 </listitem>
1458                 <listitem>
1459                         <para>
1460                         <emphasis>uri</emphasis> - The SIP URI address of the user
1461                         which to fetch the contact addresses for. It can contain
1462                         pseudo-variables that are evaluated at runtime.
1463                         </para>
1464                 </listitem>
1465                 <listitem>
1466                         <para>
1467                         <emphasis>profile</emphasis> - Name of $ulc pseudo-variable profile
1468                         that will store the fetched contacts. It is a static string.
1469                         </para>
1470                 </listitem>
1471                 </itemizedlist>
1472                 <para>
1473                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1474                 </para>
1475                 <example>
1476                 <title><function>reg_fetch_contacts</function> usage</title>
1477                 <programlisting format="linespecific">
1478 ...
1479 reg_fetch_contacts("location", "$ru", "callee");
1480 reg_fetch_contacts("location", "sip:user@kamailio.org", "caller");
1481 ...
1482 </programlisting>
1483                 </example>
1484         </section>
1485         <section id="registrar.f.reg_free_contacts">
1486                 <title>
1487                 <function moreinfo="none">reg_free_contacts(profile)</function>
1488                 </title>
1489                 <para>
1490                         The function frees the contacts from pseudo-variable $ulc(profile).
1491                         Should be called to release the content of a profile. Anyhow,
1492                         fetching a new contact addresses set over a profile will release
1493                         any existing data in that profile.
1494                 </para>
1495                 <para>Meaning of the parameters is as follows:</para>
1496                 <itemizedlist>
1497                 <listitem>
1498                         <para>
1499                         <emphasis>profile</emphasis> - Name of $ulc pseudo-variable profile
1500                         that stores fetched contacts. It is a static string.
1501                         </para>
1502                 </listitem>
1503                 </itemizedlist>
1504                 <para>
1505                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1506                 </para>
1507                 <example>
1508                 <title><function>reg_free_contacts</function> usage</title>
1509                 <programlisting format="linespecific">
1510 ...
1511 reg_free_contacts("callee");
1512 ...
1513 </programlisting>
1514                 </example>
1515         </section>
1516
1517         </section>
1518
1519 <section>
1520         <title>Event Routes</title>
1521         <section>
1522                 <title><varname>event_route[usrloc:contact-expired]</varname></title>
1523                 <para>
1524                 Executed when a contact in location table has expired. The variable
1525                 $ulc(exp=&gt;...) is filled with the attributes of the expired contact.
1526                 </para>
1527                 <example>
1528                 <title><function>event_route[usrloc:contact-expired]</function> usage</title>
1529                 <programlisting format="linespecific">
1530 ...
1531 event_route[usrloc:contact-expired] {
1532     xlog("expired contact for $ulc(exp=>aor)\n");
1533 }
1534 ...
1535 </programlisting>
1536                 </example>
1537
1538         </section>
1539 </section>
1540
1541 <section>
1542         <title>Statistics</title>
1543         <section>
1544                 <title><varname>max_expires</varname></title>
1545                 <para>
1546                 Value of max_expires parameter.
1547                 </para>
1548         </section>
1549         <section>
1550                 <title><varname>max_contacts</varname></title>
1551                 <para>
1552                 The value of max_contacts parameter.
1553                 </para>
1554         </section>
1555         <section>
1556                 <title><varname>default_expires</varname></title>
1557                 <para>
1558                 The value of default_expires parameter.
1559                 </para>
1560         </section>
1561         <section>
1562                 <title><varname>accepted_regs</varname></title>
1563                 <para>
1564                 Number of accepted registrations.
1565                 </para>
1566         </section>
1567         <section>
1568                 <title><varname>rejected_regs</varname></title>
1569                 <para>
1570                 Number of rejected registrations.
1571                 </para>
1572         </section>
1573
1574 </section>
1575
1576         <section>
1577         <title>Pseudo Variables</title>
1578                 
1579                 <section>
1580                         <title><varname>$ulc(profile=>attr)</varname></title>
1581                         <para>
1582                                 Access the attributes of contact addresses stored in
1583                                 'profile'. It must be used after a call of
1584                                 <quote>reg_fetch_contacts()</quote>.
1585                         </para>
1586                         <para>
1587                                 The <quote>profile</quote> has to be one of the values used
1588                                 with <quote>reg_fetch_contacts()</quote>.
1589                         </para>
1590                         <para>
1591                         The <quote>attr</quote> can be:
1592                         </para>
1593                         <itemizedlist>
1594                                 <listitem>
1595                                 <para><emphasis>aor</emphasis> - address of record
1596                                 </para>
1597                                 </listitem>       
1598                                 <listitem>
1599                                 <para><emphasis>domain</emphasis> - used location domain/table name
1600                                 </para>
1601                                 </listitem>       
1602                                 <listitem>
1603                                 <para><emphasis>aorhash</emphasis> - hash id for the record
1604                                 </para>
1605                                 </listitem>
1606                                 <listitem>
1607                                 <para><emphasis>addr</emphasis> - contact address
1608                                 </para>
1609                                 </listitem>       
1610                                 <listitem>
1611                                 <para><emphasis>path</emphasis> - path vector
1612                                 </para>
1613                                 </listitem>       
1614                                 <listitem>
1615                                 <para><emphasis>received</emphasis> - received address
1616                                 </para>
1617                                 </listitem>       
1618                                 <listitem>
1619                                 <para><emphasis>expires</emphasis> - expires value
1620                                 </para>
1621                                 </listitem>       
1622                                 <listitem>
1623                                 <para><emphasis>callid</emphasis> - call-id header value
1624                                 </para>
1625                                 </listitem>       
1626                                 <listitem>
1627                                 <para><emphasis>q</emphasis> - the q value
1628                                 </para>
1629                                 </listitem>       
1630                                 <listitem>
1631                                 <para><emphasis>cseq</emphasis> - the cseq value
1632                                 </para>
1633                                 </listitem>       
1634                                 <listitem>
1635                                 <para><emphasis>flags</emphasis> - flags value
1636                                 </para>
1637                                 </listitem>       
1638                                 <listitem>
1639                                 <para><emphasis>cflags</emphasis> - cflags value
1640                                 </para>
1641                                 </listitem>       
1642                                 <listitem>
1643                                 <para><emphasis>user_agent</emphasis> - user agent
1644                                 </para>
1645                                 </listitem>       
1646                                 <listitem>
1647                                 <para><emphasis>socket</emphasis> - local socket
1648                                 </para>
1649                                 </listitem>       
1650                                 <listitem>
1651                                 <para><emphasis>modified</emphasis> - last modified time
1652                                 </para>
1653                                 </listitem>       
1654                                 <listitem>
1655                                 <para><emphasis>methods</emphasis> - methods value
1656                                 </para>
1657                                 </listitem>       
1658                                 <listitem>
1659                                 <para><emphasis>count</emphasis> - number of contacts
1660                                 </para>
1661                                 </listitem>       
1662                                 <listitem>
1663                                 <para><emphasis>ruid</emphasis> - record unique ID
1664                                 </para>
1665                                 </listitem>       
1666                                 <listitem>
1667                                 <para><emphasis>regid</emphasis> - reg-id value
1668                                 </para>
1669                                 </listitem>       
1670                                 <listitem>
1671                                 <para><emphasis>instance</emphasis> - instance value
1672                                 </para>
1673                                 </listitem>       
1674                                 <listitem>
1675                                 <para><emphasis>conid</emphasis> - TCP socket internal connection ID ($null if UDP)
1676                                 </para>
1677                                 </listitem>
1678                                 <listitem>
1679                                 <para><emphasis>server_id</emphasis> - server_id value
1680                                 </para>
1681                                 </listitem>
1682                         </itemizedlist>
1683                         <para>
1684                                 The pseudo-variable accepts positive index value to access
1685                                 a specific contact record.
1686                         </para>
1687
1688                         <example>
1689                         <title><function moreinfo="none">$ulc(name)</function> usage</title>
1690 <programlisting format="linespecific">
1691 ...
1692 if(reg_fetch_contacts("location", "$fu", "caller"))
1693 {
1694   xlog("caller=&gt;aor: $(ulc(caller=&gt;aor))\n");
1695   xlog("caller=&gt;domain: $(ulc(caller=&gt;domain))\n");
1696   xlog("caller=&gt;aorhash $(ulc(caller=&gt;aorhash))\n");
1697   xlog("caller=&gt;count $(ulc(caller=&gt;count))\n");
1698   $var(i) = 0;
1699   while($var(i) &lt; $(ulc(caller=&gt;count)))
1700   {
1701     xlog("--- contact [$var(i)]\n");
1702     xlog("caller=&gt;addr:       $(ulc(caller=&gt;addr)[$var(i)])\n");
1703     xlog("caller=&gt;path:       $(ulc(caller=&gt;path)[$var(i)])\n");
1704     xlog("caller=&gt;received:   $(ulc(caller=&gt;received)[$var(i)])\n");
1705     xlog("caller=&gt;expires:    $(ulc(caller=&gt;expires)[$var(i)])\n");
1706     xlog("caller=&gt;callid:     $(ulc(caller=&gt;callid)[$var(i)])\n");
1707     xlog("caller=&gt;regid:      $(ulc(caller=&gt;regid)[$var(i)])\n");
1708     xlog("caller=&gt;q:          $(ulc(caller=&gt;q)[$var(i)])\n");
1709     xlog("caller=&gt;cseq:       $(ulc(caller=&gt;cseq)[$var(i)])\n");
1710     xlog("caller=&gt;flags:      $(ulc(caller=&gt;flags)[$var(i)])\n");
1711     xlog("caller=&gt;cflags:     $(ulc(caller=&gt;cflags)[$var(i)])\n");
1712     xlog("caller=&gt;user_agent: $(ulc(caller=&gt;user_agent)[$var(i)])\n");
1713     xlog("caller=&gt;socket:     $(ulc(caller=&gt;socket)[$var(i)])\n");
1714     xlog("caller=&gt;modified:   $(ulc(caller=&gt;modified)[$var(i)])\n");
1715     xlog("caller=&gt;methods:    $(ulc(caller=&gt;methods)[$var(i)])\n");
1716     $var(i) = $var(i) + 1;
1717   }
1718 }
1719 ...
1720                                  </programlisting>
1721                         </example>
1722                 </section>
1723         </section>
1724
1725 </chapter>
1726