name mode size
..
doc 040000
Makefile 100644 358B
README 100644 16.98kB
bind_presence.c 100644 1.45kB
bind_presence.h 100644 1.44kB
event_list.c 100644 7.74kB
event_list.h 100644 3.83kB
hash.c 100644 10kB
hash.h 100644 2.36kB
notify.c 100644 44.62kB
notify.h 100644 1.96kB
presence.c 100644 17.72kB
presence.h 100644 1.92kB
presentity.c 100644 16.4kB
presentity.h 100644 1.78kB
publish.c 100644 12.32kB
publish.h 100644 1.4kB
subscribe.c 100644 51.97kB
subscribe.h 100644 2.2kB
utils_func.c 100644 3.78kB
utils_func.h 100644 3.84kB
README
Presence Module Anca-Maria Vamanu voice-system.ro Edited by Anca-Maria Vamanu Copyright � 2006 voice-system.ro _________________________________________________________ Table of Contents 1. User's Guide 1.1. Overview 1.2. Dependencies 1.2.1. OpenSER Modules 1.2.2. External Libraries or Applications 1.3. Exported Parameters 1.3.1. db_url(str) 1.3.2. presentity_table(str) 1.3.3. active_watchers_table(str) 1.3.4. watchers_table(str) 1.3.5. clean_period (int) 1.3.6. to_tag_pref (str) 1.3.7. lock_set_size (int) 1.3.8. expires_offset (int) 1.3.9. max_expires (int) 1.3.10. server_address (str) 1.3.11. fallback2db (int) 1.4. Exported Functions 1.4.1. handle_publish(char* sender_uri) 1.4.2. handle_subscribe() 1.5. Installation 2. Developer's Guide 2.1. bind_presence(presence_api_t* api) 2.2. add_event 2.3. get_rules_doc 2.4. get_auth_status 2.5. apply_auth_nbody 2.6. agg_nbody 2.7. free_body 2.8. evs_publ_handl 2.9. evs_subs_handl 2.10. contains_event 2.11. get_event_list 2.12. update_watchers_status 3. Frequently Asked Questions 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 to_tag_pref parameter 1-7. Set lock_set_size 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. handle_publish usage 1-13. handle_subscribe usage 2-1. presence_api_t structure _________________________________________________________ Chapter 1. User's Guide 1.1. Overview The modules handles PUBLISH and SUBSCRIBE messages and generates NOTIFY messages in a general, event independent way. It allows registering events to it from other OpenSER modules. Events that can currently be added to it are: presence, presence.winfo, dialog;sla from presence_xml module and message-summary from presence_mwi module. The modules uses database storage. It has later been improved with memory caching operations to improve performance. The Subscribe dialog information are stored in memory and are periodically updated in database, while for Publish only the presence or absence of stored info for a certain resource is maintained in memory to avoid unnecessary, costly db operations. It is possible to configure a fallback to database mode(by setting 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 more machines using the same database. The module can also work only with the functionality of a library, with no message processing and generation, but used only for the exported functions. This mode of operation is enabled if the db_url parameter is not set to any value. The server follows the specifications in: RFC3265, RFC3856, RFC3857, RFC3858. _________________________________________________________ 1.2. Dependencies 1.2.1. OpenSER Modules The following modules must be loaded before this module: * a database module. * sl. * tm. _________________________________________________________ 1.2.2. External Libraries or Applications None. _________________________________________________________ 1.3. Exported Parameters 1.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@192.168.2.132/openser") ... _________________________________________________________ 1.3.2. presentity_table(str) The name of the db table where Publish information are stored. Default value is "presentity". Example 1-2. Set presentity_table parameter ... modparam("presence", "presentity_table", "presentity"); ... _________________________________________________________ 1.3.3. active_watchers_table(str) The name of the db table where active subscription information are stored. Default value is "active_watchers". Example 1-3. Set active_watchers_table parameter ... modparam("presence", "active_watchers_table", "active_watchers") ... _________________________________________________________ 1.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") ... _________________________________________________________ 1.3.5. clean_period (int) The period at which to verify if there are expired messages stored in database. Default value is "100". Example 1-5. Set clean_period parameter ... modparam("presence", "clean_period", 100) ... _________________________________________________________ 1.3.6. to_tag_pref (str) The prefix used when generating to_tag when sending replies for SUBSCRIBE requests. Default value is "10". Example 1-6. Set to_tag_pref parameter ... modparam("presence", "to_tag_pref", 'a') ... _________________________________________________________ 1.3.7. lock_set_size (int) The size of the lock used for synchronizing updating information from database. Default value is "8". Example 1-7. Set lock_set_size parameter ... modparam("presence", "lock_set_size", 8) ... _________________________________________________________ 1.3.8. expires_offset (int) The value that should be subtracted from the expires value when sending a 200OK for a publish. It is used for forcing the client cu send an update before the old publish expires. Default value is "0". Example 1-8. Set expires_offset parameter ... modparam("presence", "expires_offset", 10) ... _________________________________________________________ 1.3.9. max_expires (int) The the maximum admissible expires value for PUBLISH/SUBSCRIBE message. Default value is "3600". Example 1-9. Set max_expires parameter ... modparam("presence", "max_expires", 3600) ... _________________________________________________________ 1.3.10. server_address (str) The presence server address which will become the value of Contact header filed for 200OK 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") ... _________________________________________________________ 1.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 machines using the same database. Example 1-11. Set fallback2db parameter ... modparam("presence", "fallback2db", 1) ... _________________________________________________________ 1.4. Exported Functions 1.4.1. handle_publish(char* sender_uri) The function handles PUBLISH requests. It stores and updates published information in database and 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. Example 1-12. handle_publish usage ... if(is_method("PUBLISH")) { if($hdr(Sender)!= NULL) handle_publish("$hdr(Sender)"); else handle_publish(); t_release(); } ... _________________________________________________________ 1.4.2. handle_subscribe() The function which handles SUBSCRIBE requests. It stores or updates information in 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. Example 1-13. handle_subscribe usage ... if(method=="SUBSCRIBE") handle_subscribe(); ... _________________________________________________________ 1.5. Installation The module requires 3 table in OpenSER database: presentity, active_watchers and watchers tables. The SQL syntax to create them can be found in presence_xml-create.sql script in the database directories in the openser/scripts folder. You can also find the complete database documentation on the project webpage, http://www.openser.org/docs/db-tables/openser-db-devel.html. _________________________________________________________ Chapter 2. Developer's Guide The module provides the following functions that can be used in other OpenSER modules. _________________________________________________________ 2.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; get_event_list_t get_event_list; update_watchers_t update_watchers_status; }presence_api_t; ... _________________________________________________________ 2.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; struct pres_ev* wipeer; struct pres_ev* next; }pres_ev_t; ... _________________________________________________________ 2.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. _________________________________________________________ 2.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); ... _________________________________________________________ 2.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** ); ... _________________________________________________________ 2.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); .. _________________________________________________________ 2.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); .. _________________________________________________________ 2.8. evs_publ_handl This function is called when handling Publish requests. Most contain body correctness check. ... typedef int (publ_handling_t)(struct sip_msg*); .. _________________________________________________________ 2.9. 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*); .. _________________________________________________________ 2.10. 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. _________________________________________________________ 2.11. 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). _________________________________________________________ 2.12. 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). _________________________________________________________ Chapter 3. Frequently Asked Questions 3.1. Where can I find more about OpenSER? 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 OpenSER? Take a look at http://openser.org/. 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: * User Mailing List - http://openser.org/cgi-bin/mailman/listinfo/users * Developer Mailing List - http://openser.org/cgi-bin/mailman/listinfo/devel E-mails regarding any stable OpenSER release should be sent to <users@openser.org> and e-mails regarding development versions should be sent to <devel@openser.org>. If you want to keep the mail private, send it to <team@openser.org>. 3.3. How can I report a bug? Please follow the guidelines provided at: http://sourceforge.net/tracker/?group_id=139143.