modules/ims_qos: added patch for flow-description bug when request originates from...
[sip-router] / src / modules / app_mono / doc / app_mono_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
7 %docentities;
8
9 ]>
10
11 <!-- Module User's Guide -->
12
13 <chapter>
14     
15     <title>&adminguide;</title>
16     
17     <section>
18         <title>Overview</title>
19         <para>
20                 This module allows the execution of assemblies of managed code, among 
21                 the most popular of which is C# (.NET).
22                 It uses the Mono project (http://www.mono-project.com/) to embed the managed
23                 code interpreter inside the SIP server, providing fast execution.
24         </para>
25         <para>
26                 Besides C#, other languages can be used to build managed assemblies,
27                 such as: Java, Python, VisualBasic.NET, JavaScript. For more details on 
28                 what kind of languages can be used to build managed
29                 assemblies, see: http://www.mono-project.com/Languages
30         </para>
31         <para>
32                 A managed assembly can get access to any &kamailio; config variables
33                 and set them.  It can also perform many other functions implemented inside
34                 &kamailio; itself, allowing easier handling of SIP from managed code.
35         </para>
36         <para>
37                 There are two ways to execute managed code assemblies: load the code at
38                 startup and only execute at runtime, or load and execute at runtime. Only
39                 one mode at a time may be used.  The mode is determined by the 'load' 
40                 parameter and the function used to execute the code.
41         </para>
42     </section>
43     <section>
44         <title>Dependencies</title>
45         <section>
46             <title>&kamailio; Modules</title>
47             <para>
48                 The following modules must be loaded before this module:
49                 <itemizedlist>
50                     <listitem>
51                         <para>
52                             <emphasis>none</emphasis>.
53                         </para>
54                     </listitem>
55                 </itemizedlist>
56             </para>
57         </section>
58         <section>
59             <title>External Libraries or Applications</title>
60             <para>
61                 The following libraries or applications must be installed before running
62                 &kamailio; with this module loaded:
63                 <itemizedlist>
64                     <listitem>
65                         <para>
66                             <emphasis>mono-devel</emphasis> - Mono devel toolkit.
67                         </para>
68                     </listitem>
69                 </itemizedlist>
70             </para>
71         </section>
72     </section>
73     <section>
74         <title>Parameters</title>
75         <section>
76             <title><varname>load</varname> (string)</title>
77             <para>
78                         Set the path to the Mono assembly to be loaded at startup.  You
79                         can use mono_run(param) to execute the assembly at runtime.
80             </para>
81             <para>
82                 <emphasis>
83                     Default value is <quote>null</quote>.
84                 </emphasis>
85             </para>
86             <example>
87                 <title>Set <varname>load</varname> parameter</title>
88                 <programlisting format="linespecific">
89 ...
90 modparam("app_mono", "load", "/usr/local/etc/kamailio/mono/myscript.exe")
91 ...
92 </programlisting>
93             </example>
94         </section>
95         </section>
96         
97     <section>
98         <title>Functions</title>
99         <section>
100             <title>
101                 <function moreinfo="none">mono_exec(path [, param])</function>
102             </title>
103             <para>
104                 Execute the managed code assembly stored in 'path'. The path can be
105                 a string with pseudo-variables evaluated at runtime. A second parameter
106                 can optionally be provided; it will be passed to the assembly.
107             </para>
108                 <para>
109                 Note that the assembly is loaded every time from the file, so any change
110                 to it is immediately live. This function cannot be used if 'load'
111                 parameter is set.
112                 </para>
113                 <example>
114                 <title><function>mono_exec</function> usage</title>
115                 <programlisting format="linespecific">
116 ...
117 mono_exec("/usr/local/etc/kamailio/mono/myscript.exe");
118 ...
119 </programlisting>
120             </example>
121         </section>
122         
123         <section>
124             <title>
125                 <function moreinfo="none">mono_run([param])</function>
126             </title>
127             <para>
128                 Execute the assembly specified by 'load' module parameter. The assembly
129                 is loaded at startup, so changes to it will be effective only after &kamailio;
130                 restart.
131             </para>
132             <para>
133                         An optional parameter can be given and it will be passed over to the
134                         assembly. It can be a string with pseudo-variables; these will be
135                         evaluated at runtime.
136             </para>
137                 <example>
138                 <title><function>mono_run</function> usage</title>
139                 <programlisting format="linespecific">
140 ...
141 if(!mono_run("myparam"))
142 {
143     xdbg("SCRIPT: failed to execute mono assembly!\n");
144 }
145 ...
146 </programlisting>
147             </example>
148         </section>
149         </section>
150         
151     <section>
152         <title>Usage</title>
153         <para>
154         First, create a library from the 'SR.cs' file provided
155         in the folder 'modules/app_mono/lib/'. The examples uses the folder
156         /usr/local/etc/kamailio/mono/ to store the Mono-specific assemblies
157         to be used by &kamailio;.
158         </para>
159 <programlisting format="linespecific">
160 ...
161 mkdir -p /usr/local/etc/kamailio/mono/
162 cp modules/app_mono/lib/SR.cs /usr/local/etc/kamailio/mono/
163 gmcs -t:library SR.cs
164 ...
165 </programlisting>
166         <para>
167         You should see the 'SR.dll' file generated.
168         </para>
169     <para>
170         Create your application in C#/.NET and save it
171         in the same folder with SR.dll. You have to use the SR package in your
172         managed source code file -- say you named MySRTest.cs. Also, be
173         aware that the Main() function from the managed assembly is executed;
174         thus, be sure that you have it defined.
175     </para>
176 <programlisting format="linespecific">
177 ...
178 using SR;
179
180 namespace MySRTest {
181         class Test {
182                 static int Main(string[] args) {
183                         SR.Core.Log(1, "Kamailio API Version: " + SR.Core.APIVersion() + "\n");
184                         if (args.Length == 1) {
185                                 SR.Core.Log(1, "Parameter from Kamailio config: "
186                                         + args[0] + "\n");
187                         }
188                         SR.Core.Dbg("Request URI is: " + SR.PV.GetS("$ru") + "\n");
189                         SR.PV.SetS("$rU", "123");
190                         SR.HDR.AppendToReply("My-Mono-Hdr: ok\r\n");
191                         SR.Core.ModF("sl_reply_error");
192                         return 1;
193                 }
194         }
195 }
196 ...
197 </programlisting>
198         <para>
199         You have to compile the 'SR.dll' file generated.
200         </para>
201 <programlisting format="linespecific">
202 ...
203 $ gmcs -r:SR.dll MySRTest.cs
204 ...
205 </programlisting>
206     <para>
207                 You should see the file 'MySRTest.exe' generated in the folder.
208     </para>
209     <para>
210                 In the &kamailio; config file, load the app_mono.so module and use
211                 its functions inside the routing blocks.
212     </para>
213 <programlisting format="linespecific">
214 ...
215 loadmodule "app_mono.so"
216 ...
217 route {
218     ...
219     mono_exec("/usr/local/etc/kamailio/mono/MySRTest.exe");
220     ...
221 }
222 ...
223 </programlisting>
224     <para>
225                 The API exported by the SR package to Mono applications is documented
226                 on the &kamailio; wiki site. Also, it is easy to figure out by looking
227                 in the source code tree inside the file modules/app_mono/lib/SR.cs.
228     </para>
229     </section>
230 </chapter>
231