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