textops(s): change_reply_status() moved to textopsx

modules_s/textops/README

@@ -1,30 +1,54 @@
-
 1. Textops Module
 
 Andrei Pelinescu-Onciul
 
    FhG FOKUS
 
-   Copyright © 2003 FhG FOKUS
+   Copyright © 2003 FhG FOKUS
    Revision History
    Revision $Revision$ $Date$
-     _________________________________________________________________
-
-   Table of Contents
+     __________________________________________________________________
 
    1.1. Overview
+
+        1.1.1. Known Limitations
+
    1.2. Functions
 
+        1.2.1. search(re)
+        1.2.2. search_append(re, txt)
+        1.2.3. replace(re, txt)
+        1.2.4. subst('/re/repl/flags')
+        1.2.5. subst_uri('/re/repl/flags')
+        1.2.6. subst_user('/re/repl/flags')
+        1.2.7. append_to_reply(txt)
+        1.2.8. append_hf(hf)
+        1.2.9. append_urihf(prefix, suffix)
+        1.2.10. is_present_hf(hf_name)
+        1.2.11. append_time()
+        1.2.12. remove_hf(hf_name)
+        1.2.13. remove_hf_re(reg_exp)
+        1.2.14. append_hf_value(hf, xl_value)
+        1.2.15. insert_hf_value(hf, xl_value)
+        1.2.16. remove_hf_value(hf_par)
+        1.2.17. remove_hf_value2(hf_par)
+        1.2.18. assign_hf_value(hf, xl_value)
+        1.2.19. assign_hf_value2(hf, xl_value)
+        1.2.20. include_hf_value(hf, xl_value)
+        1.2.21. exclude_hf_value(hf, xl_value)
+        1.2.22. hf_value_exists(hf, xl_value)
+        1.2.23. @hf_value selects
+
 1.1. Overview
 
    This is mostly an example module. It implements text based operation
-   (search, replace, append a.s.o).
+   (search, replace, append a.s.o). Many functions support xl_lib
+   formating using xlog module.
 
 1.1.1. Known Limitations
 
-   search ignores folded lines. For example,
-   search("(From|f):.*@foo.bar") doesn't match the following From header
-   field:
+   search ignores folded lines. For example, search("(From|f):.*@foo.bar")
+   doesn't match the following From header field:
 From: medabeda
  <sip:[email protected]>;tag=1234
 
@@ -51,7 +75,7 @@ if ( search("[Ss][Ee][Rr]" ) { /*....*/ };
 
    Meaning of the parameters is as follows:
      * re - Regular expression.
-     * txt - String to be appended.
+     * txt - String to be appended. Xl_lib formatting supported.
 
    Example 2. search_append usage
 ...
@@ -64,7 +88,7 @@ search_append("[Ss]er", " blabla");
 
    Meaning of the parameters is as follows:
      * re - Regular expression.
-     * txt - String.
+     * txt - String. Xl_lib formatting supported.
 
    Example 3. replace usage
 ...
@@ -77,8 +101,8 @@ replace("ser", "Sip Express Router");
 
    Meaning of the parameters is as follows:
      * '/re/repl/flags' - sed like regular expression. flags can be a
-       combination of i (case insensitive), g (global) or s (match
-       newline don't treat it as end of line).
+       combination of i (case insensitive), g (global) or s (match newline
+       don't treat it as end of line).
 
    Example 4. subst usage
 ...
@@ -93,8 +117,8 @@ if ( subst('/^To:(.*)sip:[^@]*@[a-zA-Z0-9.]+(.*)$/t:\1\u\2/ig') ) {};
 
    Meaning of the parameters is as follows:
      * '/re/repl/flags' - sed like regular expression. flags can be a
-       combination of i (case insensitive), g (global) or s (match
-       newline don't treat it as end of line).
+       combination of i (case insensitive), g (global) or s (match newline
+       don't treat it as end of line).
 
    Example 5. subst usage
 ...
@@ -110,8 +134,8 @@ if (subst_uri('/^sip:([0-9]+)@(.*)$/sip:3463\1@\2;orig_uri=\0/i')){$
 
    Meaning of the parameters is as follows:
      * '/re/repl/flags' - sed like regular expression. flags can be a
-       combination of i (case insensitive), g (global) or s (match
-       newline don't treat it as end of line).
+       combination of i (case insensitive), g (global) or s (match newline
+       don't treat it as end of line).
 
    Example 6. subst usage
 ...
@@ -124,7 +148,7 @@ if (subst_user('/3642$/36423463/')){$
    Append txt to the reply.
 
    Meaning of the parameters is as follows:
-     * txt - String.
+     * txt - String. Xl_lib formatting supported.
 
    Example 7. append_to_reply usage
 ...
@@ -136,7 +160,7 @@ append_to_reply("Foo: bar\r\n");
    Appends txt after the last header field.
 
    Meaning of the parameters is as follows:
-     * hf - Header field to be appended.
+     * hf - Header field to be appended. Xl_lib formatting supported.
 
    Example 8. append_hf usage
 ...
@@ -148,8 +172,10 @@ append_hf("P-hint: VOICEMAIL\r\n");
    Append header field name with original Request-URI in middle.
 
    Meaning of the parameters is as follows:
-     * prefix - string (usually at least header field name).
-     * suffix - string (usually at least line terminator).
+     * prefix - string (usually at least header field name). Xl_lib
+       formatting supported.
+     * suffix - string (usually at least line terminator). Xl_lib
+       formatting supported.
 
    Example 9. append_urihf usage
 ...
@@ -162,8 +188,7 @@ append_urihf("CC-Diversion: ", "\r\n");
 
 Note
 
-   Takes header field names "as is" and doesn't distinguish compact
-   names.
+   Takes header field names "as is" and doesn't distinguish compact names.
 
    Meaning of the parameters is as follows:
      * hf_name - Header field name.
@@ -187,3 +212,240 @@ if (method == "REGISTER" ) {
     append_time();
 };
 ...
+
+1.2.12.  remove_hf(hf_name)
+
+   Remove from the message all the headers with the specified name.
+
+   Meaning of the parameters is as follows:
+     * hf_name - Header field name to be removed.
+
+   Example 12. remove_hf usage
+...
+remove_hf("Subject")  # strip all headers whose name is "Subject".
+...
+
+1.2.13.  remove_hf_re(reg_exp)
+
+   Remove from the message all the headers whose names match a given
+   regular expression.
+
+   Meaning of the parameters is as follows:
+     * reg_exp - Regular expression that is matched against header name
+       fields.
+
+   Example 13. remove_hf_re usage
+...
+remove_hf_re("Subject|P-.*|X-.*")  # strip all headers whose names match
+"Subject", contain "P-" or "X-".
+...
+
+1.2.14.  append_hf_value(hf, xl_value)
+
+   Append new header value after an existing header, if no index acquired
+   append at the end of list. Note that a header may consist of comma
+   delimited list of values.
+
+   Meaning of the parameters is as follows:
+     * hf - Header field to be appended. Format: HFNAME [ [IDX] ]. If
+       index is not specified new header is inserted at the end of
+       message.
+     * xl_value - Value to be added, xl_lib formatting supported.
+
+   Example 14. append_hf_value usage
+...
+append_hf_value("foo", "gogo;stamp=%Ts")   # add new header
+append_hf_value("foo[1]", "gogo")  # add new value behind first value
+append_hf_value("foo[-1]", "%@Bar") # try add value to the last header, if not e
+xists add new header
+...
+
+1.2.15.  insert_hf_value(hf, xl_value)
+
+   Insert new header value before an existing header, if no index acquired
+   insert before first hf header. Note that a header may consist of comma
+   delimited list of values. To insert value behing last value use
+   appenf_hf_value.
+
+   Meaning of the parameters is as follows:
+     * hf - Header field to be appended. Format: HFNAME [ [IDX] ]. If
+       index is not specified new header is inserted at the top of
+       message.
+     * xl_value - Value to be added, xl_lib formatting supported.
+
+   Example 15. insert_hf_value usage
+...
+insert_hf_value("foo[2]", "gogo")
+insert_hf_value("foo", "%$an_avp")   # add new header at the top of list
+insert_hf_value("foo[1]", "gogo") # try add to the first header
+...
+
+1.2.16.  remove_hf_value(hf_par)
+
+   Remove the header value from existing header, Note that a header may
+   consist of comma delimited list of values.
+
+   Meaning of the parameters is as follows:
+     * hf_par - Header field/param to be removed. Format: HFNAME [ [IDX] ]
+       [. PARAM ] If asterisk is specified as index then all values are
+       affected.
+
+   Example 16. remove_hf_value usage
+...
+remove_hf_value("foo")  # remove foo[1]
+remove_hf_value("foo[*]")  # remove all foo's headers
+remove_hf_value("foo[-1]") # last foo
+remove_hf_value("foo.bar")  # delete parameter
+remove_hf_value("foo[*].bar") # for each foo delete bar parameters
+...
+
+1.2.17.  remove_hf_value2(hf_par)
+
+   Remove specified header or parameter. It is expected header in
+   Authorization format (comma delimiters are not treated as multi-value
+   delimiters).
+
+   Meaning of the parameters is as follows:
+     * hf_par - Header/param to be removed. Format: HFNAME [ [IDX] ] [.
+       PARAM ] If asterisk is specified as index then all values are
+       affected.
+
+   Example 17. remove_hf_value2 usage
+...
+remove_hf_value2("foo")  # remove foo[1]
+remove_hf_value2("foo[*]")  # remove all foo's headers, the same as remove_hf_he
+ader("foo[*]");
+remove_hf_value2("foo[-1]") # last foo
+remove_hf_value2("foo.bar")  # delete parameter
+remove_hf_value2("foo[*].bar") # for each foo delete bar parameters
+...
+
+1.2.18.  assign_hf_value(hf, xl_value)
+
+   Assign value to specified header value / param.
+
+   Meaning of the parameters is as follows:
+     * hf_para - Header field value / param to be appended. Format: HFNAME
+       [ [IDX] ] [. PARAM] If asterisk is specified as index then all
+       values are affected.
+     * xl_value - Value to be assigned, xl_lib formatting supported. If
+       value is empty then no equal sign apears in param.
+
+   Example 18. assign_hf_value usage
+...
+assign_hf_value("foo", "gogo")  # foo[1]
+assign_hf_value("foo[-1]", "gogo")  # foo[last_foo]
+
+assign_hf_value("foo.bar", "")
+assign_hf_value("foo[3].bar", "")
+assign_hf_value("foo[*]", "")  # remove all foo's, empty value remains
+assign_hf_value("foo[*].bar", "")  # set empty value (ex. lr)
+...
+
+1.2.19.  assign_hf_value2(hf, xl_value)
+
+   Assign value to specified header. It is expected header in
+   Authorization format (comma delimiters are not treated as multi-value
+   delimiters).
+
+   Meaning of the parameters is as follows:
+     * hf_para - Header field value / param to be appended. Format: HFNAME
+       [ [IDX] ] [. PARAM] If asterisk is specified as index then all
+       values are affected.
+     * xl_value - Value to be assigned, xl_lib formatting supported. If
+       value is empty then no equal sign apears in param.
+
+   Example 19. assign_hf_value2 usage
+...
+assign_hf_value2("Authorization.integrity-protected", "\"yes\"")
+assign_hf_value2("foo[-1]", "gogo")  # foo[last_foo]
+assign_hf_value2("foo[*].bar", "")  # set empty value (ex. lr)
+...
+
+1.2.20.  include_hf_value(hf, xl_value)
+
+   Add value in set if not exists, eg. "Supported: path,100rel".
+
+   Meaning of the parameters is as follows:
+     * hf - Header field name to be affected.
+     * value - xl_lib formatting supported.
+
+   Example 20. include_hf_value usage
+...
+include_hf_value("Supported", "path");
+...
+
+1.2.21.  exclude_hf_value(hf, xl_value)
+
+   Remove value from set if exists, eg. "Supported: path,100rel".
+
+   Meaning of the parameters is as follows:
+     * hf - Header field name to be affected.
+     * value - xl_lib formatting supported.
+
+   Example 21. exclude_hf_value usage
+...
+exclude_hf_value("Supported", "100rel");
+...
+
+1.2.22.  hf_value_exists(hf, xl_value)
+
+   Check if value exists in set. Alternate select
+   @hf_value_exists.HF.VALUE may be used. It returns one or zero.
+
+   Meaning of the parameters is as follows:
+     * hf - Header field name to be affected. Underscores are treated as
+       dashes.
+     * value - xl_lib formatting supported.
+
+   Example 22. hf_value_exists usage
+...
+if (hf_value_exists("Supported", "100rel")) {
+
+}
+
+if (@hf_value_exists.supported.path == "1") {
+
+}
+...
+
+1.2.23.  @hf_value selects
+
+   Get value of required header-value or param. Note that functions called
+   'value2' works with Authorization-like headers where comma is not
+   treated as value delimiter. Formats: @hf_value.HFNAME[IDX] # idx value,
+   negative value counts from bottom @hf_value.HFNAME.PARAM_NAME
+   @hf_value.HFNAME[IDX].PARAM_NAME @hf_value.HFNAME.p.PARAM_NAME # or
+   .param., useful if requred called "uri", "p", "param"
+   @hf_value.HFNAME[IDX].p.PARAM_NAME # dtto @hf_value.HFNAME[IDX].uri #
+   (< & > excluded) @hf_value.HFNAME[*] # return comma delimited list of
+   all values (combines headers) @hf_value.HFNAME # the same as above [*]
+   but may be parsed by cfg.y @hf_value.HFNAME[*].uri # return comma
+   delimited list of uris (< & > excluded) @hf_value.HFNAME.uri # the same
+   as above [*] but may be parsed by cfg.y @hf_value.HFNAME[IDX].name #
+   returns name part, quotes excluded @hf_value.HFNAME.name # returns name
+   part of the first value @hf_value2.HFNAME # returns value of first
+   header @hf_value2.HFNAME[IDX] # returns value of idx's header
+   @hf_value2.HFNAME.PARAM_NAME @hf_value2.HFNAME[IDX].PARAM_NAME
+   @hf_value.HFNAME[IDX].uri # return URI, quotes excluded
+   @hf_value.HFNAME.p.uri # returns param named uri, not URI itself
+   @hf_value.HFNAME.p.name # returns param named name, not name itself
+   @hf_value.HFNAME[IDX].uri.name # any sel_any_uri nested features may be
+   used @hf_value.HFNAME[IDX].nameaddr.name # select_any_nameaddr
+
+   Meaning of the parameters is as follows:
+     * HFNAME - Header field name. Underscores are treated as dashes.
+     * IDX - Value index, negative value counts from bottom
+     * PARAM_NAME - name of parameter
+
+   Example 23. @hf_value select usage
+...
+$a = @hf_value.my_header[1].my_param;
+xlog("L_ERR", "%@hf_value.via[-1], %@hf_value.from.tag\n");
+$b = @hf_value.p_associated_uri;
+
+xlog("L_ERR", "Route uris: '%@hf_value.route[*].uri'\n");
+$rr = @hf_value.route.uri;
+
+$prt = @hf_value2.authorization.integrity_protected;
+...

modules_s/textops/doc/functions.xml

@@ -636,36 +636,6 @@ if (hf_value_exists("Supported", "100rel")) {
 
 if (@hf_value_exists.supported.path == "1") {
 
-}
-...
-	    </programlisting>
-	</example>
-    </section>
-
-    <section id="change_reply_status">
-	<title>
-	    <function>change_reply_status(code, reason)</function>
-	</title>
-	<para>
-		Change the status code and reason phrase of a SIP reply in onreply_route.
-	</para>
-	<para>Meaning of the parameters is as follows:</para>
-	<itemizedlist>
-	    <listitem>
-		<para><emphasis>code</emphasis> - Status code.
-		</para>
-	    </listitem>
-	    <listitem>
-		<para><emphasis>reason</emphasis> - Reason phrase.
-		</para>
-	    </listitem>
-	</itemizedlist>
-	<example>
-	    <title><function>change_reply_status</function> usage</title>
-	    <programlisting>
-...
-if (@status == "603") {
-	change_reply_status(404, "Not Found")
 }
 ...
 	    </programlisting>

modules_s/textops/textops.c

@@ -115,7 +115,6 @@ static int append_to_reply_f(struct sip_msg* msg, char* key, char* str);
 static int append_hf(struct sip_msg* msg, char* str1, char* str2);
 static int append_urihf(struct sip_msg* msg, char* str1, char* str2);
 static int append_time_f(struct sip_msg* msg, char* , char *);
-static int change_reply_status_f(struct sip_msg* msg, char* , char *);
 
 static int incexc_hf_value_f(struct sip_msg* msg, char* , char *);
 static int include_hf_value_fixup(void**, int);
@@ -131,7 +130,6 @@ static int remove_hf_value2_fixup(void** param, int param_no);
 static int assign_hf_value2_fixup(void** param, int param_no);
 static int fixup_xlstr(void** param, int param_no);
 static int fixup_regex_xlstr(void** param, int param_no);
-static int change_reply_status_fixup(void** param, int param_no);
 
 static int fixup_substre(void**, int);
 
@@ -191,8 +189,6 @@ static cmd_export_t cmds[]={
 			REQUEST_ROUTE|ONREPLY_ROUTE|FAILURE_ROUTE|BRANCH_ROUTE},
 	{"hf_value_exists",  incexc_hf_value_f,      2, hf_value_exists_fixup,
 			REQUEST_ROUTE|ONREPLY_ROUTE|FAILURE_ROUTE|BRANCH_ROUTE},
-	{"change_reply_status",	change_reply_status_f,	2, change_reply_status_fixup,
-			ONREPLY_ROUTE},
 
 	{0,0,0,0,0}
 };
@@ -1741,76 +1737,6 @@ static int assign_hf_value2_fixup(void** param, int param_no) {
 	return 0;
 }
 
-static int change_reply_status_fixup(void** param, int param_no)
-{
-	if (param_no == 1) {
-		return fixup_var_int_12(param, param_no);
-	} else if (param_no == 2)
-		return fixup_var_str_12(param, param_no);
-	else
-		return 0;
-}
-
-static int change_reply_status_f(struct sip_msg* msg, char* _code, char* _reason)
-{
-	int	code;
-	str	reason;
-	struct lump	*l;
-	char	*ch;
-
-	if (get_int_fparam(&code, msg, (fparam_t*)_code)
-		|| get_str_fparam(&reason, msg, (fparam_t*)_reason)
-		|| (reason.len == 0)
-	) {
-		LOG(L_ERR, "ERROR: textops: cannot get parameter\n");
-		return -1;
-	}
-
-	if ((code < 100) || (code > 699)) {
-		LOG(L_ERR, "ERROR: textops: wrong status code: %d\n",
-				code);
-		return -1;
-	}
-
-	if (((code < 300) || (msg->REPLY_STATUS < 300))
-		&& (code/100 != msg->REPLY_STATUS/100)
-	) {
-		LOG(L_ERR, "ERROR: textops: the class of provisional or "
-			"positive final replies cannot be changed\n");
-		return -1;
-	}
-
-	/* rewrite the status code directly in the message buffer */
-	msg->first_line.u.reply.statuscode = code;
-	msg->first_line.u.reply.status.s[2] = code % 10 + '0'; code /= 10;
-	msg->first_line.u.reply.status.s[1] = code % 10 + '0'; code /= 10;
-	msg->first_line.u.reply.status.s[0] = code + '0';
-
-	l = del_lump(msg,
-		msg->first_line.u.reply.reason.s - msg->buf,
-		msg->first_line.u.reply.reason.len,
-		0);
-	if (!l) {
-		LOG(L_ERR, "ERROR: textops(): Failed to add del lump\n");
-		return -1;
-	}
-	/* clone the reason phrase, the lumps need to be pkg allocated */
-	ch = (char *)pkg_malloc(reason.len);
-	if (!ch) {
-		LOG(L_ERR, "ERROR: textops: Not enough memory\n");
-		return -1;
-	}
-	memcpy(ch, reason.s, reason.len);
-	if (insert_new_lump_after(l, ch, reason.len, 0)==0){
-		LOG(L_ERR, "ERROR: textops: failed to add new lump: %.*s\n",
-			reason.len, ch);
-		pkg_free(ch);
-		return -1;
-	}
-
-	return 1;
-}
-
 static int sel_hf_value(str* res, select_t* s, struct sip_msg* msg) {  /* dummy */
 	return 0;
 }