From 74dcbe875d3978ba7e16bb346ea8c034468237e0 Mon Sep 17 00:00:00 2001 From: Kamailio Dev Date: Fri, 13 Jul 2018 13:01:44 +0200 Subject: [PATCH] modules: readme files regenerated - dialog ... [skip ci] --- src/modules/dialog/README | 2245 ++++++++++++++++++++++++++++++++++++ src/modules/textops/README | 426 +++---- 2 files changed, 2469 insertions(+), 202 deletions(-) diff --git a/src/modules/dialog/README b/src/modules/dialog/README index 139597f9cb0..b1b63b8e309 100644 --- a/src/modules/dialog/README +++ b/src/modules/dialog/README @@ -1,2 +1,2247 @@ +dialog Module +Bogdan-Andrei Iancu + Voice Sistem SRL + +Carsten Bock + + ng-voice.com + +Edited by + +Bogdan-Andrei Iancu + +Edited by + +Carsten Bock + +Edited by + +Alex Balashov + + + +Edited by + +Olle E. Johansson + + + + Copyright © 2006 Voice Sistem SRL + + Copyright © 2011 Carsten Bock, http://www.ng-voice.com + __________________________________________________________________ + + Table of Contents + + 1. Admin Guide + + 1. Overview + 2. How it works + 3. Dialog states + 4. Dialog profiling + 5. Dependencies + + 5.1. Kamailio Modules + 5.2. External Libraries or Applications + + 6. Parameters + + 6.1. enable_stats (integer) + 6.2. hash_size (integer) + 6.3. rr_param (string) + 6.4. dlg_flag (integer) + 6.5. timeout_avp (string) + 6.6. default_timeout (integer) + 6.7. early_timeout (integer) + 6.8. noack_timeout (integer) + 6.9. end_timeout (integer) + 6.10. dlg_extra_hdrs (string) + 6.11. dlg_match_mode (integer) + 6.12. detect_spirals (integer) + 6.13. db_url (string) + 6.14. db_mode (integer) + 6.15. db_update_period (integer) + 6.16. db_fetch_rows (integer) + 6.17. db_skip_load (integer) + 6.18. table_name (string) + 6.19. call_id_column (string) + 6.20. from_uri_column (string) + 6.21. from_tag_column (string) + 6.22. to_uri_column (string) + 6.23. to_tag_column (string) + 6.24. from_cseq_column (string) + 6.25. to_cseq_column (string) + 6.26. from_route_column (string) + 6.27. to_route_column (string) + 6.28. from_contact_column (string) + 6.29. to_contact_column (string) + 6.30. from_sock_column (string) + 6.31. to_sock_column (string) + 6.32. h_id_column (string) + 6.33. h_entry_column (string) + 6.34. state_column (string) + 6.35. start_time_column (string) + 6.36. timeout_column (string) + 6.37. sflags_column (string) + 6.38. toroute_name_column (string) + 6.39. vars_table_name (string) + 6.40. vars_h_id_column (string) + 6.41. vars_h_entry_column (string) + 6.42. vars_key_column (string) + 6.43. vars_value_column (string) + 6.44. profiles_with_value (string) + 6.45. profiles_no_value (string) + 6.46. bridge_controller (string) + 6.47. bridge_contact (string) + 6.48. initial_cbs_inscript (int) + 6.49. send_bye (int) + 6.50. wait_ack (int) + 6.51. ka_timer (int) + 6.52. ka_interval (int) + 6.53. ka_failed_limit (int) + 6.54. timeout_noreset (int) + 6.55. timer_procs (int) + 6.56. enable_dmq (int) + 6.57. track_cseq_updates (int) + 6.58. lreq_callee_headers (string) + 6.59. event_callback (str) + 6.60. h_id_start (int) + 6.61. h_id_step (int) + + 7. Functions + + 7.1. set_dlg_profile(profile,[value]) + 7.2. unset_dlg_profile(profile,[value]) + 7.3. is_in_profile(profile,[value]) + 7.4. get_profile_size(profile,[value],size) + 7.5. dlg_isflagset(flag) + 7.6. dlg_setflag(flag) + 7.7. dlg_resetflag(flag) + 7.8. dlg_bye(side) + 7.9. dlg_refer(side, address) + 7.10. dlg_manage() + 7.11. dlg_bridge(from, to, op) + 7.12. dlg_get(callid, ftag, ttag) + 7.13. is_known_dlg() + 7.14. dlg_set_timeout(timeout [, h_entry, h_id]) + 7.15. dlg_set_timeout_by_profile(profile, [value], timeout) + 7.16. dlg_set_property(attr) + 7.17. dlg_remote_profile(cmd, profile, value, uid, expires) + 7.18. dlg_set_ruri() + 7.19. dlg_db_load_callid(cival) + 7.20. dlg_db_load_extra() + + 8. Statistics + + 8.1. active_dialogs + 8.2. early_dialogs + 8.3. processed_dialogs + 8.4. expired_dialogs + 8.5. failed_dialogs + + 9. RPC Commands + + 9.1. dlg.list + 9.2. dlg.list_ctx + 9.3. dlg.dlg_list + 9.4. dlg.dlg_list_ctx + 9.5. dlg.terminate_dlg + 9.6. dlg.end_dlg + 9.7. dlg.profile_get_size + 9.8. dlg.profile_list + 9.9. dlg.bridge_dlg + 9.10. dlg.stats_active + + 10. Exported Variables + + 10.1. $DLG_count + 10.2. $DLG_status + 10.3. $DLG_lifetime + 10.4. $dlg(...) + 10.5. $dlg_ctx(...) + 10.6. $dlg_var(key) + + 11. Event Routes + + 11.1. event_route[dialog:start] + 11.2. event_route[dialog:end] + 11.3. event_route[dialog:failed] + + 2. Developer Guide + + 1. Available Functions + + 1.1. register_dlgcb (dialog, type, cb, param, free_param_cb) + + 1.2. terminate_dlg (dlg, hdrs) + + 3. Frequently Asked Questions + + List of Examples + + 1.1. Set enable_stats parameter + 1.2. Set hash_size parameter + 1.3. Set rr_param parameter + 1.4. Set dlg_flag parameter + 1.5. Set timeout_avp parameter + 1.6. Set default_timeout parameter + 1.7. Set early_timeout parameter + 1.8. Set noack_timeout parameter + 1.9. Set end_timeout parameter + 1.10. Set dlf_extra_hdrs parameter + 1.11. Set dlg_match_mode parameter + 1.12. Set detect_spirals parameter + 1.13. Set db_url parameter + 1.14. Set db_mode parameter + 1.15. Set db_update_period parameter + 1.16. Set db_fetch_rows parameter + 1.17. Set db_skip_load parameter + 1.18. Set table_name parameter + 1.19. Set call_id_column parameter + 1.20. Set from_uri_column parameter + 1.21. Set from_tag_column parameter + 1.22. Set to_uri_column parameter + 1.23. Set to_tag_column parameter + 1.24. Set from_cseq_column parameter + 1.25. Set to_cseq_column parameter + 1.26. Set from_route_column parameter + 1.27. Set to_route_column parameter + 1.28. Set from_contact_column parameter + 1.29. Set to_contact_column parameter + 1.30. Set from_sock_column parameter + 1.31. Set to_sock_column parameter + 1.32. Set h_id_column parameter + 1.33. Set h_entry_column parameter + 1.34. Set state_column parameter + 1.35. Set start_time_column parameter + 1.36. Set timeout_column parameter + 1.37. Set sflags_column parameter + 1.38. Set toroute_name_column parameter + 1.39. Set vars_table_name parameter + 1.40. Set vars_h_id_column parameter + 1.41. Set vars_h_entry_column parameter + 1.42. Set vars_key_column parameter + 1.43. Set vars_value_column parameter + 1.44. Set profiles_with_value parameter + 1.45. Set profiles_no_value parameter + 1.46. Set bridge_controller parameter + 1.47. Set bridge_contact parameter + 1.48. Set initial_cbs_inscript parameter + 1.49. Set send_bye parameter + 1.50. Set wait_ack parameter + 1.51. Set ka_timer parameter + 1.52. Set ka_interval parameter + 1.53. Set ka_failed_limit parameter + 1.54. Set timeout_noreset parameter + 1.55. Set timer_procs parameter + 1.56. Set enable_dmq parameter + 1.57. Set track_cseq_updates parameter + 1.58. Set lreq_callee_headers parameter + 1.59. Set event_callback parameter + 1.60. Set h_id_start parameter + 1.61. Set h_id_step parameter + 1.62. set_dlg_profile usage + 1.63. unset_dlg_profile usage + 1.64. is_in_profile usage + 1.65. get_profile_size usage + 1.66. dlg_isflagset usage + 1.67. dlg_setflag usage + 1.68. dlg_resetflag usage + 1.69. dlg_bye usage + 1.70. dlg_refer usage + 1.71. dlg_manage usage + 1.72. dlg_bridge usage + 1.73. dlg_get usage + 1.74. is_known_dlg() usage + 1.75. dlg_set_timeout usage + 1.76. dlg_set_timeout_by_profile usage + 1.77. dlg_set_property usage + 1.78. dlg_remote_profile usage + 1.79. dlg_set_ruri() usage + 1.80. dlg_db_load_callid() usage + 1.81. dlg_db_load_extra() usage + +Chapter 1. Admin Guide + + Table of Contents + + 1. Overview + 2. How it works + 3. Dialog states + 4. Dialog profiling + 5. Dependencies + + 5.1. Kamailio Modules + 5.2. External Libraries or Applications + + 6. Parameters + + 6.1. enable_stats (integer) + 6.2. hash_size (integer) + 6.3. rr_param (string) + 6.4. dlg_flag (integer) + 6.5. timeout_avp (string) + 6.6. default_timeout (integer) + 6.7. early_timeout (integer) + 6.8. noack_timeout (integer) + 6.9. end_timeout (integer) + 6.10. dlg_extra_hdrs (string) + 6.11. dlg_match_mode (integer) + 6.12. detect_spirals (integer) + 6.13. db_url (string) + 6.14. db_mode (integer) + 6.15. db_update_period (integer) + 6.16. db_fetch_rows (integer) + 6.17. db_skip_load (integer) + 6.18. table_name (string) + 6.19. call_id_column (string) + 6.20. from_uri_column (string) + 6.21. from_tag_column (string) + 6.22. to_uri_column (string) + 6.23. to_tag_column (string) + 6.24. from_cseq_column (string) + 6.25. to_cseq_column (string) + 6.26. from_route_column (string) + 6.27. to_route_column (string) + 6.28. from_contact_column (string) + 6.29. to_contact_column (string) + 6.30. from_sock_column (string) + 6.31. to_sock_column (string) + 6.32. h_id_column (string) + 6.33. h_entry_column (string) + 6.34. state_column (string) + 6.35. start_time_column (string) + 6.36. timeout_column (string) + 6.37. sflags_column (string) + 6.38. toroute_name_column (string) + 6.39. vars_table_name (string) + 6.40. vars_h_id_column (string) + 6.41. vars_h_entry_column (string) + 6.42. vars_key_column (string) + 6.43. vars_value_column (string) + 6.44. profiles_with_value (string) + 6.45. profiles_no_value (string) + 6.46. bridge_controller (string) + 6.47. bridge_contact (string) + 6.48. initial_cbs_inscript (int) + 6.49. send_bye (int) + 6.50. wait_ack (int) + 6.51. ka_timer (int) + 6.52. ka_interval (int) + 6.53. ka_failed_limit (int) + 6.54. timeout_noreset (int) + 6.55. timer_procs (int) + 6.56. enable_dmq (int) + 6.57. track_cseq_updates (int) + 6.58. lreq_callee_headers (string) + 6.59. event_callback (str) + 6.60. h_id_start (int) + 6.61. h_id_step (int) + + 7. Functions + + 7.1. set_dlg_profile(profile,[value]) + 7.2. unset_dlg_profile(profile,[value]) + 7.3. is_in_profile(profile,[value]) + 7.4. get_profile_size(profile,[value],size) + 7.5. dlg_isflagset(flag) + 7.6. dlg_setflag(flag) + 7.7. dlg_resetflag(flag) + 7.8. dlg_bye(side) + 7.9. dlg_refer(side, address) + 7.10. dlg_manage() + 7.11. dlg_bridge(from, to, op) + 7.12. dlg_get(callid, ftag, ttag) + 7.13. is_known_dlg() + 7.14. dlg_set_timeout(timeout [, h_entry, h_id]) + 7.15. dlg_set_timeout_by_profile(profile, [value], timeout) + 7.16. dlg_set_property(attr) + 7.17. dlg_remote_profile(cmd, profile, value, uid, expires) + 7.18. dlg_set_ruri() + 7.19. dlg_db_load_callid(cival) + 7.20. dlg_db_load_extra() + + 8. Statistics + + 8.1. active_dialogs + 8.2. early_dialogs + 8.3. processed_dialogs + 8.4. expired_dialogs + 8.5. failed_dialogs + + 9. RPC Commands + + 9.1. dlg.list + 9.2. dlg.list_ctx + 9.3. dlg.dlg_list + 9.4. dlg.dlg_list_ctx + 9.5. dlg.terminate_dlg + 9.6. dlg.end_dlg + 9.7. dlg.profile_get_size + 9.8. dlg.profile_list + 9.9. dlg.bridge_dlg + 9.10. dlg.stats_active + + 10. Exported Variables + + 10.1. $DLG_count + 10.2. $DLG_status + 10.3. $DLG_lifetime + 10.4. $dlg(...) + 10.5. $dlg_ctx(...) + 10.6. $dlg_var(key) + + 11. Event Routes + + 11.1. event_route[dialog:start] + 11.2. event_route[dialog:end] + 11.3. event_route[dialog:failed] + +1. Overview + + Kamailio can behave as a stateful proxy through the TM module. However, + "stateful" in this context refers to transaction state, not dialog + state. Certain applications may benefit from an awareness of "calls" in + the proxy, not just SIP transactions. + + For example, a common need is to limit the number of calls that can be + made concurrently by an endpoint, account, user group, etc. In order to + count the number of calls in progress, it is necessary for the proxy to + be aware of whole dialogs, not just transactions, and to provide some + means of programmatically classifying these dialogs. This is just one + common application discussed for illustrative purposes; there are many + others. + + The dialog module provides dialog awareness for the Kamailio proxy. + It's functionality is to keep track of the current dialogs, to offer + information about them (e.g. how many dialogs are active), and to + manage various characteristics of dialogs. The module exports several + functions that can be used directly from the configuration route script + as well as functions for the RPC interface. + + This module also provides a API foundation on which to build more + complex dialog-oriented functionality in other Kamailio modules. + +2. How it works + + To create the dialog associated with an initial request, the flag + “dlg_flag” (Section 6.4, “dlg_flag (integer)”) must be set before + creating the corresponding transaction. + + The dialog is automatically destroyed when a “BYE” is received. In case + of no “BYE”, the dialog lifetime is controlled via the default timeout + (see “default_timeout” - Section 6.6, “default_timeout (integer)”) and + custom timeout (see “timeout_avp” - Section 6.5, “timeout_avp + (string)”). The dialog timeout is reset each time a sequential request + is processed. + +3. Dialog states + + Dialogs have states that are shown in the RPC interface as well as + stored in the database. + * 1 : Unconfirmed dialog + * 2 : Early dialog (ringing) + * 3 : Confirmed dialog (waiting for ACK) + * 4 : Confirmed dialog (active call) + * 5 : Deleted dialog + + The early and deleted dialog states are not updated in database + storage. + +4. Dialog profiling + + Dialog profiling is a mechanism that helps in classifying, sorting and + keeping track of certain types of dialogs. The classification criteria + can be any attributes desired by the administrator; it can be SIP + message attributes, other pseudo-variables, custom values, etc. Dialogs + can be dynamically added into one or more profile tables. Logically, + each profile table can have a special meaning (like dialogs outside the + domain, dialogs terminated to the PSTN, etc.). + + There are two types of profiles: + * with no value - a dialog simply belongs to a profile (for instance, + an outbound calls profile). There is no other additional + information to describe the dialog beyond its membership in the + profile per se. + * with value - a dialog belongs to a profile having a certain value + (like in a caller profile, where the value is the caller ID). The + membership of the dialog in the profile is strictly related to the + value. For example, if the account ID of the caller is stored in + the pseudo-variable $var(account_id), you can use $var(account_id) + as a value/key by which to group dialogs so that you can count the + number of open dialogs for each account, enforce concurrent call + limits as necessary, etc. + + A dialog can be added to multiple profiles at the same time. + + Profiles are visible (at the moment) in the request route (for initial + and sequential requests) and in the branch, failure and reply routes of + the original request. + +5. Dependencies + + 5.1. Kamailio Modules + 5.2. External Libraries or Applications + +5.1. Kamailio Modules + + The following modules must be loaded before this module: + * TM - Transaction module + * RR - Record-Route module + * PV - Pseudovariables module + +5.2. External Libraries or Applications + + The following libraries or applications must be installed before + running Kamailio with this module loaded: + * None. + +6. Parameters + + 6.1. enable_stats (integer) + 6.2. hash_size (integer) + 6.3. rr_param (string) + 6.4. dlg_flag (integer) + 6.5. timeout_avp (string) + 6.6. default_timeout (integer) + 6.7. early_timeout (integer) + 6.8. noack_timeout (integer) + 6.9. end_timeout (integer) + 6.10. dlg_extra_hdrs (string) + 6.11. dlg_match_mode (integer) + 6.12. detect_spirals (integer) + 6.13. db_url (string) + 6.14. db_mode (integer) + 6.15. db_update_period (integer) + 6.16. db_fetch_rows (integer) + 6.17. db_skip_load (integer) + 6.18. table_name (string) + 6.19. call_id_column (string) + 6.20. from_uri_column (string) + 6.21. from_tag_column (string) + 6.22. to_uri_column (string) + 6.23. to_tag_column (string) + 6.24. from_cseq_column (string) + 6.25. to_cseq_column (string) + 6.26. from_route_column (string) + 6.27. to_route_column (string) + 6.28. from_contact_column (string) + 6.29. to_contact_column (string) + 6.30. from_sock_column (string) + 6.31. to_sock_column (string) + 6.32. h_id_column (string) + 6.33. h_entry_column (string) + 6.34. state_column (string) + 6.35. start_time_column (string) + 6.36. timeout_column (string) + 6.37. sflags_column (string) + 6.38. toroute_name_column (string) + 6.39. vars_table_name (string) + 6.40. vars_h_id_column (string) + 6.41. vars_h_entry_column (string) + 6.42. vars_key_column (string) + 6.43. vars_value_column (string) + 6.44. profiles_with_value (string) + 6.45. profiles_no_value (string) + 6.46. bridge_controller (string) + 6.47. bridge_contact (string) + 6.48. initial_cbs_inscript (int) + 6.49. send_bye (int) + 6.50. wait_ack (int) + 6.51. ka_timer (int) + 6.52. ka_interval (int) + 6.53. ka_failed_limit (int) + 6.54. timeout_noreset (int) + 6.55. timer_procs (int) + 6.56. enable_dmq (int) + 6.57. track_cseq_updates (int) + 6.58. lreq_callee_headers (string) + 6.59. event_callback (str) + 6.60. h_id_start (int) + 6.61. h_id_step (int) + +6.1. enable_stats (integer) + + If statistics support should be enabled or not. Via statistics + variables, the module provide information about the dialog processing. + Set it to zero to disable or to non-zero to enable it. + + Default value is “1 (enabled)”. + + Example 1.1. Set enable_stats parameter +... +modparam("dialog", "enable_stats", 0) +... + +6.2. hash_size (integer) + + The size of the hash table internally used to keep the dialogs. A + larger table is much faster but consumes more memory. The hash size + must be a power of two. + + IMPORTANT: If dialog information should be stored in a database, a + constant hash_size should be used, otherwise the restoring process will + not take place. If you really want to modify the hash_size, you must + delete all table's rows before restarting the server. + + Default value is “4096”. + + Example 1.2. Set hash_size parameter +... +modparam("dialog", "hash_size", 1024) +... + +6.3. rr_param (string) + + Name of the Record-Route parameter used to store the dialog cookie. It + is used for the fast matching of sequential requests to tracked + dialogs. + + Default value is “did”. + + Example 1.3. Set rr_param parameter +... +modparam("dialog", "rr_param", "xyz") +... + +6.4. dlg_flag (integer) + + Flag to be used for marking if a dialog should be constructed for the + current request (this make sense only for initial requests). + + Default value is “none”. + + Example 1.4. Set dlg_flag parameter +... +modparam("dialog", "dlg_flag", 4) +... + +6.5. timeout_avp (string) + + The specification of an AVP that contains a custom timeout value (in + seconds) for the dialog. It may be used only in a request (initial or + sequential) context. + + Default value is “none”. + + Example 1.5. Set timeout_avp parameter +... +modparam("dialog", "timeout_avp", "$avp(i:10)") +... + +6.6. default_timeout (integer) + + The default dialog timeout (in seconds), in the absence of a custom + value provided in an AVP. + + Default value is “43200 (12 hours)”. + + Example 1.6. Set default_timeout parameter +... +modparam("dialog", "default_timeout", 21600) +... + +6.7. early_timeout (integer) + + The timeout (in seconds) after which the dialogs in early state (no + final response received) are destroyed. + + Default value is “300 (5 minutes)”. + + Example 1.7. Set early_timeout parameter +... +modparam("dialog", "early_timeout", 180) +... + +6.8. noack_timeout (integer) + + The timeout (in seconds) after which the dialogs which were answered + with 200ok but didn't receive the ACK are marked for termination (the + lifetime is set to 10 more seconds). + + Default value is “60 (1 minute)”. + + Example 1.8. Set noack_timeout parameter +... +modparam("dialog", "noack_timeout", 90) +... + +6.9. end_timeout (integer) + + The timeout (in seconds) after which the dialogs in terminated state + are destroyed. + + Default value is “300 (5 minutes)”. + + Example 1.9. Set end_timeout parameter +... +modparam("dialog", "end_timeout", 180) +... + +6.10. dlg_extra_hdrs (string) + + A string containing the extra headers (full format, with EOH) to be + added to requests generated locally by the module (like BYEs). + + Default value is “NULL”. + + Example 1.10. Set dlf_extra_hdrs parameter +... +modparam("dialog", "dlg_extra_hdrs", "Hint: credit expired\r\n") +... + +6.11. dlg_match_mode (integer) + + How the sequential requests should be matched against the known + dialogs. The modes are a combination of matching based on a cookie + (DID) stored as cookie in Record-Route header and matching based on SIP + elements (as in RFC 3261). + + Note: DID-based matching does not replace callid/fromtag/totag + comparison. It will speed up dialog matching by not iterating over the + whole dialog list for callid/fromtag/totag comparison, but instead it + uses a hash table to find the respective dialog and then doing only one + callid/fromtag/totag comparison. Thus, there is no security issue when + using DID based matching. Use DID_FALLBACK for maximum interoperability + or use DID_ONLY to reject buggy clients or hacking attempts. DID_NONE + is only useful, when you want to hide dialog-tracking from the users + (preventing the DID Record-Route cookie). + + The supported modes are: + * 0 - DID_ONLY - the match is done exclusively based on DID; + * 1 - DID_FALLBACK - the match is first tried based on DID and if not + present, it will fall back to SIP matching; + * 2 - DID_NONE - the match is done exclusively based on SIP elements; + no DID information is added in RR. + + Default value is “0 (DID_ONLY)”. + + Example 1.11. Set dlg_match_mode parameter +... +modparam("dialog", "dlg_match_mode", 1) +... + +6.12. detect_spirals (integer) + + Whether spirals (i.e., messages routed through the proxy multiple + times) should be detected. + + If set to 0, spirals will not be detected and result in the generation + of a new, possibly dangling dialog structure per occurring spiral. If + set to 1, spirals are detected and internally mapped to existing dialog + structures. + + Default value is 1. + + Example 1.12. Set detect_spirals parameter +... +modparam("dialog", "detect_spirals", 1) +... + +6.13. db_url (string) + + In order to store information about dialogs in a database, a database + URL must be specified. + + Default value is “mysql://kamailio:kamailiorw@localhost/kamailio”. + + Example 1.13. Set db_url parameter +... +modparam("dialog", "db_url", "dbdriver://username:password@dbhost/dbname") +... + +6.14. db_mode (integer) + + Mode of synchronisation of dialog information from memory to an + underlying database (if desired): + + The supported modes are: + * 0 - NO_DB - the memory content is not flushed into DB; + * 1 - REALTIME - any dialog information changes will be reflected + into the database immediately. + * 2 - DELAYED - the dialog information changes will be flushed into + DB periodically, based on a timer routine. + * 3 - SHUTDOWN - the dialog information will be flushed into DB only + at shutdown - no runtime updates. + + Default value is “0”. + + Example 1.14. Set db_mode parameter +... +modparam("dialog", "db_mode", 1) +... + +6.15. db_update_period (integer) + + The interval (seconds) at which to update dialogs' information, if the + server is configured to store the dialog information at a given + interval. Too short an interval will generate intensive database + operations, while an excessively long one will miss dialogs with a + short lifetime. + + Default value is “60” seconds. + + Example 1.15. Set db_update_period parameter +... +modparam("dialog", "db_update_period", 120) +... + +6.16. db_fetch_rows (integer) + + The number of the rows to be fetched at once from database when loading + the dialog records at startup from the database. This value can be used + to tune the load time at startup. For 1MB of private memory (default), + it should be below 400. The database driver must support the + fetch_result() capability. A value of 0 means the database fetch is not + limited. + + Default value is “200”. + + Example 1.16. Set db_fetch_rows parameter +... +modparam("dialog", "db_fetch_rows", 500) +... + +6.17. db_skip_load (integer) + + Set db_skip_load to 1, to skip the loading of dialog data from the + database. + + Default value is “0” ( not skipped ). + + Example 1.17. Set db_skip_load parameter +... +modparam("dialog", "db_skip_load", 1) +... + +6.18. table_name (string) + + Database table name used for storing dialog information. + + Default value is “dialog”. + + Example 1.18. Set table_name parameter +... +modparam("dialog", "table_name", "my_dialog") +... + +6.19. call_id_column (string) + + The column name in the database to store the dialog call-id. + + Default value is “callid”. + + Example 1.19. Set call_id_column parameter +... +modparam("dialog", "call_id_column", "callid_c_name") +... + +6.20. from_uri_column (string) + + The column name in the database to store the caller's SIP address + (URI). + + Default value is “from_uri”. + + Example 1.20. Set from_uri_column parameter +... +modparam("dialog", "from_uri_column", "from_uri_c_name") +... + +6.21. from_tag_column (string) + + The column name in the database to store the From header tag from the + INVITE request. + + Default value is “from_tag”. + + Example 1.21. Set from_tag_column parameter +... +modparam("dialog", "from_tag_column", "from_tag_c_name") +... + +6.22. to_uri_column (string) + + The column name in the database to store the callee's SIP address + (URI). + + Default value is “to_uri”. + + Example 1.22. Set to_uri_column parameter +... +modparam("dialog", "to_uri_column", "to_uri_c_name") +... + +6.23. to_tag_column (string) + + The column name in the database to store the To header tag from the 200 + OK response to the INVITE request, if present. + + Default value is “to_tag”. + + Example 1.23. Set to_tag_column parameter +... +modparam("dialog", "to_tag_column", "to_tag_c_name") +... + +6.24. from_cseq_column (string) + + The column name in the database to store the Cseq from caller side. + + Default value is “caller_cseq”. + + Example 1.24. Set from_cseq_column parameter +... +modparam("dialog", "from_cseq_column", "from_cseq") +... + +6.25. to_cseq_column (string) + + The column name in the database to store the cseq from callee side. + + Default value is “callee_cseq”. + + Example 1.25. Set to_cseq_column parameter +... +modparam("dialog", "to_cseq_column", "to_cseq") +... + +6.26. from_route_column (string) + + The column name in the database to store the route records from caller + side (proxy to caller). + + Default value is “caller_route_set”. + + Example 1.26. Set from_route_column parameter +... +modparam("dialog", "from_route_column", "rroute_from") +... + +6.27. to_route_column (string) + + The column name in the database to store the route records from callee + side (proxy to callee). + + Default value is “callee_route_set”. + + Example 1.27. Set to_route_column parameter +... +modparam("dialog", "to_route_column", "rroute_to") +... + +6.28. from_contact_column (string) + + The column name in the database to store the caller's contact uri. + + Default value is “caller_contact”. + + Example 1.28. Set from_contact_column parameter +... +modparam("dialog", "from_contact_column", "from_contact_uri") +... + +6.29. to_contact_column (string) + + The column name in the database to store the callee's contact uri. + + Default value is “callee_contact”. + + Example 1.29. Set to_contact_column parameter +... +modparam("dialog", "to_contact_column", "to_contact_uri") +... + +6.30. from_sock_column (string) + + The column name in the database to store the information about the + local interface receiving the traffic from caller. + + Default value is “caller_sock”. + + Example 1.30. Set from_sock_column parameter +... +modparam("dialog", "from_sock_column", "socket_from") +... + +6.31. to_sock_column (string) + + The column name in the database to store information about the local + interface receiving the traffic from callee. + + Default value is “callee_sock”. + + Example 1.31. Set to_sock_column parameter +... +modparam("dialog", "to_sock_column", "socket_to") +... + +6.32. h_id_column (string) + + The column name in the database to store the dialogs' hash id + information. + + Default value is “hash_id”. + + Example 1.32. Set h_id_column parameter +... +modparam("dialog", "h_id_column", "hash_id_c_name") +... + +6.33. h_entry_column (string) + + The column name in the database to store the dialog's hash entry + information. + + Default value is “hash_entry”. + + Example 1.33. Set h_entry_column parameter +... +modparam("dialog", "h_entry_column", "h_entry_c_name") +... + +6.34. state_column (string) + + The column name in the database to store the dialog's state + information. + + Default value is “state”. + + Example 1.34. Set state_column parameter +... +modparam("dialog", "state_column", "state_c_name") +... + +6.35. start_time_column (string) + + The column name in the database to store the dialog's start time + information. + + Default value is “start_time”. + + Example 1.35. Set start_time_column parameter +... +modparam("dialog", "start_time_column", "start_time_c_name") +... + +6.36. timeout_column (string) + + The column name in the database to store the dialog's timeout. + + Default value is “timeout”. + + Example 1.36. Set timeout_column parameter +... +modparam("dialog", "timeout_column", "timeout_c_name") +... + +6.37. sflags_column (string) + + The column name in the database to store the dialog script flags. + + Default value is “sflags”. + + Example 1.37. Set sflags_column parameter +... +modparam("dialog", "sflags_column", "s_flags") +... + +6.38. toroute_name_column (string) + + The column name in the database to store the index of the route to be + executed at timeout. + + Default value is “toroute_name”. + + Example 1.38. Set toroute_name_column parameter +... +modparam("dialog", "toroute_name_column", "timeout_route") +... + +6.39. vars_table_name (string) + + If you want to store the dialog variables (“$dlg_var(name)”) for a + dialog in a database a table name must be specified. + + Default value is “dialog_vars”. + + Example 1.39. Set vars_table_name parameter +... +modparam("dialog", "vars_table_name", "my_dialog_vars") +... + +6.40. vars_h_id_column (string) + + The column name in the database to store the dialog's hash id + information (as a reference to the dialog table). + + Default value is “hash_id”. + + Example 1.40. Set vars_h_id_column parameter +... +modparam("dialog", "vars_h_id_column", "vars_h_id_name") +... + +6.41. vars_h_entry_column (string) + + The column name in the database to store the dialog's hash entry + information (as a reference to the dialog table). + + Default value is “hash_entry”. + + Example 1.41. Set vars_h_entry_column parameter +... +modparam("dialog", "vars_h_entry_column", "vars_h_entry_name") +... + +6.42. vars_key_column (string) + + The column name in the database to store the names (keys) of a dialog + variable. + + Default value is “dialog_key”. + + Example 1.42. Set vars_key_column parameter +... +modparam("dialog", "vars_key_column", "vars_key_name") +... + +6.43. vars_value_column (string) + + The column name in the database to store the values of a dialog + variable. + + Default value is “dialog_value”. + + Example 1.43. Set vars_value_column parameter +... +modparam("dialog", "vars_value_column", "vars_value_name") +... + +6.44. profiles_with_value (string) + + List of names for profiles with values, separated with semi-colon ";". + + Default value is “empty”. + + Example 1.44. Set profiles_with_value parameter +... +modparam("dialog", "profiles_with_value", "caller ; my_profile") +... + +6.45. profiles_no_value (string) + + List of names for profiles without values, separated with semi-colon + ";". + + Default value is “empty”. + + Example 1.45. Set profiles_no_value parameter +... +modparam("dialog", "profiles_no_value", "inbound ; outbound") +... + +6.46. bridge_controller (string) + + SIP address to be used in From header when initiating a call bridge. + + Default value is “sip:controller@kamailio.org”. + + Example 1.46. Set bridge_controller parameter +... +modparam("dialog", "bridge_controller", "sip:ctd@kamailio.org") +... + +6.47. bridge_contact (string) + + SIP address to be used in Contact header when doing a call bridge. + + Default value is “sip:controller@kamailio.org:5060”. + + Example 1.47. Set bridge_contact parameter +... +modparam("dialog", "bridge_contact", "sip:ctd@127.0.0.1:5060") +... + +6.48. initial_cbs_inscript (int) + + If the initial dialog callbacks (i.e., DLGCB_CREATED and + DLGCB_SPIRALED) should be executed in-script or post-script. If + dlg_manage() is not used, the setting of this parameter does not + matter; otherwise, initial callbacks will be executed directly after + dlg_manage() is called if this parameter is enabled. If it is disabled, + initial callback execution will be postponed until configuration script + execution completes. + + The supported values are: + * 0 - POST-SCRIPT - execute initial callbacks after the script + completes; + * 1 - IN-SCRIPT - execute initial callbacks during script execution, + i.e., right after dlg_manage() is called; + + Default value is “1”. + + Example 1.48. Set initial_cbs_inscript parameter +... +modparam("dialog", "initial_cbs_inscript", 0) +... + +6.49. send_bye (int) + + If set to 1, BYE requests will be sent out for each dialog that timed + out. It is an alternative to $dlg_ctx(timeout_bye)=1 for all dialogs. + + Default value is “0”. + + Example 1.49. Set send_bye parameter +... +modparam("dialog", "send_bye", 1) +... + +6.50. wait_ack (int) + + If set to 1, dialog will be kept a bit longer in memory in order to + absorb the ACK negative replies of initial INVITE. If not, the dialog + is destroyed when negative reply is sent out (less internal + complexity). + + Default value is “1”. + + Example 1.50. Set wait_ack parameter +... +modparam("dialog", "wait_ack", 0) +... + +6.51. ka_timer (int) + + Keep-alive timer step - how often to execute the callback to send + dialog keep alives (SIP OPTIONS requests within dialog). The value + represents the number of seconds. + + Default value is “0” (no keep alive). + + Example 1.51. Set ka_timer parameter +... +modparam("dialog", "ka_timer", 10) +... + +6.52. ka_interval (int) + + The interval between keep alives within dialog (SIP OPTIONS requests), + sent to caller or callee. The keep alive request will be sent by the + first callback fired by KA timer after the ka_interval elapsed from + dialog setup or previous keep-alive. The value represents the number of + seconds. + + If the requests times out (generating a 408) or if the UA responds with + 481 the lifetime is set to 10 seconds. When lifetime expires the dialog + will be terminated. Any other response (including error responses) will + reset the timers. + + Default value is “0” (no keep alive). The lowest settable interval is + 30 seconds. + + Example 1.52. Set ka_interval parameter +... +modparam("dialog", "ka_interval", 300) +... + +6.53. ka_failed_limit (int) + + The number of failed keep-alive requests that is accepted before + generating a dialog timeout. + + Default value is “1”. + + Example 1.53. Set ka_failed_limit parameter +... +modparam("dialog", "ka_failed_limit", 5) +... + +6.54. timeout_noreset (int) + + If set to 1, the dialog timeout won't be reset each time a sequential + request is processed. It is an alternative to + dlg_set_property("timeout-noreset") for all dialogs. + + Default value is “0”. + + Example 1.54. Set timeout_noreset parameter +... +modparam("dialog", "timeout_noreset", 1) +... + +6.55. timer_procs (int) + + If set to 1, the dialog module will start a separate dialog timer + process to execute dialog timeout tasks. The default is to use the core + timer process. + + Default value is “0” (use core timer process). + + Example 1.55. Set timer_procs parameter +... +modparam("dialog", "timer_procs", 1) +... + +6.56. enable_dmq (int) + + If set to 1, the dialog will be synced via dmq. For now, only very + basic dialog info is shared, just enough to have synced profiles. + Notably, it is not possible to send in-dialog requests on any but the + original proxy instance. + + Default value is “0”. + + Example 1.56. Set enable_dmq parameter +... +modparam("dialog", "enable_dmq", 1) +... + +6.57. track_cseq_updates (int) + + Enable the callbacks for tracking if CSeq number needs to be updated. + It is the case when the INVITE has to be authenticated to downstream + provider using uac_auth() from uac module. + + This is done only for requests in downstream direction. The CSeq + difference is stored in $dlg_var(cseq_diff), be sure this variable is + not overwritten via config operation. + + Default value is “0” (disabled). + + Example 1.57. Set track_cseq_updates parameter +... +modparam("dialog", "track_cseq_updates", 1) +... + +6.58. lreq_callee_headers (string) + + SIP headers to be added when sending local generated requests (e.g., + BYE) to callee. It can be useful when you use topoh module with call-id + masking (see the docs of topoh module). + + Default value is “null”. + + Example 1.58. Set lreq_callee_headers parameter +... +modparam("dialog", "lreq_callee_headers", "TH: dlh\r\n") +... + +6.59. event_callback (str) + + The name of the function in the kemi configuration file (embedded + scripting language such as Lua, Python, ...) to be executed instead of + event_route[...] blocks. + + The function receives a string parameter with the name of the event, + the values are: 'dialog:start', 'dialog:end', 'dialog:failed'. It is + also executed if '$dlg_ctx(timeout_route)' is set, the callback + function being executed with the variable value as parameter. + + Default value is 'empty' (no function is executed for events). + + Example 1.59. Set event_callback parameter +... +modparam("dialog", "event_callback", "ksr_dialog_event") +... +-- event callback function implemented in Lua +function ksr_dialog_event(evname) + KSR.info("===== dialog module triggered event: " .. evname .. "\n"); + return 1; +end +... + +6.60. h_id_start (int) + + Set the offset to be used for generating dialog internal hash id. If + set to -1, the h_id_start is set to the value of the server_id global + parameter. + + Default value is “0”. + + Example 1.60. Set h_id_start parameter +... +modparam("dialog", "h_id_start", 5) +... + +6.61. h_id_step (int) + + Set the step to increment the dialog internal hash id. + + If the value is greater than 1, the internal hash id is generated with + the rule: h_id_start + N * h_id_step. The first value of N is randomly + selected at startup, then incremented by 1 for each new dialog. Setting + h_id_start and h_id_step to non-default values should be done when + using dlg_db_load_callid(...) or dlg_db_load_extra() to load dialog + records generated by another Kamailio instance, making also sure that + those Kamailio nstances are not going to generate overalapping dialog + hash id values by using different h_id_start and the same h_id_step + (h_id_step has to be greater than the maximum value of h_id_start). + + Default value is “1”. + + Example 1.61. Set h_id_step parameter +... +modparam("dialog", "h_id_step", 10) +... + +7. Functions + + 7.1. set_dlg_profile(profile,[value]) + 7.2. unset_dlg_profile(profile,[value]) + 7.3. is_in_profile(profile,[value]) + 7.4. get_profile_size(profile,[value],size) + 7.5. dlg_isflagset(flag) + 7.6. dlg_setflag(flag) + 7.7. dlg_resetflag(flag) + 7.8. dlg_bye(side) + 7.9. dlg_refer(side, address) + 7.10. dlg_manage() + 7.11. dlg_bridge(from, to, op) + 7.12. dlg_get(callid, ftag, ttag) + 7.13. is_known_dlg() + 7.14. dlg_set_timeout(timeout [, h_entry, h_id]) + 7.15. dlg_set_timeout_by_profile(profile, [value], timeout) + 7.16. dlg_set_property(attr) + 7.17. dlg_remote_profile(cmd, profile, value, uid, expires) + 7.18. dlg_set_ruri() + 7.19. dlg_db_load_callid(cival) + 7.20. dlg_db_load_extra() + +7.1. set_dlg_profile(profile,[value]) + + Inserts the current dialog into a profile. Note that if the profile + does not support values, they will be silently discarded. Also, there + is no check for inserting the same dialog into the same profile + multiple times. + + Meaning of the parameters is as follows: + * profile - name of the profile to be added to; + * value (optional) - string value to define the membership of the + dialog in the profile. Note that the profile must support values. + Pseudo-variables are supported. + + This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, REPLY_ROUTE + and FAILURE_ROUTE. + + Example 1.62. set_dlg_profile usage +... +set_dlg_profile("inbound_call"); +set_dlg_profile("caller","$fu"); +... + +7.2. unset_dlg_profile(profile,[value]) + + Removes the current dialog from a profile. + + Meaning of the parameters is as follows: + * profile - name of the profile to be removed from; + * value (optional) - string value to define the belonging of the + dialog to the profile - note that the profile must support values. + Pseudo-variables are supported. + + This function can be used from BRANCH_ROUTE, REPLY_ROUTE and + FAILURE_ROUTE. + + Example 1.63. unset_dlg_profile usage +... +unset_dlg_profile("inbound_call"); +unset_dlg_profile("caller","$fu"); +... + +7.3. is_in_profile(profile,[value]) + + Checks if the current dialog belongs to a profile. If the profile is + defined with values, then the check is also matching with the specific + value provided as parameter. + + Note that if the profile is not defined with support for values, the + value parameter will be silently discarded. + + Meaning of the parameters is as follows: + * profile - name of the profile to be checked against; + * value (optional) - string value to be matched during the check. + Pseudo-variables are supported. + + This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, REPLY_ROUTE + and FAILURE_ROUTE. + + Example 1.64. is_in_profile usage +... +if (is_in_profile("inbound_call")) { + log("this request belongs to a inbound call\n"); +} +... +if (is_in_profile("caller","XX")) { + log("this request belongs to a call of user XX\n"); +} +... + +7.4. get_profile_size(profile,[value],size) + + Returns the number of dialogs belonging to a profile. If the profile + supports values, the check can be reinforced to take into account a + specific value, i.e. how many dialogs were inserted into the profile + with a specific value. If no value is passed, only the membership of + the dialog in the profile per se is checked. Note that if the profile + does not support values, the value parameter will be silently + discarded. + + Meaning of the parameters is as follows: + * profile - name of the profile to get the size for; + * value (optional) - string value to further restrict the check. + Pseudo-variables are supported; + * size - an AVP or script variable to return the profile size in. + + This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, REPLY_ROUTE + and FAILURE_ROUTE. + + Example 1.65. get_profile_size usage +... +if(get_profile_size("inbound_call","$avp(size)")) + xlog("currently there are $avp(size) inbound calls\n"); +... +if(get_profile_size("caller","$fu","$avp(size)")) + xlog("currently, the user $fu has $avp(size) active outgoing calls\n"); +... + +7.5. dlg_isflagset(flag) + + Check if the dialog flag is set or not. + + Meaning of the parameters is as follows: + * flag - index of the flag - can be pseudo-variable. + + This function can be used from BRANCH_ROUTE, REQUEST_ROUTE, + ONREPLY_ROUTE and FAILURE_ROUTE. + + Example 1.66. dlg_isflagset usage +... +if(dlg_isflagset("1")) +{ + ... +} +... + +7.6. dlg_setflag(flag) + + Set a dialog flag. + + Meaning of the parameters is as follows: + * flag - index of the flag - can be pseudo-variable. + + This function can be used from BRANCH_ROUTE, REQUEST_ROUTE, + ONREPLY_ROUTE and FAILURE_ROUTE. + + Example 1.67. dlg_setflag usage +... +dlg_setflag("1"); +... + +7.7. dlg_resetflag(flag) + + Reset the dialog flag. + + Meaning of the parameters is as follows: + * flag - index of the flag - can be pseudo-variable. + + This function can be used from BRANCH_ROUTE, REQUEST_ROUTE, + ONREPLY_ROUTE and FAILURE_ROUTE. + + Example 1.68. dlg_resetflag usage +... +redlg_setflag("1"); +... + +7.8. dlg_bye(side) + + Send BYE to both parties of a dialog. + + Meaning of the parameters is as follows: + * side - where to send the BYE. It can be: 'caller', 'callee', or + 'all' (send to both sides). + + This function can be used from ANY_ROUTE. + + Example 1.69. dlg_bye usage +... +dlg_bye("all"); +... + +7.9. dlg_refer(side, address) + + Refer the 'side' to a new SIP 'address'. + + Meaning of the parameters is as follows: + * side - which side of the dialog to REFER. It can be: 'caller' or + 'callee'. + * address - SIP address to refer to. + + This function can be used from BRANCH_ROUTE, REQUEST_ROUTE, + ONREPLY_ROUTE and FAILURE_ROUTE. + + Example 1.70. dlg_refer usage +... +dlg_refer("caller", "sip:announcement@kamailio.org"); +... + +7.10. dlg_manage() + + Process current SIP request with dialog module. It is an alternative to + setting dialog flag for initial INVITE and Route-parameter-callback + execution for within-dialog requests. + + This function can be used from REQUEST_ROUTE. + + Example 1.71. dlg_manage usage +... +modparam("dialog", "default_timeout", 100) +... +request_route { +... + if(is_method("INVITE") && !has_totag()) + { + $dlg_ctx(timeout_route) = "DLGTIMEOUT"; + $dlg_ctx(timeout_bye) = 1; + } + dlg_manage(); +... +} +... + +7.11. dlg_bridge(from, to, op) + + Bridge 'from' SIP address to 'to' SIP address via outbound proxy 'op'. + + Meaning of the parameters is as follows: + * from - SIP address of first side to call. + * to - SIP address to refer “from” to. + * op - outbound proxy SIP address. + + This function can be used from BRANCH_ROUTE, REQUEST_ROUTE, + ONREPLY_ROUTE and FAILURE_ROUTE. + + Example 1.72. dlg_bridge usage +... +dlg_bridge("sip:user@kamailio.org", "sip:annoucement@kamailio.org", + "sip:kamailio.org:5080"); +... + +7.12. dlg_get(callid, ftag, ttag) + + Search and set current dialog based on Call-ID, From-Tag and To-Tag + parameters. + + Meaning of the parameters is as follows: + * callid - SIP call-id. + * ftag - SIP From tag. + * ttag - SIP To tag. + + This function can be used from BRANCH_ROUTE, REQUEST_ROUTE, + ONREPLY_ROUTE and FAILURE_ROUTE. + + Example 1.73. dlg_get usage +... +if(dlg_get("abcdef", "123", "456")) +{ + dlg_bye("all"); +} +... + +7.13. is_known_dlg() + + This function checks if the current SIP message being processed belongs + to any transaction within an active dialog that the dialog module is + currently tracking. This is a check for tracking of any kind, without + regard to profiles. + + This function has numerous potential applications, among which is that + it can be used to strengthen security for loose-routing sequential + (in-dialog) requests or responses to them, as by providing a + preventative check against spoofing on the proxy level instead of + leaving the issue purely to the receiving UA. + + This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, REPLY_ROUTE + and FAILURE_ROUTE. + + Example 1.74. is_known_dlg() usage +... +if(!uri == myself) { + if(is_known_dlg()) { + xlog("Request $rm from $ci is in-dialog\n"); + } +} +... + +7.14. dlg_set_timeout(timeout [, h_entry, h_id]) + + Set the dialog timeout. Dialog timeout will be updated if it was + already set. If h_entry and h_id parameters are not provided, the + dialog will be searched based on (callid, fromtag, totag) of currently + processed SIP message. + + Meaning of the parameters is as follows: + * timeout - the interval in seconds after which the dialog will time + out. + * h_entry - h_entry value of the iternal dialog identifier. + * h_id - h_id valye if the internal dialog identifier. + + This function can be used from ANY_ROUTE. + + Example 1.75. dlg_set_timeout usage +... +if(dlg_set_timeout("180", "123", "456")) +{ + ... +} +... + +7.15. dlg_set_timeout_by_profile(profile, [value], timeout) + + Like dlg_set_timeout(), but simultaneously sets the timeout of all + dialogs in a given profile. Can be constrained by profile value. + + Meaning of the parameters is as follows: + * profile - The dialog profile across which to apply the timeout. + value (optional) - The profile value to use when applying the + dialog timeout. + timeout - the interval in seconds after which the dialog will time + out. + + This function can be used from ANY_ROUTE. + + Example 1.76. dlg_set_timeout_by_profile usage +... +# All dialogs belonging to user abc123 (tracked via set_dlg_profile()) +# will be timed out in 3 seconds. + +dlg_set_timeout_by_profile("users", "abc123", "3"); +... + +7.16. dlg_set_property(attr) + + Set a dialog property - an attribute that enable/disable various + behaviours (e.g., sending keep alive requests). + + Meaning of the parameters is as follows: + * attr - name of property. It can be: + + 'ka-src' - send keep alive OPTION requests to caller + + 'ka-dst' - send keep alive OPTION requests to callee + + 'timeout-noreset' - don't reset timeout on in-dialog messages + reception + + If keep alive is enabled for a dialog, the module will send SIP OPTIONS + requests with CSeq lower or equal than last request within dialog, with + the scope of detecting if the destination is still in the call. If the + keep alive request results in a local timeout or '481 Call + Leg/Transaction Does Not Exist', then the dialog is ended from the + server. + + If 'timeout-noreset' is set, dialog timeout won't be reset upon + reception of in-dialog messages (default behavior). + + This function can be used from ANY_ROUTE. + + Example 1.77. dlg_set_property usage +... +dlg_set_property("ka-src"); +dlg_set_property("ka-dst"); +dlg_set_property("timeout-noreset"); +... + +7.17. dlg_remote_profile(cmd, profile, value, uid, expires) + + Manage remote profile via config file. A remote profile item is + considered when the dialog is not managed by this server instance. The + notification to add/remove can be received via SIP or a RPC command, + the operation can be then triggered from configuration file. This + should allow counting active dialogs in a profile that are managed by + multiple SIP server instances. + + Meaning of the parameters is as follows: + * cmd - the operations to do: add - add an item in profile; rm - + remove an item from profile + * profile - name of profile + * value - value for profile (if no value is needed for that profile, + use an empty string. + * expires - absolute time (unix timestamp) when this profile item + should be removed automatically (time based), if still in the + profile + + This function can be used from ANY_ROUTE. + + Example 1.78. dlg_remote_profile usage +... +$var(exp) = 3600 + $Ts; +dlg_remote_profile("add", "caller", "test", "$sruid", "$var(exp)"); +... + +7.18. dlg_set_ruri() + + This function sets the R-URI with the corresponding endpoint address + stored in dialog structure (i.e., its Contact field). + + This function can be used from ANY_ROUTE. + + Example 1.79. dlg_set_ruri() usage +... +if(has_totag() and is_present_hf("Route") and uri==myself ) { + if(dlg_set_ruri()) { + xlog("Request URI changed from [$ou] to dlg value: [$ru]\n"); + } +} +... + +7.19. dlg_db_load_callid(cival) + + Load dialog record from database matching on Call-Id provided as + parameter. + + This function can be used from ANY_ROUTE. + + Example 1.80. dlg_db_load_callid() usage +... +if(has_totag()) { + if(!is_known_dlg()) { + dlg_db_load_callid("$ci"); + if(!is_known_dlg()) { + xlog("no dialog found with callid: $ci\n"); + } + } +} +... + +7.20. dlg_db_load_extra() + + Load all dialog records from database that are not in memory of the + current Kamailio instance. + + This function can be used from ANY_ROUTE. + + Example 1.81. dlg_db_load_extra() usage +... +if(has_totag()) { + if(!is_known_dlg()) { + dlg_db_load_extra(); + if(!is_known_dlg()) { + xlog("no dialog found with callid: $ci\n"); + } + } +} +... + +8. Statistics + + 8.1. active_dialogs + 8.2. early_dialogs + 8.3. processed_dialogs + 8.4. expired_dialogs + 8.5. failed_dialogs + +8.1. active_dialogs + + Returns the number of current active dialogs (may be confirmed or not). + +8.2. early_dialogs + + Returns the number of early dialogs. + +8.3. processed_dialogs + + Returns the total number of processed dialogs (terminated, expired or + active) from the startup. + +8.4. expired_dialogs + + Returns the total number of expired dialogs from the startup. + +8.5. failed_dialogs + + Returns the number of failed dialogs. + +9. RPC Commands + + 9.1. dlg.list + 9.2. dlg.list_ctx + 9.3. dlg.dlg_list + 9.4. dlg.dlg_list_ctx + 9.5. dlg.terminate_dlg + 9.6. dlg.end_dlg + 9.7. dlg.profile_get_size + 9.8. dlg.profile_list + 9.9. dlg.bridge_dlg + 9.10. dlg.stats_active + +9.1. dlg.list + + Lists the description of all dialogs (active calls). + + Name: dlg.list + + RPC Command Format: +... +kamcmd dlg.list +... + +9.2. dlg.list_ctx + + The same as the “dlg_list” but including in the dialog description the + associated context from modules sitting on top of the dialog module. + + Name: dlg.list_ctx + + RPC Command Format: +... +kamcmd dlg.list_ctx +... + +9.3. dlg.dlg_list + + Lists the description of one dialog. The dialog identifiers are to be + passed as parameter (callid and optionally fromtag). + + Name: dlg.dlg_list + + Parameters: + * callid callid of the dialog to be listed. + * from_tag from tag (as per initial request) of the dialog to be + listed. + + RPC Command Format: +... +kamcmd dlg.list abcdrssfrs122444@192.168.1.1 AAdfeEFF33 +... +kamcmd dlg.list abcdrssfrs122444@192.168.1.1 +... + +9.4. dlg.dlg_list_ctx + + The same as the “dlg.list_ctx” but including in the dialog description + the associated context from modules sitting on top of the dialog + module. + + Name: dlg.dlg_list_ctx + + Parameters: see “dlg_list” + + RPC Command Format: +... +kamcmd dlg.list_ctx abcdrssfrs122444@192.168.1.1 AAdfeEFF33 +... +kamcmd dlg.list_ctx abcdrssfrs122444@192.168.1.1 +... + +9.5. dlg.terminate_dlg + + Terminates an ongoing dialog by sending BYE in both directions, + matching the dialog on call-id, from tag and to tag. + + Name: dlg.terminate_dlg + + Parameters: + * callid - callid of dialog to be terminated + * from_tag - from tag of the dialog to terminated + * to_tag - to tag of the dialog to terminated + + The command works only for confirmed dialogs. + + RPC Command Format: + kamcmd dlg.terminate_dlg callid12345 fromtag123 totag123 + +9.6. dlg.end_dlg + + Terminates an ongoing dialog by sending BYE in both directions. + + Name: dlg.end_dlg + + Parameters: + * h_entry - hash entry of the dialog in the internal dialog table + * h_id - hash id of the dialog on the hash entry + * extra_hdrs - (optional) string containg extra headers (full format) + to be added to the BYE requests. + + The values for the h_entry and h_id can be get via the dlg_list RPC + command. + + RPC Command Format: +... +kamcmd dlg.end_dlg 342 56 +... + +9.7. dlg.profile_get_size + + Returns the number of dialogs belonging to a profile. If the profile + supports values, the check can be reinforced to take into account a + specific value - how many dialogs were inserted into the profile with a + specific value. If no value is passed, only the simply belonging of the + dialog to the profile is checked. Note that if the profile does not + support values, the value parameter will be silently discarded. + + Name: dlg.profile_get_size + + Parameters: + * profile - name of the profile to get the value for. + * value (optional)- string value to further restrict the check; + + RPC Command Format: +... +kamcmd dlg.dlg.profile_get_size inbound_calls +... + +9.8. dlg.profile_list + + Lists all the dialogs belonging to a profile. If the profile supports + values, the check can be reinforced to take into account a specific + value, i.e. list only the dialogs that were inserted into the profile + with that specific value. If no value is passed, all dialogs belonging + to the profile will be listed. Note that if the profile does not + supports values, this will be silently discarded. + + Name: dlg.profile_list + + Parameters: + * profile - name of the profile to list the dialog for. + * value (optional)- string value to further restrict the check; + + RPC Command Format: +... +kamcmd dlg.profile_list inbound_calls +... + +9.9. dlg.bridge_dlg + + Bridge two SIP addresses into a call using INVITE(hold)-REFER-BYE + mechanism. + + Name: dlg.bridge_dlg + + Parameters: + * from - SIP address to initiate the call + * to - SIP address to refer 'from' to + * op (optional) - outbound proxy SIP address. If its value is set to + '.' (dot), then it is ignored (like it would not have been + provided). + * body (optional) - SDP body for initial INVITE. If its value is set + to '.' (dot), then it is ignored (like it would not have been + provided). If body is not set via RPC command parameter, then an + internal generated SDP with G711a and G711u is used. If its value + is set to '' (empty string) or '_' (underline), then the INVITE is + sent without an SDP body. + + RPC Command Format: +... +kamcmd dlg.bridge_dlg _from_ _to_ _op_ +... + +9.10. dlg.stats_active + + Get stats about active dialogs by scanning internal list of dialogs + (not relying on core stats framework). + + Name: dlg.stats_active + + Parameters: none. + + Returned fields + * starting - initial INVITE has been processed, no ringing or 1xx has + been received. + * connecting - initial INVITE was forwarded and rining or 1xx has + been received. + * answering - initial INVITE received 200ok, but ACK was not handled + yet. + * ongoing - ongoing active dialog, after the ACK was processed. + * all - all active dialogs, respectively the sum of the above values. + + RPC Command Format: +... +kamcmd dlg.stats_active +... + +10. Exported Variables + + 10.1. $DLG_count + 10.2. $DLG_status + 10.3. $DLG_lifetime + 10.4. $dlg(...) + 10.5. $dlg_ctx(...) + 10.6. $dlg_var(key) + +10.1. $DLG_count + + Returns the number of current active dialogs (may be confirmed or not). + +10.2. $DLG_status + + Returns the status of the dialog corresponding to the processed + sequential request. This PV will be available only for sequential + requests, after doing loose_route(). + + Value may be: + * NULL - Dialog not found. + * 3 - Confirmed by a final reply but no ACK received yet. + * 4 - Confirmed by a final reply and ACK received. + * 5 - Dialog ended. + +10.3. $DLG_lifetime + + Returns the duration (in seconds) of the dialog corresponding to the + processed sequential request. The duration is calculated from the + dialog confirmation and the current moment. This PV will be available + only for sequential requests, after doing loose_route(). + + NULL will be returned if there is no dialog for the request. + +10.4. $dlg(...) + + Access to dialog attributes. + +10.5. $dlg_ctx(...) + + Access to dialog context attributes. + +10.6. $dlg_var(key) + + This is a read/write variable that can be used to store custom values + assigned with a dialog (e.g. the URI of a billing-server, an assigned + emergency-server). This pseudo-variable will be available only for + subsequential requests after doing loose_route(). + + Note: You will receive "NULL", if there is no dialog for this request. + +11. Event Routes + + 11.1. event_route[dialog:start] + 11.2. event_route[dialog:end] + 11.3. event_route[dialog:failed] + +11.1. event_route[dialog:start] + + Executed when 200 OK reply for INVITE is processed. + +11.2. event_route[dialog:end] + + Executed when the BYE for the call is processed or the dialog timed + out. + +11.3. event_route[dialog:failed] + + Executed when dialog is not completed (300 or greater reply code to + INVITE). + +Chapter 2. Developer Guide + + Table of Contents + + 1. Available Functions + + 1.1. register_dlgcb (dialog, type, cb, param, free_param_cb) + 1.2. terminate_dlg (dlg, hdrs) + +1. Available Functions + + 1.1. register_dlgcb (dialog, type, cb, param, free_param_cb) + 1.2. terminate_dlg (dlg, hdrs) + +1.1. register_dlgcb (dialog, type, cb, param, free_param_cb) + + Register a new callback to the dialog. + + Meaning of the parameters is as follows: + * struct dlg_cell* dlg - dialog to register callback to. If maybe + NULL only for DLGCB_CREATED callback type, which is not a per + dialog type. + * int type - types of callbacks; more types may be register for the + same callback function; only DLGCB_CREATED must be register alone. + Possible types: + + DLGCB_LOADED + + DLGCB_CREATED - called when a new dialog is created - it's a + global type (not associated to any dialog) + + DLGCB_FAILED - called when the dialog was negatively replied + (non-2xx) - it's a per dialog type. + + DLGCB_CONFIRMED_NA - called when the dialog is confirmed (2xx + replied) but the setup-concluding ACK message from the caller + is yet pending - it's a per dialog type. + + DLGCB_CONFIRMED - called when the dialog is confirmed (2xx + replied) and the setup-concluding ACK message from the caller + has been seen - it's a per dialog type. + + DLGCB_REQ_WITHIN - called when the dialog matches a sequential + request (excluding setup-concluding ACK messages which are + handled in DLGCB_CONFIRMED) - it's a per dialog type. + + DLGCB_TERMINATED - called when the dialog is terminated via + BYE - it's a per dialog type. + + DLGCB_TERMINATED_CONFIRMED - called when response to a BYE + request is received - it's a per dialog type. + + DLGCB_EXPIRED - called when the dialog expires without + receiving a BYE - it's a per dialog type. + + DLGCB_EARLY - called when the dialog is created in an early + state (18x replied) - it's a per dialog type. + + DLGCB_RESPONSE_FWDED - called when the dialog matches a reply + to the initial INVITE request - it's a per dialog type. + + DLGCB_RESPONSE_WITHIN - called when the dialog matches a reply + to a subsequent in dialog request - it's a per dialog type. + + DLGCB_RPC_CONTEXT - called when the rpc dlg_list_ctx command + is invoked - it's a per dialog type. + + DLGCB_SPIRALED - called when the dialog matches a spiraling + request - it's a per dialog type. + + DLGCB_DESTROY + * dialog_cb cb - callback function to be called. Prototype is: “void + (dialog_cb) (struct dlg_cell* dlg, int type, struct dlg_cb_params * + params); ” + * void *param - parameter to be passed to the callback function. + * param_free callback_param_free - callback function to be called to + free the param. Prototype is: “void (param_free_cb) (void *param);” + +1.2. terminate_dlg (dlg, hdrs) + + Terminate a Dialog + + Meaning of parameters is as follows: + * struct dlg_cell* dlg - dialog to terminate. + * str* hdrs - string containing extra headers (full format) to be + added to the BYE requests of the dialog. + +Chapter 3. Frequently Asked Questions + + 3.1. What happened with “use_tight_match” parameter? + 3.2. Where can I find more about Kamailio? + 3.3. Where can I post a question about this module? + 3.4. How can I report a bug? + + 3.1. + + What happened with “use_tight_match” parameter? + + The parameter was removed with version 1.3 as the option of tight + matching became mandatory and not configurable. Now, the tight matching + is done all the time (when using DID matching). + + 3.2. + + Where can I find more about Kamailio? + + Take a look at https://www.kamailio.org/. + + 3.3. + + 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 - + https://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-users + * Developer Mailing List - + https://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-dev + + E-mails regarding any stable Kamailio release should be sent to + and e-mails regarding development + versions should be sent to . + + 3.4. + + How can I report a bug? + + Please follow the guidelines provided at: + https://github.com/kamailio/kamailio/issues. diff --git a/src/modules/textops/README b/src/modules/textops/README index d3296dccec7..a94fe196c12 100644 --- a/src/modules/textops/README +++ b/src/modules/textops/README @@ -57,44 +57,45 @@ Ovidiu Sas 4.10. replace_body_atonce(re, txt) 4.11. replace_str(match, repl, mode) 4.12. replace_body_str(match, repl, mode) - 4.13. subst('/re/repl/flags') - 4.14. subst_uri('/re/repl/flags') - 4.15. subst_user('/re/repl/flags') - 4.16. subst_body('/re/repl/flags') - 4.17. subst_hf(hf, subexp, flags) - 4.18. set_body(txt,content_type) - 4.19. set_reply_body(txt,content_type) - 4.20. filter_body(content_type) - 4.21. append_to_reply(txt) - 4.22. append_hf(txt[, hdr]) - 4.23. insert_hf(txt[, hdr]) - 4.24. append_urihf(prefix, suffix) - 4.25. is_present_hf(hf_name) - 4.26. is_present_hf_re(hf_name_re) - 4.27. append_time() - 4.28. append_time_to_request() - 4.29. is_method(name) - 4.30. remove_hf(hname) - 4.31. remove_hf_re(re) - 4.32. remove_hf_exp(expmatch, expskip) - 4.33. has_body(), has_body(mime) - 4.34. is_audio_on_hold() - 4.35. is_privacy(privacy_type) - 4.36. in_list(subject, list, separator) - 4.37. in_list_prefix(subject, list, separator) - 4.38. cmp_str(str1, str2) - 4.39. cmp_istr(str1, str2) - 4.40. starts_with(str1, str2) - 4.41. set_body_multipart([txt,content_type][,boundary]) - 4.42. append_body_part(txt,content_type[, + 4.13. replace_hdrs_str(match, repl, mode) + 4.14. subst('/re/repl/flags') + 4.15. subst_uri('/re/repl/flags') + 4.16. subst_user('/re/repl/flags') + 4.17. subst_body('/re/repl/flags') + 4.18. subst_hf(hf, subexp, flags) + 4.19. set_body(txt,content_type) + 4.20. set_reply_body(txt,content_type) + 4.21. filter_body(content_type) + 4.22. append_to_reply(txt) + 4.23. append_hf(txt[, hdr]) + 4.24. insert_hf(txt[, hdr]) + 4.25. append_urihf(prefix, suffix) + 4.26. is_present_hf(hf_name) + 4.27. is_present_hf_re(hf_name_re) + 4.28. append_time() + 4.29. append_time_to_request() + 4.30. is_method(name) + 4.31. remove_hf(hname) + 4.32. remove_hf_re(re) + 4.33. remove_hf_exp(expmatch, expskip) + 4.34. has_body(), has_body(mime) + 4.35. is_audio_on_hold() + 4.36. is_privacy(privacy_type) + 4.37. in_list(subject, list, separator) + 4.38. in_list_prefix(subject, list, separator) + 4.39. cmp_str(str1, str2) + 4.40. cmp_istr(str1, str2) + 4.41. starts_with(str1, str2) + 4.42. set_body_multipart([txt,content_type][,boundary]) + 4.43. append_body_part(txt,content_type[, content_disposition]) - 4.43. append_body_part_hex(txt,content_type[, + 4.44. append_body_part_hex(txt,content_type[, content_disposition]) - 4.44. get_body_part(content_type, opv) - 4.45. get_body_part_raw(content_type, opv) - 4.46. remove_body_part(content_type) + 4.45. get_body_part(content_type, opv) + 4.46. get_body_part_raw(content_type, opv) + 4.47. remove_body_part(content_type) 2. Developer Guide @@ -116,40 +117,41 @@ Ovidiu Sas 1.10. replace_body_atonce usage 1.11. replace_str usage 1.12. replace_body_str usage - 1.13. subst usage - 1.14. subst_uri usage - 1.15. subst usage - 1.16. subst_body usage - 1.17. subst_hf usage - 1.18. set_body usage - 1.19. set_reply_body usage - 1.20. filter_body usage - 1.21. append_to_reply usage - 1.22. append_hf usage - 1.23. insert_hf usage - 1.24. append_urihf usage - 1.25. is_present_hf usage - 1.26. is_present_hf_re usage - 1.27. append_time usage - 1.28. append_time_to_request usage - 1.29. is_method usage - 1.30. remove_hf usage - 1.31. remove_hf_re usage - 1.32. remove_hf_exp usage - 1.33. has_body usage - 1.34. is_audio_on_hold usage - 1.35. is_privacy usage - 1.36. in_list() usage + 1.13. replace_hdrs_str usage + 1.14. subst usage + 1.15. subst_uri usage + 1.16. subst usage + 1.17. subst_body usage + 1.18. subst_hf usage + 1.19. set_body usage + 1.20. set_reply_body usage + 1.21. filter_body usage + 1.22. append_to_reply usage + 1.23. append_hf usage + 1.24. insert_hf usage + 1.25. append_urihf usage + 1.26. is_present_hf usage + 1.27. is_present_hf_re usage + 1.28. append_time usage + 1.29. append_time_to_request usage + 1.30. is_method usage + 1.31. remove_hf usage + 1.32. remove_hf_re usage + 1.33. remove_hf_exp usage + 1.34. has_body usage + 1.35. is_audio_on_hold usage + 1.36. is_privacy usage 1.37. in_list() usage - 1.38. cmp_str usage + 1.38. in_list() usage 1.39. cmp_str usage - 1.40. starts_with usage - 1.41. set_body_multipart usage - 1.42. append_body_part usage - 1.43. append_body_part_hex usage - 1.44. get_body_part usage - 1.45. get_body_part_raw usage - 1.46. remove_body_part usage + 1.40. cmp_str usage + 1.41. starts_with usage + 1.42. set_body_multipart usage + 1.43. append_body_part usage + 1.44. append_body_part_hex usage + 1.45. get_body_part usage + 1.46. get_body_part_raw usage + 1.47. remove_body_part usage Chapter 1. Admin Guide @@ -176,42 +178,43 @@ Chapter 1. Admin Guide 4.10. replace_body_atonce(re, txt) 4.11. replace_str(match, repl, mode) 4.12. replace_body_str(match, repl, mode) - 4.13. subst('/re/repl/flags') - 4.14. subst_uri('/re/repl/flags') - 4.15. subst_user('/re/repl/flags') - 4.16. subst_body('/re/repl/flags') - 4.17. subst_hf(hf, subexp, flags) - 4.18. set_body(txt,content_type) - 4.19. set_reply_body(txt,content_type) - 4.20. filter_body(content_type) - 4.21. append_to_reply(txt) - 4.22. append_hf(txt[, hdr]) - 4.23. insert_hf(txt[, hdr]) - 4.24. append_urihf(prefix, suffix) - 4.25. is_present_hf(hf_name) - 4.26. is_present_hf_re(hf_name_re) - 4.27. append_time() - 4.28. append_time_to_request() - 4.29. is_method(name) - 4.30. remove_hf(hname) - 4.31. remove_hf_re(re) - 4.32. remove_hf_exp(expmatch, expskip) - 4.33. has_body(), has_body(mime) - 4.34. is_audio_on_hold() - 4.35. is_privacy(privacy_type) - 4.36. in_list(subject, list, separator) - 4.37. in_list_prefix(subject, list, separator) - 4.38. cmp_str(str1, str2) - 4.39. cmp_istr(str1, str2) - 4.40. starts_with(str1, str2) - 4.41. set_body_multipart([txt,content_type][,boundary]) - 4.42. append_body_part(txt,content_type[, content_disposition]) - 4.43. append_body_part_hex(txt,content_type[, + 4.13. replace_hdrs_str(match, repl, mode) + 4.14. subst('/re/repl/flags') + 4.15. subst_uri('/re/repl/flags') + 4.16. subst_user('/re/repl/flags') + 4.17. subst_body('/re/repl/flags') + 4.18. subst_hf(hf, subexp, flags) + 4.19. set_body(txt,content_type) + 4.20. set_reply_body(txt,content_type) + 4.21. filter_body(content_type) + 4.22. append_to_reply(txt) + 4.23. append_hf(txt[, hdr]) + 4.24. insert_hf(txt[, hdr]) + 4.25. append_urihf(prefix, suffix) + 4.26. is_present_hf(hf_name) + 4.27. is_present_hf_re(hf_name_re) + 4.28. append_time() + 4.29. append_time_to_request() + 4.30. is_method(name) + 4.31. remove_hf(hname) + 4.32. remove_hf_re(re) + 4.33. remove_hf_exp(expmatch, expskip) + 4.34. has_body(), has_body(mime) + 4.35. is_audio_on_hold() + 4.36. is_privacy(privacy_type) + 4.37. in_list(subject, list, separator) + 4.38. in_list_prefix(subject, list, separator) + 4.39. cmp_str(str1, str2) + 4.40. cmp_istr(str1, str2) + 4.41. starts_with(str1, str2) + 4.42. set_body_multipart([txt,content_type][,boundary]) + 4.43. append_body_part(txt,content_type[, content_disposition]) + 4.44. append_body_part_hex(txt,content_type[, content_disposition]) - 4.44. get_body_part(content_type, opv) - 4.45. get_body_part_raw(content_type, opv) - 4.46. remove_body_part(content_type) + 4.45. get_body_part(content_type, opv) + 4.46. get_body_part_raw(content_type, opv) + 4.47. remove_body_part(content_type) 1. Overview @@ -262,40 +265,41 @@ From: medabeda 4.10. replace_body_atonce(re, txt) 4.11. replace_str(match, repl, mode) 4.12. replace_body_str(match, repl, mode) - 4.13. subst('/re/repl/flags') - 4.14. subst_uri('/re/repl/flags') - 4.15. subst_user('/re/repl/flags') - 4.16. subst_body('/re/repl/flags') - 4.17. subst_hf(hf, subexp, flags) - 4.18. set_body(txt,content_type) - 4.19. set_reply_body(txt,content_type) - 4.20. filter_body(content_type) - 4.21. append_to_reply(txt) - 4.22. append_hf(txt[, hdr]) - 4.23. insert_hf(txt[, hdr]) - 4.24. append_urihf(prefix, suffix) - 4.25. is_present_hf(hf_name) - 4.26. is_present_hf_re(hf_name_re) - 4.27. append_time() - 4.28. append_time_to_request() - 4.29. is_method(name) - 4.30. remove_hf(hname) - 4.31. remove_hf_re(re) - 4.32. remove_hf_exp(expmatch, expskip) - 4.33. has_body(), has_body(mime) - 4.34. is_audio_on_hold() - 4.35. is_privacy(privacy_type) - 4.36. in_list(subject, list, separator) - 4.37. in_list_prefix(subject, list, separator) - 4.38. cmp_str(str1, str2) - 4.39. cmp_istr(str1, str2) - 4.40. starts_with(str1, str2) - 4.41. set_body_multipart([txt,content_type][,boundary]) - 4.42. append_body_part(txt,content_type[, content_disposition]) - 4.43. append_body_part_hex(txt,content_type[, content_disposition]) - 4.44. get_body_part(content_type, opv) - 4.45. get_body_part_raw(content_type, opv) - 4.46. remove_body_part(content_type) + 4.13. replace_hdrs_str(match, repl, mode) + 4.14. subst('/re/repl/flags') + 4.15. subst_uri('/re/repl/flags') + 4.16. subst_user('/re/repl/flags') + 4.17. subst_body('/re/repl/flags') + 4.18. subst_hf(hf, subexp, flags) + 4.19. set_body(txt,content_type) + 4.20. set_reply_body(txt,content_type) + 4.21. filter_body(content_type) + 4.22. append_to_reply(txt) + 4.23. append_hf(txt[, hdr]) + 4.24. insert_hf(txt[, hdr]) + 4.25. append_urihf(prefix, suffix) + 4.26. is_present_hf(hf_name) + 4.27. is_present_hf_re(hf_name_re) + 4.28. append_time() + 4.29. append_time_to_request() + 4.30. is_method(name) + 4.31. remove_hf(hname) + 4.32. remove_hf_re(re) + 4.33. remove_hf_exp(expmatch, expskip) + 4.34. has_body(), has_body(mime) + 4.35. is_audio_on_hold() + 4.36. is_privacy(privacy_type) + 4.37. in_list(subject, list, separator) + 4.38. in_list_prefix(subject, list, separator) + 4.39. cmp_str(str1, str2) + 4.40. cmp_istr(str1, str2) + 4.41. starts_with(str1, str2) + 4.42. set_body_multipart([txt,content_type][,boundary]) + 4.43. append_body_part(txt,content_type[, content_disposition]) + 4.44. append_body_part_hex(txt,content_type[, content_disposition]) + 4.45. get_body_part(content_type, opv) + 4.46. get_body_part_raw(content_type, opv) + 4.47. remove_body_part(content_type) 4.1. search(re) @@ -499,7 +503,25 @@ replace_str("Kamailio", "Kamailio SIP Proxy", "a"); replace_body_str("Kamailio", "Kamailio SIP Proxy", "a"); ... -4.13. subst('/re/repl/flags') +4.13. replace_hdrs_str(match, repl, mode) + + Replaces the first or all occurrence of 'match' with 'repl' by doing + string comparison for matching. It is applied over the part with + headers of the SIP message. + + Meaning of the parameters is as follows: + * match - string to be matched. + * repl - string to be used as replacement. + * mode - 'f' - replace only first match; 'a' - replace all matches. + + This function can be used from ANY_ROUTE. + + Example 1.13. replace_hdrs_str usage +... +replace_hdrs_str("Kamailio", "Kamailio SIP Proxy", "a"); +... + +4.14. subst('/re/repl/flags') Replaces re with repl (sed or perl like). @@ -514,7 +536,7 @@ replace_body_str("Kamailio", "Kamailio SIP Proxy", "a"); This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. - Example 1.13. subst usage + Example 1.14. subst usage ... # replace the uri in to: with the message uri (just an example) if ( subst('/^To:(.*)sip:[^@]*@[a-zA-Z0-9.]+(.*)$/t:\1\u\2/ig') ) {}; @@ -525,7 +547,7 @@ if ( subst('/^To:(.*)sip:[^@]*@[a-zA-Z0-9.]+(.*)$/t:\1$avp(sip_address)\2/ig') ) ... -4.14. subst_uri('/re/repl/flags') +4.15. subst_uri('/re/repl/flags') Runs the re substitution on the message uri (like subst but works only on the uri) @@ -541,7 +563,7 @@ if ( subst('/^To:(.*)sip:[^@]*@[a-zA-Z0-9.]+(.*)$/t:\1$avp(sip_address)\2/ig') ) This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. - Example 1.14. subst_uri usage + Example 1.15. subst_uri usage ... # adds 3463 prefix to numeric uris, and save the original uri (\0 match) # as a parameter: orig_uri (just an example) @@ -553,7 +575,7 @@ if (subst_uri('/^sip:([0-9]+)@(.*)$/sip:$avp(uri_prefix)\1@\2;orig_uri=\0/i')){$ ... -4.15. subst_user('/re/repl/flags') +4.16. subst_user('/re/repl/flags') Runs the re substitution on the message uri (like subst_uri but works only on the user portion of the uri) @@ -569,7 +591,7 @@ if (subst_uri('/^sip:([0-9]+)@(.*)$/sip:$avp(uri_prefix)\1@\2;orig_uri=\0/i')){$ This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. - Example 1.15. subst usage + Example 1.16. subst usage ... # adds 3463 prefix to uris ending with 3642 (just an example) if (subst_user('/3642$/36423463/')){$ @@ -580,7 +602,7 @@ if (subst_user('/(.*)3642$/$avp(user_prefix)\13642/')){$ ... -4.16. subst_body('/re/repl/flags') +4.17. subst_body('/re/repl/flags') Replaces re with repl (sed or perl like) in the body of the message. @@ -595,13 +617,13 @@ if (subst_user('/(.*)3642$/$avp(user_prefix)\13642/')){$ This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. - Example 1.16. subst_body usage + Example 1.17. subst_body usage ... if ( subst_body('/^o=(.*) /o=$fU /') ) {}; ... -4.17. subst_hf(hf, subexp, flags) +4.18. subst_hf(hf, subexp, flags) Perl-like substitutions in the body of a header field. @@ -616,12 +638,12 @@ if ( subst_body('/^o=(.*) /o=$fU /') ) {}; This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. - Example 1.17. subst_hf usage + Example 1.18. subst_hf usage ... if ( subst_hf("From", "/:test@/:best@/", "a") ) { /*....*/ }; ... -4.18. set_body(txt,content_type) +4.19. set_body(txt,content_type) Set body to a SIP message. @@ -633,12 +655,12 @@ if ( subst_hf("From", "/:test@/:best@/", "a") ) { /*....*/ }; This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. - Example 1.18. set_body usage + Example 1.19. set_body usage ... set_body("test", "text/plain"); ... -4.19. set_reply_body(txt,content_type) +4.20. set_reply_body(txt,content_type) Set body to a SIP reply to be generated by Kamailio. @@ -650,12 +672,12 @@ set_body("test", "text/plain"); This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. - Example 1.19. set_reply_body usage + Example 1.20. set_reply_body usage ... set_reply_body("test", "text/plain"); ... -4.20. filter_body(content_type) +4.21. filter_body(content_type) Filters multipart/mixed body by leaving out all other body parts except the first body part of given type. @@ -666,7 +688,7 @@ set_reply_body("test", "text/plain"); This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. - Example 1.20. filter_body usage + Example 1.21. filter_body usage ... if (has_body("multipart/mixed")) { if (filter_body("application/sdp") { @@ -678,7 +700,7 @@ if (has_body("multipart/mixed")) { } ... -4.21. append_to_reply(txt) +4.22. append_to_reply(txt) Append txt as header to the reply. @@ -688,13 +710,13 @@ if (has_body("multipart/mixed")) { This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, FAILURE_ROUTE, ERROR_ROUTE. - Example 1.21. append_to_reply usage + Example 1.22. append_to_reply usage ... append_to_reply("Foo: bar\r\n"); append_to_reply("Foo: $rm at $Ts\r\n"); ... -4.22. append_hf(txt[, hdr]) +4.23. append_hf(txt[, hdr]) Appends 'txt' as header after first header field or after last 'hdr' header field. @@ -707,13 +729,13 @@ append_to_reply("Foo: $rm at $Ts\r\n"); This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. - Example 1.22. append_hf usage + Example 1.23. append_hf usage ... append_hf("P-hint: VOICEMAIL\r\n"); append_hf("From-username: $fU\r\n", "Call-ID"); ... -4.23. insert_hf(txt[, hdr]) +4.24. insert_hf(txt[, hdr]) Inserts 'txt' as header before the first header field or before first 'hdr' header field if 'hdr' is given. @@ -726,7 +748,7 @@ append_hf("From-username: $fU\r\n", "Call-ID"); This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. - Example 1.23. insert_hf usage + Example 1.24. insert_hf usage ... insert_hf("P-hint: VOICEMAIL\r\n"); insert_hf("To-username: $tU\r\n"); @@ -734,7 +756,7 @@ insert_hf("P-hint: VOICEMAIL\r\n", "Call-ID"); insert_hf("To-username: $tU\r\n", "Call-ID"); ... -4.24. append_urihf(prefix, suffix) +4.25. append_urihf(prefix, suffix) Append header field name with original Request-URI in middle. @@ -745,12 +767,12 @@ insert_hf("To-username: $tU\r\n", "Call-ID"); This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. - Example 1.24. append_urihf usage + Example 1.25. append_urihf usage ... append_urihf("CC-Diversion: ", "\r\n"); ... -4.25. is_present_hf(hf_name) +4.26. is_present_hf(hf_name) Return true if a header field is present in message. @@ -765,12 +787,12 @@ Note This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. - Example 1.25. is_present_hf usage + Example 1.26. is_present_hf usage ... if (is_present_hf("From")) log(1, "From HF Present"); ... -4.26. is_present_hf_re(hf_name_re) +4.27. is_present_hf_re(hf_name_re) Return true if a header field whose name matches regular expression 'hf_name_re' is present in message. @@ -781,12 +803,12 @@ if (is_present_hf("From")) log(1, "From HF Present"); This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. - Example 1.26. is_present_hf_re usage + Example 1.27. is_present_hf_re usage ... if (is_present_hf_re("^P-")) log(1, "There are headers starting with P-\n"); ... -4.27. append_time() +4.28. append_time() Adds a time header to the reply of the request. You must use it before functions that are likely to send a reply, e.g., save() from @@ -805,12 +827,12 @@ if (is_present_hf_re("^P-")) log(1, "There are headers starting with P-\n"); This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. - Example 1.27. append_time usage + Example 1.28. append_time usage ... append_time(); ... -4.28. append_time_to_request() +4.29. append_time_to_request() Adds a time header to the request. Header format is: “Date: %a, %d %b %Y %H:%M:%S GMT”, with the legend: @@ -827,13 +849,13 @@ append_time(); This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. - Example 1.28. append_time_to_request usage + Example 1.29. append_time_to_request usage ... if(!is_present_hf("Date")) append_time_to_request(); ... -4.29. is_method(name) +4.30. is_method(name) Check if the method of the message matches the name. If name is a known method (invite, cancel, ack, bye, options, info, update, register, @@ -858,7 +880,7 @@ if(!is_present_hf("Date")) This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, and BRANCH_ROUTE. - Example 1.29. is_method usage + Example 1.30. is_method usage ... if(is_method("INVITE")) { @@ -870,7 +892,7 @@ if(is_method("OPTION|UPDATE")) } ... -4.30. remove_hf(hname) +4.31. remove_hf(hname) Remove from message all headers with name “hname”. Header matching is case-insensitive. Matches and removes also the compact header forms. @@ -883,7 +905,7 @@ if(is_method("OPTION|UPDATE")) This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE and BRANCH_ROUTE. - Example 1.30. remove_hf usage + Example 1.31. remove_hf usage ... if(remove_hf("User-Agent")) { @@ -895,7 +917,7 @@ remove_hf("Contact") remove_hf("m") ... -4.31. remove_hf_re(re) +4.32. remove_hf_re(re) Remove from message all headers with name matching regular expression “re” @@ -907,7 +929,7 @@ remove_hf("m") This function can be used from ANY_ROUTE. - Example 1.31. remove_hf_re usage + Example 1.32. remove_hf_re usage ... if(remove_hf_re("^P-")) { @@ -915,7 +937,7 @@ if(remove_hf_re("^P-")) } ... -4.32. remove_hf_exp(expmatch, expskip) +4.33. remove_hf_exp(expmatch, expskip) Remove from message all headers with name matching regular expression “expmatch”, but not matching regular expression “expskip”. @@ -930,7 +952,7 @@ if(remove_hf_re("^P-")) This function can be used from ANY_ROUTE. - Example 1.32. remove_hf_exp usage + Example 1.33. remove_hf_exp usage ... if(remove_hf_exp("^P-", "^P-Keep-")) { @@ -939,7 +961,7 @@ if(remove_hf_exp("^P-", "^P-Keep-")) } ... -4.33. has_body(), has_body(mime) +4.34. has_body(), has_body(mime) The function returns true if the SIP message has a body attached. The checked includes also the “Content-Length” header presence and value. @@ -954,7 +976,7 @@ if(remove_hf_exp("^P-", "^P-Keep-")) This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE and BRANCH_ROUTE. - Example 1.33. has_body usage + Example 1.34. has_body usage ... if(has_body("application/sdp")) { @@ -962,7 +984,7 @@ if(has_body("application/sdp")) } ... -4.34. is_audio_on_hold() +4.35. is_audio_on_hold() The function returns true if the SIP message has a body attached and at least one audio stream in on hold. The return code of the function @@ -973,7 +995,7 @@ if(has_body("application/sdp")) This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE and BRANCH_ROUTE. - Example 1.34. is_audio_on_hold usage + Example 1.35. is_audio_on_hold usage ... if(is_audio_on_hold()) { @@ -989,7 +1011,7 @@ if(is_audio_on_hold()) } ... -4.35. is_privacy(privacy_type) +4.36. is_privacy(privacy_type) The function returns true if the SIP message has a Privacy header field that includes the given privacy_type among its privacy values. See @@ -999,7 +1021,7 @@ if(is_audio_on_hold()) This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE and BRANCH_ROUTE. - Example 1.35. is_privacy usage + Example 1.36. is_privacy usage ... if(is_privacy("id")) { @@ -1007,7 +1029,7 @@ if(is_privacy("id")) } ... -4.36. in_list(subject, list, separator) +4.37. in_list(subject, list, separator) Function checks if subject string is found in list string where list items are separated by separator string. Subject and list strings may @@ -1016,7 +1038,7 @@ if(is_privacy("id")) Function can be used from all kinds of routes. - Example 1.36. in_list() usage + Example 1.37. in_list() usage ... $var(subject) = "fi"; $var(list) = "dk,fi,no,se"; @@ -1025,7 +1047,7 @@ if (in_list("$var(subject)", "$var(list)", ",")) { } ... -4.37. in_list_prefix(subject, list, separator) +4.38. in_list_prefix(subject, list, separator) Function checks if any element in list string is a prefix for subject string where list items are separated by separator string. Subject and @@ -1034,7 +1056,7 @@ if (in_list("$var(subject)", "$var(list)", ",")) { Function can be used from all kinds of routes. - Example 1.37. in_list() usage + Example 1.38. in_list() usage ... $var(subject) = "final"; $var(list) = "dk,fi,no,se"; @@ -1043,7 +1065,7 @@ if (in_list_prefix("$var(subject)", "$var(list)", ",")) { } ... -4.38. cmp_str(str1, str2) +4.39. cmp_str(str1, str2) The function returns true if the two parameters matches as string case sensitive comparison. @@ -1051,7 +1073,7 @@ if (in_list_prefix("$var(subject)", "$var(list)", ",")) { This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE and BRANCH_ROUTE. - Example 1.38. cmp_str usage + Example 1.39. cmp_str usage ... if(cmp_str("$rU", "kamailio")) { @@ -1059,7 +1081,7 @@ if(cmp_str("$rU", "kamailio")) } ... -4.39. cmp_istr(str1, str2) +4.40. cmp_istr(str1, str2) The function returns true if the two parameters matches as string case insensitive comparison. @@ -1067,7 +1089,7 @@ if(cmp_str("$rU", "kamailio")) This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE and BRANCH_ROUTE. - Example 1.39. cmp_str usage + Example 1.40. cmp_str usage ... if(cmp_istr("$rU@you", "kamailio@YOU")) { @@ -1075,7 +1097,7 @@ if(cmp_istr("$rU@you", "kamailio@YOU")) } ... -4.40. starts_with(str1, str2) +4.41. starts_with(str1, str2) The function returns true if the first string starts with the second string. @@ -1083,7 +1105,7 @@ if(cmp_istr("$rU@you", "kamailio@YOU")) This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE and BRANCH_ROUTE. - Example 1.40. starts_with usage + Example 1.41. starts_with usage ... if (starts_with("$rU", "+358")) { @@ -1091,7 +1113,7 @@ if (starts_with("$rU", "+358")) } ... -4.41. set_body_multipart([txt,content_type][,boundary]) +4.42. set_body_multipart([txt,content_type][,boundary]) Set multipart body to a SIP message. If called with no parameters, will convert present body to multipart. @@ -1112,7 +1134,7 @@ if (starts_with("$rU", "+358")) Note: it may be required that msg_apply_changes() from textopsx module has to be executed if there are other operations over the new body. - Example 1.41. set_body_multipart usage + Example 1.42. set_body_multipart usage ... set_body_multipart("test", "text/plain", "delimiter"); msg_apply_changes(); @@ -1134,7 +1156,7 @@ text --delimiter ... -4.42. append_body_part(txt,content_type[, content_disposition]) +4.43. append_body_part(txt,content_type[, content_disposition]) Append a part on multipart body SIP message. Will use "unique-boundary-1" as boundary. @@ -1152,7 +1174,7 @@ text The core will take care of the last boundary ending "--". Detecting wich one is the last and fixing the others if needed. - Example 1.42. append_body_part usage + Example 1.43. append_body_part usage ... $var(b) = "7e Od 04 55 75 69 20 4d 61 6b 65 43 61 6c 6c" append_body_part("$var(b)", "application/vnd.cirpack.isdn-ext", "signal;handling @@ -1170,7 +1192,7 @@ Content-Disposition: signal;handling=required --unique-boundary-1 ... -4.43. append_body_part_hex(txt,content_type[, content_disposition]) +4.44. append_body_part_hex(txt,content_type[, content_disposition]) Append a part on multipart body SIP message, with the content provided in hexa format. Will use "unique-boundary-1" as boundary. @@ -1191,7 +1213,7 @@ Content-Disposition: signal;handling=required The core will take care of the last boundary ending "--". Detecting wich one is the last and fixing the others if needed. - Example 1.43. append_body_part_hex usage + Example 1.44. append_body_part_hex usage ... $var(b) = "6b 61 6d 61 69 6c 69 6f"; append_body_part_hex("$var(b)", "application/my-custom-ext"); @@ -1207,7 +1229,7 @@ kamailio --unique-boundary-1 ... -4.44. get_body_part(content_type, opv) +4.45. get_body_part(content_type, opv) Return the content of a multipart body SIP message, storing it in opv. @@ -1220,12 +1242,12 @@ kamailio This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, ONREPLY_ROUTE. - Example 1.44. get_body_part usage + Example 1.45. get_body_part usage ... get_body_part("application/vnd.cirpack.isdn-ext", "$var(pbody)"); ... -4.45. get_body_part_raw(content_type, opv) +4.46. get_body_part_raw(content_type, opv) Return the content of a multipart body SIP message, including headers and boundary string, storing it in opv. @@ -1239,12 +1261,12 @@ get_body_part("application/vnd.cirpack.isdn-ext", "$var(pbody)"); This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, ONREPLY_ROUTE. - Example 1.45. get_body_part_raw usage + Example 1.46. get_body_part_raw usage ... get_body_part("application/vnd.cirpack.isdn-ext", "$var(hbody)"); ... -4.46. remove_body_part(content_type) +4.47. remove_body_part(content_type) Remove a part on a multipart body SIP message. @@ -1259,7 +1281,7 @@ get_body_part("application/vnd.cirpack.isdn-ext", "$var(hbody)"); The core will take care of the last boundary ending "--". Detecting wich one is the last and fixing the others if needed. - Example 1.46. remove_body_part usage + Example 1.47. remove_body_part usage ... remove_body_part("application/vnd.cirpack.isdn-ext"); ...