kamailio/obsolete/presence_b2b/README

1. Presence B2B UA

Vaclav Kubart

   Iptel/Tekelec
   <vaclav.kubart@iptel.org>
     __________________________________________________________________

   1.1. Dependencies
   1.2. Usage
   1.3. Parameters
   1.4. Functions

   This module acts as back to back user agent for presence events. In the
   future it will do subscriptions to reg events and presence with
   resource lists too.

   It is accessible only using the internal Query Status API (QSA).
   Everywhere (in the C code) where you need subscriptions to presentity
   status, you only create an internal subscription to it and the rest is
   done by this module. It processes the internal subscription and creates
   a SIP subscription (SUBSCRIBE-NOTIFY dialog) to requested presentity.
   Every NOTIFY request produces new QSA message with status information
   into destination message queue.

   Instead of this module can be used PA module with parameter
   accept_internal_subscriptions set to 1. In that case the subscription
   will be only to internal status hold by PA.

   For every requested (record, subscriber) a new SIP subscription is
   created. This is due to authorization of such subscriptions - B2B UA
   can't decide about authorization rules, thus it has to leave it on the
   presence server to which it creates the subscription and this means,
   that it has to create the subscription as a subscriber. There is a
   possibility to do subscriptions with the same To + From only once, but
   this is left for future optimalizations (it will probably not help a
   lot).

1.1. Dependencies

   Modules
     * tm
     * dialog

   Libraries
     * libcds (internal)
     * libpresence (internal)

1.2. Usage

   This module can be used by RLS module (e.g. RLS module does internal
   subscriptions to "presence" which can be handled by this module or PA
   module).

   In near future it will be used by PA module for subscribing to users;
   this could be useful with UACs capable to process SUBSCRIBE/NOTIFY but
   not using PUBLISH for presence state publication (like Windows
   Messenger).

1.3. Parameters

   default_expiration (integer)
          Default subscription expiration timeout in seconds.

          Default value is 3600.

   on_error_retry_time (integer)
          Time in seconds to next attempt at subscription creation after
          receiving an error from peer (for example 404 response on
          SUBSCRIBE request).

          Default value is 120.

   presence_route (string)
          Route header put into first generated SUBSCRIBE request.

          Default value: empty.

   additional_presence_headers (string)
          Additional headers put into sent SUBSCRIBE requests.

          Default value: empty.

   wait_for_term_notify (integer)
          Default timeout for receiving terminating NOTIFY after
          unsubscribe (SUBSCRIBE with Expires: 0). If no NOTIFY is
          received during this time, the subscription is destroyed without
          processing last notify.

          Default value is 30.

   resubscribe_delta (integer)
          Number of seconds before subscription expiration when should be
          sent resubscription request. For example if this value is 60 and
          the subscription is for 3600 seconds (Expires in 2xx response),
          next SUBSCRIBE request will be sent after 3540 seconds.

          Default value is 30.

   min_resubscribe_time (integer)
          Minimum number of seconds between consequent SUBSCRIBE requests.
          (Renewal SUBSCRIBE is sent at least after this number of
          seconds.)

          Default value is 30.

   handle_presence_subscriptions (integer)
          If set to nonzero value the module will handle internal (QSA)
          subscriptions to presence events. If not set, these internal
          subscriptions are ignored.

          Default value is 1.

   presence_outbound_proxy
          URI where to send all presence SUBSCRIBEs. It is better to use
          this than presence_route.

          Empty by default.

   max_subscribe_delay
          If set to value greater than zero SUBSCRIBE requests are sent
          randomly at most after max_subscribe_delay seconds. SUBSCRIBE
          requests are sent immediately when processing internal (QSA)
          subscription when set to 0.

          Default value is 0.

1.4. Functions

   handle_notify()
          Handles NOTIFY request.

          The module tries to find the subscription to which the NOTIFY
          belongs to (it tries both - confirmed and unconfirmed
          subscriptions because NOTIFY may arrive before 2xx response on
          SUBSCRIBE request). If no such subscription exists, the function
          returns -1, otherwise it processes the request (generates
          internal notification, ...) and returns 1.

   Example 1. Configuration example
...
loadmodule "/home/kubartv/SER/lib/ser/modules/tm.so"
loadmodule "/home/kubartv/SER/lib/ser/modules/dialog.so"
loadmodule "/home/kubartv/SER/lib/ser/modules/presence_b2b.so"

...
modparam("presence_b2b", "presence_route", "<sip:my-sip-server.domain.com;lr>")
modparam("presence_b2b", "on_error_retry_time", 600)
modparam("presence_b2b", "wait_for_term_notify", 33)
modparam("presence_b2b", "resubscribe_delta", 15)
modparam("presence_b2b", "min_resubscribe_time", 55)
modparam("presence_b2b", "default_expiration", 667)
...

route {

        ...

        if (uri==myself) {

                ...

                if (method=="NOTIFY") {
                        if (!t_newtran()) {
                           log(1, "newtran error\n");
                           sl_reply_error();
                        };
                        if (!handle_notify()) {
                                t_reply("481", "Unable to handle notification");
                        }
                        break;
                };

                ...
        }

        ...

}