Debian Codegraph @

src/modules/pv_headers/README

raw
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/.