Documentation

Documentation.Script-Syntax-3-0 History

Hide minor edits - Show changes to markup

August 29, 2019, at 12:20 PM by liviu -
August 29, 2019, at 12:20 PM by liviu -
Changed line 165 from:

Literal "$" characters can be included in a format string using the "$$" escape sequence

to:

Note: literal "$" characters can be included in a format string using the "$$" escape sequence

August 29, 2019, at 12:20 PM by liviu -
Added lines 162-165:


Literal "$" characters can be included in a format string using the "$$" escape sequence

August 04, 2019, at 10:58 AM by liviu -
Changed line 165 from:
  • output variables which need to be passed to functions MUST NOT be quoted:
to:
  • input or output variables passed to functions must not be quoted:
August 04, 2019, at 10:35 AM by liviu -
Changed line 165 from:
  • variables which need to be passed to functions mandating them need NOT be quoted:
to:
  • output variables which need to be passed to functions MUST NOT be quoted:
August 04, 2019, at 10:33 AM by liviu -
Changed line 134 from:

Summary: OpenSIPS core functions are very useful, but also often inflexible: their parameters must have the exact type(s) as expected by the language grammar. There are plans to align the core function and module function interfaces (the latter is more powerful, see below) -- this work is scheduled for OpenSIPS 3.1. Script writers are advised to carefully consult the specifics of each core function while keeping in mind that consistency across core functions, if any, is only due to diligent collaboration between OpenSIPS developers, and is not the result of some internal programming interface.

to:

Summary: OpenSIPS core functions are very useful, but are often inflexible: their parameters must have the exact type(s) as expected by the language grammar. There are plans to align the core function and module function interfaces (the latter is more powerful, see below) -- this work is scheduled for OpenSIPS 3.1. Script writers are advised to carefully consult the specifics of each core function while keeping in mind that consistency across core functions, if any, is only due to diligent collaboration between OpenSIPS developers, and is not the result of some internal programming interface.

May 24, 2019, at 07:15 PM by liviu -
Changed line 134 from:

Summary: OpenSIPS core functions are very useful, but also inflexible: their parameters must have the exact type(s) as expected by the language grammar. There are plans to align the core function and module function interfaces (the latter is more powerful, see below) -- this work is scheduled for OpenSIPS 3.1. Script writers are advised to carefully consult the specifics of each core function while keeping in mind that consistency across core functions, if any, is only due to diligent collaboration between OpenSIPS developers, and is not the result of some internal programming interface.

to:

Summary: OpenSIPS core functions are very useful, but also often inflexible: their parameters must have the exact type(s) as expected by the language grammar. There are plans to align the core function and module function interfaces (the latter is more powerful, see below) -- this work is scheduled for OpenSIPS 3.1. Script writers are advised to carefully consult the specifics of each core function while keeping in mind that consistency across core functions, if any, is only due to diligent collaboration between OpenSIPS developers, and is not the result of some internal programming interface.

April 25, 2019, at 06:29 PM by 109.99.227.30 -
Changed line 102 from:

Core Functions

to:

Core Functions

April 25, 2019, at 06:28 PM by 109.99.227.30 -
Changed line 136 from:

Module Functions

to:

Module Functions

April 17, 2019, at 11:29 PM by liviu -
Changed line 3 from:

This page has been visited 7260 times.

to:
April 17, 2019, at 11:29 PM by liviu -
Added line 3:

This page has been visited 7260 times.

Added line 6:
April 17, 2019, at 08:59 AM by liviu -
Changed line 83 from:
  • integer (32-bit, signed).
to:
  • integer (32-bit, signed).
Changed line 86 from:
  • string (unlimited size)
to:
  • string (unlimited size)
Added line 88:
  • double (packed as string), through the mathops module
April 17, 2019, at 08:57 AM by liviu -
Added lines 81-82:

Basic

Added lines 88-92:

Complex

  • list via the $avp variable
  • map via the $json and $xml variables
April 17, 2019, at 08:50 AM by liviu -
Added lines 160-161:

\\

April 17, 2019, at 08:50 AM by liviu -
Added lines 159-168:

@]

  • integers no longer need to be passed as double-quoted strings:
ds_select_dst("1", "1");

[@ ds_select_dst(1, 1);

April 17, 2019, at 08:43 AM by liviu -
Changed line 94 from:

The core functions are always available at script level, since they are baked into the opensips binary. Currently, the calling convention for these functions varies greatly from one function to another, since each function is individually provided by the language parser.

to:

The core functions are always available at script level, since they are baked into the opensips binary. The calling convention for these functions varies greatly from one function to another, since each function is individually provided by the language parser.

April 17, 2019, at 01:02 AM by liviu -
Changed line 147 from:
  • any string function parameter can be passed as a format string
to:
  • any string function parameter can also be passed as a format string
April 17, 2019, at 01:01 AM by liviu -
Changed line 128 from:

Module functions become available for OpenSIPS script writers to use once their respective modules are loaded via the loadmodule statement (see the "Script Format" section above). All module functions internally share the same function interface, such that they benefit from the following, more sophisticated calling convention:

to:

Module functions become available for OpenSIPS script writers to use once their respective modules are loaded via the loadmodule statement (see the "Script Format" section above). All module functions implement the same internal function interface, such that they benefit from the following, more sophisticated calling convention:

April 17, 2019, at 01:00 AM by liviu -
Changed line 124 from:

Summary: OpenSIPS core functions are very useful, but also inflexible: their parameters must have the exact type(s) as expected by the language grammar. There are plans to align the core function and module function interfaces (the latter is more powerful, see below) -- this work is scheduled for OpenSIPS 3.1. Script writers are advised to carefully consult the specifics of each core function while keeping in mind that consistency across core functions, if any, is only due to careful collaboration between OpenSIPS developers, and is not the result of some internal programming interface.

to:

Summary: OpenSIPS core functions are very useful, but also inflexible: their parameters must have the exact type(s) as expected by the language grammar. There are plans to align the core function and module function interfaces (the latter is more powerful, see below) -- this work is scheduled for OpenSIPS 3.1. Script writers are advised to carefully consult the specifics of each core function while keeping in mind that consistency across core functions, if any, is only due to diligent collaboration between OpenSIPS developers, and is not the result of some internal programming interface.

April 16, 2019, at 09:07 PM by liviu -
Added line 87:

April 16, 2019, at 08:13 PM by liviu -
Changed line 123 from:

Summary: OpenSIPS core functions are very useful, but also inflexible: their parameters must have the exact type as expected by the language grammar. There are plans to align the core function and module function interfaces (the latter is more powerful, see below) -- this work is scheduled for OpenSIPS 3.1. Script writers are advised to carefully consult the specifics of each core function while keeping in mind that consistency across core functions, if any, is only due to careful collaboration between OpenSIPS developers, and is not the result of some internal programming interface.

to:

Summary: OpenSIPS core functions are very useful, but also inflexible: their parameters must have the exact type(s) as expected by the language grammar. There are plans to align the core function and module function interfaces (the latter is more powerful, see below) -- this work is scheduled for OpenSIPS 3.1. Script writers are advised to carefully consult the specifics of each core function while keeping in mind that consistency across core functions, if any, is only due to careful collaboration between OpenSIPS developers, and is not the result of some internal programming interface.

April 16, 2019, at 08:12 PM by liviu -
Changed line 123 from:

Summary: OpenSIPS core functions are very useful, but also inflexible: their parameters must have the exact type as expected by the language grammar. There are plans to align the core function and module function interfaces (the latter is more powerful, see below) -- this work is scheduled for OpenSIPS 3.1. Script writers are advised to carefully consult the specifics of each core function while keeping in mind that consistency across core functions, if any, is only due to careful collaboration between OpenSIPS developers, and not imposed by some strict internal programming interface.

to:

Summary: OpenSIPS core functions are very useful, but also inflexible: their parameters must have the exact type as expected by the language grammar. There are plans to align the core function and module function interfaces (the latter is more powerful, see below) -- this work is scheduled for OpenSIPS 3.1. Script writers are advised to carefully consult the specifics of each core function while keeping in mind that consistency across core functions, if any, is only due to careful collaboration between OpenSIPS developers, and is not the result of some internal programming interface.

April 16, 2019, at 08:11 PM by liviu -
Changed line 123 from:

Summary: OpenSIPS core functions are very useful, but also inflexible: their parameters must have the exact type as expected by the language grammar. There are plans to align the core function and module function interfaces (the latter is more powerful, see below) -- this work is scheduled for OpenSIPS 3.1. Script writers are advised to carefully consult the specifics of each such function.

to:

Summary: OpenSIPS core functions are very useful, but also inflexible: their parameters must have the exact type as expected by the language grammar. There are plans to align the core function and module function interfaces (the latter is more powerful, see below) -- this work is scheduled for OpenSIPS 3.1. Script writers are advised to carefully consult the specifics of each core function while keeping in mind that consistency across core functions, if any, is only due to careful collaboration between OpenSIPS developers, and not imposed by some strict internal programming interface.

April 16, 2019, at 08:07 PM by liviu -
Changed line 89 from:

OpenSIPS script writers build their scripting logic using functions. Currently, there are two types of functions:

to:

A significant portion of opensips.cfg scripting logic consists of functions. Currently, there are two types of functions:

April 16, 2019, at 07:57 PM by liviu -
Added lines 129-130:


Added lines 144-145:


Added lines 151-152:

\\

April 16, 2019, at 07:56 PM by liviu -
Changed line 93 from:

The core functions are always available at script level, since they are part of the opensips binary. Currently, the calling convention for these functions varies greatly from one function to another, since each function is individually provided by the language parser.

to:

The core functions are always available at script level, since they are baked into the opensips binary. Currently, the calling convention for these functions varies greatly from one function to another, since each function is individually provided by the language parser.

April 16, 2019, at 07:55 PM by liviu -
Changed line 123 from:

Summary: OpenSIPS core functions are very useful, but also inflexible: their parameters must have the exact type as expected by the language grammar. In recent years, little to no additional core functions have been added, as the majority of efforts have been focused towards module functions, which have more powerful calling conventions. There are plans to align the core function and module function interfaces -- this work is scheduled for OpenSIPS 3.1. Script writers are advised to carefully consult the specifics of each such function.

to:

Summary: OpenSIPS core functions are very useful, but also inflexible: their parameters must have the exact type as expected by the language grammar. There are plans to align the core function and module function interfaces (the latter is more powerful, see below) -- this work is scheduled for OpenSIPS 3.1. Script writers are advised to carefully consult the specifics of each such function.

April 16, 2019, at 07:54 PM by liviu -
Changed lines 123-125 from:

Note: OpenSIPS core functions are NOT flexible: their parameters must have the exact type as expected by the language grammar. In recent years, little to no additional core functions have been added, as the majority of efforts have been focused towards module functions, which have more powerful calling conventions. There are plans to align the core function and module function interfaces -- this work is scheduled for OpenSIPS 3.1.

Summary: although core functions are extremely useful, their calling convention is inflexible. Script writers are advised to carefully consult the specifics of each such function.

to:

Summary: OpenSIPS core functions are very useful, but also inflexible: their parameters must have the exact type as expected by the language grammar. In recent years, little to no additional core functions have been added, as the majority of efforts have been focused towards module functions, which have more powerful calling conventions. There are plans to align the core function and module function interfaces -- this work is scheduled for OpenSIPS 3.1. Script writers are advised to carefully consult the specifics of each such function.

April 16, 2019, at 07:53 PM by liviu -
Changed lines 111-112 from:

... will look up "my_counter" within Redis and return the results in $avp(redis_counter_val). Notice how the output parameter is unquoted for this function, while the initial one had a similar meaning, yet mandated quotes.

to:

... will look up "my_counter" within Redis and return the results in $avp(redis_counter_val). Notice how the output parameter is unquoted for this function, while the previous one, cache_raw_query(), had a similar meaning for its equivalent parameter, yet mandated quotes.

Changed lines 123-124 from:

Note: OpenSIPS core functions are NOT flexible: their parameters must have the exact type as expected by the language grammar. In recent years, very few core functions have been added, as the majority of efforts have been focused towards module functions, which have more powerful calling conventions. There are plans to align the core function and module function interfaces -- this work is scheduled for OpenSIPS 3.1.

to:

Note: OpenSIPS core functions are NOT flexible: their parameters must have the exact type as expected by the language grammar. In recent years, little to no additional core functions have been added, as the majority of efforts have been focused towards module functions, which have more powerful calling conventions. There are plans to align the core function and module function interfaces -- this work is scheduled for OpenSIPS 3.1.

Summary: although core functions are extremely useful, their calling convention is inflexible. Script writers are advised to carefully consult the specifics of each such function.

Changed lines 154-156 from:

@]

to:

@]

Summary: module functions currently benefit from a more powerful calling convention than core functions. This enables a greater flexibility when passing parameters to these functions, while additionally ensuring a greater degree of consistency across all such functions.

April 16, 2019, at 07:37 PM by liviu -
Added lines 95-96:
Example core function calls:
Deleted lines 98-100:

Example core function calls:

Changed lines 111-112 from:

... will look up "my_counter" within Redis and return the results in $avp(redis_counter_val).

to:

... will look up "my_counter" within Redis and return the results in $avp(redis_counter_val). Notice how the output parameter is unquoted for this function, while the initial one had a similar meaning, yet mandated quotes.

Added lines 120-121:

\\

April 16, 2019, at 07:35 PM by liviu -
Changed line 93 from:

The core functions are always available at script level, since they are part of the opensips binary. Currently, the calling convention for these functions varies greatly from one function to another, since each function is directly provided by the internal Yacc parser.

to:

The core functions are always available at script level, since they are part of the opensips binary. Currently, the calling convention for these functions varies greatly from one function to another, since each function is individually provided by the language parser.

April 16, 2019, at 07:34 PM by liviu -
Changed line 93 from:

The core functions are always available at script level, since they are part of the opensips binary. The calling convention for these functions varies greatly from one function to another, since each function is provided by the internal Yacc parser.

to:

The core functions are always available at script level, since they are part of the opensips binary. Currently, the calling convention for these functions varies greatly from one function to another, since each function is directly provided by the internal Yacc parser.

April 16, 2019, at 07:33 PM by liviu -
Changed lines 8-9 from:
Script Format v3.0
to:
Script Syntax v3.0
Added lines 11-12:

(:toc-float Table of Content:)

Changed lines 15-16 from:

The OpenSIPs configuration script has three main logical parts :

to:

Script Format

The OpenSIPs configuration script has three main logical parts:

Changed lines 75-151 from:

See the description of the route directive.

to:

See the description of the route directive.

Data Types

The OpenSIPS scripting language supports the following data types:

  • integer (32-bit, signed).
    • Max value: +2,147,483,647 == 2 ^ 31 - 1
    • Min value: -2,147,483,648 == - 2 ^ 31
  • string (unlimited size)
    • note that some functions which use strings may have internal buffers which limit the maximum size of the strings (e.g. the xlog() function's output buffer is configurable via xlog_buf_size)

Function Calling Conventions

OpenSIPS script writers build their scripting logic using functions. Currently, there are two types of functions:

Core Functions

The core functions are always available at script level, since they are part of the opensips binary. The calling convention for these functions varies greatly from one function to another, since each function is provided by the internal Yacc parser.


Example core function calls:

cache_raw_query("mongodb", "{ \"op\" : \"count\",\"query\": { \"username\" : $rU} }", "$avp(mongo_count_result)");

... will look up the specified document within MongoDB and return the results in $avp(mongo_count_result).


cache_fetch("redis:cluster1", "my_counter", $var(redis_counter_val));

... will look up "my_counter" within Redis and return the results in $avp(redis_counter_val).


force_send_socket(tcp:10.10.10.10:5060);

... will force the egress interface to be tcp:10.10.10.10:5060. Notice how its parameter is not a string -- in fact, it's a unique data type (a socket), as the Yacc grammar interprets it.

Note: OpenSIPS core functions are NOT flexible: their parameters must have the exact type as expected by the language grammar. In recent years, very few core functions have been added, as the majority of efforts have been focused towards module functions, which have more powerful calling conventions. There are plans to align the core function and module function interfaces -- this work is scheduled for OpenSIPS 3.1.

Module Functions

Module functions become available for OpenSIPS script writers to use once their respective modules are loaded via the loadmodule statement (see the "Script Format" section above). All module functions internally share the same function interface, such that they benefit from the following, more sophisticated calling convention:

  • any integer or string function parameter may also be passed using a "holder" variable
ds_select_dst(1, 1); 

... is equivalent to:

$var(x) = 1;
ds_select_dst($var(x), $var(x));
  • any string function parameter can be passed as a format string
set_dlg_profile("caller", "$var(country_code)_$var(area)_$fU");
  • variables which need to be passed to functions mandating them need NOT be quoted:
ds_count(1, "a", $var(out_result));
April 16, 2019, at 06:46 PM by liviu -
Changed lines 1-2 from:
Documentation -> Manuals -> Manual 3.0 -> Script Format

(:title Script Format - 3.0:)

to:
Documentation -> Manuals -> Manual 3.0 -> Script Syntax

(:title Script Syntax - 3.0:)

Changed line 4 from:

(:allVersions Script-Format 3.0:)

to:

(:allVersions Script-Syntax 3.0:)

May 03, 2016, at 08:40 AM by bsekerciler - fixed wrong ip addresses (368 => 168)
Changed lines 30-31 from:

listen = udp:193.068.3.00:5060 listen = udp:193.068.3.00:5070

to:

listen = udp:192.168.3.00:5060 listen = udp:192.168.3.00:5070

March 20, 2014, at 08:21 PM by razvancrainea -
Changed line 40 from:

In regards to the OpenSIPS modules,the modules that are to be loaded (no module is loaded by default) are specified by using the directive loadmodule. Modules are to be specified by name and an optional path (to the .so file). If no path is provided (and just the name of the module), the default path will be assumed for locating the loading the module (default path is /usr/lib/opensips/modules if not other one configured at compile time?. For configuring a different path, either the path is pushed directly with the module name (to get control per module) or it can be globally (for all modules) configured via the mpath global parameter.\\\

to:

In regards to the OpenSIPS modules,the modules that are to be loaded (no module is loaded by default) are specified by using the directive loadmodule. Modules are to be specified by name and an optional path (to the .so file). If no path is provided (and just the name of the module), the default path will be assumed for locating the loading the module (default path is /usr/lib/opensips/modules if not other one configured at compile time. For configuring a different path, either the path is pushed directly with the module name (to get control per module) or it can be globally (for all modules) configured via the mpath global parameter.\\\

March 20, 2014, at 08:18 PM by razvancrainea -
Added lines 1-71:
Documentation -> Manuals -> Manual 3.0 -> Script Format

(:title Script Format - 3.0:)


(:allVersions Script-Format 3.0:)


Script Format v3.0
PrevNext

The OpenSIPs configuration script has three main logical parts :

  1. global parameters
  2. modules section
  3. routing logic

Global parameters

Usually, in the first part, you declare the OpenSIPS global parameters - these global or core parameters are affecting the OpenSIPS core and possible the modules.

Configuring the network listeners, available transport protocols, forking (and number of processes), the logging and other global stuff is provided by these global parameters.

Example:

disable_tcp = yes
listen = udp:193.068.3.00:5060
listen = udp:193.068.3.00:5070
fork = yes
children = 4
log_stderror = no

Modules section

In regards to the OpenSIPS modules,the modules that are to be loaded (no module is loaded by default) are specified by using the directive loadmodule. Modules are to be specified by name and an optional path (to the .so file). If no path is provided (and just the name of the module), the default path will be assumed for locating the loading the module (default path is /usr/lib/opensips/modules if not other one configured at compile time?. For configuring a different path, either the path is pushed directly with the module name (to get control per module) or it can be globally (for all modules) configured via the mpath global parameter.

Once the modules are loaded, the parameters of the modules may be set using the modparam directive - to list of available parameters for each module, the type of parameter value (integer or string) can be found in the documentation of the modules, the Parameters section.

Examples:

loadmodule "modules/mi_datagram/mi_datagram.so"
modparam("mi_datagram", "socket_name", "udp:127.0.0.1:4343")
modparam("mi_datagram", "children_count", 3)

or

mpath="/usr/local/opensips_proxy/lib/modules"
loadmodule "mi_datagram.so"
modparam("mi_datagram", "socket_name", "udp:127.0.0.1:4343")
modparam("mi_datagram", "children_count", 3)
loadmodule "mi_fifo.so"
modparam("mi_fifo", "fifo_name", "/tmp/opensips_fifo")

Routing logic

The routing logic is actually a sum of routes (script routes) that contain the OpenSIPS logic for routing SIP traffic. The description of OpenSIPS behavior in relation to the SIP traffic is done via this routes.

There are different types of routes :

  1. top routes - routes that are directly triggered by OpenSIPs when some events occurs (like SIP request received, SIP reply received, transaction failed, etc)
  2. sub-routes - routes that are triggered / used from other routes in script.


What are the existing top routes, when they are triggered, what kind of SIP messages is handled, what SIP operations are allowed and other are documented in the types of routes section.

The sub-routes have names and they are to be called from any other route (top or sub) in the script via their names. The sub-routes may take parameters (when called) or return a numerical code (avoid returning 0 value as this will terminate your whole script. The sub-routes are similar to functions / procedure in any programing language. See the description of the route directive.


Page last modified on August 29, 2019, at 12:20 PM