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