
pa Module

Jan Janak

   FhG FOKUS

Edited by

Jan Janak

   Copyright  2003 FhG FOKUS
     _________________________________________________________

   Table of Contents
   1. User's Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. SER Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. default_expires (integer)
              1.3.2. default_priority_percentage (integer)
              1.3.3. timer_interval (integer)
              1.3.4. use_db (integer)
              1.3.5. use_place_table (integer)
              1.3.6. use_bsearch (integer)
              1.3.7. use_location_package (integer)
              1.3.8. db_url (string)
              1.3.9. pa_domain (string)
              1.3.10. presentity_table (string)
              1.3.11. presentity_contact_table (string)
              1.3.12. watcherinfo_table (string)
              1.3.13. place_table (string)
              1.3.14. new_watcher_pending (integer)
              1.3.15. callback_update_db (integer)
              1.3.16. callback_lock_pdomain (integer)
              1.3.17. new_tuple_on_publish (integer)
              1.3.18. pidf_priority (integer)

        1.4. Exported Functions

              1.4.1. pa_handle_registration(domain)
              1.4.2. handle_subscription(domain)
              1.4.3. handle_publish(domain)
              1.4.4. existing_subscription(domain)
              1.4.5. pua_exists(domain)

   2. Developer's Guide
   3. Frequently Asked Questions

   List of Examples
   1-1. Set default_expires parameter
   1-2. handle_subscription usage
   1-3. handle_subscription usage
     _________________________________________________________

Chapter 1. User's Guide

1.1. Overview

   This module implements a presence server, i.e. entity that
   receives SUBSCRIBE messages and sends NOTIFY when presence
   status of a user changes. Currently the presence server can be
   connected to registrar and jabber module so SIP users can see
   presence of jabber users.

   This module currently cannot work as a B2BUA, i.e. it cannot
   subscribe to presence of users using SIP. We are currently
   working on that feature.
     _________________________________________________________

1.2. Dependencies

1.2.1. SER Modules

   The following modules must be loaded before this module:

     * No dependencies on other SER modules.
     _________________________________________________________

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running SER with this module loaded:

     * None.
     _________________________________________________________

1.3. Exported Parameters

1.3.1. default_expires (integer)

   Default expires value to be used when the client doesn't
   supply one (in seconds).

   Default value is "3600". 

   Example 1-1. Set default_expires parameter
...
modparam("pa", "default_expires", 3600)
...
     _________________________________________________________

1.3.2. default_priority_percentage (integer)

   Default priority value to be used when not included in a
   PUBLISH message, expressed as a percentage.

   Default value is 50. 
     _________________________________________________________

1.3.3. timer_interval (integer)

   This parameter controls the interval between expiration timer
   runs, the value is in seconds.

   Default value is 10. 
     _________________________________________________________

1.3.4. use_db (integer)

   This parameter enables/disables database support in pa module.

   Default value is 0 (disabled). 
     _________________________________________________________

1.3.5. use_place_table (integer)

   This parameter controls if pa module should use "place"
   database table. The table assigns IDs to rooms/locations and
   contains additional information for each place.

   Default value is 0 (disabled). 
     _________________________________________________________

1.3.6. use_bsearch (integer)

   Enable/disable using of binary search instead of linear
   searching when looking up location.

   Default value is 0 (disabled). 
     _________________________________________________________

1.3.7. use_location_package (integer)

   Enable/disable location package support in pa.

   Default value is 0 (disabled). 
     _________________________________________________________

1.3.8. db_url (string)

   The URL of the database to be used when database support is
   enabled in pa module.

   Default value is "mysql://ser:heslo@localhost/ser". 
     _________________________________________________________

1.3.9. pa_domain (string)

   Hostname of XCAP server associated with presence agent.

   Default value is "sip.handhelds.org". 
     _________________________________________________________

1.3.10. presentity_table (string)

   The name of the table in database which can store information
   about presentities stored in the presence server. Presence
   server can reload data from this table after restart.

   Default value is "presentity". 
     _________________________________________________________

1.3.11. presentity_contact_table (string)

   Table containing additional information on presentities, such
   as status, location, contact value, and so on.

   Default value is "presentity_contact". 
     _________________________________________________________

1.3.12. watcherinfo_table (string)

   The name of the table in database where presence server stores
   information about subscribers to the watcherinfo package
   (watchers).

   Default value is "watcherinfo". 
     _________________________________________________________

1.3.13. place_table (string)

   The name of the table in database which contains additional
   information on places where presentities can be found. The
   presence server can use this table to lookup additional
   information about positions of presentities.

   Default value is "place". 
     _________________________________________________________

1.3.14. new_watcher_pending (integer)

   This parameter controls the initial state of new watchers.
   When set to 1 then new watchers will be listed as pending
   (waiting for authorization), when set to 0 then new watchers
   will be listed as active

   Default value is 0. 
     _________________________________________________________

1.3.15. callback_update_db (integer)

   This parameter controls the default priority value. The range
   of the parameter is 0 to 100 percent. The value will be
   internaly converted to a float.

   Default value is 50. 
     _________________________________________________________

1.3.16. callback_lock_pdomain (integer)

   Enable/disable locking in callbacks. This is for debugging
   only, use with care.

   Default value is 1 (enabled). 
     _________________________________________________________

1.3.17. new_tuple_on_publish (integer)

   The parameter controls whether a new tuple will be created if
   it does not already exists when the presence server receives a
   publish.

   Default value is 0 (no). 
     _________________________________________________________

1.3.18. pidf_priority (integer)

   Enable/disable priority parameter of contacts in pidf
   documents.

   Default value is 1 (enabled). 
     _________________________________________________________

1.4. Exported Functions

1.4.1. pa_handle_registration(domain)

   Process REGISTER messages and update the state of the
   presentity. This function is no longer used.

   Meaning of the parameters is as follows:

     * domain - The domain within the presence server.
     _________________________________________________________

1.4.2. handle_subscription(domain)

   This function processes SUBSCRIBE and generates NOTIFY.

   Meaning of the parameters is as follows:

     * domain - This can be either "registrar" or "jabber".

   Example 1-2. handle_subscription usage
...
if (method=="SUBSCRIBE") {
    if (!t_newtran()) {
       log(1, "newtran error\n");
       sl_reply_error();
    };
    handle_subscription("registrar");
    break;
};
...
     _________________________________________________________

1.4.3. handle_publish(domain)

   Process PUBLISH messages, update the state of the presentity
   accordingly and generate NOTIFY.

   Meaning of the parameters is as follows:

     * domain - The domain within the presence server.

   Example 1-3. handle_subscription usage
...
if (method=="PUBLISH") {
    if (!t_newtran()) {
       log(1, "newtran error\n");
       sl_reply_error();
    };
    handle_publish("registrar");
    break;
};
...
     _________________________________________________________

1.4.4. existing_subscription(domain)

   Lookup the table of all subscriptions in the presence server
   and return 1 if it exists and 0 if not.

   Meaning of the parameters is as follows:

     * domain - The domain within the presence server.
     _________________________________________________________

1.4.5. pua_exists(domain)

   Try to find out whether user agent supports SUBSCRIBE and
   return 1 if yes and 0 if not or not sure.

   Meaning of the parameters is as follows:

     * domain - The domain within the presence server.
     _________________________________________________________

Chapter 2. Developer's Guide

   The module does not provide any sort of API to use in other
   SER modules.
     _________________________________________________________

Chapter 3. Frequently Asked Questions

   3.1. Where can I find more about SER?
   3.2. Where can I post a question about this module?
   3.3. How can I report a bug?

   3.1. Where can I find more about SER?

   Take a look at http://iptel.org/ser.

   3.2. Where can I post a question about this module?

   First at all check if your question was already answered on
   one of our mailing lists:

     * http://mail.iptel.org/mailman/listinfo/serusers
     * http://mail.iptel.org/mailman/listinfo/serdev

   E-mails regarding any stable version should be sent to
   <serusers@iptel.org> and e-mail regarding development versions
   or CVS snapshots should be send to <serdev@iptel.org>.

   If you want to keep the mail private, send it to
   <serhelp@iptel.org>.

   3.3. How can I report a bug?

   Please follow the guidelines provided at:
   http://iptel.org/ser/bugs
