Browse code

presence: update to README content based on latest docbook files

Daniel-Constantin Mierla authored on 26/03/2015 20:18:49
Showing 1 changed files
... ...
@@ -45,22 +45,26 @@ Juha Heinanen
45 45
               3.10. to_tag_pref (str)
46 46
               3.11. expires_offset (int)
47 47
               3.12. max_expires (int)
48
-              3.13. server_address (str)
49
-              3.14. subs_db_mode (int)
50
-              3.15. publ_cache (int)
51
-              3.16. subs_htable_size (int)
52
-              3.17. pres_htable_size (int)
53
-              3.18. send_fast_notify (int)
54
-              3.19. enable_sphere_check (int)
55
-              3.20. timeout_rm_subs (int)
56
-              3.21. fetch_rows (integer)
57
-              3.22. db_table_lock_type (integer)
58
-              3.23. local_log_level (int)
59
-              3.24. subs_remove_match (int)
48
+              3.13. min_expires (int)
49
+              3.14. min_expires_action (int)
50
+              3.15. server_address (str)
51
+              3.16. subs_db_mode (int)
52
+              3.17. publ_cache (int)
53
+              3.18. subs_htable_size (int)
54
+              3.19. pres_htable_size (int)
55
+              3.20. send_fast_notify (int)
56
+              3.21. enable_sphere_check (int)
57
+              3.22. timeout_rm_subs (int)
58
+              3.23. fetch_rows (integer)
59
+              3.24. db_table_lock_type (integer)
60
+              3.25. local_log_level (int)
61
+              3.26. subs_remove_match (int)
62
+              3.27. xavp_cfg (str)
63
+              3.28. retrieve_order (int)
60 64
 
61 65
         4. Functions
62 66
 
63
-              4.1. handle_publish(char* sender_uri)
67
+              4.1. handle_publish([sender_uri])
64 68
               4.2. handle_subscribe([watcher_uri])
65 69
               4.3. pres_auth_status(watcher_uri, presentity_uri)
66 70
               4.4. pres_refresh_watchers(uri, event, type[, file_uri,
... ...
@@ -113,23 +117,27 @@ Juha Heinanen
113 113
    1.10. Set to_tag_pref parameter
114 114
    1.11. Set expires_offset parameter
115 115
    1.12. Set max_expires parameter
116
-   1.13. Set server_address parameter
117
-   1.14. Set subs_db_mode parameter
118
-   1.15. Set publ_cache parameter
119
-   1.16. Set subs_htable_size parameter
120
-   1.17. Set pres_htable_size parameter
121
-   1.18. Set send_fast_notify parameter
122
-   1.19. Set enable_sphere_check parameter
123
-   1.20. Set timeout_rm_subs parameter
124
-   1.21. Set fetch_rows parameter
125
-   1.22. Set db_table_lock_type parameter
126
-   1.23. Set local_log_level parameter
127
-   1.24. Set subs_remove_match parameter
128
-   1.25. handle_publish usage
129
-   1.26. handle_subscribe usage
130
-   1.27. pres_auth_status usage
131
-   1.28. pres_refresh_watchers usage
132
-   1.29. pres_update_watchers usage
116
+   1.13. Set min_expires parameter
117
+   1.14. Set min_expires parameter
118
+   1.15. Set server_address parameter
119
+   1.16. Set subs_db_mode parameter
120
+   1.17. Set publ_cache parameter
121
+   1.18. Set subs_htable_size parameter
122
+   1.19. Set pres_htable_size parameter
123
+   1.20. Set send_fast_notify parameter
124
+   1.21. Set enable_sphere_check parameter
125
+   1.22. Set timeout_rm_subs parameter
126
+   1.23. Set fetch_rows parameter
127
+   1.24. Set db_table_lock_type parameter
128
+   1.25. Set local_log_level parameter
129
+   1.26. Set subs_remove_match parameter
130
+   1.27. Set xavp_cfg parameter
131
+   1.28. Set retrieve_order parameter
132
+   1.29. handle_publish usage
133
+   1.30. handle_subscribe usage
134
+   1.31. pres_auth_status usage
135
+   1.32. pres_refresh_watchers usage
136
+   1.33. pres_update_watchers usage
133 137
    2.1. presence_api_t structure
134 138
 
135 139
 Chapter 1. Admin Guide
... ...
@@ -156,22 +164,26 @@ Chapter 1. Admin Guide
156 156
         3.10. to_tag_pref (str)
157 157
         3.11. expires_offset (int)
158 158
         3.12. max_expires (int)
159
-        3.13. server_address (str)
160
-        3.14. subs_db_mode (int)
161
-        3.15. publ_cache (int)
162
-        3.16. subs_htable_size (int)
163
-        3.17. pres_htable_size (int)
164
-        3.18. send_fast_notify (int)
165
-        3.19. enable_sphere_check (int)
166
-        3.20. timeout_rm_subs (int)
167
-        3.21. fetch_rows (integer)
168
-        3.22. db_table_lock_type (integer)
169
-        3.23. local_log_level (int)
170
-        3.24. subs_remove_match (int)
159
+        3.13. min_expires (int)
160
+        3.14. min_expires_action (int)
161
+        3.15. server_address (str)
162
+        3.16. subs_db_mode (int)
163
+        3.17. publ_cache (int)
164
+        3.18. subs_htable_size (int)
165
+        3.19. pres_htable_size (int)
166
+        3.20. send_fast_notify (int)
167
+        3.21. enable_sphere_check (int)
168
+        3.22. timeout_rm_subs (int)
169
+        3.23. fetch_rows (integer)
170
+        3.24. db_table_lock_type (integer)
171
+        3.25. local_log_level (int)
172
+        3.26. subs_remove_match (int)
173
+        3.27. xavp_cfg (str)
174
+        3.28. retrieve_order (int)
171 175
 
172 176
    4. Functions
173 177
 
174
-        4.1. handle_publish(char* sender_uri)
178
+        4.1. handle_publish([sender_uri])
175 179
         4.2. handle_subscribe([watcher_uri])
176 180
         4.3. pres_auth_status(watcher_uri, presentity_uri)
177 181
         4.4. pres_refresh_watchers(uri, event, type[, file_uri, filename])
... ...
@@ -245,18 +257,22 @@ Chapter 1. Admin Guide
245 245
    3.10. to_tag_pref (str)
246 246
    3.11. expires_offset (int)
247 247
    3.12. max_expires (int)
248
-   3.13. server_address (str)
249
-   3.14. subs_db_mode (int)
250
-   3.15. publ_cache (int)
251
-   3.16. subs_htable_size (int)
252
-   3.17. pres_htable_size (int)
253
-   3.18. send_fast_notify (int)
254
-   3.19. enable_sphere_check (int)
255
-   3.20. timeout_rm_subs (int)
256
-   3.21. fetch_rows (integer)
257
-   3.22. db_table_lock_type (integer)
258
-   3.23. local_log_level (int)
259
-   3.24. subs_remove_match (int)
248
+   3.13. min_expires (int)
249
+   3.14. min_expires_action (int)
250
+   3.15. server_address (str)
251
+   3.16. subs_db_mode (int)
252
+   3.17. publ_cache (int)
253
+   3.18. subs_htable_size (int)
254
+   3.19. pres_htable_size (int)
255
+   3.20. send_fast_notify (int)
256
+   3.21. enable_sphere_check (int)
257
+   3.22. timeout_rm_subs (int)
258
+   3.23. fetch_rows (integer)
259
+   3.24. db_table_lock_type (integer)
260
+   3.25. local_log_level (int)
261
+   3.26. subs_remove_match (int)
262
+   3.27. xavp_cfg (str)
263
+   3.28. retrieve_order (int)
260 264
 
261 265
 3.1. db_url(str)
262 266
 
... ...
@@ -414,8 +430,8 @@ modparam("presence", "expires_offset", 10)
414 414
 
415 415
 3.12. max_expires (int)
416 416
 
417
-   The the maximum admissible expires value for PUBLISH/SUBSCRIBE message
418
-   (in seconds).
417
+   The maximum admissible expires value for PUBLISH/SUBSCRIBE message (in
418
+   seconds).
419 419
 
420 420
    Default value is "3600".
421 421
 
... ...
@@ -424,18 +440,49 @@ modparam("presence", "expires_offset", 10)
424 424
 modparam("presence", "max_expires", 3600)
425 425
 ...
426 426
 
427
-3.13. server_address (str)
427
+3.13. min_expires (int)
428
+
429
+   The minimum admissible expires value for PUBLISH/SUBSCRIBE message (in
430
+   seconds).
431
+
432
+   If > 0 then min_expires_action parameter determines the response.
433
+
434
+   Default value is "0".
435
+
436
+   Example 1.13. Set min_expires parameter
437
+            ...
438
+            modparam("presence", "min_expires", 1800)
439
+            ...
440
+
441
+3.14. min_expires_action (int)
442
+
443
+   The action to take when UA sends a expires value less then min_expires.
444
+
445
+   Possible Values
446
+     * 1 : RFC Compliant, returns "423 Interval Too Brief"
447
+     * 2 : forces the min_expires value in the subscription
448
+
449
+   If > 0 then min_expires_action parameter determines the response.
450
+
451
+   Default value is "1".
452
+
453
+   Example 1.14. Set min_expires parameter
454
+            ...
455
+            modparam("presence", "min_expires", 1800)
456
+            ...
457
+
458
+3.15. server_address (str)
428 459
 
429 460
    The presence server address which will become the value of Contact
430 461
    header filed for 200 OK replies to SUBSCRIBE and PUBLISH and in NOTIFY
431 462
    messages.
432 463
 
433
-   Example 1.13. Set server_address parameter
464
+   Example 1.15. Set server_address parameter
434 465
 ...
435 466
 modparam("presence", "server_address", "sip:10.10.10.10:5060")
436 467
 ...
437 468
 
438
-3.14. subs_db_mode (int)
469
+3.16. subs_db_mode (int)
439 470
 
440 471
    The presence module can utilize database for persistent subscription
441 472
    storage. If you use database, your subscriptions will survive machine
... ...
@@ -469,12 +516,12 @@ modparam("presence", "server_address", "sip:10.10.10.10:5060")
469 469
 
470 470
    Default value is 2 (Write-Back scheme).
471 471
 
472
-   Example 1.14. Set subs_db_mode parameter
472
+   Example 1.16. Set subs_db_mode parameter
473 473
 ...
474 474
 modparam("presence", "subs_db_mode", 1)
475 475
 ...
476 476
 
477
-3.15. publ_cache (int)
477
+3.17. publ_cache (int)
478 478
 
479 479
    To improve performance, the presence module holds by default a publish
480 480
    cache that says if a certain publication exists in database. This is
... ...
@@ -490,12 +537,12 @@ modparam("presence", "subs_db_mode", 1)
490 490
 
491 491
    Default value is "1".
492 492
 
493
-   Example 1.15. Set publ_cache parameter
493
+   Example 1.17. Set publ_cache parameter
494 494
 ...
495 495
 modparam("presence", "publ_cache", 0)
496 496
 ...
497 497
 
498
-3.16. subs_htable_size (int)
498
+3.18. subs_htable_size (int)
499 499
 
500 500
    The size of the in-memory hash table to store subscription dialogs.
501 501
    This parameter will be used as the power of 2 when computing table
... ...
@@ -503,24 +550,24 @@ modparam("presence", "publ_cache", 0)
503 503
 
504 504
    Default value is "9 (512)".
505 505
 
506
-   Example 1.16. Set subs_htable_size parameter
506
+   Example 1.18. Set subs_htable_size parameter
507 507
 ...
508 508
 modparam("presence", "subs_htable_size", 11)
509 509
 ...
510 510
 
511
-3.17. pres_htable_size (int)
511
+3.19. pres_htable_size (int)
512 512
 
513 513
    The size of the in-memory hash table to store publish records. This
514 514
    parameter will be used as the power of 2 when computing table size.
515 515
 
516 516
    Default value is "9 (512)".
517 517
 
518
-   Example 1.17. Set pres_htable_size parameter
518
+   Example 1.19. Set pres_htable_size parameter
519 519
 ...
520 520
 modparam("presence", "pres_htable_size", 11)
521 521
 ...
522 522
 
523
-3.18. send_fast_notify (int)
523
+3.20. send_fast_notify (int)
524 524
 
525 525
    This parameter enables or disables the sending of an initial empty
526 526
    NOTIFY after a SUBSCRIBE/reSUBSCRIBE. This caused problems for MWI
... ...
@@ -530,12 +577,12 @@ modparam("presence", "pres_htable_size", 11)
530 530
 
531 531
    Default value is "1 ".
532 532
 
533
-   Example 1.18. Set send_fast_notify parameter
533
+   Example 1.20. Set send_fast_notify parameter
534 534
 ...
535 535
 modparam("presence", "send_fast_notify", 0)
536 536
 ...
537 537
 
538
-3.19. enable_sphere_check (int)
538
+3.21. enable_sphere_check (int)
539 539
 
540 540
    This parameter is a flag that should be set if permission rules include
541 541
    sphere checking. The sphere information is expected to be present in
... ...
@@ -545,12 +592,12 @@ modparam("presence", "send_fast_notify", 0)
545 545
 
546 546
    Default value is "0 ".
547 547
 
548
-   Example 1.19. Set enable_sphere_check parameter
548
+   Example 1.21. Set enable_sphere_check parameter
549 549
 ...
550 550
 modparam("presence", "enable_sphere_check", 1)
551 551
 ...
552 552
 
553
-3.20. timeout_rm_subs (int)
553
+3.22. timeout_rm_subs (int)
554 554
 
555 555
    This parameter is a flag that should be set if subscriptions should be
556 556
    removed from the active_watchers when a NOTIFY times out. RFC3265
... ...
@@ -560,23 +607,23 @@ modparam("presence", "enable_sphere_check", 1)
560 560
 
561 561
    Default value is "1".
562 562
 
563
-   Example 1.20. Set timeout_rm_subs parameter
563
+   Example 1.22. Set timeout_rm_subs parameter
564 564
 ...
565 565
 modparam("presence", "timeout_rm_subs", 0)
566 566
 ...
567 567
 
568
-3.21. fetch_rows (integer)
568
+3.23. fetch_rows (integer)
569 569
 
570 570
    Number of rows to be loaded in one step from database.
571 571
 
572 572
    Default value is 500.
573 573
 
574
-   Example 1.21. Set fetch_rows parameter
574
+   Example 1.23. Set fetch_rows parameter
575 575
 ...
576 576
 modparam("presence", "fetch_rows", 1000)
577 577
 ...
578 578
 
579
-3.22. db_table_lock_type (integer)
579
+3.24. db_table_lock_type (integer)
580 580
 
581 581
    Enable (=1) or disable (=0) the Locks for table during an transaction.
582 582
    Locking only the "current" table causes problems with a MySQL-Databases
... ...
@@ -589,23 +636,23 @@ modparam("presence", "fetch_rows", 1000)
589 589
 
590 590
    Default value is 1 (Write Lock for the Tables).
591 591
 
592
-   Example 1.22. Set db_table_lock_type parameter
592
+   Example 1.24. Set db_table_lock_type parameter
593 593
 ...
594 594
 modparam("presence", "db_table_lock_type", 0)
595 595
 ...
596 596
 
597
-3.23. local_log_level (int)
597
+3.25. local_log_level (int)
598 598
 
599 599
    Control log level for some debug messages inside the module.
600 600
 
601 601
    Default value is 2 (L_INFO).
602 602
 
603
-   Example 1.23. Set local_log_level parameter
603
+   Example 1.25. Set local_log_level parameter
604 604
 ...
605 605
 modparam("presence", "local_log_level", 3)
606 606
 ...
607 607
 
608
-3.24. subs_remove_match (int)
608
+3.26. subs_remove_match (int)
609 609
 
610 610
    Control how to match the subscriptions to remove from memory. If set to
611 611
    0, then the match is done on To-Tag (local generated), if set to 1,
... ...
@@ -614,20 +661,57 @@ modparam("presence", "local_log_level", 3)
614 614
 
615 615
    Default value is 0.
616 616
 
617
-   Example 1.24. Set subs_remove_match parameter
617
+   Example 1.26. Set subs_remove_match parameter
618 618
 ...
619 619
 modparam("presence", "subs_remove_match", 1)
620 620
 ...
621 621
 
622
+3.27. xavp_cfg (str)
623
+
624
+   The name of the xavp to be used to specify attributes for internal
625
+   processing of presence module.
626
+
627
+   Inner attributes inside xavp can be:
628
+     * priority - integer value to set the priority of the presence
629
+       document (higher value, higher priority). It can set the order of
630
+       the aggregated presence documents sent by NOTIFY (first the
631
+       document with higher priority). If xavp_cfg parameter is set but
632
+       this attribute is not in the avp, the priority of the presence
633
+       document is based on timestamp, so newer documents have higher
634
+       priority.
635
+
636
+   Default value is empty (not set).
637
+
638
+   Example 1.27. Set xavp_cfg parameter
639
+...
640
+modparam("presence", "xavp_cfg", "pres")
641
+...
642
+if(is_method("PUBLISH")) {
643
+    $xavp(pres=>priority) = 100;
644
+}
645
+...
646
+
647
+3.28. retrieve_order (int)
648
+
649
+   If set to 0, presentity records are retrieve by received_time order. if
650
+   set to 1, presentity records are retrieve by priority order.
651
+
652
+   Default value is 0.
653
+
654
+   Example 1.28. Set retrieve_order parameter
655
+...
656
+modparam("presence", "retrieve_order", 1)
657
+...
658
+
622 659
 4. Functions
623 660
 
624
-   4.1. handle_publish(char* sender_uri)
661
+   4.1. handle_publish([sender_uri])
625 662
    4.2. handle_subscribe([watcher_uri])
626 663
    4.3. pres_auth_status(watcher_uri, presentity_uri)
627 664
    4.4. pres_refresh_watchers(uri, event, type[, file_uri, filename])
628 665
    4.5. pres_update_watchers(uri, event)
629 666
 
630
-4.1. handle_publish(char* sender_uri)
667
+4.1. handle_publish([sender_uri])
631 668
 
632 669
    Handles PUBLISH requests by storing and updating published information
633 670
    in memory cache and database, then calls functions to send NOTIFY
... ...
@@ -647,7 +731,7 @@ modparam("presence", "subs_remove_match", 1)
647 647
 
648 648
    The module sends an appropriate stateless reply in all cases.
649 649
 
650
-   Example 1.25. handle_publish usage
650
+   Example 1.29. handle_publish usage
651 651
 ...
652 652
         if(is_method("PUBLISH"))
653 653
         {
... ...
@@ -678,7 +762,7 @@ modparam("presence", "subs_remove_match", 1)
678 678
 
679 679
    The module sends an appropriate stateless reply in all cases.
680 680
 
681
-   Example 1.26. handle_subscribe usage
681
+   Example 1.30. handle_subscribe usage
682 682
 ...
683 683
 if(method=="SUBSCRIBE")
684 684
     handle_subscribe();
... ...
@@ -695,7 +779,7 @@ if(method=="SUBSCRIBE")
695 695
 
696 696
    This function can be used from REQUEST_ROUTE.
697 697
 
698
-   Example 1.27. pres_auth_status usage
698
+   Example 1.31. pres_auth_status usage
699 699
 ...
700 700
 if (method=="MESSAGE") {
701 701
     pres_auth_status("$fu", $ru");
... ...
@@ -731,7 +815,7 @@ if (method=="MESSAGE") {
731 731
 
732 732
    This function can be used from ANY_ROUTE.
733 733
 
734
-   Example 1.28. pres_refresh_watchers usage
734
+   Example 1.32. pres_refresh_watchers usage
735 735
 ...
736 736
 pres_refresh_watchers("sip:test@kamailio.org", "presence", 1);
737 737
 ...
... ...
@@ -749,7 +833,7 @@ pres_refresh_watchers("sip:test@kamailio.org", "presence", 1);
749 749
 
750 750
    This function can be used from ANY_ROUTE.
751 751
 
752
-   Example 1.29. pres_update_watchers usage
752
+   Example 1.33. pres_update_watchers usage
753 753
 ...
754 754
 pres_update_watchers("sip:test@kamailio.org", "presence");
755 755
 ...