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