modules: readme files regenerated - dialog ... [skip ci]
[sip-router] / src / modules / dialog / README
1 dialog Module
2
3 Bogdan-Andrei Iancu
4
5    Voice Sistem SRL
6
7 Carsten Bock
8
9    ng-voice.com
10
11 Edited by
12
13 Bogdan-Andrei Iancu
14
15 Edited by
16
17 Carsten Bock
18
19 Edited by
20
21 Alex Balashov
22
23    <abalashov@evaristesys.com>
24
25 Edited by
26
27 Olle E. Johansson
28
29    <oej@edvina.net>
30
31    Copyright © 2006 Voice Sistem SRL
32
33    Copyright © 2011 Carsten Bock, http://www.ng-voice.com
34      __________________________________________________________________
35
36    Table of Contents
37
38    1. Admin Guide
39
40         1. Overview
41         2. How it works
42         3. Dialog states
43         4. Dialog profiling
44         5. Dependencies
45
46               5.1. Kamailio Modules
47               5.2. External Libraries or Applications
48
49         6. Parameters
50
51               6.1. enable_stats (integer)
52               6.2. hash_size (integer)
53               6.3. rr_param (string)
54               6.4. dlg_flag (integer)
55               6.5. timeout_avp (string)
56               6.6. default_timeout (integer)
57               6.7. early_timeout (integer)
58               6.8. noack_timeout (integer)
59               6.9. dlg_extra_hdrs (string)
60               6.10. dlg_match_mode (integer)
61               6.11. detect_spirals (integer)
62               6.12. db_url (string)
63               6.13. db_mode (integer)
64               6.14. db_update_period (integer)
65               6.15. db_fetch_rows (integer)
66               6.16. db_skip_load (integer)
67               6.17. table_name (string)
68               6.18. call_id_column (string)
69               6.19. from_uri_column (string)
70               6.20. from_tag_column (string)
71               6.21. to_uri_column (string)
72               6.22. to_tag_column (string)
73               6.23. from_cseq_column (string)
74               6.24. to_cseq_column (string)
75               6.25. from_route_column (string)
76               6.26. to_route_column (string)
77               6.27. from_contact_column (string)
78               6.28. to_contact_column (string)
79               6.29. from_sock_column (string)
80               6.30. to_sock_column (string)
81               6.31. h_id_column (string)
82               6.32. h_entry_column (string)
83               6.33. state_column (string)
84               6.34. start_time_column (string)
85               6.35. timeout_column (string)
86               6.36. sflags_column (string)
87               6.37. toroute_name_column (string)
88               6.38. vars_table_name (string)
89               6.39. vars_h_id_column (string)
90               6.40. vars_h_entry_column (string)
91               6.41. vars_key_column (string)
92               6.42. vars_value_column (string)
93               6.43. profiles_with_value (string)
94               6.44. profiles_no_value (string)
95               6.45. bridge_controller (string)
96               6.46. bridge_contact (string)
97               6.47. initial_cbs_inscript (int)
98               6.48. send_bye (int)
99               6.49. wait_ack (int)
100               6.50. ka_timer (int)
101               6.51. ka_interval (int)
102               6.52. ka_failed_limit (int)
103               6.53. timeout_noreset (int)
104               6.54. timer_procs (int)
105               6.55. enable_dmq (int)
106               6.56. track_cseq_updates (int)
107               6.57. lreq_callee_headers (string)
108               6.58. event_callback (str)
109
110         7. Functions
111
112               7.1. set_dlg_profile(profile,[value])
113               7.2. unset_dlg_profile(profile,[value])
114               7.3. is_in_profile(profile,[value])
115               7.4. get_profile_size(profile,[value],size)
116               7.5. dlg_isflagset(flag)
117               7.6. dlg_setflag(flag)
118               7.7. dlg_resetflag(flag)
119               7.8. dlg_bye(side)
120               7.9. dlg_refer(side, address)
121               7.10. dlg_manage()
122               7.11. dlg_bridge(from, to, op)
123               7.12. dlg_get(callid, ftag, ttag)
124               7.13. is_known_dlg()
125               7.14. dlg_set_timeout(timeout [, h_entry, h_id])
126               7.15. dlg_set_timeout_by_profile(profile, [value], timeout)
127               7.16. dlg_set_property(attr)
128               7.17. dlg_remote_profile(cmd, profile, value, uid, expires)
129
130         8. Statistics
131
132               8.1. active_dialogs
133               8.2. early_dialogs
134               8.3. processed_dialogs
135               8.4. expired_dialogs
136               8.5. failed_dialogs
137
138         9. RPC Commands
139
140               9.1. dlg.list
141               9.2. dlg.list_ctx
142               9.3. dlg.dlg_list
143               9.4. dlg.dlg_list_ctx
144               9.5. dlg.terminate_dlg
145               9.6. dlg.end_dlg
146               9.7. dlg.profile_get_size
147               9.8. dlg.profile_list
148               9.9. dlg.bridge_dlg
149
150         10. Exported Variables
151
152               10.1. $DLG_count
153               10.2. $DLG_status
154               10.3. $DLG_lifetime
155               10.4. $dlg(...)
156               10.5. $dlg_ctx(...)
157               10.6. $dlg_var(key)
158
159         11. Event Routes
160
161               11.1. event_route[dialog:start]
162               11.2. event_route[dialog:end]
163               11.3. event_route[dialog:failed]
164
165    2. Developer Guide
166
167         1. Available Functions
168
169               1.1. register_dlgcb (dialog, type, cb, param, free_param_cb)
170
171               1.2. terminate_dlg (dlg, hdrs)
172
173    3. Frequently Asked Questions
174
175    List of Examples
176
177    1.1. Set enable_stats parameter
178    1.2. Set hash_size parameter
179    1.3. Set rr_param parameter
180    1.4. Set dlg_flag parameter
181    1.5. Set timeout_avp parameter
182    1.6. Set default_timeout parameter
183    1.7. Set early_timeout parameter
184    1.8. Set noack_timeout parameter
185    1.9. Set dlf_extra_hdrs parameter
186    1.10. Set dlg_match_mode parameter
187    1.11. Set detect_spirals parameter
188    1.12. Set db_url parameter
189    1.13. Set db_mode parameter
190    1.14. Set db_update_period parameter
191    1.15. Set db_fetch_rows parameter
192    1.16. Set db_skip_load parameter
193    1.17. Set table_name parameter
194    1.18. Set call_id_column parameter
195    1.19. Set from_uri_column parameter
196    1.20. Set from_tag_column parameter
197    1.21. Set to_uri_column parameter
198    1.22. Set to_tag_column parameter
199    1.23. Set from_cseq_column parameter
200    1.24. Set to_cseq_column parameter
201    1.25. Set from_route_column parameter
202    1.26. Set to_route_column parameter
203    1.27. Set from_contact_column parameter
204    1.28. Set to_contact_column parameter
205    1.29. Set from_sock_column parameter
206    1.30. Set to_sock_column parameter
207    1.31. Set h_id_column parameter
208    1.32. Set h_entry_column parameter
209    1.33. Set state_column parameter
210    1.34. Set start_time_column parameter
211    1.35. Set timeout_column parameter
212    1.36. Set sflags_column parameter
213    1.37. Set toroute_name_column parameter
214    1.38. Set vars_table_name parameter
215    1.39. Set vars_h_id_column parameter
216    1.40. Set vars_h_entry_column parameter
217    1.41. Set vars_key_column parameter
218    1.42. Set vars_value_column parameter
219    1.43. Set profiles_with_value parameter
220    1.44. Set profiles_no_value parameter
221    1.45. Set bridge_controller parameter
222    1.46. Set bridge_contact parameter
223    1.47. Set initial_cbs_inscript parameter
224    1.48. Set send_bye parameter
225    1.49. Set wait_ack parameter
226    1.50. Set ka_timer parameter
227    1.51. Set ka_interval parameter
228    1.52. Set ka_failed_limit parameter
229    1.53. Set timeout_noreset parameter
230    1.54. Set timer_procs parameter
231    1.55. Set enable_dmq parameter
232    1.56. Set track_cseq_updates parameter
233    1.57. Set lreq_callee_headers parameter
234    1.58. Set event_callback parameter
235    1.59. set_dlg_profile usage
236    1.60. unset_dlg_profile usage
237    1.61. is_in_profile usage
238    1.62. get_profile_size usage
239    1.63. dlg_isflagset usage
240    1.64. dlg_setflag usage
241    1.65. dlg_resetflag usage
242    1.66. dlg_bye usage
243    1.67. dlg_refer usage
244    1.68. dlg_manage usage
245    1.69. dlg_bridge usage
246    1.70. dlg_get usage
247    1.71. is_known_dlg() usage
248    1.72. dlg_set_timeout usage
249    1.73. dlg_set_timeout_by_profile usage
250    1.74. dlg_set_property usage
251    1.75. dlg_remote_profile usage
252
253 Chapter 1. Admin Guide
254
255    Table of Contents
256
257    1. Overview
258    2. How it works
259    3. Dialog states
260    4. Dialog profiling
261    5. Dependencies
262
263         5.1. Kamailio Modules
264         5.2. External Libraries or Applications
265
266    6. Parameters
267
268         6.1. enable_stats (integer)
269         6.2. hash_size (integer)
270         6.3. rr_param (string)
271         6.4. dlg_flag (integer)
272         6.5. timeout_avp (string)
273         6.6. default_timeout (integer)
274         6.7. early_timeout (integer)
275         6.8. noack_timeout (integer)
276         6.9. dlg_extra_hdrs (string)
277         6.10. dlg_match_mode (integer)
278         6.11. detect_spirals (integer)
279         6.12. db_url (string)
280         6.13. db_mode (integer)
281         6.14. db_update_period (integer)
282         6.15. db_fetch_rows (integer)
283         6.16. db_skip_load (integer)
284         6.17. table_name (string)
285         6.18. call_id_column (string)
286         6.19. from_uri_column (string)
287         6.20. from_tag_column (string)
288         6.21. to_uri_column (string)
289         6.22. to_tag_column (string)
290         6.23. from_cseq_column (string)
291         6.24. to_cseq_column (string)
292         6.25. from_route_column (string)
293         6.26. to_route_column (string)
294         6.27. from_contact_column (string)
295         6.28. to_contact_column (string)
296         6.29. from_sock_column (string)
297         6.30. to_sock_column (string)
298         6.31. h_id_column (string)
299         6.32. h_entry_column (string)
300         6.33. state_column (string)
301         6.34. start_time_column (string)
302         6.35. timeout_column (string)
303         6.36. sflags_column (string)
304         6.37. toroute_name_column (string)
305         6.38. vars_table_name (string)
306         6.39. vars_h_id_column (string)
307         6.40. vars_h_entry_column (string)
308         6.41. vars_key_column (string)
309         6.42. vars_value_column (string)
310         6.43. profiles_with_value (string)
311         6.44. profiles_no_value (string)
312         6.45. bridge_controller (string)
313         6.46. bridge_contact (string)
314         6.47. initial_cbs_inscript (int)
315         6.48. send_bye (int)
316         6.49. wait_ack (int)
317         6.50. ka_timer (int)
318         6.51. ka_interval (int)
319         6.52. ka_failed_limit (int)
320         6.53. timeout_noreset (int)
321         6.54. timer_procs (int)
322         6.55. enable_dmq (int)
323         6.56. track_cseq_updates (int)
324         6.57. lreq_callee_headers (string)
325         6.58. event_callback (str)
326
327    7. Functions
328
329         7.1. set_dlg_profile(profile,[value])
330         7.2. unset_dlg_profile(profile,[value])
331         7.3. is_in_profile(profile,[value])
332         7.4. get_profile_size(profile,[value],size)
333         7.5. dlg_isflagset(flag)
334         7.6. dlg_setflag(flag)
335         7.7. dlg_resetflag(flag)
336         7.8. dlg_bye(side)
337         7.9. dlg_refer(side, address)
338         7.10. dlg_manage()
339         7.11. dlg_bridge(from, to, op)
340         7.12. dlg_get(callid, ftag, ttag)
341         7.13. is_known_dlg()
342         7.14. dlg_set_timeout(timeout [, h_entry, h_id])
343         7.15. dlg_set_timeout_by_profile(profile, [value], timeout)
344         7.16. dlg_set_property(attr)
345         7.17. dlg_remote_profile(cmd, profile, value, uid, expires)
346
347    8. Statistics
348
349         8.1. active_dialogs
350         8.2. early_dialogs
351         8.3. processed_dialogs
352         8.4. expired_dialogs
353         8.5. failed_dialogs
354
355    9. RPC Commands
356
357         9.1. dlg.list
358         9.2. dlg.list_ctx
359         9.3. dlg.dlg_list
360         9.4. dlg.dlg_list_ctx
361         9.5. dlg.terminate_dlg
362         9.6. dlg.end_dlg
363         9.7. dlg.profile_get_size
364         9.8. dlg.profile_list
365         9.9. dlg.bridge_dlg
366
367    10. Exported Variables
368
369         10.1. $DLG_count
370         10.2. $DLG_status
371         10.3. $DLG_lifetime
372         10.4. $dlg(...)
373         10.5. $dlg_ctx(...)
374         10.6. $dlg_var(key)
375
376    11. Event Routes
377
378         11.1. event_route[dialog:start]
379         11.2. event_route[dialog:end]
380         11.3. event_route[dialog:failed]
381
382 1. Overview
383
384    Kamailio can behave as a stateful proxy through the TM module. However,
385    "stateful" in this context refers to transaction state, not dialog
386    state. Certain applications may benefit from an awareness of "calls" in
387    the proxy, not just SIP transactions.
388
389    For example, a common need is to limit the number of calls that can be
390    made concurrently by an endpoint, account, user group, etc. In order to
391    count the number of calls in progress, it is necessary for the proxy to
392    be aware of whole dialogs, not just transactions, and to provide some
393    means of programmatically classifying these dialogs. This is just one
394    common application discussed for illustrative purposes; there are many
395    others.
396
397    The dialog module provides dialog awareness for the Kamailio proxy.
398    It's functionality is to keep track of the current dialogs, to offer
399    information about them (e.g. how many dialogs are active), and to
400    manage various characteristics of dialogs. The module exports several
401    functions that can be used directly from the configuration route script
402    as well as functions for the RPC interface.
403
404    This module also provides a API foundation on which to build more
405    complex dialog-oriented functionality in other Kamailio modules.
406
407 2. How it works
408
409    To create the dialog associated with an initial request, the flag
410    “dlg_flag” (Section 6.4, “dlg_flag (integer)”) must be set before
411    creating the corresponding transaction.
412
413    The dialog is automatically destroyed when a “BYE” is received. In case
414    of no “BYE”, the dialog lifetime is controlled via the default timeout
415    (see “default_timeout” - Section 6.6, “default_timeout (integer)”) and
416    custom timeout (see “timeout_avp” - Section 6.5, “timeout_avp
417    (string)”). The dialog timeout is reset each time a sequential request
418    is processed.
419
420 3. Dialog states
421
422    Dialogs have states that are shown in the RPC interface as well as
423    stored in the database.
424      * 1 : Unconfirmed dialog
425      * 2 : Early dialog (ringing)
426      * 3 : Confirmed dialog (waiting for ACK)
427      * 4 : Confirmed dialog (active call)
428      * 5 : Deleted dialog
429
430    The early and deleted dialog states are not updated in database
431    storage.
432
433 4. Dialog profiling
434
435    Dialog profiling is a mechanism that helps in classifying, sorting and
436    keeping track of certain types of dialogs. The classification criteria
437    can be any attributes desired by the administrator; it can be SIP
438    message attributes, other pseudo-variables, custom values, etc. Dialogs
439    can be dynamically added into one or more profile tables. Logically,
440    each profile table can have a special meaning (like dialogs outside the
441    domain, dialogs terminated to the PSTN, etc.).
442
443    There are two types of profiles:
444      * with no value - a dialog simply belongs to a profile (for instance,
445        an outbound calls profile). There is no other additional
446        information to describe the dialog beyond its membership in the
447        profile per se.
448      * with value - a dialog belongs to a profile having a certain value
449        (like in a caller profile, where the value is the caller ID). The
450        membership of the dialog in the profile is strictly related to the
451        value. For example, if the account ID of the caller is stored in
452        the pseudo-variable $var(account_id), you can use $var(account_id)
453        as a value/key by which to group dialogs so that you can count the
454        number of open dialogs for each account, enforce concurrent call
455        limits as necessary, etc.
456
457    A dialog can be added to multiple profiles at the same time.
458
459    Profiles are visible (at the moment) in the request route (for initial
460    and sequential requests) and in the branch, failure and reply routes of
461    the original request.
462
463 5. Dependencies
464
465    5.1. Kamailio Modules
466    5.2. External Libraries or Applications
467
468 5.1. Kamailio Modules
469
470    The following modules must be loaded before this module:
471      * TM - Transaction module
472      * RR - Record-Route module
473      * PV - Pseudovariables module
474
475 5.2. External Libraries or Applications
476
477    The following libraries or applications must be installed before
478    running Kamailio with this module loaded:
479      * None.
480
481 6. Parameters
482
483    6.1. enable_stats (integer)
484    6.2. hash_size (integer)
485    6.3. rr_param (string)
486    6.4. dlg_flag (integer)
487    6.5. timeout_avp (string)
488    6.6. default_timeout (integer)
489    6.7. early_timeout (integer)
490    6.8. noack_timeout (integer)
491    6.9. dlg_extra_hdrs (string)
492    6.10. dlg_match_mode (integer)
493    6.11. detect_spirals (integer)
494    6.12. db_url (string)
495    6.13. db_mode (integer)
496    6.14. db_update_period (integer)
497    6.15. db_fetch_rows (integer)
498    6.16. db_skip_load (integer)
499    6.17. table_name (string)
500    6.18. call_id_column (string)
501    6.19. from_uri_column (string)
502    6.20. from_tag_column (string)
503    6.21. to_uri_column (string)
504    6.22. to_tag_column (string)
505    6.23. from_cseq_column (string)
506    6.24. to_cseq_column (string)
507    6.25. from_route_column (string)
508    6.26. to_route_column (string)
509    6.27. from_contact_column (string)
510    6.28. to_contact_column (string)
511    6.29. from_sock_column (string)
512    6.30. to_sock_column (string)
513    6.31. h_id_column (string)
514    6.32. h_entry_column (string)
515    6.33. state_column (string)
516    6.34. start_time_column (string)
517    6.35. timeout_column (string)
518    6.36. sflags_column (string)
519    6.37. toroute_name_column (string)
520    6.38. vars_table_name (string)
521    6.39. vars_h_id_column (string)
522    6.40. vars_h_entry_column (string)
523    6.41. vars_key_column (string)
524    6.42. vars_value_column (string)
525    6.43. profiles_with_value (string)
526    6.44. profiles_no_value (string)
527    6.45. bridge_controller (string)
528    6.46. bridge_contact (string)
529    6.47. initial_cbs_inscript (int)
530    6.48. send_bye (int)
531    6.49. wait_ack (int)
532    6.50. ka_timer (int)
533    6.51. ka_interval (int)
534    6.52. ka_failed_limit (int)
535    6.53. timeout_noreset (int)
536    6.54. timer_procs (int)
537    6.55. enable_dmq (int)
538    6.56. track_cseq_updates (int)
539    6.57. lreq_callee_headers (string)
540    6.58. event_callback (str)
541
542 6.1. enable_stats (integer)
543
544    If statistics support should be enabled or not. Via statistics
545    variables, the module provide information about the dialog processing.
546    Set it to zero to disable or to non-zero to enable it.
547
548    Default value is “1 (enabled)”.
549
550    Example 1.1. Set enable_stats parameter
551 ...
552 modparam("dialog", "enable_stats", 0)
553 ...
554
555 6.2. hash_size (integer)
556
557    The size of the hash table internally used to keep the dialogs. A
558    larger table is much faster but consumes more memory. The hash size
559    must be a power of two.
560
561    IMPORTANT: If dialog information should be stored in a database, a
562    constant hash_size should be used, otherwise the restoring process will
563    not take place. If you really want to modify the hash_size, you must
564    delete all table's rows before restarting the server.
565
566    Default value is “4096”.
567
568    Example 1.2. Set hash_size parameter
569 ...
570 modparam("dialog", "hash_size", 1024)
571 ...
572
573 6.3. rr_param (string)
574
575    Name of the Record-Route parameter used to store the dialog cookie. It
576    is used for the fast matching of sequential requests to tracked
577    dialogs.
578
579    Default value is “did”.
580
581    Example 1.3. Set rr_param parameter
582 ...
583 modparam("dialog", "rr_param", "xyz")
584 ...
585
586 6.4. dlg_flag (integer)
587
588    Flag to be used for marking if a dialog should be constructed for the
589    current request (this make sense only for initial requests).
590
591    Default value is “none”.
592
593    Example 1.4. Set dlg_flag parameter
594 ...
595 modparam("dialog", "dlg_flag", 4)
596 ...
597
598 6.5. timeout_avp (string)
599
600    The specification of an AVP that contains a custom timeout value (in
601    seconds) for the dialog. It may be used only in a request (initial or
602    sequential) context.
603
604    Default value is “none”.
605
606    Example 1.5. Set timeout_avp parameter
607 ...
608 modparam("dialog", "timeout_avp", "$avp(i:10)")
609 ...
610
611 6.6. default_timeout (integer)
612
613    The default dialog timeout (in seconds), in the absence of a custom
614    value provided in an AVP.
615
616    Default value is “43200 (12 hours)”.
617
618    Example 1.6. Set default_timeout parameter
619 ...
620 modparam("dialog", "default_timeout", 21600)
621 ...
622
623 6.7. early_timeout (integer)
624
625    The timeout (in seconds) after which the dialogs in early state (no
626    final response received) are destroyed.
627
628    Default value is “300 (5 minutes)”.
629
630    Example 1.7. Set early_timeout parameter
631 ...
632 modparam("dialog", "early_timeout", 180)
633 ...
634
635 6.8. noack_timeout (integer)
636
637    The timeout (in seconds) after which the dialogs which were answered
638    with 200ok but didn't receive the ACK are marked for termination (the
639    lifetime is set to 10 more seconds).
640
641    Default value is “60 (1 minute)”.
642
643    Example 1.8. Set noack_timeout parameter
644 ...
645 modparam("dialog", "noack_timeout", 90)
646 ...
647
648 6.9. dlg_extra_hdrs (string)
649
650    A string containing the extra headers (full format, with EOH) to be
651    added to requests generated locally by the module (like BYEs).
652
653    Default value is “NULL”.
654
655    Example 1.9. Set dlf_extra_hdrs parameter
656 ...
657 modparam("dialog", "dlg_extra_hdrs", "Hint: credit expired\r\n")
658 ...
659
660 6.10. dlg_match_mode (integer)
661
662    How the sequential requests should be matched against the known
663    dialogs. The modes are a combination of matching based on a cookie
664    (DID) stored as cookie in Record-Route header and matching based on SIP
665    elements (as in RFC 3261).
666
667    Note: DID-based matching does not replace callid/fromtag/totag
668    comparison. It will speed up dialog matching by not iterating over the
669    whole dialog list for callid/fromtag/totag comparison, but instead it
670    uses a hash table to find the respective dialog and then doing only one
671    callid/fromtag/totag comparison. Thus, there is no security issue when
672    using DID based matching. Use DID_FALLBACK for maximum interoperability
673    or use DID_ONLY to reject buggy clients or hacking attempts. DID_NONE
674    is only useful, when you want to hide dialog-tracking from the users
675    (preventing the DID Record-Route cookie).
676
677    The supported modes are:
678      * 0 - DID_ONLY - the match is done exclusively based on DID;
679      * 1 - DID_FALLBACK - the match is first tried based on DID and if not
680        present, it will fall back to SIP matching;
681      * 2 - DID_NONE - the match is done exclusively based on SIP elements;
682        no DID information is added in RR.
683
684    Default value is “0 (DID_ONLY)”.
685
686    Example 1.10. Set dlg_match_mode parameter
687 ...
688 modparam("dialog", "dlg_match_mode", 1)
689 ...
690
691 6.11. detect_spirals (integer)
692
693    Whether spirals (i.e., messages routed through the proxy multiple
694    times) should be detected.
695
696    If set to 0, spirals will not be detected and result in the generation
697    of a new, possibly dangling dialog structure per occurring spiral. If
698    set to 1, spirals are detected and internally mapped to existing dialog
699    structures.
700
701    Default value is 1.
702
703    Example 1.11. Set detect_spirals parameter
704 ...
705 modparam("dialog", "detect_spirals", 1)
706 ...
707
708 6.12. db_url (string)
709
710    In order to store information about dialogs in a database, a database
711    URL must be specified.
712
713    Default value is “mysql://kamailio:kamailiorw@localhost/kamailio”.
714
715    Example 1.12. Set db_url parameter
716 ...
717 modparam("dialog", "db_url", "dbdriver://username:password@dbhost/dbname")
718 ...
719
720 6.13. db_mode (integer)
721
722    Mode of synchronisation of dialog information from memory to an
723    underlying database (if desired):
724
725    The supported modes are:
726      * 0 - NO_DB - the memory content is not flushed into DB;
727      * 1 - REALTIME - any dialog information changes will be reflected
728        into the database immediately.
729      * 2 - DELAYED - the dialog information changes will be flushed into
730        DB periodically, based on a timer routine.
731      * 3 - SHUTDOWN - the dialog information will be flushed into DB only
732        at shutdown - no runtime updates.
733
734    Default value is “0”.
735
736    Example 1.13. Set db_mode parameter
737 ...
738 modparam("dialog", "db_mode", 1)
739 ...
740
741 6.14. db_update_period (integer)
742
743    The interval (seconds) at which to update dialogs' information, if the
744    server is configured to store the dialog information at a given
745    interval. Too short an interval will generate intensive database
746    operations, while an excessively long one will miss dialogs with a
747    short lifetime.
748
749    Default value is “60” seconds.
750
751    Example 1.14. Set db_update_period parameter
752 ...
753 modparam("dialog", "db_update_period", 120)
754 ...
755
756 6.15. db_fetch_rows (integer)
757
758    The number of the rows to be fetched at once from database when loading
759    the dialog records at startup from the database. This value can be used
760    to tune the load time at startup. For 1MB of private memory (default),
761    it should be below 400. The database driver must support the
762    fetch_result() capability. A value of 0 means the database fetch is not
763    limited.
764
765    Default value is “200”.
766
767    Example 1.15. Set db_fetch_rows parameter
768 ...
769 modparam("dialog", "db_fetch_rows", 500)
770 ...
771
772 6.16. db_skip_load (integer)
773
774    Set db_skip_load to 1, to skip the loading of dialog data from the
775    database.
776
777    Default value is “0” ( not skipped ).
778
779    Example 1.16. Set db_skip_load parameter
780 ...
781 modparam("dialog", "db_skip_load", 1)
782 ...
783
784 6.17. table_name (string)
785
786    Database table name used for storing dialog information.
787
788    Default value is “dialog”.
789
790    Example 1.17. Set table_name parameter
791 ...
792 modparam("dialog", "table_name", "my_dialog")
793 ...
794
795 6.18. call_id_column (string)
796
797    The column name in the database to store the dialog call-id.
798
799    Default value is “callid”.
800
801    Example 1.18. Set call_id_column parameter
802 ...
803 modparam("dialog", "call_id_column", "callid_c_name")
804 ...
805
806 6.19. from_uri_column (string)
807
808    The column name in the database to store the caller's SIP address
809    (URI).
810
811    Default value is “from_uri”.
812
813    Example 1.19. Set from_uri_column parameter
814 ...
815 modparam("dialog", "from_uri_column", "from_uri_c_name")
816 ...
817
818 6.20. from_tag_column (string)
819
820    The column name in the database to store the From header tag from the
821    INVITE request.
822
823    Default value is “from_tag”.
824
825    Example 1.20. Set from_tag_column parameter
826 ...
827 modparam("dialog", "from_tag_column", "from_tag_c_name")
828 ...
829
830 6.21. to_uri_column (string)
831
832    The column name in the database to store the callee's SIP address
833    (URI).
834
835    Default value is “to_uri”.
836
837    Example 1.21. Set to_uri_column parameter
838 ...
839 modparam("dialog", "to_uri_column", "to_uri_c_name")
840 ...
841
842 6.22. to_tag_column (string)
843
844    The column name in the database to store the To header tag from the 200
845    OK response to the INVITE request, if present.
846
847    Default value is “to_tag”.
848
849    Example 1.22. Set to_tag_column parameter
850 ...
851 modparam("dialog", "to_tag_column", "to_tag_c_name")
852 ...
853
854 6.23. from_cseq_column (string)
855
856    The column name in the database to store the Cseq from caller side.
857
858    Default value is “caller_cseq”.
859
860    Example 1.23. Set from_cseq_column parameter
861 ...
862 modparam("dialog", "from_cseq_column", "from_cseq")
863 ...
864
865 6.24. to_cseq_column (string)
866
867    The column name in the database to store the cseq from callee side.
868
869    Default value is “callee_cseq”.
870
871    Example 1.24. Set to_cseq_column parameter
872 ...
873 modparam("dialog", "to_cseq_column", "to_cseq")
874 ...
875
876 6.25. from_route_column (string)
877
878    The column name in the database to store the route records from caller
879    side (proxy to caller).
880
881    Default value is “caller_route_set”.
882
883    Example 1.25. Set from_route_column parameter
884 ...
885 modparam("dialog", "from_route_column", "rroute_from")
886 ...
887
888 6.26. to_route_column (string)
889
890    The column name in the database to store the route records from callee
891    side (proxy to callee).
892
893    Default value is “callee_route_set”.
894
895    Example 1.26. Set to_route_column parameter
896 ...
897 modparam("dialog", "to_route_column", "rroute_to")
898 ...
899
900 6.27. from_contact_column (string)
901
902    The column name in the database to store the caller's contact uri.
903
904    Default value is “caller_contact”.
905
906    Example 1.27. Set from_contact_column parameter
907 ...
908 modparam("dialog", "from_contact_column", "from_contact_uri")
909 ...
910
911 6.28. to_contact_column (string)
912
913    The column name in the database to store the callee's contact uri.
914
915    Default value is “callee_contact”.
916
917    Example 1.28. Set to_contact_column parameter
918 ...
919 modparam("dialog", "to_contact_column", "to_contact_uri")
920 ...
921
922 6.29. from_sock_column (string)
923
924    The column name in the database to store the information about the
925    local interface receiving the traffic from caller.
926
927    Default value is “caller_sock”.
928
929    Example 1.29. Set from_sock_column parameter
930 ...
931 modparam("dialog", "from_sock_column", "socket_from")
932 ...
933
934 6.30. to_sock_column (string)
935
936    The column name in the database to store information about the local
937    interface receiving the traffic from callee.
938
939    Default value is “callee_sock”.
940
941    Example 1.30. Set to_sock_column parameter
942 ...
943 modparam("dialog", "to_sock_column", "socket_to")
944 ...
945
946 6.31. h_id_column (string)
947
948    The column name in the database to store the dialogs' hash id
949    information.
950
951    Default value is “hash_id”.
952
953    Example 1.31. Set h_id_column parameter
954 ...
955 modparam("dialog", "h_id_column", "hash_id_c_name")
956 ...
957
958 6.32. h_entry_column (string)
959
960    The column name in the database to store the dialog's hash entry
961    information.
962
963    Default value is “hash_entry”.
964
965    Example 1.32. Set h_entry_column parameter
966 ...
967 modparam("dialog", "h_entry_column", "h_entry_c_name")
968 ...
969
970 6.33. state_column (string)
971
972    The column name in the database to store the dialog's state
973    information.
974
975    Default value is “state”.
976
977    Example 1.33. Set state_column parameter
978 ...
979 modparam("dialog", "state_column", "state_c_name")
980 ...
981
982 6.34. start_time_column (string)
983
984    The column name in the database to store the dialog's start time
985    information.
986
987    Default value is “start_time”.
988
989    Example 1.34. Set start_time_column parameter
990 ...
991 modparam("dialog", "start_time_column", "start_time_c_name")
992 ...
993
994 6.35. timeout_column (string)
995
996    The column name in the database to store the dialog's timeout.
997
998    Default value is “timeout”.
999
1000    Example 1.35. Set timeout_column parameter
1001 ...
1002 modparam("dialog", "timeout_column", "timeout_c_name")
1003 ...
1004
1005 6.36. sflags_column (string)
1006
1007    The column name in the database to store the dialog script flags.
1008
1009    Default value is “sflags”.
1010
1011    Example 1.36. Set sflags_column parameter
1012 ...
1013 modparam("dialog", "sflags_column", "s_flags")
1014 ...
1015
1016 6.37. toroute_name_column (string)
1017
1018    The column name in the database to store the index of the route to be
1019    executed at timeout.
1020
1021    Default value is “toroute_name”.
1022
1023    Example 1.37. Set toroute_name_column parameter
1024 ...
1025 modparam("dialog", "toroute_name_column", "timeout_route")
1026 ...
1027
1028 6.38. vars_table_name (string)
1029
1030    If you want to store the dialog variables (“$dlg_var(name)”) for a
1031    dialog in a database a table name must be specified.
1032
1033    Default value is “dialog_vars”.
1034
1035    Example 1.38. Set vars_table_name parameter
1036 ...
1037 modparam("dialog", "vars_table_name", "my_dialog_vars")
1038 ...
1039
1040 6.39. vars_h_id_column (string)
1041
1042    The column name in the database to store the dialog's hash id
1043    information (as a reference to the dialog table).
1044
1045    Default value is “hash_id”.
1046
1047    Example 1.39. Set vars_h_id_column parameter
1048 ...
1049 modparam("dialog", "vars_h_id_column", "vars_h_id_name")
1050 ...
1051
1052 6.40. vars_h_entry_column (string)
1053
1054    The column name in the database to store the dialog's hash entry
1055    information (as a reference to the dialog table).
1056
1057    Default value is “hash_entry”.
1058
1059    Example 1.40. Set vars_h_entry_column parameter
1060 ...
1061 modparam("dialog", "vars_h_entry_column", "vars_h_entry_name")
1062 ...
1063
1064 6.41. vars_key_column (string)
1065
1066    The column name in the database to store the names (keys) of a dialog
1067    variable.
1068
1069    Default value is “dialog_key”.
1070
1071    Example 1.41. Set vars_key_column parameter
1072 ...
1073 modparam("dialog", "vars_key_column", "vars_key_name")
1074 ...
1075
1076 6.42. vars_value_column (string)
1077
1078    The column name in the database to store the values of a dialog
1079    variable.
1080
1081    Default value is “dialog_value”.
1082
1083    Example 1.42. Set vars_value_column parameter
1084 ...
1085 modparam("dialog", "vars_value_column", "vars_value_name")
1086 ...
1087
1088 6.43. profiles_with_value (string)
1089
1090    List of names for profiles with values, separated with semi-colon ";".
1091
1092    Default value is “empty”.
1093
1094    Example 1.43. Set profiles_with_value parameter
1095 ...
1096 modparam("dialog", "profiles_with_value", "caller ; my_profile")
1097 ...
1098
1099 6.44. profiles_no_value (string)
1100
1101    List of names for profiles without values, separated with semi-colon
1102    ";".
1103
1104    Default value is “empty”.
1105
1106    Example 1.44. Set profiles_no_value parameter
1107 ...
1108 modparam("dialog", "profiles_no_value", "inbound ; outbound")
1109 ...
1110
1111 6.45. bridge_controller (string)
1112
1113    SIP address to be used in From header when initiating a call bridge.
1114
1115    Default value is “sip:controller@kamailio.org”.
1116
1117    Example 1.45. Set bridge_controller parameter
1118 ...
1119 modparam("dialog", "bridge_controller", "sip:ctd@kamailio.org")
1120 ...
1121
1122 6.46. bridge_contact (string)
1123
1124    SIP address to be used in Contact header when doing a call bridge.
1125
1126    Default value is “sip:controller@kamailio.org:5060”.
1127
1128    Example 1.46. Set bridge_contact parameter
1129 ...
1130 modparam("dialog", "bridge_contact", "sip:ctd@127.0.0.1:5060")
1131 ...
1132
1133 6.47. initial_cbs_inscript (int)
1134
1135    If the initial dialog callbacks (i.e., DLGCB_CREATED and
1136    DLGCB_SPIRALED) should be executed in-script or post-script. If
1137    dlg_manage() is not used, the setting of this parameter does not
1138    matter; otherwise, initial callbacks will be executed directly after
1139    dlg_manage() is called if this parameter is enabled. If it is disabled,
1140    initial callback execution will be postponed until configuration script
1141    execution completes.
1142
1143    The supported values are:
1144      * 0 - POST-SCRIPT - execute initial callbacks after the script
1145        completes;
1146      * 1 - IN-SCRIPT - execute initial callbacks during script execution,
1147        i.e., right after dlg_manage() is called;
1148
1149    Default value is “1”.
1150
1151    Example 1.47. Set initial_cbs_inscript parameter
1152 ...
1153 modparam("dialog", "initial_cbs_inscript", 0)
1154 ...
1155
1156 6.48. send_bye (int)
1157
1158    If set to 1, BYE requests will be sent out for each dialog that timed
1159    out. It is an alternative to $dlg_ctx(timeout_bye)=1 for all dialogs.
1160
1161    Default value is “0”.
1162
1163    Example 1.48. Set send_bye parameter
1164 ...
1165 modparam("dialog", "send_bye", 1)
1166 ...
1167
1168 6.49. wait_ack (int)
1169
1170    If set to 1, dialog will be keept a bit longer in memory in order to
1171    absorb the ACK negative replies of initial INVITE. If not, the dialog
1172    is destroyed when negative reply is sent out (less internal
1173    complexity).
1174
1175    Default value is “1”.
1176
1177    Example 1.49. Set wait_ack parameter
1178 ...
1179 modparam("dialog", "wait_ack", 0)
1180 ...
1181
1182 6.50. ka_timer (int)
1183
1184    Keep-alive timer step - how often to execute the callback to send
1185    dialog keep alives (SIP OPTIONS requests within dialog). The value
1186    represents the number of seconds.
1187
1188    Default value is “0” (no keep alive).
1189
1190    Example 1.50. Set ka_timer parameter
1191 ...
1192 modparam("dialog", "ka_timer", 10)
1193 ...
1194
1195 6.51. ka_interval (int)
1196
1197    The interval between keep alives within dialog (SIP OPTIONS requests),
1198    sent to caller or callee. The keep alive request will be sent by the
1199    first callback fired by KA timer after the ka_interval elapsed from
1200    dialog setup or previous keep-alive. The value represents the number of
1201    seconds.
1202
1203    If the requests times out (generating a 408) or if the UA responds with
1204    481 the lifetime is set to 10 seconds. When lifetime expires the dialog
1205    will be terminated. Any other response (including error responses) will
1206    reset the timers.
1207
1208    Default value is “0” (no keep alive). The lowest settable interval is
1209    30 seconds.
1210
1211    Example 1.51. Set ka_interval parameter
1212 ...
1213 modparam("dialog", "ka_interval", 300)
1214 ...
1215
1216 6.52. ka_failed_limit (int)
1217
1218    The number of failed keep-alive requests that is accepted before
1219    generating a dialog timeout.
1220
1221    Default value is “1”.
1222
1223    Example 1.52. Set ka_failed_limit parameter
1224 ...
1225 modparam("dialog", "ka_failed_limit", 5)
1226 ...
1227
1228 6.53. timeout_noreset (int)
1229
1230    If set to 1, the dialog timeout won't be reset each time a sequential
1231    request is processed. It is an alternative to
1232    dlg_set_property("timeout-noreset") for all dialogs.
1233
1234    Default value is “0”.
1235
1236    Example 1.53. Set timeout_noreset parameter
1237 ...
1238 modparam("dialog", "timeout_noreset", 1)
1239 ...
1240
1241 6.54. timer_procs (int)
1242
1243    If set to 1, the dialog module will start a separate dialog timer
1244    process to execute dialog timeout tasks. The default is to use the core
1245    timer process.
1246
1247    Default value is “0” (use core timer process).
1248
1249    Example 1.54. Set timer_procs parameter
1250 ...
1251 modparam("dialog", "timer_procs", 1)
1252 ...
1253
1254 6.55. enable_dmq (int)
1255
1256    If set to 1, the dialog will be synced via dmq. For now, only very
1257    basic dialog info is shared, just enough to have synced profiles.
1258    Notably, it is not possible to send in-dialog requests on any but the
1259    original proxy instance.
1260
1261    Default value is “0”.
1262
1263    Example 1.55. Set enable_dmq parameter
1264 ...
1265 modparam("dialog", "enable_dmq", 1)
1266 ...
1267
1268 6.56. track_cseq_updates (int)
1269
1270    Enable the callbacks for tracking if CSeq number needs to be updated.
1271    It is the case when the INVITE has to be authenticated to downstream
1272    provider using uac_auth() from uac module.
1273
1274    This is done only for requests in downstream direction. The CSeq
1275    difference is stored in $dlg_var(cseq_diff), be sure this variable is
1276    not overwritten via config operation.
1277
1278    Default value is “0” (disabled).
1279
1280    Example 1.56. Set track_cseq_updates parameter
1281 ...
1282 modparam("dialog", "track_cseq_updates", 1)
1283 ...
1284
1285 6.57. lreq_callee_headers (string)
1286
1287    SIP headers to be added when sending local generated requests (e.g.,
1288    BYE) to callee. It can be useful when you use topoh module with call-id
1289    masking (see the docs of topoh module).
1290
1291    Default value is “null”.
1292
1293    Example 1.57. Set lreq_callee_headers parameter
1294 ...
1295 modparam("dialog", "lreq_callee_headers", "TH: dlh\r\n")
1296 ...
1297
1298 6.58. event_callback (str)
1299
1300    The name of the function in the kemi configuration file (embedded
1301    scripting language such as Lua, Python, ...) to be executed instead of
1302    event_route[...] blocks.
1303
1304    The function receives a string parameter with the name of the event,
1305    the values are: 'dialog:start', 'dialog:end', 'dialog:failed'. It is
1306    also executed if '$dlg_ctx(timeout_route)' is set, the callback
1307    function being executed with the variable value as parameter.
1308
1309    Default value is 'empty' (no function is executed for events).
1310
1311    Example 1.58. Set event_callback parameter
1312 ...
1313 modparam("dialog", "event_callback", "ksr_dialog_event")
1314 ...
1315 -- event callback function implemented in Lua
1316 function ksr_dialog_event(evname)
1317         KSR.info("===== dialog module triggered event: " .. evname .. "\n");
1318         return 1;
1319 end
1320 ...
1321
1322 7. Functions
1323
1324    7.1. set_dlg_profile(profile,[value])
1325    7.2. unset_dlg_profile(profile,[value])
1326    7.3. is_in_profile(profile,[value])
1327    7.4. get_profile_size(profile,[value],size)
1328    7.5. dlg_isflagset(flag)
1329    7.6. dlg_setflag(flag)
1330    7.7. dlg_resetflag(flag)
1331    7.8. dlg_bye(side)
1332    7.9. dlg_refer(side, address)
1333    7.10. dlg_manage()
1334    7.11. dlg_bridge(from, to, op)
1335    7.12. dlg_get(callid, ftag, ttag)
1336    7.13. is_known_dlg()
1337    7.14. dlg_set_timeout(timeout [, h_entry, h_id])
1338    7.15. dlg_set_timeout_by_profile(profile, [value], timeout)
1339    7.16. dlg_set_property(attr)
1340    7.17. dlg_remote_profile(cmd, profile, value, uid, expires)
1341
1342 7.1.  set_dlg_profile(profile,[value])
1343
1344    Inserts the current dialog into a profile. Note that if the profile
1345    does not support values, they will be silently discarded. Also, there
1346    is no check for inserting the same dialog into the same profile
1347    multiple times.
1348
1349    Meaning of the parameters is as follows:
1350      * profile - name of the profile to be added to;
1351      * value (optional) - string value to define the membership of the
1352        dialog in the profile. Note that the profile must support values.
1353        Pseudo-variables are supported.
1354
1355    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, REPLY_ROUTE
1356    and FAILURE_ROUTE.
1357
1358    Example 1.59. set_dlg_profile usage
1359 ...
1360 set_dlg_profile("inbound_call");
1361 set_dlg_profile("caller","$fu");
1362 ...
1363
1364 7.2.  unset_dlg_profile(profile,[value])
1365
1366    Removes the current dialog from a profile.
1367
1368    Meaning of the parameters is as follows:
1369      * profile - name of the profile to be removed from;
1370      * value (optional) - string value to define the belonging of the
1371        dialog to the profile - note that the profile must support values.
1372        Pseudo-variables are supported.
1373
1374    This function can be used from BRANCH_ROUTE, REPLY_ROUTE and
1375    FAILURE_ROUTE.
1376
1377    Example 1.60. unset_dlg_profile usage
1378 ...
1379 unset_dlg_profile("inbound_call");
1380 unset_dlg_profile("caller","$fu");
1381 ...
1382
1383 7.3.  is_in_profile(profile,[value])
1384
1385    Checks if the current dialog belongs to a profile. If the profile
1386    supports values, the check can be reinforced to take into account a
1387    specific value, if the dialog was inserted into the profile for a
1388    specific value. If no value is passed, only the membership of the
1389    dialog in the profile per se is checked. Note that if the profile does
1390    not support values, the value parameter will be silently discarded.
1391
1392    Meaning of the parameters is as follows:
1393      * profile - name of the profile to be checked against;
1394      * value (optional) - string value to further restrict the check.
1395        Pseudo-variables are supported.
1396
1397    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, REPLY_ROUTE
1398    and FAILURE_ROUTE.
1399
1400    Example 1.61. is_in_profile usage
1401 ...
1402 if (is_in_profile("inbound_call")) {
1403         log("this request belongs to a inbound call\n");
1404 }
1405 ...
1406 if (is_in_profile("caller","XX")) {
1407         log("this request belongs to a call of user XX\n");
1408 }
1409 ...
1410
1411 7.4.  get_profile_size(profile,[value],size)
1412
1413    Returns the number of dialogs belonging to a profile. If the profile
1414    supports values, the check can be reinforced to take into account a
1415    specific value, i.e. how many dialogs were inserted into the profile
1416    with a specific value. If no value is passed, only the membersip of the
1417    dialog in the profile per se is checked. Note that if the profile does
1418    not support values, the value parameter will be silently discarded.
1419
1420    Meaning of the parameters is as follows:
1421      * profile - name of the profile to get the size for;
1422      * value (optional) - string value to further restrict the check.
1423        Pseudo-variables are supported;
1424      * size - an AVP or script variable to return the profile size in.
1425
1426    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, REPLY_ROUTE
1427    and FAILURE_ROUTE.
1428
1429    Example 1.62. get_profile_size usage
1430 ...
1431 if(get_profile_size("inbound_call","$avp(size)"))
1432     xlog("currently there are $avp(size) inbound calls\n");
1433 ...
1434 if(get_profile_size("caller","$fu","$avp(size)"))
1435     xlog("currently, the user $fu has $avp(size) active outgoing calls\n");
1436 ...
1437
1438 7.5.  dlg_isflagset(flag)
1439
1440    Check if the dialog flag is set or not.
1441
1442    Meaning of the parameters is as follows:
1443      * flag - index of the flag - can be pseudo-variable.
1444
1445    This function can be used from BRANCH_ROUTE, REQUEST_ROUTE,
1446    ONREPLY_ROUTE and FAILURE_ROUTE.
1447
1448    Example 1.63. dlg_isflagset usage
1449 ...
1450 if(dlg_isflagset("1"))
1451 {
1452     ...
1453 }
1454 ...
1455
1456 7.6.  dlg_setflag(flag)
1457
1458    Set a dialog flag.
1459
1460    Meaning of the parameters is as follows:
1461      * flag - index of the flag - can be pseudo-variable.
1462
1463    This function can be used from BRANCH_ROUTE, REQUEST_ROUTE,
1464    ONREPLY_ROUTE and FAILURE_ROUTE.
1465
1466    Example 1.64. dlg_setflag usage
1467 ...
1468 dlg_setflag("1");
1469 ...
1470
1471 7.7.  dlg_resetflag(flag)
1472
1473    Reset the dialog flag.
1474
1475    Meaning of the parameters is as follows:
1476      * flag - index of the flag - can be pseudo-variable.
1477
1478    This function can be used from BRANCH_ROUTE, REQUEST_ROUTE,
1479    ONREPLY_ROUTE and FAILURE_ROUTE.
1480
1481    Example 1.65. dlg_resetflag usage
1482 ...
1483 redlg_setflag("1");
1484 ...
1485
1486 7.8.  dlg_bye(side)
1487
1488    Send BYE to both parties of a dialog.
1489
1490    Meaning of the parameters is as follows:
1491      * side - where to send the BYE. It can be: 'caller', 'callee', or
1492        'all' (send to both sides).
1493
1494    This function can be used from ANY_ROUTE.
1495
1496    Example 1.66. dlg_bye usage
1497 ...
1498 dlg_bye("all");
1499 ...
1500
1501 7.9.  dlg_refer(side, address)
1502
1503    Refer the 'side' to a new SIP 'address'.
1504
1505    Meaning of the parameters is as follows:
1506      * side - which side of the dialog to REFER. It can be: 'caller' or
1507        'callee'.
1508      * address - SIP address to refer to.
1509
1510    This function can be used from BRANCH_ROUTE, REQUEST_ROUTE,
1511    ONREPLY_ROUTE and FAILURE_ROUTE.
1512
1513    Example 1.67. dlg_refer usage
1514 ...
1515 dlg_refer("caller", "sip:announcement@kamailio.org");
1516 ...
1517
1518 7.10.  dlg_manage()
1519
1520    Process current SIP request with dialog module. It is an alternative to
1521    setting dialog flag for initial INVITE and Route-parameter-callback
1522    execution for within-dialog requests.
1523
1524    This function can be used from REQUEST_ROUTE.
1525
1526    Example 1.68. dlg_manage usage
1527 ...
1528 modparam("dialog", "default_timeout", 100)
1529 ...
1530 request_route {
1531 ...
1532     if(is_method("INVITE") && !has_totag())
1533     {
1534         $dlg_ctx(timeout_route) = "DLGTIMEOUT";
1535         $dlg_ctx(timeout_bye) = 1;
1536     }
1537     dlg_manage();
1538 ...
1539 }
1540 ...
1541
1542 7.11.  dlg_bridge(from, to, op)
1543
1544    Bridge 'from' SIP address to 'to' SIP address via outbound proxy 'op'.
1545
1546    Meaning of the parameters is as follows:
1547      * from - SIP address of first side to call.
1548      * to - SIP address to refer “from” to.
1549      * op - outbound proxy SIP address.
1550
1551    This function can be used from BRANCH_ROUTE, REQUEST_ROUTE,
1552    ONREPLY_ROUTE and FAILURE_ROUTE.
1553
1554    Example 1.69. dlg_bridge usage
1555 ...
1556 dlg_bridge("sip:user@kamailio.org", "sip:annoucement@kamailio.org",
1557    "sip:kamailio.org:5080");
1558 ...
1559
1560 7.12.  dlg_get(callid, ftag, ttag)
1561
1562    Search and set current dialog based on Call-ID, From-Tag and To-Tag
1563    parameters.
1564
1565    Meaning of the parameters is as follows:
1566      * callid - SIP call-id.
1567      * ftag - SIP From tag.
1568      * ttag - SIP To tag.
1569
1570    This function can be used from BRANCH_ROUTE, REQUEST_ROUTE,
1571    ONREPLY_ROUTE and FAILURE_ROUTE.
1572
1573    Example 1.70. dlg_get usage
1574 ...
1575 if(dlg_get("abcdef", "123", "456"))
1576 {
1577         dlg_bye("all");
1578 }
1579 ...
1580
1581 7.13.  is_known_dlg()
1582
1583    This function checks if the current SIP message being processed belongs
1584    to any transaction within an active dialog that the dialog module is
1585    currently tracking. This is a check for tracking of any kind, without
1586    regard to profiles.
1587
1588    This function has numerous potential applications, among which is that
1589    it can be used to strengthen security for loose-routing sequential
1590    (in-dialog) requests or responses to them, as by providing a
1591    preventative check against spoofing on the proxy level instead of
1592    leaving the issue purely to the receiving UA.
1593
1594    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, REPLY_ROUTE
1595    and FAILURE_ROUTE.
1596
1597    Example 1.71. is_known_dlg() usage
1598 ...
1599 if(!uri == myself) {
1600         if(is_known_dlg()) {
1601                 xlog("Request $rm from $ci is in-dialog\n");
1602         }
1603 }
1604 ...
1605
1606 7.14.  dlg_set_timeout(timeout [, h_entry, h_id])
1607
1608    Set the dialog timeout. Dialog timeout will be updated if it was
1609    already set. If h_entry and h_id parameters are not provided, the
1610    dialog will be searched based on (callid, fromtag, totag) of currently
1611    processed SIP message.
1612
1613    Meaning of the parameters is as follows:
1614      * timeout - the interval in seconds after which the dialog will time
1615        out.
1616      * h_entry - h_entry value of the iternal dialog identifier.
1617      * h_id - h_id valye if the internal dialog identifier.
1618
1619    This function can be used from ANY_ROUTE.
1620
1621    Example 1.72. dlg_set_timeout usage
1622 ...
1623 if(dlg_set_timeout("180", "123", "456"))
1624 {
1625     ...
1626 }
1627 ...
1628
1629 7.15.  dlg_set_timeout_by_profile(profile, [value], timeout)
1630
1631    Like dlg_set_timeout(), but simultaneously sets the timeout of all
1632    dialogs in a given profile. Can be constrained by profile value.
1633
1634    Meaning of the parameters is as follows:
1635      * profile - The dialog profile across which to apply the timeout.
1636        value (optional) - The profile value to use when applying the
1637        dialog timeout.
1638        timeout - the interval in seconds after which the dialog will time
1639        out.
1640
1641    This function can be used from ANY_ROUTE.
1642
1643    Example 1.73. dlg_set_timeout_by_profile usage
1644 ...
1645 # All dialogs belonging to user abc123 (tracked via set_dlg_profile())
1646 # will be timed out in 3 seconds.
1647
1648 dlg_set_timeout_by_profile("users", "abc123", "3");
1649 ...
1650
1651 7.16.  dlg_set_property(attr)
1652
1653    Set a dialog property - an attribute that enable/disable various
1654    behaviours (e.g., sending keep alive requests).
1655
1656    Meaning of the parameters is as follows:
1657      * attr - name of property. It can be:
1658           + 'ka-src' - send keep alive OPTION requests to caller
1659           + 'ka-dst' - send keep alive OPTION requests to callee
1660           + 'timeout-noreset' - don't reset timeout on in-dialog messages
1661             reception
1662
1663    If keep alive is enabled for a dialog, the module will send SIP OPTIONS
1664    requests with CSeq lower or equal than last request within dialog, with
1665    the scope of detecting if the destination is still in the call. If the
1666    keep alive request results in a local timeout or '481 Call
1667    Leg/Transaction Does Not Exist', then the dialog is ended from the
1668    server.
1669
1670    If 'timeout-noreset' is set, dialog timeout won't be reset upon
1671    reception of in-dialog messages (default behavior).
1672
1673    This function can be used from ANY_ROUTE.
1674
1675    Example 1.74. dlg_set_property usage
1676 ...
1677 dlg_set_property("ka-src");
1678 dlg_set_property("ka-dst");
1679 dlg_set_property("timeout-noreset");
1680 ...
1681
1682 7.17.  dlg_remote_profile(cmd, profile, value, uid, expires)
1683
1684    Manage remote profile via config file. A remote profile item is
1685    considered when the dialog is not managed by this server instance. The
1686    notification to add/remove can be received via SIP or a RPC command,
1687    the operation can be then triggered from configuration file. This
1688    should allow counting active dialogs in a profile that are managed by
1689    multiple SIP server instances.
1690
1691    Meaning of the parameters is as follows:
1692      * cmd - the operations to do: add - add an item in profile; rm -
1693        remove an item from profile
1694      * profile - name of profile
1695      * value - value for profile (if no value is needed for that profile,
1696        use an empty string.
1697      * expires - absolute time (unix timestamp) when this profile item
1698        should be removed automatically (time based), if still in the
1699        profile
1700
1701    This function can be used from ANY_ROUTE.
1702
1703    Example 1.75. dlg_remote_profile usage
1704 ...
1705 $var(exp) = 3600 + $Ts;
1706 dlg_remote_profile("add", "caller", "test", "$sruid", "$var(exp)");
1707 ...
1708
1709 8. Statistics
1710
1711    8.1. active_dialogs
1712    8.2. early_dialogs
1713    8.3. processed_dialogs
1714    8.4. expired_dialogs
1715    8.5. failed_dialogs
1716
1717 8.1. active_dialogs
1718
1719    Returns the number of current active dialogs (may be confirmed or not).
1720
1721 8.2. early_dialogs
1722
1723    Returns the number of early dialogs.
1724
1725 8.3. processed_dialogs
1726
1727    Returns the total number of processed dialogs (terminated, expired or
1728    active) from the startup.
1729
1730 8.4. expired_dialogs
1731
1732    Returns the total number of expired dialogs from the startup.
1733
1734 8.5. failed_dialogs
1735
1736    Returns the number of failed dialogs.
1737
1738 9. RPC Commands
1739
1740    9.1. dlg.list
1741    9.2. dlg.list_ctx
1742    9.3. dlg.dlg_list
1743    9.4. dlg.dlg_list_ctx
1744    9.5. dlg.terminate_dlg
1745    9.6. dlg.end_dlg
1746    9.7. dlg.profile_get_size
1747    9.8. dlg.profile_list
1748    9.9. dlg.bridge_dlg
1749
1750 9.1. dlg.list
1751
1752    Lists the description of all dialogs (active calls).
1753
1754    Name: dlg.list
1755
1756    RPC Command Format:
1757 ...
1758 kamcmd dlg.list
1759 ...
1760
1761 9.2. dlg.list_ctx
1762
1763    The same as the “dlg_list” but including in the dialog description the
1764    associated context from modules sitting on top of the dialog module.
1765
1766    Name: dlg.list_ctx
1767
1768    RPC Command Format:
1769 ...
1770 kamcmd dlg.list_ctx
1771 ...
1772
1773 9.3. dlg.dlg_list
1774
1775    Lists the description of one dialog. The dialog identifiers are to be
1776    passed as parameter (callid and optionally fromtag).
1777
1778    Name: dlg.dlg_list
1779
1780    Parameters:
1781      * callid callid of the dialog to be listed.
1782      * from_tag from tag (as per initial request) of the dialog to be
1783        listed.
1784
1785    RPC Command Format:
1786 ...
1787 kamcmd dlg.list abcdrssfrs122444@192.168.1.1 AAdfeEFF33
1788 ...
1789 kamcmd dlg.list abcdrssfrs122444@192.168.1.1
1790 ...
1791
1792 9.4. dlg.dlg_list_ctx
1793
1794    The same as the “dlg.list_ctx” but including in the dialog description
1795    the associated context from modules sitting on top of the dialog
1796    module.
1797
1798    Name: dlg.dlg_list_ctx
1799
1800    Parameters: see “dlg_list”
1801
1802    RPC Command Format:
1803 ...
1804 kamcmd dlg.list_ctx abcdrssfrs122444@192.168.1.1 AAdfeEFF33
1805 ...
1806 kamcmd dlg.list_ctx abcdrssfrs122444@192.168.1.1
1807 ...
1808
1809 9.5. dlg.terminate_dlg
1810
1811    Terminates an ongoing dialog by sending BYE in both directions,
1812    matching the dialog on call-id, from tag and to tag.
1813
1814    Name: dlg.terminate_dlg
1815
1816    Parameters:
1817      * callid - callid of dialog to be terminated
1818      * from_tag - from tag of the dialog to terminated
1819      * totag - to tag of the dialog to terminated
1820
1821    The command works only for confirmed dialogs.
1822
1823    RPC Command Format:
1824                 kamcmd dlg.dlg_terminate_dlg callid12345 fromtag123 totag123
1825
1826 9.6. dlg.end_dlg
1827
1828    Terminates an ongoing dialog by sending BYE in both directions.
1829
1830    Name: dlg.end_dlg
1831
1832    Parameters:
1833      * h_entry - hash entry of the dialog in the internal dialog table
1834      * h_id - hash id of the dialog on the hash entry
1835      * extra_hdrs - (optional) string containg extra headers (full format)
1836        to be added to the BYE requests.
1837
1838    The values for the h_entry and h_id can be get via the dlg_list RPC
1839    command.
1840
1841    RPC Command Format:
1842 ...
1843 kamcmd dlg.end_dlg 342 56
1844 ...
1845
1846 9.7. dlg.profile_get_size
1847
1848    Returns the number of dialogs belonging to a profile. If the profile
1849    supports values, the check can be reinforced to take into account a
1850    specific value - how many dialogs were inserted into the profile with a
1851    specific value. If no value is passed, only the simply belonging of the
1852    dialog to the profile is checked. Note that if the profile does not
1853    support values, the value parameter will be silently discarded.
1854
1855    Name: dlg.profile_get_size
1856
1857    Parameters:
1858      * profile - name of the profile to get the value for.
1859      * value (optional)- string value to further restrict the check;
1860
1861    RPC Command Format:
1862 ...
1863 kamcmd dlg.dlg.profile_get_size inbound_calls
1864 ...
1865
1866 9.8. dlg.profile_list
1867
1868    Lists all the dialogs belonging to a profile. If the profile supports
1869    values, the check can be reinforced to take into account a specific
1870    value, i.e. list only the dialogs that were inserted into the profile
1871    with that specific value. If no value is passed, all dialogs belonging
1872    to the profile will be listed. Note that if the profile does not
1873    supports values, this will be silently discarded.
1874
1875    Name: dlg.profile_list
1876
1877    Parameters:
1878      * profile - name of the profile to list the dialog for.
1879      * value (optional)- string value to further restrict the check;
1880
1881    RPC Command Format:
1882 ...
1883 kamcmd dlg.profile_list inbound_calls
1884 ...
1885
1886 9.9. dlg.bridge_dlg
1887
1888    Bridge two SIP addresses into a call using INVITE(hold)-REFER-BYE
1889    mechanism.
1890
1891    Name: dlg.bridge_dlg
1892
1893    Parameters:
1894      * from - SIP address to initiate the call
1895      * to - SIP address to refer 'from' to
1896      * op (optional) - outbound proxy SIP address
1897
1898    RPC Command Format:
1899 ...
1900 kamcmd dlg.list _from_ _to_ _op_
1901 ...
1902
1903 10. Exported Variables
1904
1905    10.1. $DLG_count
1906    10.2. $DLG_status
1907    10.3. $DLG_lifetime
1908    10.4. $dlg(...)
1909    10.5. $dlg_ctx(...)
1910    10.6. $dlg_var(key)
1911
1912 10.1. $DLG_count
1913
1914    Returns the number of current active dialogs (may be confirmed or not).
1915
1916 10.2. $DLG_status
1917
1918    Returns the status of the dialog corresponding to the processed
1919    sequential request. This PV will be available only for sequential
1920    requests, after doing loose_route().
1921
1922    Value may be:
1923      * NULL - Dialog not found.
1924      * 3 - Confirmed by a final reply but no ACK received yet.
1925      * 4 - Confirmed by a final reply and ACK received.
1926      * 5 - Dialog ended.
1927
1928 10.3. $DLG_lifetime
1929
1930    Returns the duration (in seconds) of the dialog corresponding to the
1931    processed sequential request. The duration is calculated from the
1932    dialog confirmation and the current moment. This PV will be available
1933    only for sequential requests, after doing loose_route().
1934
1935    NULL will be returned if there is no dialog for the request.
1936
1937 10.4. $dlg(...)
1938
1939    Access to dialog attributes.
1940
1941 10.5. $dlg_ctx(...)
1942
1943    Access to dialog context attributes.
1944
1945 10.6. $dlg_var(key)
1946
1947    This is a read/write variable that can be used to store custom values
1948    assigned with a dialog (e.g. the URI of a billing-server, an assigned
1949    emergency-server). This pseudo-variable will be available only for
1950    subsequential requests after doing loose_route().
1951
1952    Note: You will receive "NULL", if there is no dialog for this request.
1953
1954 11. Event Routes
1955
1956    11.1. event_route[dialog:start]
1957    11.2. event_route[dialog:end]
1958    11.3. event_route[dialog:failed]
1959
1960 11.1. event_route[dialog:start]
1961
1962    Executed when 200OK for INVITE is processed.
1963
1964 11.2. event_route[dialog:end]
1965
1966    Executed when BYE is processed or dialog timed out.
1967
1968 11.3. event_route[dialog:failed]
1969
1970    Executed when dialog is not completed (+300 reply to INVITE).
1971
1972 Chapter 2. Developer Guide
1973
1974    Table of Contents
1975
1976    1. Available Functions
1977
1978         1.1. register_dlgcb (dialog, type, cb, param, free_param_cb)
1979         1.2. terminate_dlg (dlg, hdrs)
1980
1981 1. Available Functions
1982
1983    1.1. register_dlgcb (dialog, type, cb, param, free_param_cb)
1984    1.2. terminate_dlg (dlg, hdrs)
1985
1986 1.1.  register_dlgcb (dialog, type, cb, param, free_param_cb)
1987
1988    Register a new callback to the dialog.
1989
1990    Meaning of the parameters is as follows:
1991      * struct dlg_cell* dlg - dialog to register callback to. If maybe
1992        NULL only for DLGCB_CREATED callback type, which is not a per
1993        dialog type.
1994      * int type - types of callbacks; more types may be register for the
1995        same callback function; only DLGCB_CREATED must be register alone.
1996        Possible types:
1997           + DLGCB_LOADED
1998           + DLGCB_CREATED - called when a new dialog is created - it's a
1999             global type (not associated to any dialog)
2000           + DLGCB_FAILED - called when the dialog was negatively replied
2001             (non-2xx) - it's a per dialog type.
2002           + DLGCB_CONFIRMED_NA - called when the dialog is confirmed (2xx
2003             replied) but the setup-concluding ACK message from the caller
2004             is yet pending - it's a per dialog type.
2005           + DLGCB_CONFIRMED - called when the dialog is confirmed (2xx
2006             replied) and the setup-concluding ACK message from the caller
2007             has been seen - it's a per dialog type.
2008           + DLGCB_REQ_WITHIN - called when the dialog matches a sequential
2009             request (excluding setup-concluding ACK messages which are
2010             handled in DLGCB_CONFIRMED) - it's a per dialog type.
2011           + DLGCB_TERMINATED - called when the dialog is terminated via
2012             BYE - it's a per dialog type.
2013           + DLGCB_TERMINATED_CONFIRMED - called when response to a BYE
2014             request is received - it's a per dialog type.
2015           + DLGCB_EXPIRED - called when the dialog expires without
2016             receiving a BYE - it's a per dialog type.
2017           + DLGCB_EARLY - called when the dialog is created in an early
2018             state (18x replied) - it's a per dialog type.
2019           + DLGCB_RESPONSE_FWDED - called when the dialog matches a reply
2020             to the initial INVITE request - it's a per dialog type.
2021           + DLGCB_RESPONSE_WITHIN - called when the dialog matches a reply
2022             to a subsequent in dialog request - it's a per dialog type.
2023           + DLGCB_RPC_CONTEXT - called when the rpc dlg_list_ctx command
2024             is invoked - it's a per dialog type.
2025           + DLGCB_SPIRALED - called when the dialog matches a spiraling
2026             request - it's a per dialog type.
2027           + DLGCB_DESTROY
2028      * dialog_cb cb - callback function to be called. Prototype is: “void
2029        (dialog_cb) (struct dlg_cell* dlg, int type, struct dlg_cb_params *
2030        params); ”
2031      * void *param - parameter to be passed to the callback function.
2032      * param_free callback_param_free - callback function to be called to
2033        free the param. Prototype is: “void (param_free_cb) (void *param);”
2034
2035 1.2.  terminate_dlg (dlg, hdrs)
2036
2037    Terminate a Dialog
2038
2039    Meaning of parameters is as follows:
2040      * struct dlg_cell* dlg - dialog to terminate.
2041      * str* hdrs - string containg extra headers (full format) to be added
2042        to the BYE requests of the dialog.
2043
2044 Chapter 3. Frequently Asked Questions
2045
2046    3.1. What happened with “use_tight_match” parameter?
2047    3.2. Where can I find more about Kamailio?
2048    3.3. Where can I post a question about this module?
2049    3.4. How can I report a bug?
2050
2051    3.1.
2052
2053        What happened with “use_tight_match” parameter?
2054
2055        The parameter was removed with version 1.3 as the option of tight
2056        matching became mandatory and not configurable. Now, the tight matching
2057        is done all the time (when using DID matching).
2058
2059    3.2.
2060
2061        Where can I find more about Kamailio?
2062
2063        Take a look at https://www.kamailio.org/.
2064
2065    3.3.
2066
2067        Where can I post a question about this module?
2068
2069        First at all check if your question was already answered on one of our
2070        mailing lists:
2071          * User Mailing List -
2072            https://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-users
2073          * Developer Mailing List -
2074            https://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-dev
2075
2076        E-mails regarding any stable Kamailio release should be sent to
2077        <sr-users@lists.kamailio.org> and e-mails regarding development
2078        versions should be sent to <sr-dev@lists.kamailio.org>.
2079
2080        If you want to keep the mail private, send it to
2081        <sr-users@lists.kamailio.org>.
2082
2083    3.4.
2084
2085        How can I report a bug?
2086
2087        Please follow the guidelines provided at:
2088        https://github.com/kamailio/kamailio/issues.