1pv_headers Module 2 3Kirill Solomko 4 5 Sipwise GmbH 6 <ksolomko@sipwise.com> 7 8Edited by 9 10Victor Seva 11 12 Sipwise GmbH 13 <vseva@sipwise.com> 14 15 Copyright © 2018 Sipwise GmbH 16 __________________________________________________________________ 17 18 Table of Contents 19 20 1. Admin Guide 21 22 1. Overview 23 2. Dependencies 24 25 2.1. Kamailio Modules 26 2.2. External Libraries or Applications 27 28 3. Parameters 29 30 3.1. xavi_name (string) 31 3.2. header_value_size (int) 32 3.3. header_collect_flag (int) 33 3.4. header_apply_flag (int) 34 3.5. skip_headers (string) 35 3.6. split_headers (string) 36 3.7. auto_msg (int) 37 38 4. Functions 39 40 4.1. pvh_collect_headers() 41 4.2. pvh_apply_headers() 42 4.3. pvh_reset_headers() 43 4.4. pvh_check_header(hname) 44 4.5. pvh_append_header(hname, hvalue) 45 4.6. pvh_modify_header(hname, hvalue, [idx]) 46 4.7. pvh_remove_header(hname, [idx]) 47 48 5. Exported Variables 49 50 List of Examples 51 52 1.1. Set xavi_name parameter 53 1.2. Set header_value_size parameter 54 1.3. Set header_collect_flag parameter 55 1.4. Set header_apply_flag parameter 56 1.5. Set skip_headers parameter 57 1.6. Set split_headers parameter 58 1.7. Set auto_msg parameter 59 60Chapter 1. Admin Guide 61 62 Table of Contents 63 64 1. Overview 65 2. Dependencies 66 67 2.1. Kamailio Modules 68 2.2. External Libraries or Applications 69 70 3. Parameters 71 72 3.1. xavi_name (string) 73 3.2. header_value_size (int) 74 3.3. header_collect_flag (int) 75 3.4. header_apply_flag (int) 76 3.5. skip_headers (string) 77 3.6. split_headers (string) 78 3.7. auto_msg (int) 79 80 4. Functions 81 82 4.1. pvh_collect_headers() 83 4.2. pvh_apply_headers() 84 4.3. pvh_reset_headers() 85 4.4. pvh_check_header(hname) 86 4.5. pvh_append_header(hname, hvalue) 87 4.6. pvh_modify_header(hname, hvalue, [idx]) 88 4.7. pvh_remove_header(hname, [idx]) 89 90 5. Exported Variables 91 921. Overview 93 94 The main goal of the module is to offload the intermediate header 95 processing into the XAVI dynamic container as well as provide with high 96 level methods and pseudovariables to simplify SIP message header 97 modifications. 98 992. Dependencies 100 101 2.1. Kamailio Modules 102 2.2. External Libraries or Applications 103 1042.1. Kamailio Modules 105 106 The following modules must be loaded before this module: 107 * uac. 108 * tm. 109 Needed only if “auto_msg” parameter is set to 1. 110 1112.2. External Libraries or Applications 112 113 The following libraries or applications must be installed before 114 running Kamailio with this module loaded: 115 * None. 116 1173. Parameters 118 119 3.1. xavi_name (string) 120 3.2. header_value_size (int) 121 3.3. header_collect_flag (int) 122 3.4. header_apply_flag (int) 123 3.5. skip_headers (string) 124 3.6. split_headers (string) 125 3.7. auto_msg (int) 126 1273.1. xavi_name (string) 128 129 Name of the XAVI where the collected headers are stored. 130 131 Default value is “headers”. 132 133 Example 1.1. Set xavi_name parameter 134... 135modparam("pv_headers", "xavi_name", "headers") 136... 137 138 Result: $xavi(headers[0]=>From) $xavi(headers[0]=>To) 139 $xavi(headers[0]=>Call-ID) 140 1413.2. header_value_size (int) 142 143 Defines an internal maximum SIP header value size. Header values longer 144 than this setting will be stripped down when collected or applied. 145 146 Default value is 1024. 147 148 Example 1.2. Set header_value_size parameter 149... 150modparam("pv_headers", "header_value_size", 512) 151... 152 1533.3. header_collect_flag (int) 154 155 Used to mark that headers are collected for the SIP message, leading to 156 subsequent headers collection on this message to be declined with an 157 error. Should be used only in branches and replies. 158 159 Default value is 27. 160 161 Example 1.3. Set header_collect_flag parameter 162... 163modparam("pv_headers", "header_collect_flag", 37) 164... 165 1663.4. header_apply_flag (int) 167 168 Used to mark that headers are applied for the SIP message, leading to 169 subsequent headers applies on this message to be declined with an 170 error. Should be used only in branches and replies. 171 172 Default value is 28. 173 174 Example 1.4. Set header_apply_flag parameter 175... 176modparam("pv_headers", "header_apply_flag", 38) 177... 178 1793.5. skip_headers (string) 180 181 A comma separated headers list that must be excluded from processing 182 (they are skipped when pvh_apply_headers() changes the SIP message 183 headers). 184 185 If the parameter is set to an empty string then all the SIP message 186 headers are processed. 187 188 Default value is 189 “Record-Route,Via,Route,Content-Length,Max-Forwards,CSeq”. 190 191 Example 1.5. Set skip_headers parameter 192... 193modparam("pv_headers", "skip_headers", "Record-Route,Via,Route") 194... 195 1963.6. split_headers (string) 197 198 A comma separated headers list that must be split into multi headers if 199 their value is a comma separated list. 200 201 If the parameter is set to an empty string then no headers are split. 202 203 Default value is “”. 204 205 Example 1.6. Set split_headers parameter 206... 207modparam("pv_headers", "split_headers", "Diversion") 208... 209 210 Result: Received Diversion header: Diversion: 211 <user1@test.local>,<user2@test.local>,<user3@test.local> After split: 212 Diversion: <user1@test.local> Diversion: <user2@test.local> Diversion: 213 <user3@test.local> 214 215 Becomes handy if used together with pvh_modify_header() or 216 pvh_remove_header() to change or remove value 2 for instance. 217 2183.7. auto_msg (int) 219 220 Defines wether the headers are automatically collected for incoming 221 messages, as well as automatically applied for forwarded messages. 222 223 It is enabled by default and requires the 'tm' module to be loaded, 224 otherwise the mode is disabled and manual invocation of 225 pvh_collect_headers()/pvh_apply_headers() is required. 226 227 Default value is 1 (enabled). 228 229 Example 1.7. Set auto_msg parameter 230... 231modparam("pv_headers", "auto_msg", 1) 232... 233 2344. Functions 235 236 4.1. pvh_collect_headers() 237 4.2. pvh_apply_headers() 238 4.3. pvh_reset_headers() 239 4.4. pvh_check_header(hname) 240 4.5. pvh_append_header(hname, hvalue) 241 4.6. pvh_modify_header(hname, hvalue, [idx]) 242 4.7. pvh_remove_header(hname, [idx]) 243 244 \ 245 2464.1. pvh_collect_headers() 247 248 Collects all headers from the message into the XAVP. It should be used 249 preferably just when the SIP message is received by Kamailio. 250 251 This function can be used from ANY_ROUTE. 252 2534.2. pvh_apply_headers() 254 255 Applies the current XAVP headers state to the real headers. and should 256 be called only once per branch when the message is about to leave 257 Kamailio. 258 259 The following rules apply: 260 * all headers in the XAVP except for ones provided in the 261 skip_headers parameter and From/To are recreated in the SIP 262 message. 263 * From/To headers are processed by the uac module if it is loaded. 264 * From/To headers are not changed in the reply messages. 265 * headers with NULL value are removed if exist in the SIP message. 266 * the initial order of the SIP headers is preserved. 267 268 This function can be used from ANY_ROUTE. 269 2704.3. pvh_reset_headers() 271 272 Collects all headers from the message into the XAVP. It should be used 273 preferably just when the SIP message is received by >Kamailio. 274 275 This function can be used from ANY_ROUTE. 276 2774.4. pvh_check_header(hname) 278 279 Checks if the header “hname” already exists in the XAVP. 280 281 This function can be used from ANY_ROUTE but only after 282 pvh_collect_headers() or with “auto_msg” parameter enabled. 283 2844.5. pvh_append_header(hname, hvalue) 285 286 Appends a new header “hname” with the value “hvalue” into the XAVP. 287 Please note that subsequent "pv_append_header" calls will result in 288 multiple headers. 289 290 If the provided “hvalue” is $null then the header is added into the 291 XAVP but it is not going to be added into the message. 292 293 This function can be used from ANY_ROUTE but only after 294 pvh_collect_headers() or with “auto_msg” parameter enabled. 295 2964.6. pvh_modify_header(hname, hvalue, [idx]) 297 298 Modifies an existing header in the XAVP “hname” with the value “hvalue” 299 into the XAVP. Index order is top to bottom. Please note that 300 subsequent pvh_append_header calls will result in multiple headers. 301 302 Please note that if the header “hname”does not exist it will be 303 explicitly appended. If there are multiple headers with the same name 304 and “idx” is omitted, only the first one will be affected. 305 306 This function can be used from ANY_ROUTE but only after 307 pvh_collect_headers() or with “auto_msg” parameter enabled. 308 3094.7. pvh_remove_header(hname, [idx]) 310 311 Removes an existing header “hname” from the XAVP. Index order is top to 312 bottom. 313 314 If there are multiple headers with the same name and “idx” is omitted, 315 all of them will be removed. 316 317 This function can be used from ANY_ROUTE but only after 318 pvh_collect_headers() or with “auto_msg” parameter enabled. 319 3205. Exported Variables 321 322 * $x_hdr 323 * $x_fu 324 * $x_fU 325 * $x_fd 326 * $x_fn 327 * $x_ft 328 * $x_tu 329 * $x_tU 330 * $x_td 331 * $x_tn 332 * $x_tt 333 * $x_rs 334 * $x_rr 335 336 Exported pseudo-variables are documented at 337 https://www.kamailio.org/wiki/. 338