From 1d00cf66f8006b082c0e0258371f4da5015b2ac2 Mon Sep 17 00:00:00 2001 From: Kamailio Dev Date: Wed, 31 Mar 2021 08:46:14 +0200 Subject: [PATCH] modules: readme files regenerated - cplc ... [skip ci] --- src/modules/cplc/README | 606 ++++++++++++++++++++++++++++++ src/modules/pua_dialoginfo/README | 556 +++++++++++++++++++++++++++ 2 files changed, 1162 insertions(+) diff --git a/src/modules/cplc/README b/src/modules/cplc/README index 8b137891791..76789354ed3 100644 --- a/src/modules/cplc/README +++ b/src/modules/cplc/README @@ -1 +1,607 @@ +cplc Module +Bogdan-Andrei Iancu + + Voice Sistem SRL + +Edited by + +Bogdan-Andrei Iancu + +Frederic Gaisnon + + + + Copyright © 2003 FhG FOKUS + + Copyright © 2021 MomentTech + __________________________________________________________________ + + 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 (string) + 3.2. db_table (string) + 3.3. username_column (string) + 3.4. domain_column (string) + 3.5. cpl_xml_column (string) + 3.6. cpl_bin_column (string) + 3.7. cpl_dtd_file (string) + 3.8. log_dir (string) + 3.9. proxy_recurse (int) + 3.10. proxy_route (string) + 3.11. case_sensitive (int) + 3.12. realm_prefix (string) + 3.13. timer_avp (string) + 3.14. lookup_domain (string) + 3.15. lookup_append_branches (int) + 3.16. use_domain (integer) + 3.17. redirect_route (string) + 3.18. ignore3xx (integer) + + 4. Functions + + 4.1. cpl_run_script(type,mode, [uri]) + 4.2. cpl_process_register() + 4.3. cpl_process_register_norpl() + + 5. RPC Commands + + 5.1. cpl.load + 5.2. cpl.remove + 5.3. cpl.get + + 6. Installation and Running + + 6.1. Database setup + + List of Examples + + 1.1. Set db_url parameter + 1.2. Set db_table parameter + 1.3. Set username_column parameter + 1.4. Set domain_column parameter + 1.5. Set cpl_xml_column parameter + 1.6. Set cpl_bin_column parameter + 1.7. Set cpl_dtd_file parameter + 1.8. Set log_dir parameter + 1.9. Set proxy_recurse parameter + 1.10. Set proxy_route parameter + 1.11. Set case_sensitive parameter + 1.12. Set realm_prefix parameter + 1.13. Set timer_avp parameter + 1.14. Set lookup_domain parameter + 1.15. Set lookup_append_branches parameter + 1.16. Set use_domain parameter + 1.17. Set redirect_route parameter + 1.18. Set ignore3xx parameter + 1.19. cpl_run_script usage + 1.20. cpl_process_register usage + 1.21. cpl_process_register_norpl 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 (string) + 3.2. db_table (string) + 3.3. username_column (string) + 3.4. domain_column (string) + 3.5. cpl_xml_column (string) + 3.6. cpl_bin_column (string) + 3.7. cpl_dtd_file (string) + 3.8. log_dir (string) + 3.9. proxy_recurse (int) + 3.10. proxy_route (string) + 3.11. case_sensitive (int) + 3.12. realm_prefix (string) + 3.13. timer_avp (string) + 3.14. lookup_domain (string) + 3.15. lookup_append_branches (int) + 3.16. use_domain (integer) + 3.17. redirect_route (string) + 3.18. ignore3xx (integer) + + 4. Functions + + 4.1. cpl_run_script(type,mode, [uri]) + 4.2. cpl_process_register() + 4.3. cpl_process_register_norpl() + + 5. RPC Commands + + 5.1. cpl.load + 5.2. cpl.remove + 5.3. cpl.get + + 6. Installation and Running + + 6.1. Database setup + +1. Overview + + cplc modules implements a CPL (Call Processing Language) interpreter. + Support for uploading/downloading/removing scripts via SIP REGISTER + method is present. + + CPL is an IETF specification detailed in RFC3880 + (https://tools.ietf.org/html/rfc3880). + +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: + * any DB module- a DB module for interfacing the DB operations + (modules like mysql, postgres, dbtext, etc) + * TM (Transaction) module- used for proxying/forking requests + * SL (StateLess) module - used for sending stateless reply when + responding to REGISTER request or for sending back error responses + * USRLOC (User Location) module - used for implementing + lookup("registration") tag (adding into location set of the users' + contact) + +2.2. External Libraries or Applications + + The following libraries or applications must be installed before + running Kamailio with this module loaded: + * libxml2 and libxml2-devel - on some SO, these to packages are + merged into libxml2. This library contains an engine for XML + parsing, DTD validation and DOM manipulation. + +3. Parameters + + 3.1. db_url (string) + 3.2. db_table (string) + 3.3. username_column (string) + 3.4. domain_column (string) + 3.5. cpl_xml_column (string) + 3.6. cpl_bin_column (string) + 3.7. cpl_dtd_file (string) + 3.8. log_dir (string) + 3.9. proxy_recurse (int) + 3.10. proxy_route (string) + 3.11. case_sensitive (int) + 3.12. realm_prefix (string) + 3.13. timer_avp (string) + 3.14. lookup_domain (string) + 3.15. lookup_append_branches (int) + 3.16. use_domain (integer) + 3.17. redirect_route (string) + 3.18. ignore3xx (integer) + +3.1. db_url (string) + + A SQL URL have to be given to the module for knowing where the database + containing the table with CPL scripts is locates. If required a user + name and password can be specified for allowing the module to connect + to the database server. + + Default value is “mysql://kamailio:kamailiorw@localhost/kamailio”. + + Example 1.1. Set db_url parameter +... +modparam("cplc","db_url","dbdriver://username:password@dbhost/dbname") +... + +3.2. db_table (string) + + Indicates the name of the table that store the CPL scripts. This table + must be locate into the database specified by “db_url” parameter. For + more about the format of the CPL table please see the + modules/cplc/init.mysql file. + + Default value is “cpl”. + + Example 1.2. Set db_table parameter +... +modparam("cplc","cpl_table","cpl") +... + +3.3. username_column (string) + + Indicates the name of the column used for storing the username. + + Default value is “username”. + + Example 1.3. Set username_column parameter +... +modparam("cplc","username_column","username") +... + +3.4. domain_column (string) + + Indicates the name of the column used for storing the domain. + + Default value is “domain”. + + Example 1.4. Set domain_column parameter +... +modparam("cplc","domain_column","domain") +... + +3.5. cpl_xml_column (string) + + Indicates the name of the column used for storing the XML version of + the cpl script. + + Default value is “cpl_xml”. + + Example 1.5. Set cpl_xml_column parameter +... +modparam("cplc","cpl_xml_column","cpl_xml") +... + +3.6. cpl_bin_column (string) + + Indicates the name of the column used for storing the binary version of + the cpl script (compiled version). + + Default value is “cpl_bin”. + + Example 1.6. Set cpl_bin_column parameter +... +modparam("cplc","cpl_bin_column","cpl_bin") +... + +3.7. cpl_dtd_file (string) + + Points to the DTD file describing the CPL grammar. The file name may + include also the path to the file. This path can be absolute or + relative (be careful the path will be relative to the starting + directory of Kamailio). + + This parameter is MANDATORY! + + Example 1.7. Set cpl_dtd_file parameter +... +modparam("cplc","cpl_dtd_file","/etc/kamailio/cpl-06.dtd") +... + +3.8. log_dir (string) + + Points to a directory where should be created all the log file + generated by the LOG CPL node. A log file per user will be created (on + demand) having the name username.log. + + If this parameter is absent, the logging will be disabled without + generating error on execution. + + Example 1.8. Set log_dir parameter +... +modparam("cplc","log_dir","/var/log/kamailio/cpl") +... + +3.9. proxy_recurse (int) + + Tells for how many time is allow to have recurse for PROXY CPL node If + it has value 2, when doing proxy, only twice the proxy action will be + re-triggered by a redirect response; the third time, the proxy + execution will end by going on REDIRECTION branch. The recurse feature + can be disable by setting this parameter to 0 + + Default value of this parameter is 0. + + Example 1.9. Set proxy_recurse parameter +... +modparam("cplc","proxy_recurse",2) +... + +3.10. proxy_route (string) + + Before doing proxy (forward), a script route can be executed. This + parameter indicates the name of the route called. All modifications + made by that route will be reflected only for the current branch. + + Default value of this parameter is NULL (none). + + Example 1.10. Set proxy_route parameter +... +modparam("cplc","proxy_route","CPL_PROXY") +... + +3.11. case_sensitive (int) + + Tells if the username matching should be perform case sensitive or not. + Set it to a non zero value to force a case sensitive handling of + usernames. + + Default value of this parameter is 0. + + Example 1.11. Set case_sensitive parameter +... +modparam("cplc","case_sensitive",1) +... + +3.12. realm_prefix (string) + + Defines a prefix for the domain part which should be ignored in + handling users and scripts. + + Default value of this parameter is empty string. + + Example 1.12. Set realm_prefix parameter +... +modparam("cplc","realm_prefix","sip.") +... + +3.13. timer_avp (string) + + Full specification (ID, NAME, ALIAS) of the AVP to be used to set the + value of the Final Response INVITE timeout - it's used by the TIMEOUT + attribute from the PROXY tag. + + NOTE: take care and synchronize this value with the similar parameters + in TM module. + + Default value of this parameter is NULL. + + Example 1.13. Set timer_avp parameter +... +modparam("cplc","timer_avp","$avp(i:14)") +... + +3.14. lookup_domain (string) + + Used by lookup tag to indicate where to perform user location. + Basically this is the name of the usrloc domain (table) where the user + registrations are kept. + + If set to empty string, the lookup node will be disabled - no user + location will be performed. + + Default value of this parameter is NULL. + + Example 1.14. Set lookup_domain parameter +... +modparam("cplc","lookup_domain","location") +... + +3.15. lookup_append_branches (int) + + Tells if the lookup tag should append branches (to do parallel forking) + if user_location lookup returns more than one contact. Set it to a non + zero value to enable parallel forking for location lookup tag. + + Default value of this parameter is 0. + + Example 1.15. Set lookup_append_branches parameter +... +modparam("cplc","lookup_append_branches",1) +... + +3.16. use_domain (integer) + + Indicates if the domain part of the URI should be used in user + identification (otherwise only username part will be used). + + Default value is “0 (disabled)”. + + Example 1.16. Set use_domain parameter +... +modparam("cplc","use_domain",1) +... + +3.17. redirect_route (string) + + Before doing redirect (deflection), a script route can be executed. + This parameter indicates the name of the route called. All + modifications made by that route will be reflected only for the current + branch. + + Default value of this parameter is NULL (none). + + Example 1.17. Set redirect_route parameter +... +modparam("cplc","redirect_route", "CPL_REDIRECT") +... + +3.18. ignore3xx (integer) + + Indicates if 3xx SIP response must be ignored. + + Default value is “0 (disabled)”. + + Example 1.18. Set ignore3xx parameter +... +modparam("cplc","ignore3xx",1) +... + +4. Functions + + 4.1. cpl_run_script(type,mode, [uri]) + 4.2. cpl_process_register() + 4.3. cpl_process_register_norpl() + +4.1. cpl_run_script(type,mode, [uri]) + + Starts the execution of the CPL script. The user name is fetched from + new_uri or requested uri or from To header -in this order- (for + incoming execution) or from FROM header (for outgoing execution). + Regarding the stateful/stateless message processing, the function is + very flexible, being able to run in different modes (see below + the"mode" parameter). Normally this function will end script execution. + There is no guaranty that the CPL script interpretation ended when + Kamailio script ended also (for the same INVITE ;-)) - this can happen + when the CPL script does a PROXY and the script interpretation pause + after proxying and it will be resume when some reply is received (this + can happen in a different process of SER). If the function returns to + script, the SIP server should continue with the normal behavior as if + no script existed. When some error is returned, the function itself + haven't sent any SIP error reply (this can be done from script). + + Meaning of the parameters is as follows: + * type - which part of the script should be run; set it to "incoming" + for having the incoming part of script executed (when an INVITE is + received) or to "outgoing" for running the outgoing part of script + (when a user is generating an INVITE - call). + * mode - sets the interpreter mode as stateless/stateful behavior. + The following modes are accepted: + + IS_STATELESS - the current INVITE has no transaction created + yet. All replies (redirection or deny) will be done is a + stateless way. The execution will switch to stateful only when + proxy is done. So, if the function returns, will be in + stateless mode. + + IS_STATEFUL - the current INVITE has already a transaction + associated. All signaling operations (replies or proxy) will + be done in stateful way.So, if the function returns, will be + in stateful mode. + + FORCE_STATEFUL - the current INVITE has no transaction created + yet. All signaling operations will be done is a stateful way + (on signaling, the transaction will be created from within the + interpreter). So, if the function returns, will be in + stateless mode. + HINT: is_stateful is very difficult to manage from the routing + script (script processing can continue in stateful mode); + is_stateless is the fastest and less resources consumer + (transaction is created only if proxying is done), but there is + minimal protection against retransmissions (since replies are send + stateless); force_stateful is a good compromise - all signaling is + done stateful (retransmission protection) and in the same time, if + returning to script, it will be in stateless mode (easy to continue + the routing script execution) + * uri - optional - provide the SIP URI to be used for loading the CPL + script, instead of taking it from R-URI or headers. + + This function can be used from REQUEST_ROUTE. + + Example 1.19. cpl_run_script usage +... +cpl_run_script("incoming","force_stateful"); +... + +4.2. cpl_process_register() + + This function MUST be called only for REGISTER requests. It checks if + the current REGISTER request is related or not with CPL script + upload/download/ remove. If it is, all the needed operation will be + done. For checking if the REGISTER is CPL related, the function looks + fist to "Content-Type" header. If it exists and has a the mime type set + to "application/cpl+xml" means this is a CPL script upload/remove + operation. The distinction between to case is made by looking at + "Content-Disposition" header; id its value is "script;action=store", + means it's an upload; if it's "script;action=remove", means it's a + remove operation; other values are considered to be errors. If no + "Content-Type" header is present, the function looks to "Accept" header + and if it contains the "*" or "application/cpl-xml" the request it will + be consider one for downloading CPL scripts. The functions returns to + script only if the REGISTER is not related to CPL. In other case, the + function will send by itself the necessary replies (stateless - using + sl), including for errors. + + This function can be used from REQUEST_ROUTE. + + Example 1.20. cpl_process_register usage +... +if (method=="REGISTER") { + cpl_process_register(); +} +... + +4.3. cpl_process_register_norpl() + + Same as “cpl_process_register” without internally generating the reply. + All information (script) is appended to the reply but without sending + it out. + + Main purpose of this function is to allow integration between CPL and + UserLocation services via same REGISTER messages. + + This function can be used from REQUEST_ROUTE. + + Example 1.21. cpl_process_register_norpl usage +... +if (method=="REGISTER") { + cpl_process_register(); + # continue with usrloc part + save("location"); +} +... + +5. RPC Commands + + 5.1. cpl.load + 5.2. cpl.remove + 5.3. cpl.get + +5.1. cpl.load + + For the given user, loads the XML cpl file, compiles it into binary + format and stores both format into database. + + Name: cpl.load + + Parameters: + * username : name of the user + * cpl_filename: file name + + RPC Command format: +... +kamcmd cpl.load username cpl_filename +... + +5.2. cpl.remove + + For the given user, removes the entire database record (XML cpl and + binary cpl); user with empty cpl scripts are not accepted. + + Name: cpl.remove + + Parameters: + * username : name of the user + + RPC Command format: +... +kamcmd cpl.remove username +... + +5.3. cpl.get + + For the given user, returns the CPL script in XML format. + + Name: cpl.get + + Parameters: + * username : name of the user + + RPC Command format: +... +kamcmd cpl.get username +... + +6. Installation and Running + + 6.1. Database setup + +6.1. Database setup + + Before running Kamailio with cplc, you have to setup the database table + where the module will store the CPL scripts. For that, if the table was + not created by the installation script or you choose to install + everything by yourself you can use the cpc-create.sql SQL script in the + database directories in the kamailio/scripts folder as template. + Database and table name can be set with module parameters so they can + be changed, but the name of the columns must be as they are in the SQL + script. You can also find the complete database documentation on the + project webpage, + https://www.kamailio.org/docs/db-tables/kamailio-db-devel.html. diff --git a/src/modules/pua_dialoginfo/README b/src/modules/pua_dialoginfo/README index 8b137891791..52077e6645c 100644 --- a/src/modules/pua_dialoginfo/README +++ b/src/modules/pua_dialoginfo/README @@ -1 +1,557 @@ +pua dialoginfo +Anca-Maria Vamanu + + Voice Sistem SRL + +Edited by + +Anca-Maria Vamanu + +Klaus Darilion + + IPCom (Module implementation was partly sponsored by Silver Server + (www.sil.at)) + +Klaus Darilion + + IPCom + +Phil Lavin + +Frederic Gaisnon + + + + Copyright © 2006 Voice Sistem SRL + + Copyright © 2008 Klaus Darilion IPCom + + Copyright © 2021 MomentTech + __________________________________________________________________ + + Table of Contents + + 1. Admin Guide + + 1. Overview + 2. Activate Functionality + 3. Known issues + 4. Dependencies + + 4.1. Kamailio Modules + 4.2. External Libraries or Applications + + 5. Parameters + + 5.1. include_callid (int) + 5.2. include_tags (int) + 5.3. include_localremote (int) + 5.4. override_lifetime (int) + 5.5. include_req_uri (int) + 5.6. caller_confirmed (int) + 5.7. send_publish_flag (int) + 5.8. disable_caller_publish_flag (int) + 5.9. disable_callee_publish_flag (int) + 5.10. use_pubruri_avps (int) + 5.11. pubruri_caller_avp (str) + 5.12. pubruri_callee_avp (str) + 5.13. pubruri_caller_dlg_var (str) + 5.14. pubruri_callee_dlg_var (str) + 5.15. callee_trying (int) + 5.16. caller_entity_when_publish_disabled (int) + 5.17. callee_entity_when_publish_disabled (int) + 5.18. publish_dialog_req_within (int) + + 6. Functions + + List of Examples + + 1.1. Set include_callid parameter + 1.2. Set include_tags parameter + 1.3. Set include_localremote parameter + 1.4. Set override_lifetime parameter + 1.5. Set include_req_uri parameter + 1.6. Set caller_confirmed parameter + 1.7. Set send_publish_flag parameter + 1.8. Set disable_caller_publish_flag parameter + 1.9. Set disable_callee_publish_flag parameter + 1.10. Set use_pubruri_avps parameter + 1.11. Set pubruri_caller_avp parameter + 1.12. Set pubruri_callee_avp parameter + 1.13. Set pubruri_caller_avp parameter + 1.14. Set pubruri_callee_dlg_var parameter + 1.15. Set callee_trying parameter + 1.16. Set caller_entity_when_publish_disabled parameter + 1.17. Set callee_entity_when_publish_disabled parameter + 1.18. Set publish_dialog_req_within parameter + +Chapter 1. Admin Guide + + Table of Contents + + 1. Overview + 2. Activate Functionality + 3. Known issues + 4. Dependencies + + 4.1. Kamailio Modules + 4.2. External Libraries or Applications + + 5. Parameters + + 5.1. include_callid (int) + 5.2. include_tags (int) + 5.3. include_localremote (int) + 5.4. override_lifetime (int) + 5.5. include_req_uri (int) + 5.6. caller_confirmed (int) + 5.7. send_publish_flag (int) + 5.8. disable_caller_publish_flag (int) + 5.9. disable_callee_publish_flag (int) + 5.10. use_pubruri_avps (int) + 5.11. pubruri_caller_avp (str) + 5.12. pubruri_callee_avp (str) + 5.13. pubruri_caller_dlg_var (str) + 5.14. pubruri_callee_dlg_var (str) + 5.15. callee_trying (int) + 5.16. caller_entity_when_publish_disabled (int) + 5.17. callee_entity_when_publish_disabled (int) + 5.18. publish_dialog_req_within (int) + + 6. Functions + +1. Overview + + The pua_dialoginfo retrieves dialog state information from the dialog + module and PUBLISHes the dialog-information using the pua module. Thus, + in combination with the presence_xml module this can be used to derive + dialog-info from the dialog module and NOTIFY the subscribed watchers + about dialog-info changes. This can be used for example with SNOM and + Linksys phones. + + Note: This implements dialog-info according to RFC 4235 and is not + compatible with the BLA feature defined in + draft-anil-sipping-bla-03.txt. (Actually the BLA draft is really crap + as it changes SIP semantics) + + The module is based on code (copy/paste) from pua_usrloc and + nat_traversal module. + + Following you will show some examples of an dialog-info XML document + taken from RFC 4235. This will help you to understand the meaning of + the module parameters: + + + + early + + + + The root element is the "dialog-info". It contains the namespace, the + version (which must be incremented for each new PUBLISH for this + certain dialog), the state (this module only supports state=full) and + the entity for which we publish the dialog-info. + + The "dialog" element must contain an id parameter. The id parameter is + usually different to the optional call-id parameter (which is the + call-id of the INVITE request) as an INVITE can create multiple dialogs + (forked request). But as the dialog module does not support multiple + dialogs created by a single transaction, the pua_dialoginfo module sets + the id parameter to the same value as the call-id parameter. The + "local-tag" indicates the local tag of the entity. The remote-tag + indicates the tag of the remote party. The "direction" indicates if the + entity was the initiator of the dialog or the recipient (aka if the + entity sent or received the first INVITE). + + The "state" element describes the state of the dialog state machine and + must be either: trying, proceeding, early, confirmed or terminated. + + The dialog element can contain optional "local" and "remote" elements + which describes the local and the remote party in more detail, for + example: + + + + early + + sip:alice@example.com + + + + sip:bob@example.org + + + + + + The local and remote elements are needed to implement call pickup. For + example if the above XML document is received by somebody who + SUBSCRIBEd the dialog-info of Alice, then it can pick-up the call by + sending an INVITE to Bob (actually I am not sure if it should use the + URI in the identity element or the URI in the target parameter) which + contains a Replaces header which contains the call-id and the tags. + This was tested successfully with Linksys SPA962 phones and with SNOM + 320 Firmware 7.3.7 (you have to set the function key to "Extension"). + + A dialog-info XML document may contain multiple "dialog" elements, for + example if the entity has multiple ongoing dialogs. For example the + following XML document shows a confirmed dialog and an early (probably + a second incoming call) dialog. + + + + confirmed + + + early + + + + As the dialog module callbacks only address a certain dialog, the + pua_dialoginfo always PUBLISHes XML documents with a single "dialog" + element. If an entity has multiple concurrent dialogs, the + pua_dialoginfo module will send PUBLISH for each dialog. These multiple + "presenties" can be aggregated by the presence_dialoginfo module into a + single XML document with multiple "dialog" elements. Please see the + description of the presence_dialoginfo module for details about the + aggregation. + + If there are problems with the callbacks from dialog module and you + want to debug them you define PUA_DIALOGINFO_DEBUG in pua_dialoginfo.c + and recompile. + +2. Activate Functionality + + This module is directly coupled with the dialog module. Thus, if the + module is loaded, it is automatically active for all calls tracked by + the dialog module. Thus, make sure that you activate the dialog module + for a certain call if you want dialog-state to be PUBLISHED. This + means, the dlg_flag of the dialog module must be configured and the + respective flag must be set during call processing. + +3. Known issues + + * The module tries to find out if the entity is a local user. Only + PUBLISH to local user are sent. Therefore, the module needs to find + out if the domain is a local one or not. It uses the same mechanism + as the "==myself" mechanism. Thus, all domains have to be declared + with the "alias=..." option in Kamailio.cfg. DB-based multidomain + support as offered by "domain" module is not supported yet. + Conclusion: The module has the same "domain" problems as the "rr" + module. + * The module puts the call-id of the dialog into an XML parameter. + Thus, if the call-id contains quotes, they should be escaped. This + is not yet implemented. Thus, if the call-id contains quotes the + XML document will be invalid. + * The module derives the AoR of the callee from the To: header. Thus, + if the To header does not contain the canonical AoR the PUBLISH + might have the wrong SIP URI in the RURI and the entity parameter. + +4. Dependencies + + 4.1. Kamailio Modules + 4.2. External Libraries or Applications + +4.1. Kamailio Modules + + The following modules must be loaded before this module: + * dialog. + * pua. + +4.2. External Libraries or Applications + + The following libraries or applications must be installed before + running Kamailio with this module loaded: + * libxml. + +5. Parameters + + 5.1. include_callid (int) + 5.2. include_tags (int) + 5.3. include_localremote (int) + 5.4. override_lifetime (int) + 5.5. include_req_uri (int) + 5.6. caller_confirmed (int) + 5.7. send_publish_flag (int) + 5.8. disable_caller_publish_flag (int) + 5.9. disable_callee_publish_flag (int) + 5.10. use_pubruri_avps (int) + 5.11. pubruri_caller_avp (str) + 5.12. pubruri_callee_avp (str) + 5.13. pubruri_caller_dlg_var (str) + 5.14. pubruri_callee_dlg_var (str) + 5.15. callee_trying (int) + 5.16. caller_entity_when_publish_disabled (int) + 5.17. callee_entity_when_publish_disabled (int) + 5.18. publish_dialog_req_within (int) + +5.1. include_callid (int) + + If this parameter is set, the optional call-id will be put into the + dialog element. This is needed for call-pickup features. + + Default value is “1”. + + Example 1.1. Set include_callid parameter +... +modparam("pua_dialoginfo", "include_callid", 0) +... + +5.2. include_tags (int) + + If this parameter is set, the local and remote tag will be put into the + dialog element. This is needed for call-pickup features. + + Default value is “1”. + + Example 1.2. Set include_tags parameter +... +modparam("pua_dialoginfo", "include_tags", 0) +... + +5.3. include_localremote (int) + + If this parameter is set, the optional local and remote elements will + be put into the dialog element. This is needed for call-pickup + features. + + Default value is “1”. + + Example 1.3. Set include_localremote parameter +... +modparam("pua_dialoginfo", "include_localremote", 0) +... + +5.4. override_lifetime (int) + + The PUBLISH requests used to send the dialog-info contain an Expires + header. The value of the expires is usually taken from the lifetime of + the dialog (see README of dialog module). If the override_lifetime is + set, the value specified here is used instead of the lifetime of the + dialog module. If used, the value should at least be a few seconds more + than the fr_inv_timer of the tm module. + + Default value is “0”. + + Example 1.4. Set override_lifetime parameter +... +modparam("pua_dialoginfo", "override_lifetime", 300) +... + +5.5. include_req_uri (int) + + controls if R-URI is going to be used instead of To header value in the + PUBLISH as "identity" on "remote" node. + + Default value is “0”. Disabled + + Example 1.5. Set include_req_uri parameter +... +modparam("pua_dialoginfo", "include_req_uri", 1) +... + +5.6. caller_confirmed (int) + + Usually the dialog-info of the caller will be "trying -> early -> + confirmed" and the dialog-info of the callee will be "early -> + confirmed". On some phones the function LED will start blinking if the + state is early, regardless if is is the caller or the callee (indicated + with the "direction" parameter). To avoid blinking LEDs for the caller, + you can enable this parameter. Then the state of the caller will be + signaled as "confirmed" even in "early" state. This is a workaround for + the buggy Linksys SPA962 phones. SNOM phones work well with the default + setting. + + Default value is “0”. + + Example 1.6. Set caller_confirmed parameter +... +modparam("pua_dialoginfo", "caller_confirmed", 1) +... + +5.7. send_publish_flag (int) + + This message flag indicates whether to send PUBLISH requests or not. If + not set, PUBLISH requests are sent out only if their R-URI is local + (according to myself). + + Default value is “-1”. + + Example 1.7. Set send_publish_flag parameter +... +modparam("pua_dialoginfo", "send_publish_flag", 8) +... + +5.8. disable_caller_publish_flag (int) + + This message flag indicates whether to send caller (initiator) PUBLISH + requests or not. If set, PUBLISH requests are not sent for the caller + (initiator). + + Default value is “-1”. + + Example 1.8. Set disable_caller_publish_flag parameter +... +modparam("pua_dialoginfo", "disable_caller_publish_flag", 9) +... + +5.9. disable_callee_publish_flag (int) + + This message flag indicates whether to send callee (recipient) PUBLISH + requests or not. If set, PUBLISH requests are not sent for the callee + (recipient). + + Default value is “-1”. + + Example 1.9. Set disable_callee_publish_flag parameter +... +modparam("pua_dialoginfo", "disable_callee_publish_flag", 10) +... + +5.10. use_pubruri_avps (int) + + Get Publish R-Uri from avps (see corresponding avp params), not from + request to/from uri. + + Default value is “0”. + + Example 1.10. Set use_pubruri_avps parameter +... +modparam("pua_dialoginfo", "use_pubruri_avps", 1) +... + +5.11. pubruri_caller_avp (str) + + If use_pubruri_avps is enabled, PUBLISH-requests reporting + dialog-information about the caller (entity=caller) are sent using the + value of the specified avp as R-Uri. If multiple AVPs with the same + name (but different indexes) are present, for each value a + corresponding PUBLISH-request is generated. If no AVP with the + specified name exists, no caller-related PUBLISH requests are sent. + + Default value is “NULL”. + + Example 1.11. Set pubruri_caller_avp parameter +... +modparam("pua_dialoginfo", "pubruri_caller_avp", "$avp(s:puburis_caller)") +... + +5.12. pubruri_callee_avp (str) + + If use_pubruri_avps is enabled, PUBLISH-requests reporting + dialog-information about the callee (entity=callee) are sent using the + value of the specified avp as R-Uri. If multiple AVPs with the same + name (but different indexes) are present, for each value a + corresponding PUBLISH-request is generated. If no AVP with the + specified name exists, no callee-related PUBLISH requests are sent. + + Default value is “NULL”. + + Example 1.12. Set pubruri_callee_avp parameter +... +modparam("pua_dialoginfo", "pubruri_callee_avp", "$avp(s:puburis_callee)") +... + +5.13. pubruri_caller_dlg_var (str) + + Must be set to the name of dialog variable where to store the URI for + caller, used to send the notifications. This is needed to restored the + value after Kamailio restart. If not set, loaded dialogs at restart are + no longer sending notifications. New dialogs are working fine. + + Default value is “NULL”. + + Example 1.13. Set pubruri_caller_avp parameter +... +modparam("pua_dialoginfo", "pubruri_caller_dlg_var", "pubruri_caller") +... + +5.14. pubruri_callee_dlg_var (str) + + Must be set to the name of dialog variable where to store the URI for + callee, used to send the notifications. This is needed to restored the + value after Kamailio restart. If not set, loaded dialogs at restart are + no longer sending notifications. New dialogs are working fine. + + Default value is “NULL”. + + Example 1.14. Set pubruri_callee_dlg_var parameter +... +modparam("pua_dialoginfo", "pubruri_callee_dlg_var", "pubruri_callee") +... + +5.15. callee_trying (int) + + If this parameter is set, a "Trying" state will be sent for both the + caller and callee, rather than just the caller. + + Default value is “0”. + + Example 1.15. Set callee_trying parameter +... +modparam("pua_dialoginfo", "callee_trying", 1) +... + +5.16. caller_entity_when_publish_disabled (int) + + Must be a valid sip uri. If this parameter is set, this uri is used as + caller entity in publish xml body if associated dialog has the flag + disable_caller_publish_flag set. Note only the flag received on dialog + creation is used to activate this feature. + + Default value is “NULL”. + + Example 1.16. Set caller_entity_when_publish_disabled parameter +... +modparam("pua_dialoginfo", "caller_entity_when_publish_disabled", "sip:caller@pu +blish.disabled.com") +... + +5.17. callee_entity_when_publish_disabled (int) + + Must be a valid sip uri. If this parameter is set, this uri is used as + callee entity in publish xml body if associated dialog has the flag + disable_callee_publish_flag set. Note only the flag received on dialog + creation is used to activate this feature. + + Default value is “NULL”. + + Example 1.17. Set callee_entity_when_publish_disabled parameter +... +modparam("pua_dialoginfo", "callee_entity_when_publish_disabled", "sip:callee@pu +blish.disabled.com") +... + +5.18. publish_dialog_req_within (int) + + If this parameter is set to 1, subsequents requests received in dialog + generate corresponding publish request. + + Default value is “1”. + + Example 1.18. Set publish_dialog_req_within parameter +... +modparam("pua_dialoginfo", "publish_dialog_req_within", 0) +... + +6. Functions