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