Table of Contents
List of Tables
List of Examples
pretty_printing parametertrace_destination parametertrace_destination parametermi without paramsmi with params in commandmi with returnmi without return but with indexed paramsmi with return and named parametersmi without return, with an array parameter valueasync mi call usageThis module provides multiple hooks to run Management Interface commands directly from OpenSIPS script. It supports running both synchronous and asynchronous commands. Depending on the nature of the command (asynchronous or not), and on the way the mi command is run from script, the returned result is different.
In case of success, the MI command returns with success. If a return variable is provided as parameter, a JSON is also stored in the variable provided.
In case of failure of the MI command, JSON-RPC reply error code is stored in the $rc variable, as a negative number. Lower values, such as -1,-2,-3 can also be returned to indicate an internal error. If a return variable is provided, it is stored to the error description.
The following modules must be loaded before this module:
proto_hep module, in case MI tracing is used.
Indicates whether the JSON responses stored in the return variable should be pretty-printed or not.
Default value is “0 - no pretty-printing”.
Trace destination as defined in the tracing module. Currently the only tracing module is proto_hep. This is where traced mi messages will go.
WARNING: A tracing module must be loaded in order for this parameter to work. (for example proto_hep).
Default value is none(not defined).
Example 1.2. Set trace_destination parameter
...
modparam("proto_hep", "trace_destination", "[hep_dest]10.0.0.2;transport=tcp;version=3")
modparam("mi_stream", "trace_destination", "hep_dest")
...
Filter traced mi commands based on a blacklist or a whitelist. trace_destination must be defined for this parameter to have any purpose. Whitelists can be defined using 'w' or 'W', blacklists using 'b' or 'B'. The type is separate by the actual blacklist by ':'. The mi commands in the list must be separated by ','.
Defining a blacklists means all the commands that are not blacklisted will be traced. Defining a whitelist means all the commands that are not whitelisted will not be traced. WARNING: One can't define both a whitelist and a blacklist. Only one of them is allowed. Defining the parameter a second time will just overwrite the first one.
WARNING: A tracing module must be loaded in order for this parameter to work. (for example proto_hep).
Default value is none(not defined).
Example 1.3. Set trace_destination parameter
...
## blacklist ps and which mi commands
## all the other commands shall be traced
modparam("mi_stream", "trace_bwlist", "b: ps, which")
...
## allow only sip_trace mi command
## all the other commands will not be traced
modparam("mi_stream", "trace_bwlist", "w: sip_trace")
...
Runs an MI command in synchronous mode, blocking until a response is available.
IMPORTANT: it is highly recommended to prevent using this function for tasks that take long time, such as reloads, as the function would block until the command ends. Moreover, if the running MI command is configured to run in asynchronous mode (such as t_uac_dlg the command blocks in a busy waiting manner until the response is received.
This function can be used in any route.
The function can receive the following parameters:
command(string) - the MI command to be run. This can be a single token, representing the MI command to run (without parameters), or can be followed by several space separated parameters (no escaping is handled). Each space separated parameter will be passed to the MI command as an indexed parameter.
NOTE: named parameters can not be specified using this parameter, and you will have to use the params_avp and/or the vals_avp parameters to specify named commands, in which case this parameter will only consist of the MI command.
ret_var(var, optional) - a variable used to store the return of the MI command execution. In case of success, a JSON is stored, otherwise an erorr message.
params_avp(avp, optional) - an AVP consisting of all the parameters names that will be sent to the MI command. If this parameter is used without the vals_avp, all the values inside the AVP will be passed to the MI command as indexed parameters, otherwise as named parameters.
NOTE: if this parameter is used, the parameters specified in the command parameter are ignored.
NOTE: the order the parameters are passed to the command is the same as the one you populate the AVPs (thus somehow reversed compared to the way AVPs are stored in memory - the first AVP added is the first parameter)
vals_avp(avp, optional) - an AVP consisting of all the parameters values that will be sent to the MI command. This parameter only makes sense if the params_avp is set, and has to contain the same number of values as there are parameters.
To specify array values, enclose your space-separated array elements in the __array() pseudo-function call. For example: "__array(HEARTBEAT BACKGROUND_JOB)"
Example 1.5. mi with params in command
...
# this command is similar to the above
mi("cache_remove local password_user1");
...
Example 1.7. mi without return but with indexed params
...
$avp(params) = "local";
$avp(params) = "password_user1";
mi("cache_remove",,$avp(params));
# the following command is similar to the above
mi("cache_remove local password_user1");
...
Example 1.8. mi with return and named parameters
...
$avp(params) = "callid";
$avp(vals) = "SEARCH_FOR_THIS_CALLID";
$avp(params) = "from_tag";
$avp(vals) = "SEARCH_FOR_THIS_FROM_TAG";
mi("dlg_list", $var(dlg), $avp(params), $avp(vals));
...
Example 1.9. mi without return, with an array parameter value
...
$avp(params) = "freeswitch_url";
$avp(vals) = "fs://:ClueCon@192.168.20.8:8021";
$avp(params) = "events";
$avp(vals) = "__array(HEARTBEAT BACKGROUND_JOB)";
mi("fs_subscribe", , $avp(params), $avp(vals));
...
The function works is more or less the same as its synchronous corespondent, except that the MI command is run in an asynchronous manner - the process does not block to wait for the response, but it continues its execution and the MI command is run in an asynchronous context.
NOTE: currently MI commands run asynchronously cannot be traced through hep.
Example 1.10. async mi call usage
...
xlog("reload starting\n");
async(mi("dr_reload"), after_reload);
...
route[after_reload] {
xlog("reload completed\n");
}
Table 2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
| Name | DevScore | Commits | Lines ++ | Lines -- | |
|---|---|---|---|---|---|
| 1. | Razvan Crainea (@razvancrainea) | 17 | 6 | 1112 | 13 |
| 2. | Liviu Chircu (@liviuchircu) | 5 | 3 | 69 | 8 |
| 3. | Maksym Sobolyev (@sobomax) | 4 | 2 | 3 | 4 |
(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)
(2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".
(3) ignoring whitespace edits, renamed files and auto-generated files
Table 2.2. Most recently active contributors(1) to this module
| Name | Commit Activity | |
|---|---|---|
| 1. | Liviu Chircu (@liviuchircu) | Jun 2022 - Aug 2024 |
| 2. | Maksym Sobolyev (@sobomax) | Feb 2023 - Feb 2023 |
| 3. | Razvan Crainea (@razvancrainea) | May 2021 - Sep 2022 |
(1) including any documentation-related commits, excluding merge commits
Last edited by: Liviu Chircu (@liviuchircu), Razvan Crainea (@razvancrainea).
Documentation Copyrights:
Copyright © 2021 OpenSIPS Solutions