PRESENCE USER AGENT module
Admin Guide
Section titled “Admin Guide”Overview
Section titled “Overview”This module offer the functionality of a presence user agent client, sending Subscribe and Publish messages.
Now it can be used with the following modules: pua_mi and pua_usrloc, pua_bla and pua_xmpp. The pua_mi offer the possibility to publish any kind of information or subscribing to a resource through fifo. The pua_usrloc module calls a function exported by pua modules to publish elementary presence information, such as basic status “open” or “closed”, for clients that do not implement client-to-server presence. Through pua_bla , BRIDGED LINE APPEARANCE features are added to OpenSIPs. The pua_xmpp module represents a gateway between SIP and XMPP, so that jabber and SIP clients can exchange presence information.
The module use cache to store presentity list and writes to database on timer to be able to recover upon restart.
Dependencies
Section titled “Dependencies”OpenSIPS Modules
Section titled “OpenSIPS Modules”The following modules must be loaded before this module:
- a database modules.
- tm.
External Libraries or Applications
Section titled “External Libraries or Applications”The following libraries or applications must be installed before running OpenSIPS with this module loaded:
- libxml.
Exported Parameters
Section titled “Exported Parameters”hash_size (int)
Section titled “hash_size (int)”The size of the hash table used for storing Subscribe and Publish information. This parameter will be used as the power of 2 when computing table size.
Default value is “9”.
...modparam("pua", "hash_size", 11)...db_url (str)
Section titled “db_url (str)”Database url.
Default value is “>mysql://opensips:opensipsrw@localhost/opensips”.
...modparam("pua", "db_url" "dbdriver://username:password@dbhost/dbname")...db_table (str)
Section titled “db_table (str)”The name of the database table.
Default value is “pua”.
...modparam("pua", "db_table", "pua")...min_expires (int)
Section titled “min_expires (int)”The inferior expires limit for both Publish and Subscribe.
Default value is “300”.
...modparam("pua", "min_expires", 0)...default_expires (int)
Section titled “default_expires (int)”The default expires value used in case this information is not provisioned.
Default value is “3600”.
...modparam("pua", "default_expires", 3600)...update_period (int)
Section titled “update_period (int)”The interval at which the information in database and hash table should be updated. In the case of the hash table updating is deleting expired messages.
Default value is “30”.
...modparam("pua", "update_period", 100)...Exported Functions
Section titled “Exported Functions”pua_update_contact()
Section titled “pua_update_contact()”The remote target can be updated by the Contact of a subsequent in dialog request. In the PUA watcher case (sending a SUBSCRIBE messages), this means that the remote target for the following Subscribe messages can be updated at any time by the contact of a Notify message. If this function is called on request route on receiving a Notify message, it will try to update the stored remote target.
This function can be used from REQUEST_ROUTE.
Return code:
- 1 - if success.
- -1 - if error.
...if($rm=="NOTIFY") pua_update_contact();...Installation
Section titled “Installation”The module requires 1 table in OpenSIPS database: pua. The SQL
syntax to create it can be found in presence_xml-create.sql
script in the database directories in the opensips/scripts folder.
You can also find the complete database documentation on the
project webpage, https://opensips.org/docs/db/db-schema-devel.html.
Developer Guide
Section titled “Developer Guide”The module provides the following functions that can be used in other OpenSIPS modules.
bind_pua(pua_api_t* api)
Section titled “bind_pua(pua_api_t* api)”This function binds the pua modules and fills the structure with the two exported function.
...typedef struct pua_api { send_subscribe_t send_subscribe; send_publish_t send_publish; query_dialog_t is_dialog; register_puacb_t register_puacb; add_pua_event_t add_event;} pua_api_t;...send_publish
Section titled “send_publish”Field type:
...typedef int (*send_publish_t)(publ_info_t* publ);...This function receives as a parameter a structure with Publish required information and sends a Publish message.
The structure received as a parameter:
...typedef struct publ_info
str id; /* (optional )a value unique for one combination of pres_uri and flag */ str* pres_uri; /* the presentity uri */ str* body; /* the body of the Publish message; can be NULL in case of an update expires*/ int expires; /* the expires value that will be used in Publish Expires header*/ int flag; /* it can be : INSERT_TYPE or UPDATE_TYPE if missing it will be established according to the result of the search in hash table*/ int source_flag; /* flag identifying the resource ; supported values: UL_PUBLISH, MI_PUBLISH, BLA_PUBLISH, XMPP_PUBLISH*/ int event; /* the event flag; supported values: PRESENCE_EVENT, BLA_EVENT, MWI_EVENT */ str content_type; /* the content_type of the body if present (optional if the same as the default value for that event)*/ str* etag; /* (optional) the value of the etag the request should match */ str* extra_headers /* (optional) extra_headers that should be added to Publish msg*/ publrpl_cb_t* cbrpl;/* callback function to be called when receiving the reply for the sent request */ void* cbparam; /* extra parameter for tha callback function */
str outbound_proxy; /* the outbound proxy to be used when sending the Publish request*/
}publ_info_t;...The callback function type:
...typedef int (publrpl_cb_t)(struct sip_msg* reply, void* extra_param);...send_subscribe
Section titled “send_subscribe”Field type:
...typedef int (*send_subscribe_t)(subs_info_t* subs);...This function receives as a parameter a structure with Subscribe required information and sends a Subscribe message.
The structure received as a parameter:
...typedef struct subs_info
str id; /* an id value unique for one combination of pres_uri and flag */ str* pres_uri; /* the presentity uri */ str* watcher_uri; /* the watcher uri */ str* contact; /* the uri that will be used in Contact header*/ str* remote_target; /* the uri that will be used as R-URI for the Subscribe message(not compulsory; if not set the value of the pres_uri field is used) */ str* outbound_proxy; /* the outbound_proxy to use when sending the Subscribe request*/ int event; /* the event flag; supported value: PRESENCE_EVENT, BLA_EVENT, PWINFO_EVENT*/ int expires; /* the expires value that will be used in Subscribe Expires header */ int flag; /* it can be : INSERT_TYPE or UPDATE_TYPE not compulsory */ int source_flag; /* flag identifying the resource ; supported values: MI_SUBSCRIBE, BLA_SUBSCRIBE, XMPP_SUBSCRIBE, XMPP_INITIAL_SUBS */}subs_info_t;...is_dialog
Section titled “is_dialog”Field type:
...typedef int (*query_dialog_t)(ua_pres_t* presentity);...This function checks is the parameter corresponds to a stored Subscribe initiated dialog.
... if(pua_is_dialog(dialog) < 0) { LM_ERR("querying dialog\n"); goto error; }...register_puacb
Section titled “register_puacb”Field type:
...typedef int (*register_puacb_t)(int types, pua_cb f, void* param );...This function registers a callback to be called on receiving the reply message for a sent Subscribe request. The type parameter should be set the same as the source_flag for that request. The function registered as callback for pua should be of type pua_cb , which is: typedef void (pua_cb)(ua_pres_t* hentity, struct msg_start * fl); The parameters are the dialog structure for that request and the first line of the reply message.
... if(pua.register_puacb(XMPP_SUBSCRIBE, Sipreply2Xmpp, NULL) & 0) { LM_ERR("Could not register callback\n"); return -1; }...add_event
Section titled “add_event”Field type:
...typedef int (*add_pua_event_t)(int ev_flag, char* name, char* content_type,evs_process_body_t* process_body);
- ev_flag : an event flag defined as a macro in pua module- name : the event name to be used in Event request headers- content_type: the default content_type for Publish body for that event (NULL if winfo event)- process_body: function that processes the received body before using it to construct the PUBLISH request (NULL if winfo event)...This function allows registering new events to the pua module. Now there are 4 events supported by the pua module: presence, presence;winfo, message-summary, dialog;sla. These events are registered from within the pua module.
Filed type for process_body:
...typedef int (evs_process_body_t)(struct publ_info* publ, str** final_body, int ver, str* tuple);- publ : the structure received as a parameter in send_publish function ( initial body found in publ->body)- final_body: the pointer where the result(final_body) should be stored- ver : a counter for the sent Publish requests (used for winfo events)- tuple : a unique identifier for the resource; if an initial Publish it should be returned as a result and it will be stored for that record, otherwise it will be given as a parameter;...... if(pua.add_event((PRESENCE_EVENT, "presence", "application/pidf+xml", pres_process_body) & 0) { LM_ERR("Could not register new event\n"); return -1; }...Contributors
Section titled “Contributors”By Commit Statistics
Section titled “By Commit Statistics”Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
| # | Name | DevScore | Commits | Lines++ | Lines— |
|---|---|---|---|---|---|
| 1. | Anca Vamanu | 271 | 106 | 10017 | 4766 |
| 2. | Bogdan-Andrei Iancu (@bogdan-iancu) | 61 | 48 | 508 | 467 |
| 3. | Ovidiu Sas (@ovidiusas) | 19 | 13 | 284 | 163 |
| 4. | Liviu Chircu (@liviuchircu) | 17 | 11 | 194 | 231 |
| 5. | Daniel-Constantin Mierla (@miconda) | 10 | 8 | 57 | 24 |
| 6. | Stefan Darius (@dariusstefan) | 10 | 4 | 534 | 51 |
| 7. | Razvan Crainea (@razvancrainea) | 9 | 7 | 26 | 27 |
| 8. | Saúl Ibarra Corretgé (@saghul) | 9 | 5 | 247 | 35 |
| 9. | Henning Westerholt (@henningw) | 7 | 4 | 92 | 82 |
| 10. | Vlad Patrascu (@rvlad-patrascu) | 5 | 3 | 18 | 9 |
All remaining contributors: Vlad Paiu (@vladpaiu), Juha Heinanen (@juha-h), Denis Bilenko, Walter Doekes (@wdoekes), Alex Hermann, Damien Sandras (@dsandras), Elena-Ramona Modroiu, John Riordan, Dan Pascu (@danpascu), Sergio Gutierrez, Konstantin Bokarius, Dusan Klinec (@ph4r05), Zero King (@l2dy), Peter Lemenkov (@lemenkov), Vallimamod Abdullah, UnixDev, Edson Gellert Schubert, Stanislaw Pitucha, Julien Blache.
(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)
(2) including any documentation-related commits, excluding merge commits
(3) ignoring whitespace edits, renamed files and auto-generated files
By Commit Activity
Section titled “By Commit Activity”| # | Name | Commit Activity |
|---|---|---|
| 1. | Stefan Darius (@dariusstefan) | Jun 2026 - Jul 2026 |
| 2. | Razvan Crainea (@razvancrainea) | Feb 2012 - Jun 2026 |
| 3. | Bogdan-Andrei Iancu (@bogdan-iancu) | Jan 2007 - Jan 2023 |
| 4. | Liviu Chircu (@liviuchircu) | Mar 2014 - Jul 2020 |
| 5. | Zero King (@l2dy) | Mar 2020 - Mar 2020 |
| 6. | Vlad Patrascu (@rvlad-patrascu) | May 2017 - Apr 2019 |
| 7. | Peter Lemenkov (@lemenkov) | Jun 2018 - Jun 2018 |
| 8. | Ovidiu Sas (@ovidiusas) | Nov 2010 - Feb 2016 |
| 9. | Dusan Klinec (@ph4r05) | Dec 2015 - Dec 2015 |
| 10. | Damien Sandras (@dsandras) | Sep 2013 - Sep 2013 |
All remaining contributors: Saúl Ibarra Corretgé (@saghul), Vlad Paiu (@vladpaiu), Anca Vamanu, Vallimamod Abdullah, Alex Hermann, Stanislaw Pitucha, Walter Doekes (@wdoekes), John Riordan, UnixDev, Sergio Gutierrez, Denis Bilenko, Henning Westerholt (@henningw), Dan Pascu (@danpascu), Daniel-Constantin Mierla (@miconda), Juha Heinanen (@juha-h), Konstantin Bokarius, Edson Gellert Schubert, Julien Blache, Elena-Ramona Modroiu.
(1) including any documentation-related commits, excluding merge commits
Documentation
Section titled “Documentation”Contributors
Section titled “Contributors”Last edited by: Razvan Crainea (@razvancrainea), Peter Lemenkov (@lemenkov), Liviu Chircu (@liviuchircu), Vlad Patrascu (@rvlad-patrascu), Bogdan-Andrei Iancu (@bogdan-iancu), Saúl Ibarra Corretgé (@saghul), Anca Vamanu, Henning Westerholt (@henningw), Daniel-Constantin Mierla (@miconda), Juha Heinanen (@juha-h), Konstantin Bokarius, Edson Gellert Schubert, Elena-Ramona Modroiu.
License
Section titled “License”All documentation files (i.e. .md extension) are licensed under the Creative Common License 4.0