$Revision: 1.12 $
$Date: 2006/07/03 10:37:49 $

# Functions

## `search(re)`

Searches for the re in the message.

Meaning of the parameters is as follows:

- re - Regular expression.

### `search` usage

    ...
    if ( search("[Ss][Ee][Rr]" ) { /*....*/ };
    ...

## `search_append(re, txt)`

Searches for the first match of re and appends txt after it.

Meaning of the parameters is as follows:

- re - Regular expression.

- txt - String to be appended. Xl_lib formatting supported.

### `search_append` usage

    ...
    search_append("[Ss]er", " blabla");
    ...

## `replace(re, txt)`

Replaces the first occurrence of re with txt.

Meaning of the parameters is as follows:

- re - Regular expression.

- txt - String. Xl_lib formatting supported.

### `replace` usage

    ...
    replace("ser", "Sip Express Router");
    ...

## `subst('/re/repl/flags')`

Replaces re with repl (sed or perl like).

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).

### `subst` usage

    ...
    # replace the uri in to: with the message uri (just an example)
    if ( subst('/^To:(.*)sip:[^@]*@[a-zA-Z0-9.]+(.*)$/t:\1\u\2/ig') ) {};
    ...

## `subst_uri('/re/repl/flags')`

Runs the re substitution on the message uri (like subst but works only on the uri)

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).

### `subst` usage

    ...
    # adds 3463 prefix to numeric uris, and save the original uri (\0 match)
    # as a parameter: orig_uri (just an example)
    if (subst_uri('/^sip:([0-9]+)@(.*)$/sip:3463\1@\2;orig_uri=\0/i')){$
    ...

## `subst_user('/re/repl/flags')`

Runs the re substitution on the message uri (like subst_uri but works only on the user portion of the uri)

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).

### `subst` usage

    ...
    # adds 3463 prefix to uris ending with 3642 (just an example)
    if (subst_user('/3642$/36423463/')){$
    ...

## `append_to_reply(txt)`

Append txt to the reply.

Meaning of the parameters is as follows:

- txt - String. Xl_lib formatting supported.

### `append_to_reply` usage

    ...
    append_to_reply("Foo: bar\r\n");
    ...

## `append_hf(hf)`

Appends txt after the last header field.

Meaning of the parameters is as follows:

- hf - Header field to be appended. Xl_lib formatting supported.

### `append_hf` usage

    ...
    append_hf("P-hint: VOICEMAIL\r\n");
    ...

## `append_urihf(prefix, suffix)`

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). Xl_lib formatting supported.

- suffix - string (usually at least line terminator). Xl_lib formatting supported.

### `append_urihf` usage

    ...
    append_urihf("CC-Diversion: ", "\r\n");
    ...

## `is_present_hf(hf_name)`

Return true if a header field is present in message.

Takes header field names "as is" and doesn't distinguish compact names.

Meaning of the parameters is as follows:

- hf_name - Header field name.

### `is_present_hf` usage

    ...
    if (is_present_hf("From")) log(1, "From HF Present");
    ...

## `append_time()`

Append "Date" header containing the current date and time to the reply generated by SER.

### `is_present_hf` usage

    ...
    if (method == "REGISTER" ) {
        # Many user agents can use the Date header field
        # in 200 OK replies to REGISTER to synchronize
        # internal clock
        apppend_date();
    };
    ...

## `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.

### `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 exists add new header
    ...

## `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.

### `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
    ...

## `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.

### `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
    ...

## `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.

### `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_header("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
    ...

## `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.

### `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)
    ...

## `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.

### `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)
    ...

## `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.

### `include_hf_value` usage

    ...
    include_hf_value("Supported", "path");
    ...

## `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.

### `exclude_hf_value` usage

    ...
    exclude_hf_value("Supported", "100rel");
    ...

## `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.

### `hf_value_exists` usage

    ...
    if (hf_value_exists("Supported", "100rel")) {

    }

    if (@hf_value_exists.supported.path == "1") {

    }
    ...

## `@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

### `@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;
    ...