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