– Kamailio SIP Server –

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:

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

  1. verifies if the SUBSCRIBE message is correct:
    1. check its structure;
    2. if inside a dialog checks is a record of that dialog is present
  2. if the conditions are not complied with it sends an adequate error message
  3. if a correct message
    1. sends 200OK for SUBSCRIBE messages for event “presence.winfo” and 202OK for Subscribe for “presence”; they both contain a Expires header field
    2. if a new SUBSCRIBE:
      1. it inserts a new row in database
      2. if SUBSCRIBE for “presence”:
        1. 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
        2. calls a function to send Notify with the presence information of the person he has subscribed to
  1. if SUBSCRIBE for “presence.winfo”
  2. calls a function to send Notify with presence.winfo to the subscriber with full state informing only about all the watchers
  3. if a Subscribe inside a dialog
  4. if the Expires header field value is 0
  5. deletes the registration from the database
  6. if event is “presence” calls a function which sends Notify with presence.winfo to the presentity with full state
  7. if update, it updates the stored expires value

Exported parameters

  • db_url : database url
  • clean_period : time period for cleaning expired PUBLISH or SUBSCRIBE messages from database
  • to_tag_pref : prefix used when generating to_tag when sending replies for SUBSCRIBE requests
  • totag_avpid: the id of the avp variable used for storing to_tag value;
  • lock_set_size : the size of the lock used for synchronizing updating information from database
  • expires_offset : 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
  • force_active : 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).
  • max_expires : reduce validity of PUBLISH/SUBSCRIBE to this value if the Expires in request is greater.
  • server_address: presence server address to be included in Contact header field for Subscribe and Publish replies and in Notify messages.