1pua dialoginfo
2
3Anca-Maria Vamanu
4
5 Voice Sistem SRL
6
7Edited by
8
9Anca-Maria Vamanu
10
11Klaus Darilion
12
13 IPCom (Module implementation was partly sponsored by Silver Server
14 (www.sil.at))
15
16Klaus Darilion
17
18 IPCom
19
20Phil Lavin
21
22 Copyright © 2006 Voice Sistem SRL
23
24 Copyright © 2008 Klaus Darilion IPCom
25 __________________________________________________________________
26
27 Table of Contents
28
29 1. Admin Guide
30
31 1. Overview
32 2. Activate Functionality
33 3. Known issues
34 4. Dependencies
35
36 4.1. Kamailio Modules
37 4.2. External Libraries or Applications
38
39 5. Parameters
40
41 5.1. include_callid (int)
42 5.2. include_tags (int)
43 5.3. include_localremote (int)
44 5.4. override_lifetime (int)
45 5.5. include_req_uri (int)
46 5.6. caller_confirmed (int)
47 5.7. send_publish_flag (int)
48 5.8. disable_caller_publish_flag (int)
49 5.9. disable_callee_publish_flag (int)
50 5.10. use_pubruri_avps (int)
51 5.11. pubruri_caller_avp (str)
52 5.12. pubruri_callee_avp (str)
53 5.13. pubruri_caller_dlg_var (str)
54 5.14. pubruri_callee_dlg_var (str)
55 5.15. callee_trying (int)
56
57 6. Functions
58
59 List of Examples
60
61 1.1. Set include_callid parameter
62 1.2. Set include_tags parameter
63 1.3. Set include_localremote parameter
64 1.4. Set override_lifetime parameter
65 1.5. Set include_req_uri parameter
66 1.6. Set caller_confirmed parameter
67 1.7. Set send_publish_flag parameter
68 1.8. Set disable_caller_publish_flag parameter
69 1.9. Set disable_callee_publish_flag parameter
70 1.10. Set use_pubruri_avps parameter
71 1.11. Set pubruri_caller_avp parameter
72 1.12. Set pubruri_callee_avp parameter
73 1.13. Set pubruri_caller_avp parameter
74 1.14. Set pubruri_callee_dlg_var parameter
75 1.15. Set callee_trying parameter
76
77Chapter 1. Admin Guide
78
79 Table of Contents
80
81 1. Overview
82 2. Activate Functionality
83 3. Known issues
84 4. Dependencies
85
86 4.1. Kamailio Modules
87 4.2. External Libraries or Applications
88
89 5. Parameters
90
91 5.1. include_callid (int)
92 5.2. include_tags (int)
93 5.3. include_localremote (int)
94 5.4. override_lifetime (int)
95 5.5. include_req_uri (int)
96 5.6. caller_confirmed (int)
97 5.7. send_publish_flag (int)
98 5.8. disable_caller_publish_flag (int)
99 5.9. disable_callee_publish_flag (int)
100 5.10. use_pubruri_avps (int)
101 5.11. pubruri_caller_avp (str)
102 5.12. pubruri_callee_avp (str)
103 5.13. pubruri_caller_dlg_var (str)
104 5.14. pubruri_callee_dlg_var (str)
105 5.15. callee_trying (int)
106
107 6. Functions
108
1091. Overview
110
111 The pua_dialoginfo retrieves dialog state information from the dialog
112 module and PUBLISHes the dialog-information using the pua module. Thus,
113 in combination with the presence_xml module this can be used to derive
114 dialog-info from the dialog module and NOTIFY the subscribed watchers
115 about dialog-info changes. This can be used for example with SNOM and
116 Linksys phones.
117
118 Note: This implements dialog-info according to RFC 4235 and is not
119 compatible with the BLA feature defined in
120 draft-anil-sipping-bla-03.txt. (Actually the BLA draft is really crap
121 as it changes SIP semantics)
122
123 The module is based on code (copy/paste) from pua_usrloc and
124 nat_traversal module.
125
126 Following you will show some examples of an dialog-info XML document
127 taken from RFC 4235. This will help you to understand the meaning of
128 the module parameters:
129<?xml version="1.0"?>
130<dialog-info xmlns="urn:ietf:params:xml:ns:dialog-info"
131 version="1"
132 state="full"
133 entity="sip:alice@example.com">
134 <dialog id="as7d900as8"
135 call-id="a84b4c76e66710"
136 local-tag="1928301774"
137 remote-tag="456887766"
138 direction="initiator">
139 <state>early</state>
140 </dialog>
141</dialog-info>
142
143 The root element is the "dialog-info". It contains the namespace, the
144 version (which must be incremented for each new PUBLISH for this
145 certain dialog), the state (this module only supports state=full) and
146 the entity for which we publish the dialog-info.
147
148 The "dialog" element must contain an id parameter. The id parameter is
149 usually different to the optional call-id parameter (which is the
150 call-id of the INVITE request) as an INVITE can create multiple dialogs
151 (forked request). But as the dialog module does not support multiple
152 dialogs created by a single transaction, the pua_dialoginfo module sets
153 the id parameter to the same value as the call-id parameter. The
154 "local-tag" indicates the local tag of the entity. The remote-tag
155 indicates the tag of the remote party. The "direction" indicates if the
156 entity was the initiator of the dialog or the recipient (aka if the
157 entity sent or received the first INVITE).
158
159 The "state" element describes the state of the dialog state machine and
160 must be either: trying, proceeding, early, confirmed or terminated.
161
162 The dialog element can contain optional "local" and "remote" elements
163 which describes the local and the remote party in more detail, for
164 example:
165<?xml version="1.0" encoding="UTF-8"?>
166<dialog-info xmlns="urn:ietf:params:xml:ns:dialog-info"
167 version="1" state="full">
168 <dialog id="as7d900as8"
169 call-id="a84b4c76e66710"
170 local-tag="1928301774"
171 remote-tag="456887766"
172 direction="initiator">
173 <state>early</state>
174 <local>
175 <identity display="Alice">sip:alice@example.com</identity>
176 <target uri="sip:alice@phone11.example.com"/>
177 </local>
178 <remote>
179 <identity display="Bob">sip:bob@example.org</identity>
180 <target uri="sip:bobster@phone21.example.org"/>
181 </remote>
182 </dialog>
183</dialog-info>
184
185 The local and remote elements are needed to implement call pickup. For
186 example if the above XML document is received by somebody who
187 SUBSCRIBEd the dialog-info of Alice, then it can pick-up the call by
188 sending an INVITE to Bob (actually I am not sure if it should use the
189 URI in the identity element or the URI in the target parameter) which
190 contains a Replaces header which contains the call-id and the tags.
191 This was tested successfully with Linksys SPA962 phones and with SNOM
192 320 Firmware 7.3.7 (you have to set the function key to "Extension").
193
194 A dialog-info XML document may contain multiple "dialog" elements, for
195 example if the entity has multiple ongoing dialogs. For example the
196 following XML document shows a confirmed dialog and an early (probably
197 a second incoming call) dialog.
198<?xml version="1.0"?>
199<dialog-info xmlns="urn:ietf:params:xml:ns:dialog-info"
200 version="3"
201 state="full"
202 entity="sip:alice@example.com">
203 <dialog id="as7d900as8" call-id="a84b4c76e66710"
204 local-tag="1928301774" remote-tag="hh76a"
205 direction="initiator">
206 <state>confirmed</state>
207 </dialog>
208 <dialog id="j7zgt54" call-id="ASDRRVASDRF"
209 local-tag="123456789" remote-tag="EE345"
210 direction="recipient">
211 <state>early</state>
212 </dialog>
213</dialog-info>
214
215 As the dialog module callbacks only address a certain dialog, the
216 pua_dialoginfo always PUBLISHes XML documents with a single "dialog"
217 element. If an entity has multiple concurrent dialogs, the
218 pua_dialoginfo module will send PUBLISH for each dialog. These multiple
219 "presenties" can be aggregated by the presence_dialoginfo module into a
220 single XML document with multiple "dialog" elements. Please see the
221 description of the presence_dialoginfo module for details about the
222 aggregation.
223
224 If there are problems with the callbacks from dialog module and you
225 want to debug them you define PUA_DIALOGINFO_DEBUG in pua_dialoginfo.c
226 and recompile.
227
2282. Activate Functionality
229
230 This module is directly coupled with the dialog module. Thus, if the
231 module is loaded, it is automatically active for all calls tracked by
232 the dialog module. Thus, make sure that you activate the dialog module
233 for a certain call if you want dialog-state to be PUBLISHED. This
234 means, the dlg_flag of the dialog module must be configured and the
235 respective flag must be set during call processing.
236
2373. Known issues
238
239 * The module tries to find out if the entity is a local user. Only
240 PUBLISH to local user are sent. Therefore, the module needs to find
241 out if the domain is a local one or not. It uses the same mechanism
242 as the "==myself" mechanism. Thus, all domains have to be declared
243 with the "alias=..." option in Kamailio.cfg. DB-based multidomain
244 support as offered by "domain" module is not supported yet.
245 Conclusion: The module has the same "domain" problems as the "rr"
246 module.
247 * The module puts the call-id of the dialog into an XML parameter.
248 Thus, if the call-id contains quotes, they should be escaped. This
249 is not yet implemented. Thus, if the call-id contains quotes the
250 XML document will be invalid.
251 * The module derives the AoR of the callee from the To: header. Thus,
252 if the To header does not contain the canonical AoR the PUBLISH
253 might have the wrong SIP URI in the RURI and the entity parameter.
254
2554. Dependencies
256
257 4.1. Kamailio Modules
258 4.2. External Libraries or Applications
259
2604.1. Kamailio Modules
261
262 The following modules must be loaded before this module:
263 * dialog.
264 * pua.
265
2664.2. External Libraries or Applications
267
268 The following libraries or applications must be installed before
269 running Kamailio with this module loaded:
270 * libxml.
271
2725. Parameters
273
274 5.1. include_callid (int)
275 5.2. include_tags (int)
276 5.3. include_localremote (int)
277 5.4. override_lifetime (int)
278 5.5. include_req_uri (int)
279 5.6. caller_confirmed (int)
280 5.7. send_publish_flag (int)
281 5.8. disable_caller_publish_flag (int)
282 5.9. disable_callee_publish_flag (int)
283 5.10. use_pubruri_avps (int)
284 5.11. pubruri_caller_avp (str)
285 5.12. pubruri_callee_avp (str)
286 5.13. pubruri_caller_dlg_var (str)
287 5.14. pubruri_callee_dlg_var (str)
288 5.15. callee_trying (int)
289
2905.1. include_callid (int)
291
292 If this parameter is set, the optional call-id will be put into the
293 dialog element. This is needed for call-pickup features.
294
295 Default value is “1”.
296
297 Example 1.1. Set include_callid parameter
298...
299modparam("pua_dialoginfo", "include_callid", 0)
300...
301
3025.2. include_tags (int)
303
304 If this parameter is set, the local and remote tag will be put into the
305 dialog element. This is needed for call-pickup features.
306
307 Default value is “1”.
308
309 Example 1.2. Set include_tags parameter
310...
311modparam("pua_dialoginfo", "include_tags", 0)
312...
313
3145.3. include_localremote (int)
315
316 If this parameter is set, the optional local and remote elements will
317 be put into the dialog element. This is needed for call-pickup
318 features.
319
320 Default value is “1”.
321
322 Example 1.3. Set include_localremote parameter
323...
324modparam("pua_dialoginfo", "include_localremote", 0)
325...
326
3275.4. override_lifetime (int)
328
329 The PUBLISH requests used to send the dialog-info contain an Expires
330 header. The value of the expires is usually taken from the lifetime of
331 the dialog (see README of dialog module). If the override_lifetime is
332 set, the value specified here is used instead of the lifetime of the
333 dialog module. If used, the value should at least be a few seconds more
334 than the fr_inv_timer of the tm module.
335
336 Default value is “0”.
337
338 Example 1.4. Set override_lifetime parameter
339...
340modparam("pua_dialoginfo", "override_lifetime", 300)
341...
342
3435.5. include_req_uri (int)
344
345 controls if R-URI is going to be used instead of To header value in the
346 PUBLISH as "identity" on "remote" node.
347
348 Default value is “0”. Disabled
349
350 Example 1.5. Set include_req_uri parameter
351...
352modparam("pua_dialoginfo", "include_req_uri", 1)
353...
354
3555.6. caller_confirmed (int)
356
357 Usually the dialog-info of the caller will be "trying -> early ->
358 confirmed" and the dialog-info of the callee will be "early ->
359 confirmed". On some phones the function LED will start blinking if the
360 state is early, regardless if is is the caller or the callee (indicated
361 with the "direction" parameter). To avoid blinking LEDs for the caller,
362 you can enable this parameter. Then the state of the caller will be
363 signaled as "confirmed" even in "early" state. This is a workaround for
364 the buggy Linksys SPA962 phones. SNOM phones work well with the default
365 setting.
366
367 Default value is “0”.
368
369 Example 1.6. Set caller_confirmed parameter
370...
371modparam("pua_dialoginfo", "caller_confirmed", 1)
372...
373
3745.7. send_publish_flag (int)
375
376 This message flag indicates whether to send PUBLISH requests or not. If
377 not set, PUBLISH requests are sent out only if their R-URI is local
378 (according to myself).
379
380 Default value is “-1”.
381
382 Example 1.7. Set send_publish_flag parameter
383...
384modparam("pua_dialoginfo", "send_publish_flag", 8)
385...
386
3875.8. disable_caller_publish_flag (int)
388
389 This message flag indicates whether to send caller (initiator) PUBLISH
390 requests or not. If set, PUBLISH requests are not sent for the caller
391 (initiator).
392
393 Default value is “-1”.
394
395 Example 1.8. Set disable_caller_publish_flag parameter
396...
397modparam("pua_dialoginfo", "disable_caller_publish_flag", 9)
398...
399
4005.9. disable_callee_publish_flag (int)
401
402 This message flag indicates whether to send callee (recipient) PUBLISH
403 requests or not. If set, PUBLISH requests are not sent for the callee
404 (recipient).
405
406 Default value is “-1”.
407
408 Example 1.9. Set disable_callee_publish_flag parameter
409...
410modparam("pua_dialoginfo", "disable_callee_publish_flag", 10)
411...
412
4135.10. use_pubruri_avps (int)
414
415 Get Publish R-Uri from avps (see corresponding avp params), not from
416 request to/from uri.
417
418 Default value is “0”.
419
420 Example 1.10. Set use_pubruri_avps parameter
421...
422modparam("pua_dialoginfo", "use_pubruri_avps", 1)
423...
424
4255.11. pubruri_caller_avp (str)
426
427 If use_pubruri_avps is enabled, PUBLISH-requests reporting
428 dialog-information about the caller (entity=caller) are sent using the
429 value of the specified avp as R-Uri. If multiple AVPs with the same
430 name (but different indexes) are present, for each value a
431 corresponding PUBLISH-request is generated. If no AVP with the
432 specified name exists, no caller-related PUBLISH requests are sent.
433
434 Default value is “NULL”.
435
436 Example 1.11. Set pubruri_caller_avp parameter
437...
438modparam("pua_dialoginfo", "pubruri_caller_avp", "$avp(s:puburis_caller)")
439...
440
4415.12. pubruri_callee_avp (str)
442
443 If use_pubruri_avps is enabled, PUBLISH-requests reporting
444 dialog-information about the callee (entity=callee) are sent using the
445 value of the specified avp as R-Uri. If multiple AVPs with the same
446 name (but different indexes) are present, for each value a
447 corresponding PUBLISH-request is generated. If no AVP with the
448 specified name exists, no callee-related PUBLISH requests are sent.
449
450 Default value is “NULL”.
451
452 Example 1.12. Set pubruri_callee_avp parameter
453...
454modparam("pua_dialoginfo", "pubruri_callee_avp", "$avp(s:puburis_callee)")
455...
456
4575.13. pubruri_caller_dlg_var (str)
458
459 Must be set to the name of dialog variable where to store the URI for
460 caller, used to send the notifications. This is needed to restored the
461 value after Kamailio restart. If not set, loaded dialogs at restart are
462 no longer sending notifications. New dialogs are working fine.
463
464 Default value is “NULL”.
465
466 Example 1.13. Set pubruri_caller_avp parameter
467...
468modparam("pua_dialoginfo", "pubruri_caller_dlg_var", "pubruri_caller")
469...
470
4715.14. pubruri_callee_dlg_var (str)
472
473 Must be set to the name of dialog variable where to store the URI for
474 callee, used to send the notifications. This is needed to restored the
475 value after Kamailio restart. If not set, loaded dialogs at restart are
476 no longer sending notifications. New dialogs are working fine.
477
478 Default value is “NULL”.
479
480 Example 1.14. Set pubruri_callee_dlg_var parameter
481...
482modparam("pua_dialoginfo", "pubruri_callee_dlg_var", "pubruri_callee")
483...
484
4855.15. callee_trying (int)
486
487 If this parameter is set, a "Trying" state will be sent for both the
488 caller and callee, rather than just the caller.
489
490 Default value is “0”.
491
492 Example 1.15. Set callee_trying parameter
493...
494modparam("pua_dialoginfo", "callee_trying", 1)
495...
496
4976. Functions
498