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 117
    1.10. Set to_tag_pref parameter
114 118
    1.11. Set expires_offset parameter
115 119
    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
120
+   1.13. Set min_expires parameter
121
+   1.14. Set min_expires parameter
122
+   1.15. Set server_address parameter
123
+   1.16. Set subs_db_mode parameter
124
+   1.17. Set publ_cache parameter
125
+   1.18. Set subs_htable_size parameter
126
+   1.19. Set pres_htable_size parameter
127
+   1.20. Set send_fast_notify parameter
128
+   1.21. Set enable_sphere_check parameter
129
+   1.22. Set timeout_rm_subs parameter
130
+   1.23. Set fetch_rows parameter
131
+   1.24. Set db_table_lock_type parameter
132
+   1.25. Set local_log_level parameter
133
+   1.26. Set subs_remove_match parameter
134
+   1.27. Set xavp_cfg parameter
135
+   1.28. Set retrieve_order parameter
136
+   1.29. handle_publish usage
137
+   1.30. handle_subscribe usage
138
+   1.31. pres_auth_status usage
139
+   1.32. pres_refresh_watchers usage
140
+   1.33. pres_update_watchers usage
133 141
    2.1. presence_api_t structure
134 142
 
135 143
 Chapter 1. Admin Guide
... ...
@@ -156,22 +164,26 @@ Chapter 1. Admin Guide
156 164
         3.10. to_tag_pref (str)
157 165
         3.11. expires_offset (int)
158 166
         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)
167
+        3.13. min_expires (int)
168
+        3.14. min_expires_action (int)
169
+        3.15. server_address (str)
170
+        3.16. subs_db_mode (int)
171
+        3.17. publ_cache (int)
172
+        3.18. subs_htable_size (int)
173
+        3.19. pres_htable_size (int)
174
+        3.20. send_fast_notify (int)
175
+        3.21. enable_sphere_check (int)
176
+        3.22. timeout_rm_subs (int)
177
+        3.23. fetch_rows (integer)
178
+        3.24. db_table_lock_type (integer)
179
+        3.25. local_log_level (int)
180
+        3.26. subs_remove_match (int)
181
+        3.27. xavp_cfg (str)
182
+        3.28. retrieve_order (int)
171 183
 
172 184
    4. Functions
173 185
 
174
-        4.1. handle_publish(char* sender_uri)
186
+        4.1. handle_publish([sender_uri])
175 187
         4.2. handle_subscribe([watcher_uri])
176 188
         4.3. pres_auth_status(watcher_uri, presentity_uri)
177 189
         4.4. pres_refresh_watchers(uri, event, type[, file_uri, filename])
... ...
@@ -245,18 +257,22 @@ Chapter 1. Admin Guide
245 257
    3.10. to_tag_pref (str)
246 258
    3.11. expires_offset (int)
247 259
    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)
260
+   3.13. min_expires (int)
261
+   3.14. min_expires_action (int)
262
+   3.15. server_address (str)
263
+   3.16. subs_db_mode (int)
264
+   3.17. publ_cache (int)
265
+   3.18. subs_htable_size (int)
266
+   3.19. pres_htable_size (int)
267
+   3.20. send_fast_notify (int)
268
+   3.21. enable_sphere_check (int)
269
+   3.22. timeout_rm_subs (int)
270
+   3.23. fetch_rows (integer)
271
+   3.24. db_table_lock_type (integer)
272
+   3.25. local_log_level (int)
273
+   3.26. subs_remove_match (int)
274
+   3.27. xavp_cfg (str)
275
+   3.28. retrieve_order (int)
260 276
 
261 277
 3.1. db_url(str)
262 278
 
... ...
@@ -414,8 +430,8 @@ modparam("presence", "expires_offset", 10)
414 430
 
415 431
 3.12. max_expires (int)
416 432
 
417
-   The the maximum admissible expires value for PUBLISH/SUBSCRIBE message
418
-   (in seconds).
433
+   The maximum admissible expires value for PUBLISH/SUBSCRIBE message (in
434
+   seconds).
419 435
 
420 436
    Default value is "3600".
421 437
 
... ...
@@ -424,18 +440,49 @@ modparam("presence", "expires_offset", 10)
424 440
 modparam("presence", "max_expires", 3600)
425 441
 ...
426 442
 
427
-3.13. server_address (str)
443
+3.13. min_expires (int)
444
+
445
+   The minimum admissible expires value for PUBLISH/SUBSCRIBE message (in
446
+   seconds).
447
+
448
+   If > 0 then min_expires_action parameter determines the response.
449
+
450
+   Default value is "0".
451
+
452
+   Example 1.13. Set min_expires parameter
453
+            ...
454
+            modparam("presence", "min_expires", 1800)
455
+            ...
456
+
457
+3.14. min_expires_action (int)
458
+
459
+   The action to take when UA sends a expires value less then min_expires.
460
+
461
+   Possible Values
462
+     * 1 : RFC Compliant, returns "423 Interval Too Brief"
463
+     * 2 : forces the min_expires value in the subscription
464
+
465
+   If > 0 then min_expires_action parameter determines the response.
466
+
467
+   Default value is "1".
468
+
469
+   Example 1.14. Set min_expires parameter
470
+            ...
471
+            modparam("presence", "min_expires", 1800)
472
+            ...
473
+
474
+3.15. server_address (str)
428 475
 
429 476
    The presence server address which will become the value of Contact
430 477
    header filed for 200 OK replies to SUBSCRIBE and PUBLISH and in NOTIFY
431 478
    messages.
432 479
 
433
-   Example 1.13. Set server_address parameter
480
+   Example 1.15. Set server_address parameter
434 481
 ...
435 482
 modparam("presence", "server_address", "sip:10.10.10.10:5060")
436 483
 ...
437 484
 
438
-3.14. subs_db_mode (int)
485
+3.16. subs_db_mode (int)
439 486
 
440 487
    The presence module can utilize database for persistent subscription
441 488
    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 516
 
470 517
    Default value is 2 (Write-Back scheme).
471 518
 
472
-   Example 1.14. Set subs_db_mode parameter
519
+   Example 1.16. Set subs_db_mode parameter
473 520
 ...
474 521
 modparam("presence", "subs_db_mode", 1)
475 522
 ...
476 523
 
477
-3.15. publ_cache (int)
524
+3.17. publ_cache (int)
478 525
 
479 526
    To improve performance, the presence module holds by default a publish
480 527
    cache that says if a certain publication exists in database. This is
... ...
@@ -490,12 +537,12 @@ modparam("presence", "subs_db_mode", 1)
490 537
 
491 538
    Default value is "1".
492 539
 
493
-   Example 1.15. Set publ_cache parameter
540
+   Example 1.17. Set publ_cache parameter
494 541
 ...
495 542
 modparam("presence", "publ_cache", 0)
496 543
 ...
497 544
 
498
-3.16. subs_htable_size (int)
545
+3.18. subs_htable_size (int)
499 546
 
500 547
    The size of the in-memory hash table to store subscription dialogs.
501 548
    This parameter will be used as the power of 2 when computing table
... ...
@@ -503,24 +550,24 @@ modparam("presence", "publ_cache", 0)
503 550
 
504 551
    Default value is "9 (512)".
505 552
 
506
-   Example 1.16. Set subs_htable_size parameter
553
+   Example 1.18. Set subs_htable_size parameter
507 554
 ...
508 555
 modparam("presence", "subs_htable_size", 11)
509 556
 ...
510 557
 
511
-3.17. pres_htable_size (int)
558
+3.19. pres_htable_size (int)
512 559
 
513 560
    The size of the in-memory hash table to store publish records. This
514 561
    parameter will be used as the power of 2 when computing table size.
515 562
 
516 563
    Default value is "9 (512)".
517 564
 
518
-   Example 1.17. Set pres_htable_size parameter
565
+   Example 1.19. Set pres_htable_size parameter
519 566
 ...
520 567
 modparam("presence", "pres_htable_size", 11)
521 568
 ...
522 569
 
523
-3.18. send_fast_notify (int)
570
+3.20. send_fast_notify (int)
524 571
 
525 572
    This parameter enables or disables the sending of an initial empty
526 573
    NOTIFY after a SUBSCRIBE/reSUBSCRIBE. This caused problems for MWI
... ...
@@ -530,12 +577,12 @@ modparam("presence", "pres_htable_size", 11)
530 577
 
531 578
    Default value is "1 ".
532 579
 
533
-   Example 1.18. Set send_fast_notify parameter
580
+   Example 1.20. Set send_fast_notify parameter
534 581
 ...
535 582
 modparam("presence", "send_fast_notify", 0)
536 583
 ...
537 584
 
538
-3.19. enable_sphere_check (int)
585
+3.21. enable_sphere_check (int)
539 586
 
540 587
    This parameter is a flag that should be set if permission rules include
541 588
    sphere checking. The sphere information is expected to be present in
... ...
@@ -545,12 +592,12 @@ modparam("presence", "send_fast_notify", 0)
545 592
 
546 593
    Default value is "0 ".
547 594
 
548
-   Example 1.19. Set enable_sphere_check parameter
595
+   Example 1.21. Set enable_sphere_check parameter
549 596
 ...
550 597
 modparam("presence", "enable_sphere_check", 1)
551 598
 ...
552 599
 
553
-3.20. timeout_rm_subs (int)
600
+3.22. timeout_rm_subs (int)
554 601
 
555 602
    This parameter is a flag that should be set if subscriptions should be
556 603
    removed from the active_watchers when a NOTIFY times out. RFC3265
... ...
@@ -560,23 +607,23 @@ modparam("presence", "enable_sphere_check", 1)
560 607
 
561 608
    Default value is "1".
562 609
 
563
-   Example 1.20. Set timeout_rm_subs parameter
610
+   Example 1.22. Set timeout_rm_subs parameter
564 611
 ...
565 612
 modparam("presence", "timeout_rm_subs", 0)
566 613
 ...
567 614
 
568
-3.21. fetch_rows (integer)
615
+3.23. fetch_rows (integer)
569 616
 
570 617
    Number of rows to be loaded in one step from database.
571 618
 
572 619
    Default value is 500.
573 620
 
574
-   Example 1.21. Set fetch_rows parameter
621
+   Example 1.23. Set fetch_rows parameter
575 622
 ...
576 623
 modparam("presence", "fetch_rows", 1000)
577 624
 ...
578 625
 
579
-3.22. db_table_lock_type (integer)
626
+3.24. db_table_lock_type (integer)
580 627
 
581 628
    Enable (=1) or disable (=0) the Locks for table during an transaction.
582 629
    Locking only the "current" table causes problems with a MySQL-Databases
... ...
@@ -589,23 +636,23 @@ modparam("presence", "fetch_rows", 1000)
589 636
 
590 637
    Default value is 1 (Write Lock for the Tables).
591 638
 
592
-   Example 1.22. Set db_table_lock_type parameter
639
+   Example 1.24. Set db_table_lock_type parameter
593 640
 ...
594 641
 modparam("presence", "db_table_lock_type", 0)
595 642
 ...
596 643
 
597
-3.23. local_log_level (int)
644
+3.25. local_log_level (int)
598 645
 
599 646
    Control log level for some debug messages inside the module.
600 647
 
601 648
    Default value is 2 (L_INFO).
602 649
 
603
-   Example 1.23. Set local_log_level parameter
650
+   Example 1.25. Set local_log_level parameter
604 651
 ...
605 652
 modparam("presence", "local_log_level", 3)
606 653
 ...
607 654
 
608
-3.24. subs_remove_match (int)
655
+3.26. subs_remove_match (int)
609 656
 
610 657
    Control how to match the subscriptions to remove from memory. If set to
611 658
    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 661
 
615 662
    Default value is 0.
616 663
 
617
-   Example 1.24. Set subs_remove_match parameter
664
+   Example 1.26. Set subs_remove_match parameter
618 665
 ...
619 666
 modparam("presence", "subs_remove_match", 1)
620 667
 ...
621 668
 
669
+3.27. xavp_cfg (str)
670
+
671
+   The name of the xavp to be used to specify attributes for internal
672
+   processing of presence module.
673
+
674
+   Inner attributes inside xavp can be:
675
+     * priority - integer value to set the priority of the presence
676
+       document (higher value, higher priority). It can set the order of
677
+       the aggregated presence documents sent by NOTIFY (first the
678
+       document with higher priority). If xavp_cfg parameter is set but
679
+       this attribute is not in the avp, the priority of the presence
680
+       document is based on timestamp, so newer documents have higher
681
+       priority.
682
+
683
+   Default value is empty (not set).
684
+
685
+   Example 1.27. Set xavp_cfg parameter
686
+...
687
+modparam("presence", "xavp_cfg", "pres")
688
+...
689
+if(is_method("PUBLISH")) {
690
+    $xavp(pres=>priority) = 100;
691
+}
692
+...
693
+
694
+3.28. retrieve_order (int)
695
+
696
+   If set to 0, presentity records are retrieve by received_time order. if
697
+   set to 1, presentity records are retrieve by priority order.
698
+
699
+   Default value is 0.
700
+
701
+   Example 1.28. Set retrieve_order parameter
702
+...
703
+modparam("presence", "retrieve_order", 1)
704
+...
705
+
622 706
 4. Functions
623 707
 
624
-   4.1. handle_publish(char* sender_uri)
708
+   4.1. handle_publish([sender_uri])
625 709
    4.2. handle_subscribe([watcher_uri])
626 710
    4.3. pres_auth_status(watcher_uri, presentity_uri)
627 711
    4.4. pres_refresh_watchers(uri, event, type[, file_uri, filename])
628 712
    4.5. pres_update_watchers(uri, event)
629 713
 
630
-4.1. handle_publish(char* sender_uri)
714
+4.1. handle_publish([sender_uri])
631 715
 
632 716
    Handles PUBLISH requests by storing and updating published information
633 717
    in memory cache and database, then calls functions to send NOTIFY
... ...
@@ -647,7 +731,7 @@ modparam("presence", "subs_remove_match", 1)
647 731
 
648 732
    The module sends an appropriate stateless reply in all cases.
649 733
 
650
-   Example 1.25. handle_publish usage
734
+   Example 1.29. handle_publish usage
651 735
 ...
652 736
         if(is_method("PUBLISH"))
653 737
         {
... ...
@@ -678,7 +762,7 @@ modparam("presence", "subs_remove_match", 1)
678 762
 
679 763
    The module sends an appropriate stateless reply in all cases.
680 764
 
681
-   Example 1.26. handle_subscribe usage
765
+   Example 1.30. handle_subscribe usage
682 766
 ...
683 767
 if(method=="SUBSCRIBE")
684 768
     handle_subscribe();
... ...
@@ -695,7 +779,7 @@ if(method=="SUBSCRIBE")
695 779
 
696 780
    This function can be used from REQUEST_ROUTE.
697 781
 
698
-   Example 1.27. pres_auth_status usage
782
+   Example 1.31. pres_auth_status usage
699 783
 ...
700 784
 if (method=="MESSAGE") {
701 785
     pres_auth_status("$fu", $ru");
... ...
@@ -731,7 +815,7 @@ if (method=="MESSAGE") {
731 815
 
732 816
    This function can be used from ANY_ROUTE.
733 817
 
734
-   Example 1.28. pres_refresh_watchers usage
818
+   Example 1.32. pres_refresh_watchers usage
735 819
 ...
736 820
 pres_refresh_watchers("sip:test@kamailio.org", "presence", 1);
737 821
 ...
... ...
@@ -749,7 +833,7 @@ pres_refresh_watchers("sip:test@kamailio.org", "presence", 1);
749 833
 
750 834
    This function can be used from ANY_ROUTE.
751 835
 
752
-   Example 1.29. pres_update_watchers usage
836
+   Example 1.33. pres_update_watchers usage
753 837
 ...
754 838
 pres_update_watchers("sip:test@kamailio.org", "presence");
755 839
 ...