Presence Module

Anca-Maria Vamanu

   Voice Sistem SRL

Juha Heinanen

   TutPro Inc.

Edited by

Anca-Maria Vamanu

Edited by

Juha Heinanen

   Copyright © 2006 Voice Sistem SRL

   Copyright © 2009 Juha Heinanen
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. db_url(str)
              3.2. presentity_table(str)
              3.3. active_watchers_table(str)
              3.4. watchers_table(str)
              3.5. clean_period (int)
              3.6. db_update_period (int)
              3.7. to_tag_pref (str)
              3.8. expires_offset (int)
              3.9. max_expires (int)
              3.10. server_address (str)
              3.11. fallback2db (int)
              3.12. db_mode (int)
              3.13. subs_htable_size (int)
              3.14. pres_htable_size (int)
              3.15. send_fast_notify (int)
              3.16. enable_sphere_check (int)
              3.17. timeout_rm_subs (int)

        4. Functions

              4.1. handle_publish(char* sender_uri)
              4.2. handle_subscribe()
              4.3. pres_auth_status(watcher_uri, presentity_uri)
              4.4. pres_refresh_watchers(uri, event, type)
              4.5. pres_update_watchers(uri, event)

        5. MI Commands

              5.1. refreshWatchers
              5.2. cleanup

        6. Installation

   2. Developer Guide

        1. bind_presence(presence_api_t* api)
        2. add_event
        3. get_rules_doc
        4. get_auth_status
        5. apply_auth_nbody
        6. agg_nbody
        7. free_body
        8. aux_body_processing
        9. aux_free_body
        10. evs_publ_handl
        11. evs_subs_handl
        12. contains_event
        13. get_event_list
        14. update_watchers_status
        15. get_sphere
        16. get_presentity
        17. free_presentity

   List of Examples

   1.1. Set db_url parameter
   1.2. Set presentity_table parameter
   1.3. Set active_watchers_table parameter
   1.4. Set watchers_table parameter
   1.5. Set clean_period parameter
   1.6. Set db_update_period parameter
   1.7. Set to_tag_pref parameter
   1.8. Set expires_offset parameter
   1.9. Set max_expires parameter
   1.10. Set server_address parameter
   1.11. Set fallback2db parameter
   1.12. Set db_mode parameter
   1.13. Set subs_htable_size parameter
   1.14. Set pres_htable_size parameter
   1.15. Set send_fast_notify parameter
   1.16. Set enable_sphere_check parameter
   1.17. Set timeout_rm_subs parameter
   1.18. handle_publish usage
   1.19. handle_subscribe usage
   1.20. pres_auth_status usage
   1.21. pres_refresh_watchers usage
   1.22. pres_update_watchers usage
   2.1. presence_api_t structure

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Parameters

        3.1. db_url(str)
        3.2. presentity_table(str)
        3.3. active_watchers_table(str)
        3.4. watchers_table(str)
        3.5. clean_period (int)
        3.6. db_update_period (int)
        3.7. to_tag_pref (str)
        3.8. expires_offset (int)
        3.9. max_expires (int)
        3.10. server_address (str)
        3.11. fallback2db (int)
        3.12. db_mode (int)
        3.13. subs_htable_size (int)
        3.14. pres_htable_size (int)
        3.15. send_fast_notify (int)
        3.16. enable_sphere_check (int)
        3.17. timeout_rm_subs (int)

   4. Functions

        4.1. handle_publish(char* sender_uri)
        4.2. handle_subscribe()
        4.3. pres_auth_status(watcher_uri, presentity_uri)
        4.4. pres_refresh_watchers(uri, event, type)
        4.5. pres_update_watchers(uri, event)

   5. MI Commands

        5.1. refreshWatchers
        5.2. cleanup

   6. Installation

1. Overview

   The Presence module implements the core functionality of SIP event
   notification. It handles PUBLISH and SUBSCRIBE messages and generates
   NOTIFY messages in a general, event independent way. It is extensible
   and allows registering events to it from other Kamailio modules.
   Supported SIP event packages are presence, presence.winfo, dialog;sla
   from the presence_xml module and message-summary from the presence_mwi
   module.

   The module uses database storage and memory caching (to improve
   performance). The SIP SUBSCRIBE dialog information is stored in memory
   and is periodically updated in the database, while for PUBLISH only the
   presence or absence of stored info for a certain resource is maintained
   in memory to avoid unnecessary, costly database operations. It is
   possible to disable in-memory caching by configuring a fallback to
   database mode (by setting the module parameter "fallback2db"). In this
   mode, in case a searched record is not found in cache, the search is
   continued in database. This is useful for an architecture in which
   processing and memory load might be divided on several Kamailio
   instances, maybe on different servers using the same database. This
   parameter remains only for legacy purposes. As a new feature for the
   presence engine, it is possible to have three database modes, which one
   can configure through the db_mode parameter. Setting db_mode to 0, 1, 2
   respective will cause the subscribers to be retrieved from memory only,
   from memory and to fallback to database mode in case a record is not
   found in memory, and from database only.

   The module implements several API functions, that can be used by other
   modules. In fact, it can be used only as a resource module, or
   "library". This mode of operation is enabled if the db_url parameter is
   not set to any value.

   The Kamailio Presence module implements the specifications in: RFC3265,
   RFC3856, RFC3857, RFC3858.

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The following modules must be loaded before this module:
     * a database module.
     * sl.
     * tm.

2.2. External Libraries or Applications

     * libxml.

3. Parameters

   3.1. db_url(str)
   3.2. presentity_table(str)
   3.3. active_watchers_table(str)
   3.4. watchers_table(str)
   3.5. clean_period (int)
   3.6. db_update_period (int)
   3.7. to_tag_pref (str)
   3.8. expires_offset (int)
   3.9. max_expires (int)
   3.10. server_address (str)
   3.11. fallback2db (int)
   3.12. db_mode (int)
   3.13. subs_htable_size (int)
   3.14. pres_htable_size (int)
   3.15. send_fast_notify (int)
   3.16. enable_sphere_check (int)
   3.17. timeout_rm_subs (int)

3.1. db_url(str)

   The database url.

   If set, the module is a fully operational presence server. Otherwise,
   it is used as a 'library', for its exported functions.

   Default value is “NULL”.

   Example 1.1. Set db_url parameter
...
modparam("presence", "db_url",
        "mysql://openser:openserrw@localhost/openser")
...

3.2. presentity_table(str)

   The name of the db table where PUBLISH presence information is stored.

   Default value is “presentity”.

   Example 1.2. Set presentity_table parameter
...
modparam("presence", "presentity_table", "presentity")
...

3.3. active_watchers_table(str)

   The name of the db table where active subscription information is
   stored.

   Default value is “active_watchers”.

   Example 1.3. Set active_watchers_table parameter
...
modparam("presence", "active_watchers_table", "active_watchers")
...

3.4. watchers_table(str)

   The name of the db table where subscription states are stored.

   Default value is “watchers”.

   Example 1.4. Set watchers_table parameter
...
modparam("presence", "watchers_table", "watchers")
...

3.5. clean_period (int)

   The period in seconds between checks if there are expired messages
   stored in database.

   Default value is “100”. A zero or negative value disables this
   activity.

   Example 1.5. Set clean_period parameter
...
modparam("presence", "clean_period", 100)
...

3.6. db_update_period (int)

   The period at which to synchronize cached subscriber info with the
   database.

   Default value is “100”. A zero or negative value disables
   synchronization.

   Example 1.6. Set db_update_period parameter
...
modparam("presence", "db_update_period", 100)
...

3.7. to_tag_pref (str)

   The prefix used when generating to_tag when sending replies for
   SUBSCRIBE requests.

   Default value is “10”.

   Example 1.7. Set to_tag_pref parameter
...
modparam("presence", "to_tag_pref", 'pres')
...

3.8. expires_offset (int)

   The value in seconds that should be subtracted from the expires value
   when sending a 200OK for a publish. It is used for forcing the client
   to send an update before the old publish expires.

   Default value is “0”.

   Example 1.8. Set expires_offset parameter
...
modparam("presence", "expires_offset", 10)
...

3.9. max_expires (int)

   The the maximum admissible expires value for PUBLISH/SUBSCRIBE message
   (in seconds).

   Default value is “3600”.

   Example 1.9. Set max_expires parameter
...
modparam("presence", "max_expires", 3600)
...

3.10. server_address (str)

   The presence server address which will become the value of Contact
   header filed for 200 OK replies to SUBSCRIBE and PUBLISH and in NOTIFY
   messages.

   Example 1.10. Set server_address parameter
...
modparam("presence", "server_address", "sip:10.10.10.10:5060")
...

3.11. fallback2db (int)

   Setting this parameter enables a fallback to db mode of operation. In
   this mode, in case a searched record is not found in cache, the search
   is continued in database. Useful for an architecture in which
   processing and memory load might be divided on more servers using the
   same database. This parameter overwrite the configuration specified
   from the “db_mode” parameter.

   This parameter is obsolet and will be removed in future releases.

   Example 1.11. Set fallback2db parameter
...
modparam("presence", "fallback2db", 1)
...

3.12. db_mode (int)

   This parameter sets the mode in which records are retrieved. Setting
   this parameter to 0 or 1 is equivalent to setting fallback2db to 0 or
   1, respectiv. The db_mode parameter can also take a third value, 2, in
   which records are retrieved from database only. So, the three database
   modes in which the presence engine can operate are: memory only,
   fallback to database, and database only.

   Example 1.12. Set db_mode parameter
...
modparam("presence", "db_mode", 2)
...

3.13. subs_htable_size (int)

   The size of the in-memory hash table to store subscription dialogs.
   This parameter will be used as the power of 2 when computing table
   size.

   Default value is “9 (512)”.

   Example 1.13. Set subs_htable_size parameter
...
modparam("presence", "subs_htable_size", 11)
...

3.14. pres_htable_size (int)

   The size of the in-memory hash table to store publish records. This
   parameter will be used as the power of 2 when computing table size.

   Default value is “9 (512)”.

   Example 1.14. Set pres_htable_size parameter
...
modparam("presence", "pres_htable_size", 11)
...

3.15. send_fast_notify (int)

   This parameter enables or disables the sending of an initial empty
   NOTIFY after a SUBSCRIBE/reSUBSCRIBE. This caused problems for MWI
   application, because some CPEs (like Samsung) fail to understand an
   empty NOTIFY to an message-summary event. This parameter is enabled by
   default, thus addering to the standard.

   Default value is “1 ”.

   Example 1.15. Set send_fast_notify parameter
...
modparam("presence", "send_fast_notify", 0)
...

3.16. enable_sphere_check (int)

   This parameter is a flag that should be set if permission rules include
   sphere checking. The sphere information is expected to be present in
   the RPID body published by the presentity. The flag is introduced as
   this check requires extra processing that should be avoided if this
   feature is not supported by the clients.

   Default value is “0 ”.

   Example 1.16. Set enable_sphere_check parameter
...
modparam("presence", "enable_sphere_check", 1)
...

3.17. timeout_rm_subs (int)

   This parameter is a flag that should be set if subscriptions should be
   removed from the active_watchers when a NOTIFY times out. RFC3265
   section 3.2.2 defines this behaviour as a SHOULD, so by default it is
   on. Disabling this will keep subscriptions active on unreliable
   networks.

   Default value is “1”.

   Example 1.17. Set timeout_rm_subs parameter
...
modparam("presence", "timeout_rm_subs", 0)
...

4. Functions

   4.1. handle_publish(char* sender_uri)
   4.2. handle_subscribe()
   4.3. pres_auth_status(watcher_uri, presentity_uri)
   4.4. pres_refresh_watchers(uri, event, type)
   4.5. pres_update_watchers(uri, event)

4.1.  handle_publish(char* sender_uri)

   Handles PUBLISH requests by storing and updating published information
   in memory cache and database, then calls functions to send NOTIFY
   messages when changes in the published information occur. It takes one
   argument -> sender_uri. The parameter was added for enabling BLA
   implementation. If present, notification of a change in published state
   is not sent to the respective uri even though a subscription exists. It
   should be taken from the Sender header. It was left at the decision of
   the administrator whether or not to transmit the content of this header
   as parameter for handle_publish, to prevent security problems.

   This function can be used from REQUEST_ROUTE.

   Return code:
     * 1 - if success.
     * -1 - if error.

   The module sends an appropriate stateless reply in all cases.

   Example 1.18. handle_publish usage
...
        if(is_method("PUBLISH"))
        {
                if($hdr(Sender)!= NULL)
                        handle_publish("$hdr(Sender)");
                else
                        handle_publish();
                t_release();
        }
...

4.2.  handle_subscribe()

   The function which handles SUBSCRIBE requests. It stores or updates
   information in memory and database and calls functions to send NOTIFY
   messages when a SUBSCRIBE which initiate a dialog is received

   This function can be used from REQUEST_ROUTE.

   Return code:
     * 1 - if success.
     * -1 - if error.

   The module sends an appropriate stateless reply in all cases.

   Example 1.19. handle_subscribe usage
...
if(method=="SUBSCRIBE")
    handle_subscribe();
...

4.3.  pres_auth_status(watcher_uri, presentity_uri)

   The function checks if watcher is authorized to subscribe event
   'presence' of presentity. Both watcher_uri and presentity_uri are
   pseudo variables. Function returns ACTIVE_STATUS, if subscription is
   allowed and PENDING_STATUS, TERMINATED_STATUS, or WAITING_STATUS
   otherwise. See presence/subscribe.h for the corresponding integer
   codes. In case of error, function returns -1.

   This function can be used from REQUEST_ROUTE.

   Example 1.20. pres_auth_status usage
...
if (method=="MESSAGE") {
    pres_auth_status("$fu", $ru");
    if ($retcode == 1) {
        t_relay();
    } else {
        send_reply("403", "Forbidden");
    }
}
...

4.4.  pres_refresh_watchers(uri, event, type)

   The function can be used in configuration to triger notifies to
   watchers if a change in watchers authorization or in published state
   occurred (i.e., updates of xcap documents).

   Parameters:
     * uri - the uri of the user who made the change and whose watchers
       should be informed.
     * event - the event package.
     * type - it distinguishes between the two different types of events
       that can trigger the refresh, depending on its value:
          + 0 - a change in watchers authentication.
          + 1 - a statical update in published state (either through
            direct update in db table or by modifying the pidf
            manipulation document, if pidf_manipulation parameter is set).

   This function can be used from ANY_ROUTE.

   Example 1.21. pres_refresh_watchers usage
...
pres_refresh_watchers("sip:test@kamailio.org", "presence", 1);
...

4.5.  pres_update_watchers(uri, event)

   The function can be used in configuration to triger updates to watchers
   status if a change in watchers authorization state occurred (i.e.,
   updates of xcap documents change state from pending to active).

   Parameters:
     * uri - the uri of the user who made the change and whose watchers
       should be informed. Can be PV.
     * event - the event package (e.g., presence).

   This function can be used from ANY_ROUTE.

   Example 1.22. pres_update_watchers usage
...
pres_update_watchers("sip:test@kamailio.org", "presence");
...

5. MI Commands

   5.1. refreshWatchers
   5.2. cleanup

5.1.  refreshWatchers

   Triggers sending Notify messages to watchers if a change in watchers
   authorization or in published state occurred.

   Name: refreshWatchers

   Parameters:
     * presentity_uri : the uri of the user who made the change and whose
       watchers should be informed
     * event : the event package
     * refresh type : it distinguishes between the two different types of
       events that can trigger a refresh:
          + a change in watchers authentication: refresh type= 0 ;
          + a statical update in published state (either through direct
            update in db table or by modifying the pidf manipulation
            document, if pidf_manipulation parameter is set): refresh
            type!= 0.

   MI FIFO Command Format:
                :refreshWatchers:fifo_reply
                sip:test@kamailio.org
                presence
                1
                _empty_line_

5.2.  cleanup

   Manually triggers the cleanup functions for watchers and presentity
   tables. Useful if you have set clean_period to zero or less.

   Name: cleanup

   Parameters:none.emphasis>

   MI FIFO Command Format:
                :cleanup:fifo_reply
                _empty_line_

6. Installation

   The module requires 3 tables in the Kamailio database: "presentity",
   "active_watchers" and "watchers". The SQL syntax to create them can be
   found in presence-create.sql script in the database directories in the
   kamailio/scripts folder. You can also find the complete database
   documentation on the project webpage,
   http://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.

Chapter 2. Developer Guide

   Table of Contents

   1. bind_presence(presence_api_t* api)
   2. add_event
   3. get_rules_doc
   4. get_auth_status
   5. apply_auth_nbody
   6. agg_nbody
   7. free_body
   8. aux_body_processing
   9. aux_free_body
   10. evs_publ_handl
   11. evs_subs_handl
   12. contains_event
   13. get_event_list
   14. update_watchers_status
   15. get_sphere
   16. get_presentity
   17. free_presentity

   The module provides the following functions that can be used in other
   Kamailio modules.

1.  bind_presence(presence_api_t* api)

   This function binds the presence modules and fills the structure with
   one exported function -> add_event, which when called adds a new event
   to be handled by presence.

   Example 2.1. presence_api_t structure
...
typedef struct presence_api {
        add_event_t add_event;
        contains_event_t contains_event;
        search_event_t search_event;
        get_event_list_t get_event_list;

        update_watchers_t update_watchers_status;

        /* subs hash table handling functions */
        new_shtable_t new_shtable;
        destroy_shtable_t destroy_shtable;
        insert_shtable_t insert_shtable;
        search_shtable_t search_shtable;
        delete_shtable_t delete_shtable;
        update_shtable_t update_shtable;
        /* function to duplicate a subs structure*/
        mem_copy_subs_t  mem_copy_subs;
        /* function used for update in database*/
        update_db_subs_t update_db_subs;
        /* function to extract dialog information from a
        SUBSCRIBE message */
        extract_sdialog_info_t extract_sdialog_info;
        /* function to request sphere defition for a presentity */
        pres_get_sphere_t get_sphere;

}presence_api_t;
...

2.  add_event

   Field type:
...
typedef int (*add_event_t)(pres_ev_t* event);
...

   This function receives as a parameter a structure with event specific
   information and adds it to presence event list.

   The structure received as a parameter:
...
typedef struct pres_ev
{
        str name;
        event_t* evp;
        str content_type;
        int default_expires;
        int type;
        int etag_not_new;
        /*
         *  0 - the standard mechanism (allocating new etag
                        for each Publish)
         *  1 - allocating an etag only
                        for an initial Publish
        */
        int req_auth;
        get_rules_doc_t* get_rules_doc;
        apply_auth_t*  apply_auth_nbody;
        is_allowed_t*  get_auth_status;

        /* an agg_body_t function should be registered
         * if the event permits having multiple published
         * states and requires an aggregation of the information
         * otherwise, this field should be NULL and the last
         * published state is taken when constructing Notify msg
         */
        agg_nbody_t* agg_nbody;
        publ_handling_t  * evs_publ_handl;
        subs_handling_t  * evs_subs_handl;
        free_body_t* free_body;
    /* sometimes it is necessary that a module make changes for a body for each
     * active watcher (e.g. setting the "version" parameter in an XML document.
     * If a module registers the aux_body_processing callback, it gets called fo
r
     * each watcher. It either gets the body received by the PUBLISH, or the bod
y
     * generated by the agg_nbody function.
     * The module can deceide if it makes a copy of the original body, which is
then
     * manipulated, or if it works directly in the original body. If the module
makes a
     * copy of the original body, it also has to register the aux_free_body() to
     * free this "per watcher" body.
     */
    aux_body_processing_t* aux_body_processing;
    free_body_t* aux_free_body;
        struct pres_ev* wipeer;
        struct pres_ev* next;

}pres_ev_t;
...

3.  get_rules_doc

   Filed type:
...
typedef int (get_rules_doc_t)(str* user, str* domain, str** rules_doc);
...

   This function returns the authorization rules document that will be
   used in obtaining the status of the subscription and processing the
   notified body. A reference to the document should be put in the
   auth_rules_doc of the subs_t structure given as a parameter to the
   functions described bellow.

4.  get_auth_status

   This filed is a function to be called for a subscription request to
   return the state for that subscription according to authorization
   rules. In the auth_rules_doc field of the subs_t structure received as
   a parameter should contain the rules document of the presentity in
   case, if it exists.

   It is called only if the req_auth field is not 0.

   Filed type:
...
typedef int (is_allowed_t)(struct subscription* subs);
...

5.  apply_auth_nbody

   This parameter should be a function to be called for an event that
   requires authorization, when constructing final body. The authorization
   document is taken from the auth_rules_doc field of the subs_t structure
   given as a parameter. It is called only if the req_auth field is not 0.

   Filed type:
...
typedef int (apply_auth_t)(str* , struct subscription*, str** );
...

6.  agg_nbody

   If present, this field marks that the events requires aggregation of
   states. This function receives a body array and should return the final
   body. If not present, it is considered that the event does not require
   aggregation and the most recent published information is used when
   constructing Notifies.

   Filed type:
...
typedef str* (agg_nbody_t)(str* pres_user, str* pres_domain,
str** body_array, int n, int off_index);
..

7.  free_body

   This field must be field in if subsequent processing is performed on
   the info from database before being inserted in Notify message body(if
   agg_nbody or apply_auth_nbody fields are filled in). It should match
   the allocation function used when processing the body.

   Filed type:
...
typedef void(free_body_t)(char* body);
..

8.  aux_body_processing

   This field must be set if the module needs to manipulate the NOTIFY
   body for each watcher. E.g. if the XML body includes a 'version'
   parameter which will be increased for each NOTIFY, on a "per watcher"
   basis. The module can either allocate a new buffer for the new body an
   return it (aux_free_body function must be set too) or it manipualtes
   the original body directly and returns NULL.

   Filed type:
...
typedef str* (aux_body_processing_t)(struct subscription *subs, str* body);
..

9.  aux_free_body

   This field must be set if the module registers the aux_body_processing
   function and allocates memory for the new modified body. Then, this
   function will be used to free the pointer returned by the
   aux_body_processing function. If the module does use the
   aux_body_processing, but does not allocate new memory, but manipulates
   directly the original body buffer, then the aux_body_processing must
   return NULL and this field should not be set.

   Filed type:
...
typedef void(free_body_t)(char* body);
..

10.  evs_publ_handl

   This function is called when handling Publish requests. Most contain
   body correctness check.

...
typedef int (publ_handling_t)(struct sip_msg*);
..

11.  evs_subs_handl

   It is not compulsory. Should contain event specific handling for
   Subscription requests.

   Filed type:
...
typedef int (subs_handling_t)(struct sip_msg*);
..

12.  contains_event

   Field type:
..
typedef pres_ev_t* (*contains_event_t)(str* name,
event_t* parsed_event);
...

   The function parses the event name received as a parameter and searches
   the result in the list. It returns the found event or NULL, if not
   found. If the second argument is an allocated event_t* structure it
   fills it with the result of the parsing.

13.  get_event_list

   Field type:
...
typedef int (*get_event_list_t) (str** ev_list);
...

   This function returns a string representation of the events registered
   in presence module.( used for Allowed-Events header).

14.  update_watchers_status

   Field type:
...
typedef int (*update_watchers_t)(str pres_uri, pres_ev_t* ev,
str* rules_doc);
...

   This function is an external command that can be used to announce a
   change in authorization rules for a presentity. It updates the stored
   status and sends a Notify to the watchers whose status has changes.
   (used by presence_xml module when notified through an MI command of a
   change in an xcap document).

15.  get_sphere

   Field type:
...
typedef char* (*pres_get_sphere_t)(str* pres_uri);
...

   This function searches for a sphere definition in the published
   information if this has type RPID. If not found returns NULL. (the
   return value is allocated in private memory and should be freed)

16.  get_presentity

   Field type:
...
typedef str* (*pres_get_presentity_t)(str pres_uri, pres_ev_t *ev, str *etag, st
r *contact);
...

   This function returns a pointer to a str containing an XML document
   with all of the matching presentities. If no matching presentities are
   found the function returns NULL.

   The etag and contact parameters are optional and may be set to NULL.
   Once you are finished with the presentity document you must call
   free_presentity to free the allocated memory.

17.  free_presentity

   Field type:
...
typedef void (*pres_free_presentity_t)(str *presentity, pres_ev_t *ev);
...

   This function frees memory allocated by a call to get_presentity. The
   ev parameter MUST point to the same pres_ev_t data-structure that was
   used in the call to get_presentity.
