mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
358 lines
9.9 KiB
358 lines
9.9 KiB
Presence_XML Module
|
|
|
|
Anca-Maria Vamanu
|
|
|
|
Voice Sistem SRL
|
|
|
|
Edited by
|
|
|
|
Anca-Maria Vamanu
|
|
|
|
Copyright © 2007 Voice Sistem SRL
|
|
__________________________________________________________________
|
|
|
|
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. xcap_table(str)
|
|
3.3. disable_presence(int)
|
|
3.4. disable_winfo(int)
|
|
3.5. disable_bla(int)
|
|
3.6. force_active (int)
|
|
3.7. integrated_xcap_server (int)
|
|
3.8. xcap_server (str)
|
|
3.9. passive_mode(int)
|
|
3.10. xcapauth_userdel_reason(str)
|
|
|
|
4. Functions
|
|
|
|
4.1. pres_check_basic(presentity_uri, status)
|
|
4.2. pres_check_activities(presentity_uri, activity)
|
|
|
|
5. Installation
|
|
6. Exported pseudo-variables
|
|
|
|
2. Developer Guide
|
|
|
|
List of Examples
|
|
|
|
1.1. Set db_url parameter
|
|
1.2. Set xcap_table parameter
|
|
1.3. Set disable_presence parameter
|
|
1.4. Set disable_winfo parameter
|
|
1.5. Set disable_bla parameter
|
|
1.6. Set force_active parameter
|
|
1.7. Set integrated_xcap_server parameter
|
|
1.8. Set xcap_server parameter
|
|
1.9. Set passive_mode parameter
|
|
1.10. Set xcapauth_userdel_reason parameter
|
|
1.11. pres_check_basic usage
|
|
1.12. pres_check_activities usage
|
|
|
|
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. xcap_table(str)
|
|
3.3. disable_presence(int)
|
|
3.4. disable_winfo(int)
|
|
3.5. disable_bla(int)
|
|
3.6. force_active (int)
|
|
3.7. integrated_xcap_server (int)
|
|
3.8. xcap_server (str)
|
|
3.9. passive_mode(int)
|
|
3.10. xcapauth_userdel_reason(str)
|
|
|
|
4. Functions
|
|
|
|
4.1. pres_check_basic(presentity_uri, status)
|
|
4.2. pres_check_activities(presentity_uri, activity)
|
|
|
|
5. Installation
|
|
6. Exported pseudo-variables
|
|
|
|
1. Overview
|
|
|
|
The module does specific handling for notify-subscribe events using xml
|
|
bodies. It is used with the general event handling module, presence. It
|
|
constructs and adds 3 events to it:
|
|
* presence - SIMPLE status presence: RFC 3856
|
|
* presence.winfo - SIMPLE watcher info: RFC 3857
|
|
* dialog;sla (or dialog;ma) - Bridged Line Appearances (BLA) (or
|
|
Multiple Line Appearances (MLA)): draft-anil-sipping-bla
|
|
|
|
You can control which events are enabled via module parameters.
|
|
|
|
This module takes the XCAP permission rule documents from xcap_table.
|
|
The presence permission rules are interpreted according to the
|
|
specifications in RFC 4745 and RFC 5025.
|
|
|
|
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.
|
|
* presence.
|
|
* sl.
|
|
* xcap_client.
|
|
Only compulsory if not using an integrated xcap server (if
|
|
'integrated_xcap_server' parameter is not set).
|
|
|
|
2.2. External Libraries or Applications
|
|
|
|
The following libraries or applications must be installed before
|
|
running Kamailio with this module loaded:
|
|
* libxml.
|
|
|
|
3. Parameters
|
|
|
|
3.1. db_url(str)
|
|
3.2. xcap_table(str)
|
|
3.3. disable_presence(int)
|
|
3.4. disable_winfo(int)
|
|
3.5. disable_bla(int)
|
|
3.6. force_active (int)
|
|
3.7. integrated_xcap_server (int)
|
|
3.8. xcap_server (str)
|
|
3.9. passive_mode(int)
|
|
3.10. xcapauth_userdel_reason(str)
|
|
|
|
3.1. db_url(str)
|
|
|
|
The database URL.
|
|
|
|
Default value is "mysql://kamailio:kamailiorw@localhost/kamailio".
|
|
|
|
Example 1.1. Set db_url parameter
|
|
...
|
|
modparam("presence_xml", "db_url", "dbdriver://username:password@dbhost/dbname")
|
|
...
|
|
|
|
3.2. xcap_table(str)
|
|
|
|
The name of the database table where XCAP documents are stored.
|
|
|
|
Default value is "xcap".
|
|
|
|
Example 1.2. Set xcap_table parameter
|
|
...
|
|
modparam("presence_xml", "xcap_table", "xcaps")
|
|
...
|
|
|
|
3.3. disable_presence(int)
|
|
|
|
Set this parameter to disable the handling of the "presence" event.
|
|
|
|
Default value: "0".
|
|
|
|
Example 1.3. Set disable_presence parameter
|
|
...
|
|
modparam("presence_xml", "disable_presence", 1)
|
|
...
|
|
|
|
3.4. disable_winfo(int)
|
|
|
|
Set this parameter to disable the handling of the "presence.winfo"
|
|
event.
|
|
|
|
Default value: "0".
|
|
|
|
Example 1.4. Set disable_winfo parameter
|
|
...
|
|
modparam("presence_xml", "disable_winfo", 1)
|
|
...
|
|
|
|
3.5. disable_bla(int)
|
|
|
|
Set this parameter to disable the handling of the "dialog;sla" event.
|
|
|
|
Default value: "1" (0 - enabled, 1 - disabled).
|
|
|
|
Example 1.5. Set disable_bla parameter
|
|
...
|
|
modparam("presence_xml", "disable_bla", 1)
|
|
...
|
|
|
|
3.6. force_active (int)
|
|
|
|
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 (should be set to 1 if not
|
|
using an XCAP server). Otherwise, the XCAP server is queried and the
|
|
subscription states is according to user defined permission rules. If
|
|
no rules are defined for a certain watcher, the subscriptions remains
|
|
in pending state and the Notify sent will have no body.
|
|
|
|
Note: When switching from one value to another, the watchers table must
|
|
be emptied.
|
|
|
|
Default value is "0".
|
|
|
|
Example 1.6. Set force_active parameter
|
|
...
|
|
modparam("presence_xml", "force_active", 1)
|
|
...
|
|
|
|
3.7. integrated_xcap_server (int)
|
|
|
|
This parameter is a flag for the type of XCAP servers used. If the XCAP
|
|
server is integrated with Kamailio presence_xml module and access the
|
|
same database tables directly, like the embedded XCAP server
|
|
implemented in xcap_server module, the parameter should be set to a
|
|
positive value. Apart from updating in xcap table, if the integrated
|
|
server is not running on the same Kamailio instance, it must send an MI
|
|
command refershWatchers [pres_uri] [event] when a user modifies a rules
|
|
document, to instruct the presence_xml module to update states from the
|
|
database and, if needed, send NOTIFY updates.
|
|
|
|
Otherwise, it uses xcap_client module to fetch documents from the XCAP
|
|
servers with HTTP requests.
|
|
|
|
Default value is "0".
|
|
|
|
Example 1.7. Set integrated_xcap_server parameter
|
|
...
|
|
modparam("presence_xml", "integrated_xcap_server", 1)
|
|
...
|
|
|
|
3.8. xcap_server (str)
|
|
|
|
The address of the xcap servers used for storage. This parameter is
|
|
compulsory if the integrated_xcap_server parameter is not set. It can
|
|
be set more that once, to construct an address list of trusted XCAP
|
|
servers.
|
|
|
|
Example 1.8. Set xcap_server parameter
|
|
...
|
|
modparam("presence_xml", "xcap_server", "xcap_server.example.org")
|
|
modparam("presence_xml", "xcap_server", "xcap_server.ag.org")
|
|
...
|
|
|
|
3.9. passive_mode(int)
|
|
|
|
If set to 1, module acts in passive mode - no bind to presence module,
|
|
no connection to database. Useful when needing only to use $xml(...)
|
|
pseudoc-variable.
|
|
|
|
Default value: "0" (0 - active mode, 1 - passive mode).
|
|
|
|
Example 1.9. Set passive_mode parameter
|
|
...
|
|
modparam("presence_xml", "passive_mode", 1)
|
|
...
|
|
|
|
3.10. xcapauth_userdel_reason(str)
|
|
|
|
This parameter represents the reason that will be included in the
|
|
Subscription-State header of the Notify when a rule is no longer found
|
|
in the XCAP pres-auth document for a user that was previously allowed.
|
|
The Subscription state in this case switches to "terminated". Because
|
|
it is not clear which reason is most appropriate in this case from the
|
|
ones defined by the RFC 3265, this parameter offers the possibility for
|
|
the admin to decide which one he wishes to use.
|
|
|
|
Default value: "probation" . Since probation also accepts a retry-after
|
|
parameter to specify after at least how may seconds the client should
|
|
reattempt to resubscribe, you can include this in the parameter also.
|
|
|
|
Example 1.10. Set xcapauth_userdel_reason parameter
|
|
...
|
|
modparam("presence_xml", "xcapauth_userdel_reason", "probation;retry-after=30")
|
|
modparam("presence_xml", "xcapauth_userdel_reason", "rejected")
|
|
...
|
|
|
|
4. Functions
|
|
|
|
4.1. pres_check_basic(presentity_uri, status)
|
|
4.2. pres_check_activities(presentity_uri, activity)
|
|
|
|
4.1. pres_check_basic(presentity_uri, status)
|
|
|
|
Checks the /presence/tuple/status/basic nodes in the presentity for
|
|
presentity_uri against the value in status.
|
|
|
|
This function can be used from ANY_ROUTE.
|
|
|
|
Return code:
|
|
* 1 - if a match is found.
|
|
* -1 - if a match is not found.
|
|
|
|
Example 1.11. pres_check_basic usage
|
|
...
|
|
if (pres_check_basic("$ru", "open")) {
|
|
...
|
|
} else {
|
|
if (is_method("MESSAGE"))
|
|
m_store();
|
|
else
|
|
send_reply("404", "Not Found");
|
|
}
|
|
...
|
|
|
|
4.2. pres_check_activities(presentity_uri, activity)
|
|
|
|
Checks whether a /presence/person/activities/activity node exists in
|
|
the presentity for presentity_uri.
|
|
|
|
This function can be used from ANY_ROUTE.
|
|
|
|
Return code:
|
|
* 1 - if a match is found.
|
|
* -1 - if a match is not found.
|
|
* -2 - if /presence/person or /presence/person/activity do not exist.
|
|
|
|
Example 1.12. pres_check_activities usage
|
|
...
|
|
if (pres_check_basic("$ru", "open")) {
|
|
pres_check_activities("$ru", "unknown");
|
|
if ($retcode || $retcode == -2 || !is_method("INVITE"))
|
|
t_relay();
|
|
else
|
|
send_reply("486", "Busy Here");
|
|
} else {
|
|
...
|
|
}
|
|
...
|
|
|
|
5. Installation
|
|
|
|
The module requires one table in Kamailio database: "xcap". The SQL
|
|
syntax to create it 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.
|
|
|
|
6. Exported pseudo-variables
|
|
|
|
* $xml(name=>spec)
|
|
|
|
Exported pseudo-variables are documented at
|
|
http://www.kamailio.org/wiki/.
|
|
|
|
Chapter 2. Developer Guide
|
|
|
|
The module exports no function to be used in other Kamailio modules.
|