Merge pull request #1311 from grumvalski/async_unixodbc
[kamailio] / 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 maximim percentage from expires that
162                 will be substracted 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 rquest 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                 </programlisting>
735                 </example>
736         </section>
737
738         <section id="registrar.p.xavp_rcd">
739                 <title><varname>xavp_rcd</varname> (string)</title>
740                 <para>
741                         Defines the name of XAVP class to store details from the
742                         location records. The values are stored as inner XAVPs, like
743                         $xavp(class[0]=&gt;attribute). Valid inner XAVP names:
744                 </para>
745                 <itemizedlist>
746                 <listitem>
747                         <para>
748                                 <emphasis>ruid</emphasis> - the record's internal unique
749                                 id.
750                         </para>
751                 </listitem>
752                 <listitem>
753                         <para>
754                                 <emphasis>contact</emphasis> - the record's contact value.
755                         </para>
756                 </listitem>
757                 <listitem>
758                         <para>
759                                 <emphasis>expires</emphasis> - the record's expires value.
760                         </para>
761                 </listitem>
762                 <listitem>
763                         <para>
764                                 <emphasis>received</emphasis> - the record's received value.
765                         </para>
766                 </listitem>
767                 </itemizedlist>
768                 <para>
769                         For example. if this parameter is set to 'ulrcd', then values are set in:
770                 </para>
771                 <itemizedlist>
772                 <listitem>
773                         <para><emphasis>$xavp(ulrcd[0]=&gt;ruid)</emphasis></para>
774                 </listitem>
775                 <listitem>
776                         <para><emphasis>$xavp(ulrcd[0]=&gt;contact)</emphasis></para>
777                 </listitem>
778                 <listitem>
779                         <para><emphasis>$xavp(ulrcd[0]=&gt;received)</emphasis></para>
780                 </listitem>
781                 </itemizedlist>
782                 <para>
783                 <emphasis>
784                         Default value is NULL (disabled).
785                 </emphasis>
786                 </para>
787                 <example>
788                 <title>Set <varname>xavp_rcd</varname> parameter</title>
789                 <programlisting format="linespecific">
790 ...
791 modparam("registrar", "xavp_rcd", "ulrcd")
792 ...
793                 </programlisting>
794                 </example>
795         </section>
796
797         <section id="registrar.p.gruu_enabled">
798                 <title><varname>gruu_enabled</varname> (integer)</title>
799                 <para>
800                 If set to 1 and the <quote>+sip.instance</quote> parameter to
801                 Contact header of REGISTER is present, then the value of the
802                 parameter is saved to location and pub-gruu and temp-gruu addresses
803                 are generated.
804                 </para>
805                 <para>
806                 Set it to 0 if you want to ignore GRUU extensions in REGISTER.
807                 </para>
808                 <para>
809                 <emphasis>
810                         Default value is 1 (enabled).
811                 </emphasis>
812                 </para>
813                 <example>
814                 <title>Set <varname>gruu_enabled</varname> parameter</title>
815                 <programlisting format="linespecific">
816 ...
817 modparam("registrar", "gruu_enabled", 0)
818 ...
819                 </programlisting>
820                 </example>
821         </section>
822
823         <section id="registrar.p.outbound_mode">
824                 <title><varname>outbound_mode</varname> (integer)</title>
825                 <para>
826                 If set to 0 this module will accept REGISTER requests that do
827                 not contain a <quote>Supported:</quote> header with the outbound options-tag.
828                 The 200 OK response to REGISTER requests that this module
829                 generates will not contain <quote>Require:</quote> or 
830                 <quote>Supported:</quote> headers with
831                 the outbound options-tag. If the client has a <quote>Require:</quote> header
832                 with the outbound options tag the REGISTER will be rejected
833                 with a <quote>420 Bad Extension</quote> response.
834                 </para>
835                 <para>
836                 If set to 1 this module will accept REGISTER requests that
837                 do not contain a <quote>Supported:</quote> header with the outbound
838                 options-tag and REGISTER requests that do contain a Supported:
839                 or Requires: header with the outbound options-tag. When the
840                 client supports <emphasis>outbound</emphasis> the appropriate
841                 RFC5626 procedures will be followed.
842                 </para>
843                 <para>
844                 If set to 2 this module will reject REGISTER requests that
845                 do not contain a <quote>Supported:</quote> header with the outbound
846                 options-tag. When the client supports outbound the appropriate
847                 RFC5626 procedures will be followed.
848                 </para>
849                 <para>
850                 <emphasis>
851                         Default value is 0.
852                 </emphasis>
853                 </para>
854                 <example>
855                 <title>Set <varname>outbound_mode</varname> parameter</title>
856                 <programlisting format="linespecific">
857 ...
858 modparam("registrar", "outbound_mode", 2)
859 ...
860                 </programlisting>
861                 </example>
862         </section>
863
864         <section id="registrar.p.regid_mode">
865                 <title><varname>regid_mode</varname> (integer)</title>
866                 <para>
867                 If set to 0 this module will ignore the <quote>regid</quote> contact param
868                 when saving REGISTER request if the request does not
869                 indicate support for outbound.
870                 </para>
871                 <para>
872                 If set to 1 this module will use <quote>regid</quote> contact param
873                 (if present) when saving REGISTER request even if 
874                 REGISTER request does not indicate support for outbound.
875                 </para>
876                 <para>
877                 <emphasis>
878                         Default value is 0.
879                 </emphasis>
880                 </para>
881                 <example>
882                 <title>Set <varname>regid_mode</varname> parameter</title>
883                 <programlisting format="linespecific">
884 ...
885 modparam("registrar", "regid_mode", 1)
886 ...
887                 </programlisting>
888                 </example>
889         </section>
890
891         <section id="registrar.p.flow_timer">
892                 <title><varname>flow_timer</varname> (integer)</title>
893                 <para>
894                 If set to 0 then this module will not add a <quote>Flow-Timer:</quote> header
895                 to 200 OK responses to REGISTER requests.
896                 </para>
897                 <para>
898                 If set to > 0 then this module will add a <quote>Flow-Timer:</quote> header
899                 containing this value to 200 OK responses to REGISTER requests.
900                 This parameter may only be set to a value > 0 when
901                 <emphasis>outbound_mode</emphasis> is set to 1 or 2.
902                 </para>
903                 <para>
904                 When set to a value greater than 0 this parameter should be set to slightly
905                 less than the connection timeout value between the UAC and the
906                 network (this corresponds to the core
907                 <emphasis>tcp_connection_lifetime</emphasis> option and
908                 <emphasis>websocket</emphasis>
909                 <emphasis>keepalive_timeout</emphasis> modparam). This
910                 parameter is most useful when you have a single edge
911                 proxy/registrar or if you have an edge proxy that cannot modify
912                 responses. If you are using a separate edge proxy you should
913                 consider leaving this parameter set to 0 and adding the
914                 <quote>Flow-Timer:</quote> header on the edge proxy as this allows you to
915                 keep all of the timer values for a specific flow in one
916                 configuration.
917                 </para>
918                 <para>
919                 <emphasis>
920                         Default value is 0.
921                 </emphasis>
922                 </para>
923                 <example>
924                 <title>Set <varname>flow_timer</varname> parameter</title>
925                 <programlisting format="linespecific">
926 ...
927 modparam("registrar", "flow_timer", 25)
928 ...
929                 </programlisting>
930                 </example>
931         </section>
932
933         <section id="registrar.p.contact_max_size">
934                 <title><varname>contact_max_size</varname> (integer)</title>
935                 <para>
936                 Max size of URIs in <quote>Contact:</quote> header.
937                 </para>
938                 <para>
939                 The size of URIs in <quote>Contact:</quote> headers are checked to be
940                 lower or equal to this value.
941                 A warning is logged and a 400 Bad Request is sent in response to REGISTER
942                 requests with contact URIs that are longer than this value.
943                 </para>
944                 <para>
945                 If a database is used then you must make sure that your database model supports
946                 strings of the configured size in the column <quote>contact</quote> of the table
947                 specified in <quote>save()</quote> function.
948                 </para>
949                 <para>
950                 <emphasis>
951                         Default value is 512.
952                 </emphasis>
953                 </para>
954                 <example>
955                 <title>Set <varname>contact_max_size</varname> parameter</title>
956                 <programlisting format="linespecific">
957 ...
958 modparam("registrar", "contact_max_size", 1024)
959 ...
960                 </programlisting>
961                 </example>
962         </section>
963
964         </section>
965
966         
967         <section>
968         <title>Functions</title>
969         <section id="registrar.f.save">
970                 <title>
971                 <function moreinfo="none">save(domain, [, flags [, uri]])</function>
972                 </title>
973                 <para>
974                 The function processes a <emphasis>REGISTER</emphasis> message. It can add, remove or 
975                 modify location records (in usrloc) depending on Contact and Expires HFs in the 
976                 REGISTER message. On success and when called from the REQUEST_ROUTE, 
977                 <quote>200 OK</quote> will be returned listing all contacts that are currently in 
978                 the location database. On an error, an error message will be sent with a short
979                 description in reason phrase.
980                 </para>
981                 <para>Meaning of the parameters is as follows:</para>
982                 <itemizedlist>
983                 <listitem>
984                         <para>
985                         <emphasis>domain</emphasis> - Logical domain within the registrar. 
986                         If a database is used then this must be name of the table which 
987                         stores the contacts.
988                         </para>
989                 </listitem>
990                 <listitem>
991                         <para>
992                         <emphasis>flags</emphasis> (optional) - the value may be a bitwise
993                         OR of the following flags:
994                         </para>
995                         <itemizedlist>
996                                 <listitem>
997                                         <para><emphasis>0x01</emphasis> - save the contacts only
998                                         in memory cache without no DB operation;
999                                         </para>
1000                                 </listitem>
1001                                 <listitem>
1002                                         <para><emphasis>0x02</emphasis> - do not generate a SIP 
1003                                                 reply to the current REGISTER request. When used in
1004                                                 ONREPLY_ROUTE, this parameter is obsolete.</para>
1005                                 </listitem>
1006                                 <listitem>
1007                                         <para><emphasis>0x04</emphasis> - store and maintain one
1008                                         contact per AoR. If there are other contact addresses for
1009                                         AoR not matching current registration, remove them.
1010                                         This mode ensures one contact per AoR (user).</para>
1011                                 </listitem>
1012                                 <listitem>
1013                                         <para><emphasis>0x08</emphasis> - Do not apply
1014                                         <emphasis>expires_range</emphasis> or 
1015                                         <emphasis>default_expires_range</emphasis> to this
1016                                         registration.
1017                                         </para>
1018                                 </listitem>
1019                         </itemizedlist>
1020                         <para>The flags may be given in decimal or hexa format.</para>
1021                 </listitem>
1022                 <listitem>
1023                         <para>
1024                         <emphasis>uri</emphasis> (optional - flags param has to be set and
1025                         can be 0 for default behavior) - SIP URI to do be used instead of To
1026                         header URI. It can be a dynamic string with pseudo-variables.
1027                         </para>
1028                 </listitem>
1029                 </itemizedlist>
1030                 <para>Return codes:</para>
1031                 <itemizedlist>
1032                 <listitem>
1033                         <para>
1034                         <emphasis>-2</emphasis> - error, too many contacts for AOR.
1035                         </para>
1036                         <para>
1037                         <emphasis>-1</emphasis> - error.
1038                         </para>
1039                         <para>
1040                         <emphasis>1</emphasis> - contacts inserted.
1041                         </para>
1042                         <para>
1043                         <emphasis>2</emphasis> - contacts updated.
1044                         </para>
1045                         <para>
1046                         <emphasis>3</emphasis> - contacts deleted.
1047                         </para>
1048                         <para>
1049                         <emphasis>4</emphasis> - contacts returned.
1050                         </para>
1051                 </listitem>
1052                 </itemizedlist>
1053                 <para>
1054                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE and REPLY_ROUTE.
1055                 </para>
1056                 <example>
1057                 <title><function>save</function> usage</title>
1058                 <programlisting format="linespecific">
1059 ...
1060 save("location");
1061 save("location", "0x01");
1062 save("location", "0x00", "sip:test@kamailio.org");
1063 ...
1064 </programlisting>
1065                 </example>
1066         </section>
1067
1068         <section id="registrar.f.lookup">
1069                 <title>
1070                 <function moreinfo="none">lookup(domain [, uri])</function>
1071                 </title>
1072                 <para>
1073                 The lookup function extracts username and/or domain from Request-URI and tries to find 
1074                 all contacts for the username in usrloc. If there are no such 
1075                 contacts, -1 will be returned.  If there are such contacts, 
1076                 Request-URI will be overwritten with the contact that has
1077                 the highest q value and optionally the rest will be appended to 
1078                 the message (depending on append_branches parameter value).
1079                 </para>
1080                 <para>
1081                 If the <varname>method_filtering</varname> option is enabled and
1082         request is initial request without to-tag, the
1083         <function>lookup</function> function 
1084                 will return only the contacts that support the method of the
1085                 processed request.
1086                 </para>
1087                 <para>Meaning of the parameters is as follows:</para>
1088                 <itemizedlist>
1089                 <listitem>
1090                         <para>
1091                         <emphasis>domain</emphasis> - Name of table that should be used 
1092                         for the lookup.
1093                         </para>
1094                 </listitem>
1095                 <listitem>
1096                         <para>
1097                         <emphasis>uri</emphasis> (optional) - SIP URI to do be used instead
1098                         of R-URI. It can be a dynamic string with pseudo-variables.
1099                         </para>
1100                 </listitem>
1101                 </itemizedlist>
1102                 <para>Return codes:</para>
1103                 <itemizedlist>
1104                 <listitem>
1105                         <para>
1106                         <emphasis>1</emphasis> - contacts found and returned.
1107                         </para>
1108                         <para>
1109                         <emphasis>-1</emphasis> - no contact found.
1110                         </para>
1111                         <para>
1112                         <emphasis>-2</emphasis> - contacts found, but method not supported.
1113                         </para>
1114                         <para>
1115                         <emphasis>-3</emphasis> - internal error during processing.
1116                         </para>
1117                 </listitem>
1118                 </itemizedlist>
1119
1120                 <para>
1121                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1122                 </para>
1123                 <example>
1124                 <title><function>lookup</function> usage</title>
1125                 <programlisting format="linespecific">
1126 ...
1127 lookup("location");
1128 switch ($retcode) {
1129     case -1:
1130     case -3:
1131         sl_send_reply("404", "Not Found");
1132         exit;
1133     case -2:
1134         sl_send_reply("405", "Not Found");
1135         exit;
1136 };
1137 ...
1138 </programlisting>
1139                 </example>
1140         </section>
1141
1142         <section id="registrar.f.lookup_branches">
1143                 <title>
1144                 <function moreinfo="none">lookup_branches(domain)</function>
1145                 </title>
1146                 <para>
1147                 The function performs lookup(domain) on r-uri and additional
1148                 branches (only branches that have no other attributes set than uri).
1149                 </para>
1150                 <para>Meaning of the parameters is as follows:</para>
1151                 <itemizedlist>
1152                 <listitem>
1153                         <para>
1154                         <emphasis>domain</emphasis> - Name of table that should be used 
1155                         for the lookup.
1156                         </para>
1157                 </listitem>
1158                 </itemizedlist>
1159                 <para>Return codes are propagated from the <function>lookup(domain)</function> function.
1160                 </para>
1161
1162                 <para>
1163                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1164                 </para>
1165                 <example>
1166                 <title><function>lookup_branches</function> usage</title>
1167                 <programlisting format="linespecific">
1168 ...
1169 lookup_branches("location");
1170 ...
1171 </programlisting>
1172                 </example>
1173         </section>
1174
1175         <section id="registrar.f.registered">
1176                 <title>
1177                 <function moreinfo="none">registered(domain [, uri [, match_option [, match_action]]])</function>
1178                 </title>
1179                 <para>
1180                 The function returns true if the AOR in the URI is 
1181                 registered, false otherwise.  The function does not modify the 
1182                 message being process, it neither rewrites the Request-URI if a 
1183                 contact is found nor append branches. If uri parameter is not
1184                 provided, then it considered to be the Request-URI for SIP requests
1185                 and To-URI for SIP replies.
1186                 </para>
1187                 <para>Meaning of the parameters is as follows:</para>
1188                 <itemizedlist>
1189                 <listitem>
1190                         <para>
1191                         <emphasis>domain</emphasis> - Name of table that should be 
1192                         used for the lookup.
1193                         </para>
1194                 </listitem>
1195                 <listitem>
1196                         <para>
1197                         <emphasis>uri</emphasis> (optional) - SIP URI to do be used instead
1198                         of Request/To-URI. It can be a dynamic string with pseudo-variables.
1199                         </para>
1200                 </listitem>
1201                 <listitem>
1202                         <para>
1203                         <emphasis>match_option</emphasis> (optional) - flag parameter to restrict
1204                         contact search. use reg_xavp_cfg to set the values to compare to.
1205                         </para>
1206             <para>flag values is as follows:</para>
1207                         <itemizedlist>
1208                                 <listitem>
1209                                         <para>1 - match_callid</para>
1210                                 </listitem>
1211                                 <listitem>
1212                                         <para>2 - match_received</para>
1213                                 </listitem>
1214                                 <listitem>
1215                                         <para>4 - match_contact</para>
1216                                 </listitem>
1217                         </itemizedlist>
1218                 </listitem>
1219                 <listitem>
1220                         <para>
1221                         <emphasis>match_action</emphasis> (optional) - actions to perform when match is positive.
1222                         </para>
1223             <para>flag values is as follows:</para>
1224                         <itemizedlist>
1225                                 <listitem>
1226                                         <para>1 - restore the xavps associated with the matched contact</para>
1227                                 </listitem>
1228                                 <listitem>
1229                                         <para>2 - skip adding the matched location record attributes to xavp_rcd
1230                                         (e.g., the ruid, contact, received, ...)</para>
1231                                 </listitem>
1232                         </itemizedlist>
1233                 </listitem>
1234                 </itemizedlist>
1235                 <para>
1236                 This function can be used from ANY_ROUTE.
1237                 </para>
1238                 <example>
1239                 <title><function>registered</function> usage</title>
1240                 <programlisting format="linespecific">
1241 ...
1242 if (registered("location")) {
1243         sl_send_reply("100", "Trying");
1244         ...
1245 };
1246 ...
1247 $xavp(regcfg=>match_received) = $su;
1248 if (registered("location","$rz:$Au", 2)) {
1249         sl_send_reply("100", "Trying");
1250         ...
1251 };
1252 ...
1253
1254 </programlisting>
1255                 </example>
1256         </section>
1257
1258         <section id="registrar.f.add_sock_hdr">
1259                 <title>
1260                 <function moreinfo="none">add_sock_hdr(hdr_name)</function>
1261                 </title>
1262                 <para>
1263                 Adds a new header to the current REGISTER request with 
1264                 <quote>hdr_name</quote> which contains the description of the
1265                 received socket (proto:ip:port)
1266                 </para>
1267                 <para>
1268                 This makes sense only in multiple replicated servers scenarios.
1269                 </para>
1270                 <para>Meaning of the parameters is as follows:</para>
1271                 <itemizedlist>
1272                 <listitem>
1273                         <para>
1274                         <emphasis>hdr_name</emphasis> - header name to be used, it can be
1275                         a static string or contain variables.
1276                         </para>
1277                 </listitem>
1278                 </itemizedlist>
1279                 <para>
1280                 This function can be used from REQUEST_ROUTE.
1281                 </para>
1282                 <example>
1283                 <title><function>add_sock_hdr</function> usage</title>
1284                 <programlisting format="linespecific">
1285 ...
1286 add_sock_hdr("Sock-Info");
1287 ...
1288 </programlisting>
1289                 </example>
1290         </section>
1291         <section id="registrar.f.unregister">
1292                 <title>
1293                 <function moreinfo="none">unregister(domain, uri[, ruid])</function>
1294                 </title>
1295                 <para>
1296                 The function removes contacts associated with 'uri' from the location
1297                 database. If 'ruid' is provided a specific contact is removed,
1298                 if 'ruid' is not provided all the current contacts are removed. 
1299                 If 'ruid' is provided and the <quote>usrloc</quote> module is
1300                 using <quote>db_mode=3</quote>, 'uri' does not need to be given and can be
1301                 empty string.
1302                 </para>
1303                 <para>Meaning of the parameters is as follows:</para>
1304                 <itemizedlist>
1305                 <listitem>
1306                         <para>
1307                         <emphasis>domain</emphasis> - Name of table that should be 
1308                         used for the lookup or contact addresses.
1309                         </para>
1310                 </listitem>
1311                 <listitem>
1312                         <para>
1313                         <emphasis>uri</emphasis> - The SIP URI address of the user
1314                         which to remove the contact addresses for. It can contain
1315                         pseudo-variables that are evaluated at runtime.
1316                         </para>
1317                 </listitem>
1318                 <listitem>
1319                         <para>
1320                         <emphasis>ruid</emphasis> - The record unique ID for a
1321                         a specific contact to be removed. It can contain
1322                         pseudo-variables that are evaluated at runtime.
1323                         </para>
1324                 </listitem>
1325                 </itemizedlist>
1326                 <para>
1327                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1328                 </para>
1329                 <para>
1330                 Return values:
1331                 </para>
1332                 <itemizedlist>
1333                 <listitem>
1334                         <para>
1335                         <emphasis>0</emphasis> - Successfully deleted contact(s)
1336                         </para>
1337                 </listitem>
1338                 <listitem>
1339                         <para>
1340                         <emphasis>-1</emphasis> - Failed to extract or parse address of record from argument
1341                         </para>
1342                 </listitem>
1343                 <listitem>
1344                         <para>
1345                         <emphasis>-2</emphasis> - Error in unregistering user
1346                         </para>
1347                 </listitem>
1348                 <listitem>
1349                         <para>
1350                         <emphasis>-3</emphasis> - Contacts for AOR not found
1351                         </para>
1352                 </listitem>
1353                 </itemizedlist>
1354                 <example>
1355                 <title><function>unregister</function> usage</title>
1356                 <programlisting format="linespecific">
1357 ...
1358 unregister("location", "$ru");
1359 unregister("location", "sip:user@kamailio.org");
1360 unregister("location", "$ru", "$ulc(caller=>ruid)");
1361 unregister("location", "", "$ruid");
1362 ...
1363 </programlisting>
1364                 </example>
1365         </section>
1366         <section id="registrar.f.reg_fetch_contacts">
1367                 <title>
1368                 <function moreinfo="none">reg_fetch_contacts(domain, uri, profile)</function>
1369                 </title>
1370                 <para>
1371                         The function fetches the contacts for 'uri' from table 'domain'
1372                         to pseudo-variable $ulc(profile).
1373                 </para>
1374                 <para>Meaning of the parameters is as follows:</para>
1375                 <itemizedlist>
1376                 <listitem>
1377                         <para>
1378                         <emphasis>domain</emphasis> - Name of table that should be 
1379                         used for the lookup of contact addresses.
1380                         </para>
1381                 </listitem>
1382                 <listitem>
1383                         <para>
1384                         <emphasis>uri</emphasis> - The SIP URI address of the user
1385                         which to fetch the contact addresses for. It can contain
1386                         pseudo-variables that are evaluated at runtime.
1387                         </para>
1388                 </listitem>
1389                 <listitem>
1390                         <para>
1391                         <emphasis>profile</emphasis> - Name of $ulc pseudo-variable profile
1392                         that will store the fetched contacts. It is a static string.
1393                         </para>
1394                 </listitem>
1395                 </itemizedlist>
1396                 <para>
1397                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1398                 </para>
1399                 <example>
1400                 <title><function>reg_fetch_contacts</function> usage</title>
1401                 <programlisting format="linespecific">
1402 ...
1403 reg_fetch_contacts("location", "$ru", "callee");
1404 reg_fetch_contacts("location", "sip:user@kamailio.org", "caller");
1405 ...
1406 </programlisting>
1407                 </example>
1408         </section>
1409         <section id="registrar.f.reg_free_contacts">
1410                 <title>
1411                 <function moreinfo="none">reg_free_contacts(profile)</function>
1412                 </title>
1413                 <para>
1414                         The function frees the contacts from pseudo-variable $ulc(profile).
1415                         Should be called to release the content of a profile. Anyhow,
1416                         fetching a new contact addresses set over a profile will release
1417                         any existing data in that profile.
1418                 </para>
1419                 <para>Meaning of the parameters is as follows:</para>
1420                 <itemizedlist>
1421                 <listitem>
1422                         <para>
1423                         <emphasis>profile</emphasis> - Name of $ulc pseudo-variable profile
1424                         that stores fetched contacts. It is a static string.
1425                         </para>
1426                 </listitem>
1427                 </itemizedlist>
1428                 <para>
1429                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1430                 </para>
1431                 <example>
1432                 <title><function>reg_free_contacts</function> usage</title>
1433                 <programlisting format="linespecific">
1434 ...
1435 reg_free_contacts("callee");
1436 ...
1437 </programlisting>
1438                 </example>
1439         </section>
1440
1441         </section>
1442
1443 <section>
1444         <title>Event Routes</title>
1445         <section>
1446                 <title><varname>event_route[usrloc:contact-expired]</varname></title>
1447                 <para>
1448                 Executed when a contact in location table has expired. The variable
1449                 $ulc(exp=&gt;...) is filled with the attributes of the expired contact.
1450                 </para>
1451                 <example>
1452                 <title><function>event_route[usrloc:contact-expired]</function> usage</title>
1453                 <programlisting format="linespecific">
1454 ...
1455 event_route[usrloc:contact-expired] {
1456     xlog("expired contact for $ulc(exp=>aor)\n");
1457 }
1458 ...
1459 </programlisting>
1460                 </example>
1461
1462         </section>
1463 </section>
1464
1465 <section>
1466         <title>Statistics</title>
1467         <section>
1468                 <title><varname>max_expires</varname></title>
1469                 <para>
1470                 Value of max_expires parameter.
1471                 </para>
1472         </section>
1473         <section>
1474                 <title><varname>max_contacts</varname></title>
1475                 <para>
1476                 The value of max_contacts parameter.
1477                 </para>
1478         </section>
1479         <section>
1480                 <title><varname>default_expires</varname></title>
1481                 <para>
1482                 The value of default_expires parameter.
1483                 </para>
1484         </section>
1485         <section>
1486                 <title><varname>accepted_regs</varname></title>
1487                 <para>
1488                 Number of accepted registrations.
1489                 </para>
1490         </section>
1491         <section>
1492                 <title><varname>rejected_regs</varname></title>
1493                 <para>
1494                 Number of rejected registrations.
1495                 </para>
1496         </section>
1497
1498 </section>
1499
1500         <section>
1501         <title>Pseudo Variables</title>
1502                 
1503                 <section>
1504                         <title><varname>$ulc(profile=>attr)</varname></title>
1505                         <para>
1506                                 Access the attributes of contact addresses stored in
1507                                 'profile'. It must be used after a call of
1508                                 <quote>reg_fetch_contacts()</quote>.
1509                         </para>
1510                         <para>
1511                                 The <quote>profile</quote> has to be one of the values used
1512                                 with <quote>reg_fetch_contacts()</quote>.
1513                         </para>
1514                         <para>
1515                         The <quote>attr</quote> can be:
1516                         </para>
1517                         <itemizedlist>
1518                                 <listitem>
1519                                 <para><emphasis>aor</emphasis> - address of record
1520                                 </para>
1521                                 </listitem>       
1522                                 <listitem>
1523                                 <para><emphasis>domain</emphasis> - used location domain/table name
1524                                 </para>
1525                                 </listitem>       
1526                                 <listitem>
1527                                 <para><emphasis>aorhash</emphasis> - hash id for the record
1528                                 </para>
1529                                 </listitem>
1530                                 <listitem>
1531                                 <para><emphasis>addr</emphasis> - contact address
1532                                 </para>
1533                                 </listitem>       
1534                                 <listitem>
1535                                 <para><emphasis>path</emphasis> - path vector
1536                                 </para>
1537                                 </listitem>       
1538                                 <listitem>
1539                                 <para><emphasis>received</emphasis> - received address
1540                                 </para>
1541                                 </listitem>       
1542                                 <listitem>
1543                                 <para><emphasis>expires</emphasis> - expires value
1544                                 </para>
1545                                 </listitem>       
1546                                 <listitem>
1547                                 <para><emphasis>callid</emphasis> - call-id header value
1548                                 </para>
1549                                 </listitem>       
1550                                 <listitem>
1551                                 <para><emphasis>q</emphasis> - the q value
1552                                 </para>
1553                                 </listitem>       
1554                                 <listitem>
1555                                 <para><emphasis>cseq</emphasis> - the cseq value
1556                                 </para>
1557                                 </listitem>       
1558                                 <listitem>
1559                                 <para><emphasis>flags</emphasis> - flags value
1560                                 </para>
1561                                 </listitem>       
1562                                 <listitem>
1563                                 <para><emphasis>cflags</emphasis> - cflags value
1564                                 </para>
1565                                 </listitem>       
1566                                 <listitem>
1567                                 <para><emphasis>user_agent</emphasis> - user agent
1568                                 </para>
1569                                 </listitem>       
1570                                 <listitem>
1571                                 <para><emphasis>socket</emphasis> - local socket
1572                                 </para>
1573                                 </listitem>       
1574                                 <listitem>
1575                                 <para><emphasis>modified</emphasis> - last modified time
1576                                 </para>
1577                                 </listitem>       
1578                                 <listitem>
1579                                 <para><emphasis>methods</emphasis> - methods value
1580                                 </para>
1581                                 </listitem>       
1582                                 <listitem>
1583                                 <para><emphasis>count</emphasis> - number of contacts
1584                                 </para>
1585                                 </listitem>       
1586                                 <listitem>
1587                                 <para><emphasis>ruid</emphasis> - record unique ID
1588                                 </para>
1589                                 </listitem>       
1590                                 <listitem>
1591                                 <para><emphasis>regid</emphasis> - reg-id value
1592                                 </para>
1593                                 </listitem>       
1594                                 <listitem>
1595                                 <para><emphasis>instance</emphasis> - instance value
1596                                 </para>
1597                                 </listitem>       
1598                                 <listitem>
1599                                 <para><emphasis>conid</emphasis> - TCP socket internal connection ID ($null if UDP)
1600                                 </para>
1601                                 </listitem>
1602                                 <listitem>
1603                                 <para><emphasis>server_id</emphasis> - server_id value
1604                                 </para>
1605                                 </listitem>
1606                         </itemizedlist>
1607                         <para>
1608                                 The pseudo-variable accepts positive index value to access
1609                                 a specific contact record.
1610                         </para>
1611
1612                         <example>
1613                         <title><function moreinfo="none">$ulc(name)</function> usage</title>
1614 <programlisting format="linespecific">
1615 ...
1616 if(reg_fetch_contacts("location", "$fu", "caller"))
1617 {
1618   xlog("caller=&gt;aor: $(ulc(caller=&gt;aor))\n");
1619   xlog("caller=&gt;domain: $(ulc(caller=&gt;domain))\n");
1620   xlog("caller=&gt;aorhash $(ulc(caller=&gt;aorhash))\n");
1621   xlog("caller=&gt;count $(ulc(caller=&gt;count))\n");
1622   $var(i) = 0;
1623   while($var(i) &lt; $(ulc(caller=&gt;count)))
1624   {
1625     xlog("--- contact [$var(i)]\n");
1626     xlog("caller=&gt;addr:       $(ulc(caller=&gt;addr)[$var(i)])\n");
1627     xlog("caller=&gt;path:       $(ulc(caller=&gt;path)[$var(i)])\n");
1628     xlog("caller=&gt;received:   $(ulc(caller=&gt;received)[$var(i)])\n");
1629     xlog("caller=&gt;expires:    $(ulc(caller=&gt;expires)[$var(i)])\n");
1630     xlog("caller=&gt;callid:     $(ulc(caller=&gt;callid)[$var(i)])\n");
1631     xlog("caller=&gt;regid:      $(ulc(caller=&gt;regid)[$var(i)])\n");
1632     xlog("caller=&gt;q:          $(ulc(caller=&gt;q)[$var(i)])\n");
1633     xlog("caller=&gt;cseq:       $(ulc(caller=&gt;cseq)[$var(i)])\n");
1634     xlog("caller=&gt;flags:      $(ulc(caller=&gt;flags)[$var(i)])\n");
1635     xlog("caller=&gt;cflags:     $(ulc(caller=&gt;cflags)[$var(i)])\n");
1636     xlog("caller=&gt;user_agent: $(ulc(caller=&gt;user_agent)[$var(i)])\n");
1637     xlog("caller=&gt;socket:     $(ulc(caller=&gt;socket)[$var(i)])\n");
1638     xlog("caller=&gt;modified:   $(ulc(caller=&gt;modified)[$var(i)])\n");
1639     xlog("caller=&gt;methods:    $(ulc(caller=&gt;methods)[$var(i)])\n");
1640     $var(i) = $var(i) + 1;
1641   }
1642 }
1643 ...
1644                                  </programlisting>
1645                         </example>
1646                 </section>
1647         </section>
1648
1649 </chapter>
1650