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