sipwise
/
kamailio
mirror of https://github.com/sipwise/kamailio.git
1
0
Fork 0
Code Issues Releases Wiki Activity
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.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '07d22578d2'
${ noResults }
kamailio/modules/presence/README

1343 lines
39 KiB
Raw Blame History

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. waitn_time (int)
3.8. notifier_poll_rate (int)
3.9. notifier_processes (int)
3.10. to_tag_pref (str)
3.11. expires_offset (int)
3.12. max_expires (int)
3.13. min_expires (int)
3.14. min_expires_action (int)
3.15. server_address (str)
3.16. subs_db_mode (int)
3.17. publ_cache (int)
3.18. subs_htable_size (int)
3.19. pres_htable_size (int)
3.20. send_fast_notify (int)
3.21. enable_sphere_check (int)
3.22. timeout_rm_subs (int)
3.23. fetch_rows (integer)
3.24. db_table_lock_type (integer)
3.25. local_log_level (int)
3.26. subs_remove_match (int)
3.27. xavp_cfg (str)
3.28. retrieve_order (int)
3.29. sip_uri_match (int)
4. Functions
4.1. handle_publish([sender_uri])
4.2. handle_subscribe([watcher_uri])
4.3. pres_auth_status(watcher_uri, presentity_uri)
4.4. pres_refresh_watchers(uri, event, type[, file_uri,
filename])
4.5. pres_update_watchers(uri, event)
5. MI Commands
5.1. refreshWatchers
5.2. cleanup
6. RPC Commands
6.1. presence.cleanup
7. Pseudo Variables
7.1. $subs(attr)
7.2. $notify_reply(attr)
8. Events
8.1. present:notify-reply
9. 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 waitn_time parameter
1.8. Set notifier_poll_rate parameter
1.9. Set notifier_processes parameter
1.10. Set to_tag_pref parameter
1.11. Set expires_offset parameter
1.12. Set max_expires parameter
1.13. Set min_expires parameter
1.14. Set min_expires parameter
1.15. Set server_address parameter
1.16. Set subs_db_mode parameter
1.17. Set publ_cache parameter
1.18. Set subs_htable_size parameter
1.19. Set pres_htable_size parameter
1.20. Set send_fast_notify parameter
1.21. Set enable_sphere_check parameter
1.22. Set timeout_rm_subs parameter
1.23. Set fetch_rows parameter
1.24. Set db_table_lock_type parameter
1.25. Set local_log_level parameter
1.26. Set subs_remove_match parameter
1.27. Set xavp_cfg parameter
1.28. Set retrieve_order parameter
1.29. Set sip_uri_match parameter
1.30. handle_publish usage
1.31. handle_subscribe usage
1.32. pres_auth_status usage
1.33. pres_refresh_watchers usage
1.34. pres_update_watchers usage
1.35. $subs(name) usage
1.36. $notify_reply(name) usage
1.37. $notify_reply(name) 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. waitn_time (int)
3.8. notifier_poll_rate (int)
3.9. notifier_processes (int)
3.10. to_tag_pref (str)
3.11. expires_offset (int)
3.12. max_expires (int)
3.13. min_expires (int)
3.14. min_expires_action (int)
3.15. server_address (str)
3.16. subs_db_mode (int)
3.17. publ_cache (int)
3.18. subs_htable_size (int)
3.19. pres_htable_size (int)
3.20. send_fast_notify (int)
3.21. enable_sphere_check (int)
3.22. timeout_rm_subs (int)
3.23. fetch_rows (integer)
3.24. db_table_lock_type (integer)
3.25. local_log_level (int)
3.26. subs_remove_match (int)
3.27. xavp_cfg (str)
3.28. retrieve_order (int)
3.29. sip_uri_match (int)
4. Functions
4.1. handle_publish([sender_uri])
4.2. handle_subscribe([watcher_uri])
4.3. pres_auth_status(watcher_uri, presentity_uri)
4.4. pres_refresh_watchers(uri, event, type[, file_uri, filename])
4.5. pres_update_watchers(uri, event)
5. MI Commands
5.1. refreshWatchers
5.2. cleanup
6. RPC Commands
6.1. presence.cleanup
7. Pseudo Variables
7.1. $subs(attr)
7.2. $notify_reply(attr)
8. Events
8.1. present:notify-reply
9. 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 can use database and memory storage (to improve
performance). For subscriptions it supports the 4 storage modes: Memory
Only, Write Back, Write Through and DB Only. For publishes, it stores
the state documents in database only(because of the large size) and it
can store a publish cache in memory to avoid unnecessairy database
queries. Read the subs_db_mode and publ_cache parameter sections to
decide which is the best storage configuration for you.
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. waitn_time (int)
3.8. notifier_poll_rate (int)
3.9. notifier_processes (int)
3.10. to_tag_pref (str)
3.11. expires_offset (int)
3.12. max_expires (int)
3.13. min_expires (int)
3.14. min_expires_action (int)
3.15. server_address (str)
3.16. subs_db_mode (int)
3.17. publ_cache (int)
3.18. subs_htable_size (int)
3.19. pres_htable_size (int)
3.20. send_fast_notify (int)
3.21. enable_sphere_check (int)
3.22. timeout_rm_subs (int)
3.23. fetch_rows (integer)
3.24. db_table_lock_type (integer)
3.25. local_log_level (int)
3.26. subs_remove_match (int)
3.27. xavp_cfg (str)
3.28. retrieve_order (int)
3.29. sip_uri_match (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://kamailio:kamailiorw@localhost/kamailio")
...
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. waitn_time (int)
The maximum time period that NOTIFY requests will be buffered for. The
server will attempt to send NOTIFY requests within many seconds of a
change occurring.
Note: this parameter is only used when notifier_processes is greater
than 0. When notifier_processes is less than or equal to 0 NOTIFY
requests are sent immediately.
Default value is “5”.
Example 1.7. Set waitn_time parameter
...
modparam("presence", "waitn_time", 10)
...
3.8. notifier_poll_rate (int)
The number of times per second that the notifier processes should check
for work. Approximately 1/(waitn_time * notifier_poll_rate *
notifier_processes) of the pending updates will be sent each time a
notifier process runs.
Separate notifier processes are only run when subs_db_mode is 3 (DB
only mode).
Default value is “10”.
Example 1.8. Set notifier_poll_rate parameter
...
modparam("presence", "notifier_poll_rate", 20)
...
3.9. notifier_processes (int)
The number of notifier processes that should be started.
Separate notifier processes are only run when subs_db_mode is 3 (DB
only mode).
Note: setting this parameter to 0 when subs_db_mode is 3 keeps the old
behaviour (sending NOTIFY requests immediately). This (old) behaviour
is disabled by default in DB only mode because under load, when lots of
NOTIFY requests can be sent on a dialog at the same time, there are
race conditions which result in CSeq re-use.
Default value is “1”.
Example 1.9. Set notifier_processes parameter
...
modparam("presence", "notifier_processes", 2)
...
3.10. to_tag_pref (str)
The prefix used when generating to_tag when sending replies for
SUBSCRIBE requests.
Default value is “10”.
Example 1.10. Set to_tag_pref parameter
...
modparam("presence", "to_tag_pref", 'pres')
...
3.11. 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.11. Set expires_offset parameter
...
modparam("presence", "expires_offset", 10)
...
3.12. max_expires (int)
The maximum admissible expires value for PUBLISH/SUBSCRIBE message (in
seconds).
Default value is “3600”.
Example 1.12. Set max_expires parameter
...
modparam("presence", "max_expires", 3600)
...
3.13. min_expires (int)
The minimum admissible expires value for PUBLISH/SUBSCRIBE message (in
seconds).
If > 0 then min_expires_action parameter determines the response.
Default value is “0”.
Example 1.13. Set min_expires parameter
...
modparam("presence", "min_expires", 1800)
...
3.14. min_expires_action (int)
The action to take when UA sends a expires value less then min_expires.
Possible Values
* 1 : RFC Compliant, returns “423 Interval Too Brief”
* 2 : forces the min_expires value in the subscription
If > 0 then min_expires_action parameter determines the response.
Default value is “1”.
Example 1.14. Set min_expires parameter
...
modparam("presence", "min_expires", 1800)
...
3.15. 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.15. Set server_address parameter
...
modparam("presence", "server_address", "sip:10.10.10.10:5060")
...
3.16. subs_db_mode (int)
The presence module can utilize database for persistent subscription
storage. If you use database, your subscriptions will survive machine
restarts or SW crashes. The disadvantage is that accessing database can
be time consuming. Therefore, presence module implements four database
accessing modes:
* 0 - This disables database completely. Only memory will be used.
Subscriptions will not survive restart. Use this value if you need
a really fast presence module and subscription persistence is not
necessary or is provided by other means.
* 1 - Write-Through scheme. Subscriptions are updated synchronously
in database and in memory(used for read operations). Use this
scheme if speed is not top priority, but it's important that no
subscriptions will be lost during crash or reboot or if you have an
external application that reads the state of the subscriptions from
database and they need to be updated synchronously.
* 2 - Write-Back scheme. This is a combination of previous two
schemes. All changes are made to memory and database
synchronization is done in the timer. The timer deletes all expired
contacts and flushes all modified or new subscriptions to database.
Use this scheme if you encounter high-load peaks and want them to
process as fast as possible. Latency of this mode is much lower
than latency of mode 1, but slightly higher than latency of mode 0.
To control the interval at which data is flushed to database, set
the db_update_period parameter.
* 3 - DB-Only scheme. No memory cache is kept, all operations being
directly performed with the database. The timer deletes all expired
subscriptions from database. The mode is useful if you configure
more servers sharing the same DB without any replication at SIP
level. The mode may be slower due the high number of DB operation.
Default value is 2 (Write-Back scheme).
Example 1.16. Set subs_db_mode parameter
...
modparam("presence", "subs_db_mode", 1)
...
3.17. publ_cache (int)
To improve performance, the presence module holds by default a publish
cache that says if a certain publication exists in database. This is
only a list of URI + event, so it does not use much memory. The cache
is used when a Subscription is received to check if there is any
published state in database. This way unnecessary queries in presentity
table are avoided.
Setting this parameter to 0 will disable the usage of the publish
cache. This is desirable when you have more servers sharing the same
database or there are other external entities inserting data into the
presentity table.
Default value is “1”.
Example 1.17. Set publ_cache parameter
...
modparam("presence", "publ_cache", 0)
...
3.18. 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.18. Set subs_htable_size parameter
...
modparam("presence", "subs_htable_size", 11)
...
3.19. 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.19. Set pres_htable_size parameter
...
modparam("presence", "pres_htable_size", 11)
...
3.20. 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.20. Set send_fast_notify parameter
...
modparam("presence", "send_fast_notify", 0)
...
3.21. 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.21. Set enable_sphere_check parameter
...
modparam("presence", "enable_sphere_check", 1)
...
3.22. 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.22. Set timeout_rm_subs parameter
...
modparam("presence", "timeout_rm_subs", 0)
...
3.23. fetch_rows (integer)
Number of rows to be loaded in one step from database.
Default value is 500.
Example 1.23. Set fetch_rows parameter
...
modparam("presence", "fetch_rows", 1000)
...
3.24. db_table_lock_type (integer)
Enable (=1) or disable (=0) the Locks for table during an transaction.
Locking only the "current" table causes problems with a MySQL-Databases
in "DB-Only" mode.
In order to use the Presence-Module in "DB_ONLY"-mode with a
MySQL-Backend, set this parameter to "0", otherwise the
MySQL-Operations will fail. The Presence-Module will generate a "500
Server error" due to the failed MySQL-queries.
Default value is 1 (Write Lock for the Tables).
Example 1.24. Set db_table_lock_type parameter
...
modparam("presence", "db_table_lock_type", 0)
...
3.25. local_log_level (int)
Control log level for some debug messages inside the module.
Default value is 2 (L_INFO).
Example 1.25. Set local_log_level parameter
...
modparam("presence", "local_log_level", 3)
...
3.26. subs_remove_match (int)
Control how to match the subscriptions to remove from memory. If set to
0, then the match is done on To-Tag (local generated), if set to 1,
then the match is done on all dialog attributes (Call-Id, From-Tag,
To-Tag).
Default value is 0.
Example 1.26. Set subs_remove_match parameter
...
modparam("presence", "subs_remove_match", 1)
...
3.27. xavp_cfg (str)
The name of the xavp to be used to specify attributes for internal
processing of presence module.
Inner attributes inside xavp can be:
* priority - integer value to set the priority of the presence
document (higher value, higher priority). It can set the order of
the aggregated presence documents sent by NOTIFY (first the
document with higher priority). If xavp_cfg parameter is set but
this attribute is not in the avp, the priority of the presence
document is based on timestamp, so newer documents have higher
priority.
Default value is empty (not set).
Example 1.27. Set xavp_cfg parameter
...
modparam("presence", "xavp_cfg", "pres")
...
if(is_method("PUBLISH")) {
$xavp(pres=>priority) = 100;
}
...
3.28. retrieve_order (int)
If set to 0, presentity records are retrieve by received_time order. if
set to 1, presentity records are retrieve by priority order.
Default value is 0.
Example 1.28. Set retrieve_order parameter
...
modparam("presence", "retrieve_order", 1)
...
3.29. sip_uri_match (int)
The mode used when comparing uris.
Possible Values
* 0 : case sensitive
* 1 : case insensitive
Default value is “0”.
Example 1.29. Set sip_uri_match parameter
...
modparam("presence", "sip_uri_match", 1)
...
4. Functions
4.1. handle_publish([sender_uri])
4.2. handle_subscribe([watcher_uri])
4.3. pres_auth_status(watcher_uri, presentity_uri)
4.4. pres_refresh_watchers(uri, event, type[, file_uri, filename])
4.5. pres_update_watchers(uri, event)
4.1. handle_publish([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.30. handle_publish usage
...
if(is_method("PUBLISH"))
{
if($hdr(Sender)!= NULL)
handle_publish("$hdr(Sender)");
else
handle_publish();
t_release();
}
...
4.2. handle_subscribe([watcher_uri])
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.
By default this function uses the From: URI from the SUBSCRIBE request
as the Watcher URI. The optional watcher_uri parameter can be used to
specify a different Watcher URI, possibly taken from a SIP header like
P-Asserted-Identity:.
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.31. 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.32. 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[, file_uri, filename])
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 three 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 through direct update
in db table.
+ 2 - a statical update in published state by modifying the pidf
manipulation document.
* file_uri - the uri of the pidf-manipulation file on the XCAP server
(only used for type 2).
* filename - the name of the pidf-manipulation file on the XCAP
server (only used for type 2).
This function can be used from ANY_ROUTE.
Example 1.33. 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.34. 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:
* 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 three 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 through direct update
in db table.
+ 2 - a statical update in published state by modifying the pidf
manipulation document.
* file_uri - the uri of the pidf-manipulation file on the XCAP server
(only used for type 2).
* filename - the name of the pidf-manipulation file on the XCAP
server (only used for type 2).
MI FIFO Command Format:
:refreshWatchers:fifo_reply
sip:test@kamailio.org
presence
1
_empty_line_
5.2. cleanup
Manually triggers the cleanup functions for the active_watchers,
presentity, and watchers tables. Useful if you have set clean_period
and/or db_update_period to zero or less.
Name: cleanup
Parameters: none
MI FIFO Command Format:
:cleanup:fifo_reply
_empty_line_
6. RPC Commands
6.1. presence.cleanup
6.1. presence.cleanup
Manually triggers the cleanup functions for the active_watchers,
presentity, and watchers tables. Useful if you have set clean_period
and/or db_update_period to zero or less.
Name: presence.cleanup
Parameters: none
7. Pseudo Variables
7.1. $subs(attr)
7.2. $notify_reply(attr)
7.1. $subs(attr)
Access the attributes of handled subscription. It must be used after a
successful call of “handle_subscription()” or in the following events.
* tm:local-request - before notify is sent
* present:notify-reply - after notify is sent
The “attr” can be:
* uri - subscription presentity uri
* pres_uri - alias for presentity uri
* to_user
* to_domain
* from_user
* from_domain
* watcher_username
* watcher_domain
* event
* event_id
* to_tag
* from_tag
* callid
* remote_cseq
* local_cseq
* contact
* local_contact
* record_route
* expires
* status
* reason
* version
* flags
* user_agent
Example 1.35. $subs(name) usage
...
if(handle_subscription())
{
xlog("presentity=$subs(uri)\n");
}
...
7.2. $notify_reply(attr)
Access the reply message received when notifying subscriber. It must be
used in the following events.
* present:notify-reply - after notify is sent
The “attr” can be any pseudo var that accesses attributes of msg
Example 1.36. $notify_reply(name) usage
...
event_route[presence:notify-reply]
{
xlog("received message = $notify_reply($mb)\n");
}
...
8. Events
8.1. present:notify-reply
8.1. present:notify-reply
Fired after notify reply is received or timeout.
Example 1.37. $notify_reply(name) usage
...
event_route[presence:notify-reply]
{
xlog("received message = $notify_reply($mb)\n");
}
...
9. 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_timer;
/* 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.
Reference in new issue View Git Blame Copy Permalink