kamailio/modules/app_mono/README

app_mono Module

Daniel-Constantin Mierla

   asipto.com

Edited by

Daniel-Constantin Mierla

   <miconda@gmail.com>

Edited by

Alex Balashov

   <abalashov@evaristesys.com>

   Copyright © 2012 Daniel-Constantin Mierla (asipto.com)
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. load (string)

        4. Functions

              4.1. mono_exec(path [, param])
              4.2. mono_run([param])

        5. Usage

   List of Examples

   1.1. Set load parameter
   1.2. mono_exec usage
   1.3. mono_run usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Parameters

        3.1. load (string)

   4. Functions

        4.1. mono_exec(path [, param])
        4.2. mono_run([param])

   5. Usage

1. Overview

   This module allows the execution of assemblies of managed code, among
   the most popular of which is C# (.NET). It uses the Mono project
   (http://www.mono-project.com/) to embed the managed code interpreter
   inside the SIP server, providing fast execution.

   Besides C#, other languages can be used to build managed assemblies,
   such as: Java, Python, VisualBasic.NET, JavaScript. For more details on
   what kind of languages can be used to build managed assemblies, see:
   http://www.mono-project.com/Languages

   A managed assembly can get access to any Kamailio config variables and
   set them. It can also perform many other functions implemented inside
   Kamailio itself, allowing easier handling of SIP from managed code.

   There are two ways to execute managed code assemblies: load the code at
   startup and only execute at runtime, or load and execute at runtime.
   Only one mode at a time may be used. The mode is determined by the
   'load' parameter and the function used to execute the code.

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The following modules must be loaded before this module:
     * none.

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * mono-devel - Mono devel toolkit.

3. Parameters

   3.1. load (string)

3.1. load (string)

   Set the path to the Mono assembly to be loaded at startup. You can use
   mono_run(param) to execute the assembly at runtime.

   Default value is “null”.

   Example 1.1. Set load parameter
...
modparam("app_mono", "load", "/usr/local/etc/kamailio/mono/myscript.exe")
...

4. Functions

   4.1. mono_exec(path [, param])
   4.2. mono_run([param])

4.1.  mono_exec(path [, param])

   Execute the managed code assembly stored in 'path'. The path can be a
   string with pseudo-variables evaluated at runtime. A second parameter
   can optionally be provided; it will be passed to the assembly.

   Note that the assembly is loaded every time from the file, so any
   change to it is immediately live. This function cannot be used if
   'load' parameter is set.

   Example 1.2. mono_exec usage
...
mono_exec("/usr/local/etc/kamailio/mono/myscript.exe");
...

4.2.  mono_run([param])

   Execute the assembly specified by 'load' module parameter. The assembly
   is loaded at startup, so changes to it will be effective only after
   Kamailio restart.

   An optional parameter can be given and it will be passed over to the
   assembly. It can be a string with pseudo-variables; these will be
   evaluated at runtime.

   Example 1.3. mono_run usage
...
if(!mono_run("myparam"))
{
    xdbg("SCRIPT: failed to execute mono assembly!\n");
}
...

5. Usage

   First, create a library from the 'SR.cs' file provided in the folder
   'modules/app_mono/lib/'. The examples uses the folder
   /usr/local/etc/kamailio/mono/ to store the Mono-specific assemblies to
   be used by Kamailio.
...
mkdir -p /usr/local/etc/kamailio/mono/
cp modules/app_mono/lib/SR.cs /usr/local/etc/kamailio/mono/
gmcs -t:library SR.cs
...

   You should see the 'SR.dll' file generated.

   Create your application in C#/.NET and save it in the same folder with
   SR.dll. You have to use the SR package in your managed source code file
   -- say you named MySRTest.cs. Also, be aware that the Main() function
   from the managed assembly is executed; thus, be sure that you have it
   defined.
...
using SR;

namespace MySRTest {
        class Test {
                static int Main(string[] args) {
                        SR.Core.Log(1, "Kamailio API Version: " + SR.Core.APIVer
sion() + "\n");
                        if (args.Length == 1) {
                                SR.Core.Log(1, "Parameter from Kamailio config:
"
                                        + args[0] + "\n");
                        }
                        SR.Core.Dbg("Request URI is: " + SR.PV.GetS("$ru") + "\n
");
                        SR.PV.SetS("$rU", "123");
                        SR.HDR.AppendToReply("My-Mono-Hdr: ok\r\n");
                        SR.Core.ModF("sl_reply_error");
                        return 1;
                }
        }
}
...

   You have to compile the 'SR.dll' file generated.
...
$ gmcs -r:SR.dll MySRTest.cs
...

   You should see the file 'MySRTest.exe' generated in the folder.

   In the Kamailio config file, load the app_mono.so module and use its
   functions inside the routing blocks.
...
loadmodule "app_mono.so"
...
route {
    ...
    mono_exec("/usr/local/etc/kamailio/mono/MySRTest.exe");
    ...
}
...

   The API exported by the SR package to Mono applications is documented
   on the Kamailio wiki site. Also, it is easy to figure out by looking in
   the source code tree inside the file modules/app_mono/lib/SR.cs.