presence: fix typo in presence_admin.xml
[sip-router] / modules / presence / doc / presence_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 "../../../docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter>
13         <title>&adminguide;</title>
14
15         <section>
16         <title>Overview</title>
17         <para> The Presence module implements the core functionality of SIP event notification.
18         It handles PUBLISH and SUBSCRIBE messages and generates
19         NOTIFY messages in a general, event independent way. It is extensible and allows registering
20         events to it from other &kamailio; modules.
21         Supported SIP event packages are presence, presence.winfo, dialog;sla from the presence_xml
22         module and message-summary from the presence_mwi module.
23         </para>
24         <para>
25         The module can use database and memory storage (to improve performance).
26         For subscriptions it supports the 4 storage modes: Memory Only, Write Back,
27         Write Through and DB Only. For publishes, it stores the state documents in
28         database only(because of the large size) and it can store a publish cache in
29         memory to avoid unnecessairy database queries. Read the
30         <emphasis>subs_db_mode</emphasis> and <emphasis>publ_cache</emphasis> parameter
31         sections to decide which is the best storage configuration for you.
32         </para>
33         <para>The module implements several API functions, that can be used by other
34         modules. In fact, it can be used only as a resource module, or "library".
35         This mode of operation is enabled if the db_url parameter is not set to any value.
36         </para>
37         <para>
38         The &kamailio; Presence module implements the specifications in: RFC3265, RFC3856, RFC3857,
39         RFC3858.
40         </para>
41         </section>
42
43         <section>
44         <title>Dependencies</title>
45         <section>
46                 <title>&kamailio; Modules</title>
47                 <para>
48                 The following modules must be loaded before this module:
49                         <itemizedlist>
50                         <listitem>
51                         <para>
52                                 <emphasis>a database module</emphasis>.
53                         </para>
54                         </listitem>
55                         <listitem>
56                         <para>
57                                 <emphasis>sl</emphasis>.
58                         </para>
59                         </listitem>
60                         <listitem>
61                         <para>
62                                 <emphasis>tm</emphasis>.
63                         </para>
64                         </listitem>
65                         </itemizedlist>
66                 </para>
67         </section>
68
69         <section>
70                 <title>External Libraries or Applications</title>
71                 <itemizedlist>
72                         <listitem>
73                         <para>
74                                 <emphasis>libxml</emphasis>.
75                         </para>
76                         </listitem>
77                 </itemizedlist>
78
79                 </section>
80         </section>
81
82         <section>
83         <title>Parameters</title>
84         <section id="presence.p.db_url">
85                 <title><varname>db_url</varname>(str)</title>
86                 <para>
87                 The database url.
88                 </para>
89                 <para>If set, the module is a fully operational
90                 presence server. Otherwise, it is used as a 'library', for
91                 its exported functions.
92                 </para>
93                 <para>
94                 <emphasis>Default value is <quote>NULL</quote>.</emphasis>
95                 </para>
96                 <example>
97                 <title>Set <varname>db_url</varname> parameter</title>
98                 <programlisting format="linespecific">
99 ...
100 modparam("presence", "db_url",
101         "&defaultdb;")
102 ...
103 </programlisting>
104                 </example>
105         </section>
106         <section id="presence.p.presentity_table">
107                 <title><varname>presentity_table</varname>(str)</title>
108                 <para>
109                 The name of the db table where PUBLISH presence information is stored.
110                 </para>
111                 <para>
112                 <emphasis>      Default value is <quote>presentity</quote>.
113                 </emphasis>
114                 </para>
115                 <example>
116                 <title>Set <varname>presentity_table</varname> parameter</title>
117                 <programlisting format="linespecific">
118 ...
119 modparam("presence", "presentity_table", "presentity")
120 ...
121 </programlisting>
122                 </example>
123         </section>
124         <section id="presence.p.active_watchers_table">
125                 <title><varname>active_watchers_table</varname>(str)</title>
126                 <para>
127                 The name of the db table where active subscription information is stored.
128                 </para>
129                 <para>
130                 <emphasis>      Default value is <quote>active_watchers</quote>.
131                 </emphasis>
132                 </para>
133                 <example>
134                 <title>Set <varname>active_watchers_table</varname> parameter</title>
135                 <programlisting format="linespecific">
136 ...
137 modparam("presence", "active_watchers_table", "active_watchers")
138 ...
139 </programlisting>
140                 </example>
141         </section>
142         <section id="presence.p.watchers_table">
143                 <title><varname>watchers_table</varname>(str)</title>
144                 <para>
145                 The name of the db table where subscription states are stored.
146                 </para>
147                 <para>
148                 <emphasis>      Default value is <quote>watchers</quote>.
149                 </emphasis>
150                 </para>
151                 <example>
152                 <title>Set <varname>watchers_table</varname> parameter</title>
153                 <programlisting format="linespecific">
154 ...
155 modparam("presence", "watchers_table", "watchers")
156 ...
157 </programlisting>
158                 </example>
159         </section>
160         <section id="presence.p.clean_period">
161                 <title><varname>clean_period</varname> (int)</title>
162                 <para>
163                 The period in seconds between checks if there are expired messages stored in database.
164                 </para>
165                 <para>
166                 <emphasis>Default value is <quote>100</quote>. A zero or negative value disables this activity.
167                 </emphasis>
168                 </para>
169                 <example>
170                 <title>Set <varname>clean_period</varname> parameter</title>
171                 <programlisting format="linespecific">
172 ...
173 modparam("presence", "clean_period", 100)
174 ...
175 </programlisting>
176                 </example>
177         </section>
178         <section id="presence.p.db_update_period">
179                 <title><varname>db_update_period</varname> (int)</title>
180                 <para>
181                 The period at which to synchronize cached subscriber info with the
182                 database.
183                 </para>
184                 <para>
185                 <emphasis>Default value is <quote>100</quote>. A zero or negative value disables synchronization.
186                 </emphasis>
187                 </para>
188                 <example>
189                 <title>Set <varname>db_update_period</varname> parameter</title>
190                 <programlisting format="linespecific">
191 ...
192 modparam("presence", "db_update_period", 100)
193 ...
194 </programlisting>
195                 </example>
196         </section>
197
198         <section id="presence.p.waitn_time">
199                 <title><varname>waitn_time</varname> (int)</title>
200                 <para>
201                 The maximum time period that NOTIFY requests will
202                 be buffered for.  The server will attempt to send
203                 NOTIFY requests within many seconds of a change occurring.
204                 </para>
205                 <para>
206                 Note: this parameter is only used when notifier_processes is
207                 greater than 0. When notifier_processes is less than or equal
208                 to 0 NOTIFY requests are sent immediately.
209                 </para>
210                 <para>
211                 <emphasis>Default value is <quote>5</quote>.
212                 </emphasis>
213                 </para>
214                 <example>
215                 <title>Set <varname>waitn_time</varname> parameter</title>
216                 <programlisting format="linespecific">
217 ...
218 modparam("presence", "waitn_time", 10)
219 ...
220 </programlisting>
221                 </example>
222         </section>
223
224         <section id="presence.p.notifier_poll_rate">
225                 <title><varname>notifier_poll_rate</varname> (int)</title>
226                 <para>
227                 The number of times per second that the notifier processes
228                 should check for work.  Approximately
229                 1/(waitn_time * notifier_poll_rate * notifier_processes) of the
230                 pending updates will be sent each time a notifier process runs.
231                 </para>
232                 <para>
233                 Separate notifier processes are only run when subs_db_mode is 3
234                 (DB only mode).
235                 </para>
236                 <para>
237                 <emphasis>Default value is <quote>10</quote>.
238                 </emphasis>
239                 </para>
240                 <example>
241                 <title>Set <varname>notifier_poll_rate</varname> parameter</title>
242                 <programlisting format="linespecific">
243 ...
244 modparam("presence", "notifier_poll_rate", 20)
245 ...
246 </programlisting>
247                 </example>
248         </section>
249
250         <section id="presence.p.notifier_processes">
251                 <title><varname>notifier_processes</varname> (int)</title>
252                 <para>
253                 The number of notifier processes that should be started.
254                 </para>
255                 <para>
256                 Separate notifier processes are only run when subs_db_mode is
257                 3 (DB only mode).
258                 </para>
259                 <para>
260                 Note: setting this parameter to 0 when subs_db_mode is 3
261                 keeps the old behaviour (sending NOTIFY requests immediately).
262                 This (old) behaviour is disabled by default in DB only mode
263                 because under load, when lots of NOTIFY requests can be sent
264                 on a dialog at the same time, there are race conditions which
265                 result in CSeq re-use.
266                 </para>
267                 <para>
268                 <emphasis>Default value is <quote>1</quote>.
269                 </emphasis>
270                 </para>
271                 <example>
272                 <title>Set <varname>notifier_processes</varname> parameter</title>
273                 <programlisting format="linespecific">
274 ...
275 modparam("presence", "notifier_processes", 2)
276 ...
277 </programlisting>
278                 </example>
279         </section>
280
281         <section id="presence.p.force_delete">
282                 <title><varname>force_delete</varname> (int)</title>
283                 <para>
284                 Enabling this parameter will delete expired presentity records without updating watchers.
285                 </para>
286                 <para>
287                 Set this parameter to <quote>1</quote> to enable.
288                 </para>
289                 <para>
290                 <emphasis>Default value is <quote>0</quote>.
291                 </emphasis>
292                 </para>
293                 <example>
294                 <title>Set <varname>force_delete</varname> parameter</title>
295                 <programlisting format="linespecific">
296 ...
297 modparam("presence", "force_delete", 1)
298 ...
299 </programlisting>
300                 </example>
301         </section>
302
303         <section id="presence.p.to_tag_pref">
304                 <title><varname>to_tag_pref</varname> (str)</title>
305                 <para>
306                 The prefix used when generating to_tag when sending replies for
307                 SUBSCRIBE requests.
308                 </para>
309                 <para>
310                 <emphasis>Default value is <quote>10</quote>.
311                 </emphasis>
312                 </para>
313                 <example>
314                 <title>Set <varname>to_tag_pref</varname> parameter</title>
315                 <programlisting format="linespecific">
316 ...
317 modparam("presence", "to_tag_pref", 'pres')
318 ...
319         </programlisting>
320                 </example>
321         </section>
322
323         <section id="presence.p.expires_offset">
324                 <title><varname>expires_offset</varname> (int)</title>
325                 <para>
326                 The value in seconds that should be subtracted from the expires value when
327                 sending a 200OK for a publish. It is used for forcing the client
328                 to send an update before the old publish expires.
329                 </para>
330                 <para>
331                 <emphasis>Default value is <quote>0</quote>.
332                 </emphasis>
333                 </para>
334                 <example>
335                 <title>Set <varname>expires_offset</varname> parameter</title>
336                 <programlisting format="linespecific">
337 ...
338 modparam("presence", "expires_offset", 10)
339 ...
340 </programlisting>
341                 </example>
342
343 </section>
344        <section id="presence.p.max_expires">
345                <title><varname>max_expires</varname> (int)</title>
346                <para>
347                The maximum admissible expires value for PUBLISH/SUBSCRIBE
348                message (in seconds).
349                </para>
350                <para>
351                <emphasis>Default value is <quote>3600</quote>.
352                </emphasis>
353                </para>
354                <example>
355                <title>Set <varname>max_expires</varname> parameter</title>
356                <programlisting format="linespecific">
357 ...
358 modparam("presence", "max_expires", 3600)
359 ...
360 </programlisting>
361         </example>
362 </section>
363
364 <section id="presence.p.min_expires">
365     <title><varname>min_expires</varname> (int)</title>
366     <para>
367         The minimum admissible expires value for PUBLISH/SUBSCRIBE
368         message (in seconds).
369     </para>
370     <para>
371         If &gt; 0 then min_expires_action parameter determines the response.
372     </para>
373     <para>
374         <emphasis>Default value is <quote>0</quote>.
375         </emphasis>
376     </para>
377     <example>
378         <title>Set <varname>min_expires</varname> parameter</title>
379         <programlisting format="linespecific">
380             ...
381             modparam("presence", "min_expires", 1800)
382             ...
383         </programlisting>
384     </example>
385 </section>
386
387 <section id="presence.p.min_expires_action">
388     <title><varname>min_expires_action</varname> (int)</title>
389     <para>
390         The action to take when UA sends a expires value less then min_expires.
391     </para>
392     <para>
393         <itemizedlist>
394             <title>Possible Values</title>
395             <listitem>
396                 <para> 1 : RFC Compliant, returns <quote>423 Interval Too Brief</quote></para>
397             </listitem>
398             <listitem>
399                 <para> 2 : forces the min_expires value in the subscription</para>
400             </listitem>
401         </itemizedlist>
402     </para>
403     <para>
404         If &gt; 0 then min_expires_action parameter determines the response.
405     </para>
406     <para>
407         <emphasis>Default value is <quote>1</quote>.</emphasis>
408     </para>
409     <example>
410         <title>Set <varname>min_expires</varname> parameter</title>
411         <programlisting format="linespecific">
412             ...
413             modparam("presence", "min_expires", 1800)
414             ...
415         </programlisting>
416     </example>
417 </section>
418
419 <section id="presence.p.server_address">
420                 <title><varname>server_address</varname> (str)</title>
421                 <para>
422                 The presence server address which will become the value of Contact header filed
423                 for 200 OK replies to SUBSCRIBE and PUBLISH and in NOTIFY messages.
424                 </para>
425                 <example>
426                 <title>Set <varname>server_address</varname> parameter</title>
427                 <programlisting format="linespecific">
428 ...
429 modparam("presence", "server_address", "sip:10.10.10.10:5060")
430 ...
431 </programlisting>
432                 </example>
433         </section>
434
435 <section id="presence.p.subs_db_mode">
436                 <title><varname>subs_db_mode</varname> (int)</title>
437                 <para>
438                 The presence module can utilize database for persistent subscription storage.
439                 If you use database, your subscriptions will survive machine restarts or
440                 SW crashes. The disadvantage is that accessing database can be time consuming.
441                 Therefore, presence module implements four database accessing modes:
442                 </para>
443                 <itemizedlist>
444                 <listitem>
445                         <para>
446                         0 - This disables database completely. Only memory will be used.
447                         Subscriptions will not survive restart. Use this value if you need a
448                         really fast presence module and subscription persistence is not necessary or
449                         is provided by other means.
450                         </para>
451                 </listitem>
452                 <listitem>
453                         <para>
454                         1 - Write-Through scheme. Subscriptions are updated synchronously
455                         in database and in memory(used for read operations). Use this
456                         scheme if speed is not top priority, but it's important that no
457                         subscriptions will be lost during crash or reboot or if you have
458                         an external application that reads the state of the subscriptions
459                         from database and they need to be updated synchronously.
460                         </para>
461                 </listitem>
462                 <listitem>
463                         <para>
464                         2 - Write-Back scheme. This is a combination of previous two
465                         schemes. All changes are made to memory and database
466                         synchronization is done in the timer. The timer deletes all
467                         expired contacts and flushes all modified or new subscriptions to
468                         database. Use this scheme if you encounter high-load peaks
469                         and want them to process as fast as possible. Latency of this
470                         mode is much lower than latency of mode 1, but slightly higher
471                         than latency of mode 0. To control the interval at which data is
472                         flushed to database, set the <emphasis>db_update_period</emphasis>
473                         parameter.
474                         </para>
475                 </listitem>
476                 <listitem>
477                         <para>
478                         3 - DB-Only scheme. No memory cache is kept, all operations being
479                         directly performed with the database. The timer deletes all expired
480                         subscriptions from database. The mode is useful if you configure
481                         more servers sharing the same DB without any replication at SIP
482                         level. The mode may be slower due the high number of DB operation.
483                         </para>
484                 </listitem>
485                 </itemizedlist>
486                 <para>
487                 <emphasis>Default value is 2 (Write-Back scheme).</emphasis>
488                 </para>
489
490                 <example>
491                 <title>Set <varname>subs_db_mode</varname> parameter</title>
492                 <programlisting format="linespecific">
493 ...
494 modparam("presence", "subs_db_mode", 1)
495 ...
496 </programlisting>
497                 </example>
498         </section>
499
500         <section id="presence.p.publ_cache">
501                 <title><varname>publ_cache</varname> (int)</title>
502                 <para>
503                 To improve performance, the presence module holds by default a
504                 publish cache that says if a certain publication exists in database.
505                 This is only a list of URI + event, so it does not use much memory.
506                 The cache is used when a Subscription is received to check if there
507                 is any published state in database. This way unnecessary queries in
508                 presentity table are avoided.
509                 </para>
510                 <para>
511                 Setting this parameter to 0 will disable the usage of the publish
512                 cache. This is desirable when you have more servers sharing the same
513                 database or there are other external entities inserting data into the
514                 presentity table.
515                 </para>
516                 <para>
517                 <emphasis>Default value is <quote>1</quote>.
518                 </emphasis>
519                 </para>
520                 <example>
521                 <title>Set <varname>publ_cache</varname> parameter</title>
522                 <programlisting format="linespecific">
523 ...
524 modparam("presence", "publ_cache", 0)
525 ...
526         </programlisting>
527                 </example>
528         </section>
529
530         <section id="presence.p.subs_htable_size">
531                 <title><varname>subs_htable_size</varname> (int)</title>
532                 <para>
533                 The size of the in-memory hash table to store subscription dialogs.
534                 This parameter will be used as the power of 2 when computing table size.
535                 </para>
536                 <para>
537                 <emphasis>Default value is <quote>9 (512)</quote>.
538                 </emphasis>
539                 </para>
540                 <example>
541                 <title>Set <varname>subs_htable_size</varname> parameter</title>
542                 <programlisting format="linespecific">
543 ...
544 modparam("presence", "subs_htable_size", 11)
545 ...
546         </programlisting>
547                 </example>
548         </section>
549
550         <section id="presence.p.pres_htable_size">
551                 <title><varname>pres_htable_size</varname> (int)</title>
552                 <para>
553                 The size of the in-memory hash table to store publish records.
554                 This parameter will be used as the power of 2 when computing table size.
555                 </para>
556                 <para>
557                 <emphasis>Default value is <quote>9 (512)</quote>.
558                 </emphasis>
559                 </para>
560                 <example>
561                 <title>Set <varname>pres_htable_size</varname> parameter</title>
562                 <programlisting format="linespecific">
563 ...
564 modparam("presence", "pres_htable_size", 11)
565 ...
566         </programlisting>
567                 </example>
568         </section>
569         <section id="presence.p.send_fast_notify">
570                 <title><varname>send_fast_notify</varname> (int)</title>
571                 <para>
572                 This parameter enables or disables the sending of an initial empty NOTIFY after a SUBSCRIBE/reSUBSCRIBE.
573                 This caused problems for MWI application, because some CPEs (like Samsung) fail to understand an empty
574                 NOTIFY to an message-summary event. This parameter is enabled by default, thus addering to the standard.
575                 </para>
576                 <para>
577                 <emphasis>Default value is <quote>1 </quote>.
578                 </emphasis>
579                 </para>
580                 <example>
581                 <title>Set <varname>send_fast_notify</varname> parameter</title>
582                 <programlisting format="linespecific">
583 ...
584 modparam("presence", "send_fast_notify", 0)
585 ...
586         </programlisting>
587                 </example>
588         </section>
589
590         <section id="presence.p.enable_sphere_check">
591                 <title><varname>enable_sphere_check</varname> (int)</title>
592                 <para>
593                 This parameter is a flag that should be set if permission rules include
594                 sphere checking.
595                 The sphere information is expected to be present in the RPID body
596                 published by the presentity. The flag is introduced as this check requires
597                 extra processing that should be avoided if this feature is not supported
598                 by the clients.
599                 </para>
600                 <para>
601                 <emphasis>Default value is <quote>0 </quote>.
602                 </emphasis>
603                 </para>
604                 <example>
605                 <title>Set <varname>enable_sphere_check</varname> parameter</title>
606                 <programlisting format="linespecific">
607 ...
608 modparam("presence", "enable_sphere_check", 1)
609 ...
610         </programlisting>
611                 </example>
612         </section>
613
614         <section id="presence.p.timeout_rm_subs">
615                 <title><varname>timeout_rm_subs</varname> (int)</title>
616                 <para>
617                 This parameter is a flag that should be set if subscriptions should be
618                 removed from the active_watchers when a NOTIFY times out. RFC3265
619                 section 3.2.2 defines this behaviour as a SHOULD, so by default it is
620                 on. Disabling this will keep subscriptions active on unreliable
621                 networks.
622                 </para>
623                 <para>
624                 <emphasis>Default value is <quote>1</quote>.
625                 </emphasis>
626                 </para>
627                 <example>
628                 <title>Set <varname>timeout_rm_subs</varname> parameter</title>
629                 <programlisting format="linespecific">
630 ...
631 modparam("presence", "timeout_rm_subs", 0)
632 ...
633         </programlisting>
634                 </example>
635         </section>
636         <section id="presence.p.fetch_rows">
637             <title><varname>fetch_rows</varname> (integer)</title>
638             <para>
639                 Number of rows to be loaded in one step from database.
640             </para>
641             <para>
642                 <emphasis>
643                     Default value is 500.
644                 </emphasis>
645             </para>
646             <example>
647                 <title>Set <varname>fetch_rows</varname> parameter</title>
648                 <programlisting format="linespecific">
649 ...
650 modparam("presence", "fetch_rows", 1000)
651 ...
652 </programlisting>
653             </example>
654         </section>
655         <section id="presence.p.db_table_lock_type">
656             <title><varname>db_table_lock_type</varname> (integer)</title>
657             <para>
658                 Enable (=1) or disable (=0) the Locks for table during an
659                 transaction. Locking only the "current" table causes problems
660                 with a MySQL-Databases in "DB-Only" mode.
661             </para>
662             <para>
663                 In order to use the Presence-Module in "DB_ONLY"-mode with a
664                 MySQL-Backend, set this parameter to "0", otherwise the
665                 MySQL-Operations will fail. The Presence-Module will generate
666                 a "500 Server error" due to the failed MySQL-queries.
667             </para>
668             <para>
669                 <emphasis>
670                     Default value is 1 (Write Lock for the Tables).
671                 </emphasis>
672             </para>
673             <example>
674                 <title>Set <varname>db_table_lock_type</varname> parameter</title>
675                 <programlisting format="linespecific">
676 ...
677 modparam("presence", "db_table_lock_type", 0)
678 ...
679 </programlisting>
680             </example>
681         </section>
682         <section id="presence.p.local_log_level">
683             <title><varname>local_log_level</varname> (int)</title>
684             <para>
685                 Control log level for some debug messages inside the module.
686             </para>
687             <para>
688                 <emphasis>
689                     Default value is 2 (L_INFO).
690                 </emphasis>
691             </para>
692             <example>
693                 <title>Set <varname>local_log_level</varname> parameter</title>
694                 <programlisting format="linespecific">
695 ...
696 modparam("presence", "local_log_level", 3)
697 ...
698 </programlisting>
699             </example>
700         </section>
701         <section id="presence.p.subs_remove_match">
702             <title><varname>subs_remove_match</varname> (int)</title>
703             <para>
704                 Control how to match the subscriptions to remove from memory.
705                 If set to 0, then the match is done on To-Tag (local generated),
706                 if set to 1, then the match is done on all dialog attributes
707                 (Call-Id, From-Tag, To-Tag).
708             </para>
709             <para>
710                 <emphasis>
711                     Default value is 0.
712                 </emphasis>
713             </para>
714             <example>
715                 <title>Set <varname>subs_remove_match</varname> parameter</title>
716                 <programlisting format="linespecific">
717 ...
718 modparam("presence", "subs_remove_match", 1)
719 ...
720 </programlisting>
721             </example>
722         </section>
723         <section id="presence.p.xavp_cfg">
724     <title><varname>xavp_cfg</varname> (str)</title>
725     <para>
726                 The name of the xavp to be used to specify attributes for internal
727                 processing of presence module.
728     </para>
729     <para>
730                 Inner attributes inside xavp can be:
731     </para>
732     <itemizedlist>
733         <listitem>
734                         <para><emphasis>priority</emphasis> - integer value to set the
735                         priority of the presence document (higher value, higher priority).
736                         It can set the order of the aggregated presence documents sent by
737                         NOTIFY (first the document with higher priority). If xavp_cfg
738                         parameter is set but this attribute is not in the avp,
739                         the priority of the presence document is based on timestamp,
740                         so newer documents have higher priority.</para>
741         </listitem>
742      </itemizedlist>
743     <para>
744         Default value is <emphasis>empty</emphasis> (not set).
745     </para>
746     <example>
747         <title>Set <varname>xavp_cfg</varname> parameter</title>
748         <programlisting format="linespecific">
749 ...
750 modparam("presence", "xavp_cfg", "pres")
751 ...
752 if(is_method("PUBLISH")) {
753     $xavp(pres=>priority) = 100;
754 }
755 ...
756 </programlisting>
757     </example>
758         </section>
759
760         <section id="presence.p.retrieve_order">
761             <title><varname>retrieve_order</varname> (int)</title>
762             <para>
763                 If set to 0, presentity records are retrieve by received_time order.
764                 if set to 1, presentity records are retrieve by priority order.
765             </para>
766             <para>
767                 <emphasis>
768                     Default value is 0.
769                 </emphasis>
770             </para>
771             <example>
772                 <title>Set <varname>retrieve_order</varname> parameter</title>
773                 <programlisting format="linespecific">
774 ...
775 modparam("presence", "retrieve_order", 1)
776 ...
777 </programlisting>
778             </example>
779         </section>
780
781 <section id="presence.p.sip_uri_match">
782     <title><varname>sip_uri_match</varname> (int)</title>
783     <para>
784         The mode used when comparing uris.
785     </para>
786     <para>
787         <itemizedlist>
788             <title>Possible Values</title>
789             <listitem>
790                 <para> 0 : case sensitive</para>
791             </listitem>
792             <listitem>
793                 <para> 1 : case insensitive</para>
794             </listitem>
795         </itemizedlist>
796     </para>
797     <para>
798         <emphasis>Default value is <quote>0</quote>.</emphasis>
799     </para>
800     <example>
801         <title>Set <varname>sip_uri_match</varname> parameter</title>
802         <programlisting format="linespecific">
803             ...
804             modparam("presence", "sip_uri_match", 1)
805             ...
806         </programlisting>
807     </example>
808 </section>
809
810 </section>
811
812 <section>
813         <title>Functions</title>
814         <section id="presence.f.handle_publish">
815                 <title>
816                 <function moreinfo="none">handle_publish([sender_uri])</function>
817                 </title>
818                 <para>
819                 Handles PUBLISH requests by storing and updating
820                 published information in memory cache and database, then calls functions to send
821                 NOTIFY messages when changes in the published information occur.
822                 It takes one argument -> sender_uri. The parameter was added
823                 for enabling BLA implementation. If present, notification of
824                 a change in published state is not sent to the respective uri
825                 even though a subscription exists.
826                 It should be taken from the Sender header. It was left at the
827                 decision of the administrator whether or not to transmit the
828                 content of this header as parameter for handle_publish, to
829                 prevent security problems.
830                 </para>
831                 <para>
832                 This function can be used from REQUEST_ROUTE.
833                 </para>
834                 <para>
835                 <emphasis>Return code:</emphasis>
836                 <itemizedlist>
837                         <listitem>
838                         <para>
839                                 <emphasis> 1 - if success</emphasis>.
840                         </para>
841                         </listitem>
842                         <listitem>
843                         <para>
844                                 <emphasis> -1 - if error</emphasis>.
845                         </para>
846                         </listitem>
847                 </itemizedlist>
848                 </para>
849                 <para>
850                         The module sends an appropriate stateless reply
851                         in all cases.
852                 </para>
853
854                 <example>
855                 <title><function>handle_publish</function> usage</title>
856                 <programlisting format="linespecific">
857 ...
858         if(is_method("PUBLISH"))
859         {
860                 if($hdr(Sender)!= NULL)
861                         handle_publish("$hdr(Sender)");
862                 else
863                         handle_publish();
864                 t_release();
865         }
866 ...
867 </programlisting>
868                 </example>
869         </section>
870
871         <section id="presence.f.handle_subscribe">
872                 <title>
873                 <function moreinfo="none">handle_subscribe([watcher_uri])</function>
874                 </title>
875                 <para>
876                 The function which handles SUBSCRIBE requests. It stores or
877                 updates information in memory and database and calls functions to send NOTIFY
878                 messages when a SUBSCRIBE which initiate a dialog is received.
879                 </para>
880                 <para>
881                 By default this function uses the From: URI from the SUBSCRIBE
882                 request as the Watcher URI.  The optional watcher_uri parameter
883                 can be used to specify a different Watcher URI, possibly taken
884                 from a SIP header like P-Asserted-Identity:.
885                 </para>
886                 <para>
887                 This function can be used from REQUEST_ROUTE.
888                 </para>
889                 <para>
890                 <emphasis>Return code:</emphasis>
891                 <itemizedlist>
892                         <listitem>
893                         <para>
894                                 <emphasis> 1 - if success</emphasis>.
895                         </para>
896                         </listitem>
897                         <listitem>
898                         <para>
899                                 <emphasis> -1 - if error</emphasis>.
900                         </para>
901                         </listitem>
902                 </itemizedlist>
903                 </para>
904                 <para>
905                         The module sends an appropriate stateless reply
906                         in all cases.
907                 </para>
908
909                 <example>
910                 <title><function>handle_subscribe</function> usage</title>
911                 <programlisting format="linespecific">
912 ...
913 if(method=="SUBSCRIBE")
914     handle_subscribe();
915 ...
916 </programlisting>
917                 </example>
918         </section>
919
920         <section id="presence.f.pres_auth_status">
921                 <title>
922                 <function moreinfo="none">pres_auth_status(watcher_uri, presentity_uri)</function>
923                 </title>
924                 <para>
925                 The function checks if watcher is authorized to subscribe
926                 event 'presence' of presentity.  Both watcher_uri and
927                 presentity_uri are pseudo variables.  Function returns
928                 ACTIVE_STATUS, if subscription is allowed and
929                 PENDING_STATUS, TERMINATED_STATUS, or WAITING_STATUS
930                 otherwise.  See presence/subscribe.h for the
931                 corresponding integer codes.  In case of error, function
932                 returns -1.
933                 </para>
934                 <para>
935                 This function can be used from REQUEST_ROUTE.
936                 </para>
937
938                 <example>
939                 <title><function>pres_auth_status</function> usage</title>
940                 <programlisting format="linespecific">
941 ...
942 if (method=="MESSAGE") {
943     pres_auth_status("$fu", $ru");
944     if ($retcode == 1) {
945         t_relay();
946     } else {
947         send_reply("403", "Forbidden");
948     }
949 }
950 ...
951 </programlisting>
952                 </example>
953         </section>
954
955         <section id="presence.f.pres_refresh_watchers">
956                 <title>
957                 <function moreinfo="none">pres_refresh_watchers(uri, event, type[, file_uri, filename])</function>
958                 </title>
959                 <para>
960                         The function can be used in configuration to triger notifies to watchers
961                         if a change in watchers authorization or in published state occurred
962                         (i.e., updates of xcap documents).
963                 </para>
964                 <para>Parameters:</para>
965                 <itemizedlist>
966                         <listitem>
967                                 <para>uri - the uri of the user who made the change
968                                 and whose watchers should be informed.</para>
969                         </listitem>
970                         <listitem>
971                                 <para>event - the event package.</para>
972                         </listitem>
973                         <listitem>
974                                 <para>type - it distinguishes between the three different types of events
975                                                 that can trigger the refresh, depending on its value:
976                                                 <itemizedlist>
977                                                         <listitem>
978                                                                 <para>0 - a change in watchers authentication.</para>
979                                                         </listitem>
980                                                         <listitem>
981                                                                 <para>1 - a statical update in published state through direct
982                                                                 update in db table.
983                                                                 </para>
984                                                         </listitem>
985                                                         <listitem>
986                                                                 <para>2 - a statical update in published state by modifying
987                                                                 the pidf manipulation document.
988                                                                 </para>
989                                                         </listitem>
990                                                 </itemizedlist>
991                                 </para>
992                         </listitem>
993                         <listitem>
994                                 <para>file_uri - the uri of the pidf-manipulation file on
995                                 the XCAP server (only used for type 2).</para>
996                         </listitem>
997                         <listitem>
998                                 <para>filename - the name of the pidf-manipulation file on
999                                 the XCAP server (only used for type 2).</para>
1000                         </listitem>
1001                 </itemizedlist>
1002                 <para>
1003                 This function can be used from ANY_ROUTE.
1004                 </para>
1005                 <example>
1006                 <title><function>pres_refresh_watchers</function> usage</title>
1007                 <programlisting format="linespecific">
1008 ...
1009 pres_refresh_watchers("sip:test@kamailio.org", "presence", 1);
1010 ...
1011 </programlisting>
1012                 </example>
1013         </section>
1014
1015         <section id="presence.f.pres_update_whatchers">
1016                 <title>
1017                 <function moreinfo="none">pres_update_watchers(uri, event)</function>
1018                 </title>
1019                 <para>
1020                         The function can be used in configuration to triger updates to watchers
1021                         status if a change in watchers authorization state occurred
1022                         (i.e., updates of xcap documents change state from pending to active).
1023                 </para>
1024                 <para>Parameters:</para>
1025                 <itemizedlist>
1026                         <listitem>
1027                                 <para>uri - the uri of the user who made the change
1028                                 and whose watchers should be informed. Can be PV.</para>
1029                         </listitem>
1030                         <listitem>
1031                                 <para>event - the event package (e.g., presence).</para>
1032                         </listitem>
1033         </itemizedlist>
1034                 <para>
1035                 This function can be used from ANY_ROUTE.
1036                 </para>
1037                 <example>
1038                 <title><function>pres_update_watchers</function> usage</title>
1039                 <programlisting format="linespecific">
1040 ...
1041 pres_update_watchers("sip:test@kamailio.org", "presence");
1042 ...
1043 </programlisting>
1044                 </example>
1045         </section>
1046 </section>
1047
1048 <section>
1049         <title>MI Commands</title>
1050         <section>
1051                 <title>
1052                 <function moreinfo="none">refreshWatchers</function>
1053                 </title>
1054                 <para>
1055                 Triggers sending Notify messages to watchers if a change in watchers
1056                 authorization or in published state occurred.
1057                 </para>
1058                 <para>
1059                 Name: <emphasis>refreshWatchers</emphasis>
1060                 </para>
1061                 <para>Parameters:</para>
1062                 <itemizedlist>
1063                         <listitem>
1064                                 <para>uri - the uri of the user who made the change
1065                                 and whose watchers should be informed</para>
1066                         </listitem>
1067                         <listitem>
1068                                 <para>event - the event package.</para>
1069                         </listitem>
1070                         <listitem>
1071                                 <para>type - it distinguishes between the three different types of events
1072                                                 that can trigger the refresh, depending on its value:
1073                                                 <itemizedlist>
1074                                                         <listitem>
1075                                                                 <para>0 - a change in watchers authentication.</para>
1076                                                         </listitem>
1077                                                         <listitem>
1078                                                                 <para>1 - a statical update in published state through direct
1079                                                                 update in db table.
1080                                                                 </para>
1081                                                         </listitem>
1082                                                         <listitem>
1083                                                                 <para>2 - a statical update in published state by modifying
1084                                                                 the pidf manipulation document.
1085                                                                 </para>
1086                                                         </listitem>
1087                                                 </itemizedlist>
1088                                 </para>
1089                         </listitem>
1090                         <listitem>
1091                                 <para>file_uri - the uri of the pidf-manipulation file on
1092                                 the XCAP server (only used for type 2).</para>
1093                         </listitem>
1094                         <listitem>
1095                                 <para>filename - the name of the pidf-manipulation file on
1096                                 the XCAP server (only used for type 2).</para>
1097                         </listitem>
1098                 </itemizedlist>
1099         <para>
1100                 MI FIFO Command Format:
1101                 </para>
1102         <programlisting  format="linespecific">
1103                 :refreshWatchers:fifo_reply
1104                 sip:test@kamailio.org
1105                 presence
1106                 1
1107                 _empty_line_
1108                 </programlisting>
1109         </section>
1110
1111         <section>
1112           <title>
1113                 <function moreinfo="none">cleanup</function>
1114           </title>
1115           <para>
1116                 Manually triggers the cleanup functions for the active_watchers, presentity,
1117                 and watchers tables. Useful if you have set <varname>clean_period</varname>
1118                 and/or <varname>db_update_period</varname> to zero or less.
1119           </para>
1120           <para>
1121                 Name: <emphasis>cleanup</emphasis>
1122           </para>
1123           <para>Parameters: <emphasis>none</emphasis></para>
1124
1125           <para>
1126                 MI FIFO Command Format:
1127           </para>
1128           <programlisting  format="linespecific">
1129                 :cleanup:fifo_reply
1130                 _empty_line_
1131           </programlisting>
1132         </section>
1133 </section>
1134
1135 <section>
1136         <title>RPC Commands</title>
1137         <section>
1138           <title>
1139                 <function moreinfo="none">presence.cleanup</function>
1140           </title>
1141           <para>
1142                 Manually triggers the cleanup functions for the active_watchers, presentity,
1143                 and watchers tables. Useful if you have set <varname>clean_period</varname>
1144                 and/or <varname>db_update_period</varname> to zero or less.
1145           </para>
1146           <para>
1147                 Name: <emphasis>presence.cleanup</emphasis>
1148           </para>
1149           <para>Parameters: <emphasis>none</emphasis></para>
1150
1151         </section>
1152 </section>
1153
1154 <section>
1155         <title>Pseudo Variables</title>
1156
1157                 <section>
1158                         <title><varname>$subs(attr)</varname></title>
1159                         <para>
1160                                 Access the attributes of handled subscription.
1161                                 It must be used after a successful call of
1162                                 <quote>handle_subscription()</quote> or in the following events.
1163                         <itemizedlist>
1164                                 <listitem>
1165                                 <para><emphasis>tm:local-request</emphasis> - before notify is sent
1166                                 </para>
1167                                 </listitem>
1168                                 <listitem>
1169                                 <para><emphasis>present:notify-reply</emphasis> - after notify is sent
1170                                 </para>
1171                                 </listitem>
1172                         </itemizedlist>
1173                         </para>
1174                         <para>
1175                         The <quote>attr</quote> can be:
1176                         </para>
1177                         <itemizedlist>
1178                                 <listitem>
1179                                 <para><emphasis>uri</emphasis> - subscription presentity uri
1180                                 </para>
1181                                 </listitem>
1182                                 <listitem>
1183                                 <para><emphasis>pres_uri</emphasis> - alias for presentity uri
1184                                 </para>
1185                                 </listitem>
1186                                 <listitem>
1187                                 <para><emphasis>to_user</emphasis>
1188                                 </para>
1189                                 </listitem>
1190                                 <listitem>
1191                                 <para><emphasis>to_domain</emphasis>
1192                                 </para>
1193                                 </listitem>
1194                                 <listitem>
1195                                 <para><emphasis>from_user</emphasis>
1196                                 </para>
1197                                 </listitem>
1198                                 <listitem>
1199                                 <para><emphasis>from_domain</emphasis>
1200                                 </para>
1201                                 </listitem>
1202                                 <listitem>
1203                                 <para><emphasis>watcher_username</emphasis>
1204                                 </para>
1205                                 </listitem>
1206                                 <listitem>
1207                                 <para><emphasis>watcher_domain</emphasis>
1208                                 </para>
1209                                 </listitem>
1210                                 <listitem>
1211                                 <para><emphasis>event</emphasis>
1212                                 </para>
1213                                 </listitem>
1214                                 <listitem>
1215                                 <para><emphasis>event_id</emphasis>
1216                                 </para>
1217                                 </listitem>
1218                                 <listitem>
1219                                 <para><emphasis>to_tag</emphasis>
1220                                 </para>
1221                                 </listitem>
1222                                 <listitem>
1223                                 <para><emphasis>from_tag</emphasis>
1224                                 </para>
1225                                 </listitem>
1226                                 <listitem>
1227                                 <para><emphasis>callid</emphasis>
1228                                 </para>
1229                                 </listitem>
1230                                 <listitem>
1231                                 <para><emphasis>remote_cseq</emphasis>
1232                                 </para>
1233                                 </listitem>
1234                                 <listitem>
1235                                 <para><emphasis>local_cseq</emphasis>
1236                                 </para>
1237                                 </listitem>
1238                                 <listitem>
1239                                 <para><emphasis>contact</emphasis>
1240                                 </para>
1241                                 </listitem>
1242                                 <listitem>
1243                                 <para><emphasis>local_contact</emphasis>
1244                                 </para>
1245                                 </listitem>
1246                                 <listitem>
1247                                 <para><emphasis>record_route</emphasis>
1248                                 </para>
1249                                 </listitem>
1250                                 <listitem>
1251                                 <para><emphasis>expires</emphasis>
1252                                 </para>
1253                                 </listitem>
1254                                 <listitem>
1255                                 <para><emphasis>status</emphasis>
1256                                 </para>
1257                                 </listitem>
1258                                 <listitem>
1259                                 <para><emphasis>reason</emphasis>
1260                                 </para>
1261                                 </listitem>
1262                                 <listitem>
1263                                 <para><emphasis>version</emphasis>
1264                                 </para>
1265                                 </listitem>
1266                                 <listitem>
1267                                 <para><emphasis>flags</emphasis>
1268                                 </para>
1269                                 </listitem>
1270                                 <listitem>
1271                                 <para><emphasis>user_agent</emphasis>
1272                                 </para>
1273                                 </listitem>
1274                         </itemizedlist>
1275
1276                         <example>
1277                         <title><function moreinfo="none">$subs(name)</function> usage</title>
1278 <programlisting format="linespecific">
1279 ...
1280 if(handle_subscription())
1281 {
1282   xlog("presentity=$subs(uri)\n");
1283 }
1284 ...
1285                                  </programlisting>
1286                         </example>
1287                 </section>
1288
1289                 <section>
1290                         <title><varname>$notify_reply(attr)</varname></title>
1291                         <para>
1292                                 Access the reply message received when notifying subscriber.
1293                                 It must be used in the following events.
1294                         <itemizedlist>
1295                                 <listitem>
1296                                 <para><emphasis>present:notify-reply</emphasis> - after notify is sent
1297                                 </para>
1298                                 </listitem>
1299                         </itemizedlist>
1300                         </para>
1301                         <para>
1302                         The <quote>attr</quote> can be any pseudo var that accesses attributes of msg
1303                         </para>
1304
1305                         <example>
1306                         <title><function moreinfo="none">$notify_reply(name)</function> usage</title>
1307 <programlisting format="linespecific">
1308 ...
1309 event_route[presence:notify-reply]
1310 {
1311   xlog("received message = $notify_reply($mb)\n");
1312 }
1313 ...
1314                                  </programlisting>
1315                         </example>
1316                 </section>
1317 </section>
1318
1319 <section>
1320         <title>Events</title>
1321                 <section>
1322                         <title><varname>present:notify-reply</varname></title>
1323                         <para>
1324                                 Fired after notify reply is received or timeout.
1325                         </para>
1326
1327                         <example>
1328                         <title><function moreinfo="none">$notify_reply(name)</function> usage</title>
1329 <programlisting format="linespecific">
1330 ...
1331 event_route[presence:notify-reply]
1332 {
1333   xlog("received message = $notify_reply($mb)\n");
1334 }
1335 ...
1336                                  </programlisting>
1337                         </example>
1338                 </section>
1339 </section>
1340
1341 <section>
1342         <title>Installation</title>
1343         <para>
1344         The module requires 3 tables in the &kamailio; database: "presentity",
1345         "active_watchers" and "watchers". The SQL
1346         syntax to create them can be found in presence-create.sql
1347         script in the database directories in the kamailio/scripts folder.
1348         You can also find the complete database documentation on the
1349         project webpage, &kamailiodbdocslink;.
1350         </para>
1351 </section>
1352
1353 </chapter>
1354