9f563378135db24046a862024411e6e3f9e19a99
[sip-router] / modules / textopsx / README
1 1. Textopsx Module
2
3 Andrei Pelinescu-Onciul
4
5    FhG FOKUS
6
7 Daniel-Constantin Mierla
8
9    asipto.com
10    <miconda@gmail.com>
11
12    Copyright © 2003 FhG FOKUS
13      __________________________________________________________________
14
15    1.1. Overview
16    1.2. Functions
17
18         1.2.1. msg_apply_changes()
19         1.2.2. change_reply_status(code, reason)
20         1.2.3. remove_body()
21         1.2.4. keep_hf(regexp)
22         1.2.5. fnmatch(value, expr [, flags])
23         1.2.6. append_hf_value(hf, hvalue)
24         1.2.7. insert_hf_value(hf, hvalue)
25         1.2.8. remove_hf_value(hf_par)
26         1.2.9. remove_hf_value2(hf_par)
27         1.2.10. assign_hf_value(hf, hvalue)
28         1.2.11. assign_hf_value2(hf, hvalue)
29         1.2.12. include_hf_value(hf, hvalue)
30         1.2.13. exclude_hf_value(hf, hvalue)
31         1.2.14. hf_value_exists(hf, hvalue)
32         1.2.15. Selects
33
34               1.2.15.1. @hf_value
35               1.2.15.2. @hf_value2
36               1.2.15.3. @hf_value_exists
37
38 1.1. Overview
39
40    This module implements functions for SIP message text operations in
41    routing block configurations. It adds new features similar to the
42    textops module (textops eXtentions).
43
44 1.2. Functions
45
46 1.2.1. msg_apply_changes()
47
48    Use this function to apply changes performed on SIP request content. Be
49    careful when using this function; due to special handling of changes to
50    the SIP message buffer so far, using this function might change the
51    behaviour of your config. Do test your config properly!
52
53    This function can be used from REQUEST_ROUTE.
54
55    Example 1. msg_apply_changes() usage
56 ...
57 append_hf("My-Header: yes\r\n");
58 if(msg_apply_changes())
59 {
60     # msg buffer has a new content
61     if(is_present_hf("My-Header"))
62     {
63         # will get here always
64     }
65 }
66 ...
67
68 1.2.2. change_reply_status(code, reason)
69
70    Intercept a SIP reply (in an onreply_route) and change its status code
71    and reason phrase prior to forwarding it.
72
73    Meaning of the parameters is as follows:
74      * code - Status code.
75      * reason - Reason phrase.
76
77    This function can be used from ONREPLY_ROUTE.
78
79    Example 2. change_reply_status usage
80 ...
81 onreply_route {
82     if (@status == "603") {
83         change_reply_status(404, "Not Found");
84         exit;
85     }
86 }
87 ...
88
89 1.2.3. remove_body()
90
91    Use this function to remove the body of SIP requests or replies.
92
93    This function can be used from ANY_ROUTE.
94
95    Example 3. remove_body() usage
96 ...
97 remove_body();
98 ...
99
100 1.2.4. keep_hf(regexp)
101
102    Remove headers that don't match the regular expression regexp. Several
103    header are ignored always (thus not removed): Via, From, To, Call-ID,
104    CSeq, Content-Lenght, Content-Type, Max-Forwards, Contact, Route,
105    Record-Route -- these can be removed one by one with remove_hf().
106
107    This function can be used from ANY_ROUTE.
108
109    Example 4. keep_hf() usage
110 ...
111 keep_hf("User-Agent");
112 ...
113
114 1.2.5. fnmatch(value, expr [, flags])
115
116    Match the value against the expr using shell-style pattern for file
117    name matching (see man page for C function fnmatch()). It is known to
118    be faster and use less-memory than regular expressions.
119
120    Parameter 'flags' is optional and can be 'i' to do case insensitive
121    matching.
122
123    This function can be used from ANY_ROUTE.
124
125    Example 5. fnmatch() usage
126 ...
127 if(fnmatch("$rU", "123*"))
128 {
129     ...
130 }
131 ...
132
133 1.2.6. append_hf_value(hf, hvalue)
134
135    Append new header value after an existing header, if no index acquired
136    append at the end of list. Note that a header may consist of comma
137    delimited list of values.
138
139    Meaning of the parameters is as follows:
140      * hf - Header field to be appended. Format: HFNAME [ [IDX] ]. If
141        index is not specified new header is inserted at the end of
142        message.
143      * hvalue - Value to be added, config var formatting supported.
144
145    Example 6. append_hf_value usage
146 ...
147 append_hf_value("foo", "gogo;stamp=$Ts")   # add new header
148 append_hf_value("foo[1]", "gogo")  # add new value behind first value
149 append_hf_value("foo[-1]", "$var(Bar)") # try add value to the last header, if n
150 ot exists add new header
151 ...
152
153 1.2.7. insert_hf_value(hf, hvalue)
154
155    Insert new header value before an existing header, if no index acquired
156    insert before first hf header. Note that a header may consist of comma
157    delimited list of values. To insert value behing last value use
158    appenf_hf_value.
159
160    Meaning of the parameters is as follows:
161      * hf - Header field to be appended. Format: HFNAME [ [IDX] ]. If
162        index is not specified new header is inserted at the top of
163        message.
164      * hvalue - Value to be added, config var formatting supported.
165
166    Example 7. insert_hf_value usage
167 ...
168 insert_hf_value("foo[2]", "gogo")
169 insert_hf_value("foo", "$avp(foo)")   # add new header at the top of list
170 insert_hf_value("foo[1]", "gogo") # try add to the first header
171 ...
172
173 1.2.8. remove_hf_value(hf_par)
174
175    Remove the header value from existing header, Note that a header may
176    consist of comma delimited list of values.
177
178    Meaning of the parameters is as follows:
179      * hf_par - Header field/param to be removed. Format: HFNAME [ [IDX] ]
180        [. PARAM ] If asterisk is specified as index then all values are
181        affected.
182
183    Example 8. remove_hf_value usage
184 ...
185 remove_hf_value("foo")  # remove foo[1]
186 remove_hf_value("foo[*]")  # remove all foo's headers
187 remove_hf_value("foo[-1]") # last foo
188 remove_hf_value("foo.bar")  # delete parameter
189 remove_hf_value("foo[*].bar") # for each foo delete bar parameters
190 ...
191
192 1.2.9. remove_hf_value2(hf_par)
193
194    Remove specified header or parameter. It is expected header in
195    Authorization format (comma delimiters are not treated as multi-value
196    delimiters).
197
198    Meaning of the parameters is as follows:
199      * hf_par - Header/param to be removed. Format: HFNAME [ [IDX] ] [.
200        PARAM ] If asterisk is specified as index then all values are
201        affected.
202
203    Example 9. remove_hf_value2 usage
204 ...
205 remove_hf_value2("foo")  # remove foo[1]
206 remove_hf_value2("foo[*]")  # remove all foo's headers, the same as remove_hf_he
207 ader("foo[*]");
208 remove_hf_value2("foo[-1]") # last foo
209 remove_hf_value2("foo.bar")  # delete parameter
210 remove_hf_value2("foo[*].bar") # for each foo delete bar parameters
211 ...
212
213 1.2.10. assign_hf_value(hf, hvalue)
214
215    Assign value to specified header value / param.
216
217    Meaning of the parameters is as follows:
218      * hf_para - Header field value / param to be appended. Format: HFNAME
219        [ [IDX] ] [. PARAM] If asterisk is specified as index then all
220        values are affected.
221      * hvalue - Value to be assigned, config var formatting supported. If
222        value is empty then no equal sign apears in param.
223
224    Example 10. assign_hf_value usage
225 ...
226 assign_hf_value("foo", "gogo")  # foo[1]
227 assign_hf_value("foo[-1]", "gogo")  # foo[last_foo]
228
229 assign_hf_value("foo.bar", "")
230 assign_hf_value("foo[3].bar", "")
231 assign_hf_value("foo[*]", "")  # remove all foo's, empty value remains
232 assign_hf_value("foo[*].bar", "")  # set empty value (ex. lr)
233 ...
234
235 1.2.11. assign_hf_value2(hf, hvalue)
236
237    Assign value to specified header. It is expected header in
238    Authorization format (comma delimiters are not treated as multi-value
239    delimiters).
240
241    Meaning of the parameters is as follows:
242      * hf_para - Header field value / param to be appended. Format: HFNAME
243        [ [IDX] ] [. PARAM] If asterisk is specified as index then all
244        values are affected.
245      * hvalue - Value to be assigned, config var formatting supported. If
246        value is empty then no equal sign apears in param.
247
248    Example 11. assign_hf_value2 usage
249 ...
250 assign_hf_value2("Authorization.integrity-protected", "\"yes\"")
251 assign_hf_value2("foo[-1]", "gogo")  # foo[last_foo]
252 assign_hf_value2("foo[*].bar", "")  # set empty value (ex. lr)
253 ...
254
255 1.2.12. include_hf_value(hf, hvalue)
256
257    Add value in set if not exists, eg. "Supported: path,100rel".
258
259    Meaning of the parameters is as follows:
260      * hf - Header field name to be affected.
261      * hvalue - config var formatting supported.
262
263    Example 12. include_hf_value usage
264 ...
265 include_hf_value("Supported", "path");
266 ...
267
268 1.2.13. exclude_hf_value(hf, hvalue)
269
270    Remove value from set if exists, eg. "Supported: path,100rel".
271
272    Meaning of the parameters is as follows:
273      * hf - Header field name to be affected.
274      * hvalue - config formatting supported.
275
276    Example 13. exclude_hf_value usage
277 ...
278 exclude_hf_value("Supported", "100rel");
279 ...
280
281 1.2.14. hf_value_exists(hf, hvalue)
282
283    Check if value exists in set. Alternate select
284    @hf_value_exists.HF.VALUE may be used. It returns one or zero.
285
286    Meaning of the parameters is as follows:
287      * hf - Header field name to be affected. Underscores are treated as
288        dashes.
289      * hvalue - config var formatting supported.
290
291    Example 14. hf_value_exists usage
292 ...
293 if (hf_value_exists("Supported", "100rel")) {
294
295 }
296
297 if (@hf_value_exists.supported.path == "1") {
298
299 }
300 ...
301
302 1.2.15. Selects
303
304 1.2.15.1. @hf_value
305
306    Get value of required header-value or param. Note that functions called
307    'value2' works with Authorization-like headers where comma is not
308    treated as value delimiter. Formats: @hf_value.HFNAME[IDX] # idx value,
309    negative value counts from bottom @hf_value.HFNAME.PARAM_NAME
310    @hf_value.HFNAME[IDX].PARAM_NAME @hf_value.HFNAME.p.PARAM_NAME # or
311    .param., useful if requred called "uri", "p", "param"
312    @hf_value.HFNAME[IDX].p.PARAM_NAME # dtto @hf_value.HFNAME[IDX].uri #
313    (< & > excluded) @hf_value.HFNAME[*] # return comma delimited list of
314    all values (combines headers) @hf_value.HFNAME # the same as above [*]
315    but may be parsed by cfg.y @hf_value.HFNAME[*].uri # return comma
316    delimited list of uris (< & > excluded) @hf_value.HFNAME.uri # the same
317    as above [*] but may be parsed by cfg.y @hf_value.HFNAME[IDX].name #
318    returns name part, quotes excluded @hf_value.HFNAME.name # returns name
319    part of the first value @hf_value2.HFNAME # returns value of first
320    header @hf_value2.HFNAME[IDX] # returns value of idx's header
321    @hf_value2.HFNAME.PARAM_NAME @hf_value2.HFNAME[IDX].PARAM_NAME
322    @hf_value.HFNAME[IDX].uri # return URI, quotes excluded
323    @hf_value.HFNAME.p.uri # returns param named uri, not URI itself
324    @hf_value.HFNAME.p.name # returns param named name, not name itself
325    @hf_value.HFNAME[IDX].uri.name # any sel_any_uri nested features may be
326    used @hf_value.HFNAME[IDX].nameaddr.name # select_any_nameaddr
327
328    Meaning of the parameters is as follows:
329      * HFNAME - Header field name. Underscores are treated as dashes.
330      * IDX - Value index, negative value counts from bottom
331      * PARAM_NAME - name of parameter
332
333    Example 15. @hf_value select usage
334 ...
335 $a = @hf_value.my_header[1].my_param;
336 xplog("L_ERR", "$sel(@hf_value.via[-1]), $sel(@hf_value.from.tag)\n");
337 $b = @hf_value.p_associated_uri;
338
339 xplog("L_ERR", "Route uris: '$sel(@hf_value.route[*].uri)'\n");
340 $rr = @hf_value.route.uri;
341
342 $prt = @hf_value2.authorization.integrity_protected;
343 ...
344
345 1.2.15.2. @hf_value2
346
347    TBA.
348
349 1.2.15.3. @hf_value_exists
350
351    TBA.