====== Presence Module - Parameters and Functions ======


===== Exported Functions =====

  * **handle_publish()**
  * **handle_subscribe()**



==== handle_publish() ====

  * function which handles PUBLISH requests. It stores and updates presence information in database and calls functions to send NOTIFY messages when changes in presence information occur;
  * it does not take any parameter.
   
__ Actions:  __ 

     - verifies if the PUBLISH message is correct: 
                - check its structure;
                - if it has a SIP-if-Match header, checks is there is a previous storage for the same presentity;
                - if not present checks if a body is present
     - if the conditions are not complied with it sends an adequate error message
     - if a correct message:
                - sends a 200Ok message with 2 extra header fields : Expires and SIP-if-Match 
                - if a new PUBLISH without a Sip-if-Match header field 
                             - it generates one
                             - inserts a new row in database
                             - calls a function which sends Notify with presence to all the watchers which have subscribed to the presentity
                - if the PUBLISH message is inside a dialog
                             - updates the expires value
                             - if body present
                                       - updates body (replace with the new one) 
                                       - calls a function which sends Notify with presence to all watchers  
                                      





==== handle_subscribe() ====

 
  * function which handles SUBSCRIBE requests. It stores or updates information in database and calls functions to send Notify messages when a Subscribe which initiate a dialog is received
  * it does not take any parameter.

__Actions__
       -verifies if the SUBSCRIBE message is correct: 
                - check its structure;
                - if inside a dialog checks is a record of that dialog is present
       -if the conditions are not complied with it sends an adequate error message
       -if a correct message 
                - sends 200OK for SUBSCRIBE messages for event "presence.winfo" and 202OK for Subscribe for "presence"; they both contain a Expires header field
                - if a new SUBSCRIBE: 
                           -it inserts a new row in database
                           -if SUBSCRIBE for "presence": 
                                  -calls a function to send Notify with presence.winfo to the presentity with a partial state informing only about the subscription status of the new watcher
                                  -calls a function to send Notify with the presence information of the person he  has subscribed to
                                  
                          -if SUBSCRIBE for "presence.winfo"
                                   -calls a function to send Notify with presence.winfo to the subscriber with full state informing only about all the watchers
                - if a Subscribe inside a dialog
                          -if the Expires header field value is 0 
                                    -deletes the registration from the database
                                    -if event is "presence" calls a function which sends Notify with presence.winfo to the presentity with full state
                          -if update, it updates the stored expires value


=====  Exported parameters =====


* [b]db_url[/b] : database url
* [b]clean_period[/b] : time period for cleaning expired PUBLISH or SUBSCRIBE messages from database
* [b]to_tag_pref[/b] : prefix used when generating to_tag when sending replies for SUBSCRIBE requests
* [b]totag_avpid[/b]: the id of the avp variable used for storing to_tag value;
* [b]lock_set_size[/b] : the size of the lock used for synchronizing updating information from database
* [b]expires_offset[/b] : the value that should be substracted from the expires value when sending a 200OK for a publish to force the client cu send an update before the old publish expires
* [b]force_active[/b] : this parameter is used for permissions when handling Subscribe messages. If set to 1, subscription state is considered active and the presentity is not queried for permissions. Otherwise,the xcap_table is queried and the state is extracted from there. If no record exists, the subscriptions remains in pending state and the watcher receives Notify messages with no body. ( If not using an xcap server, you should set this parameter to 1).
* [b]max_expires[/b] : reduce validity of PUBLISH/SUBSCRIBE to this value if the Expires in request is greater.
* [b]server_address[/b]: presence server address to be included in Contact header field for Subscribe and Publish replies and in Notify messages.

===== Presence-Related Stuff =====

{{indexmenu>presence|js}}