mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
248 lines
6.6 KiB
248 lines
6.6 KiB
<?xml version="1.0" encoding='ISO-8859-1'?>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
|
|
|
|
<!-- Include general documentation entities -->
|
|
<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
|
|
%docentities;
|
|
|
|
]>
|
|
<!-- Module User's Guide -->
|
|
|
|
<chapter>
|
|
|
|
<title>&adminguide;</title>
|
|
|
|
<section>
|
|
<title>Overview</title>
|
|
<para>
|
|
NOTE: this module depends on specific versions of libxmlrpc-c3, which may
|
|
not be available on your OS. You better use the 'xmlrpc' module located in
|
|
'modules/' folder. It can run any MI command by loading 'mi_rpc' module and
|
|
executing RPC command 'mi', with first parameter being the MI command,
|
|
then followed by other parameters that will be passed to the MI command.
|
|
</para>
|
|
<para>
|
|
This module implements a xmlrpc server that handles xmlrpc requests and
|
|
generates xmlrpc responses. When a xmlrpc message is received a default
|
|
method is executed.
|
|
</para>
|
|
<para>
|
|
At first, it looks up the MI command. If found it parses the called
|
|
procedure's parameters into a MI tree and the command is executed. A
|
|
MI reply tree is returned that is formatted back in xmlrpc. The
|
|
response is built in two ways - like a string that contains the MI
|
|
tree nodes information (name, values and attributes) or like an array
|
|
whose elements are consisted of each MI tree node stored information.
|
|
</para>
|
|
<para>
|
|
Implementation of mi_xmlrpc module's xmlrpc server is based on Abyss
|
|
XML-RPC server. Current version of Abyss server
|
|
"normalizes" CRLF sequence in received XML-RPC strings
|
|
to LF character, which makes it impossible to pass CRLF
|
|
sequence from xmlrpc client application to &kamailio; modules,
|
|
such as mi_fifo and pua_mi, that accept requests via MI
|
|
transport. To overcome this limitation mi_xmlrpc module
|
|
implements a hack that coverts each LFLF sequence in
|
|
received XML-RPC strings to CRLF sequence.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>To-do</title>
|
|
<para>
|
|
Features to be added in the future:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
possibility to select the listening IP address
|
|
</para></listitem>
|
|
<listitem><para>
|
|
multiple ports per IP address
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Dependencies</title>
|
|
<section>
|
|
<title>&kamailio; Modules</title>
|
|
<para>
|
|
The following modules must be loaded before this module:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>No dependencies on other &kamailio; modules</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>External Libraries or Applications</title>
|
|
<para>
|
|
The following libraries or applications must be installed before
|
|
running &kamailio; with this module loaded:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>libxml</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>libxmlrpc-c3</emphasis> version 0.9.10 or version 1.06.[10-30].
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>libxmlrpc-c3-dev</emphasis> version 0.9.10 or version 1.06.[10-30].
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
If libxmlrpc-c3[-dev] package is not available on your system, you may
|
|
check if packages for your OS are not available on the
|
|
<quote>xmlrpc-c</quote>project
|
|
(<ulink url='http://xmlrpc-c.sourceforge.net/'>
|
|
http://xmlrpc-c.sourceforge.net/</ulink>). Otherwise you need
|
|
to install the library and devel headers from the sources.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Parameters</title>
|
|
<section>
|
|
<title><varname>port</varname>(integer)</title>
|
|
<para>
|
|
The port number used by the XMLRPX server to listen for incoming
|
|
requests.
|
|
</para>
|
|
<para>
|
|
<emphasis>The default value is 8080.</emphasis>
|
|
Ports lower than 1024 are not accepted.
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>port</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("mi_xmlrpc", "port", 8000)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>log_file</varname>(string)</title>
|
|
<para>
|
|
A log file to be used by the internal Abyss html server used by the
|
|
XMLRPX library.
|
|
</para>
|
|
<para>
|
|
<emphasis>The default values NONE (no logging).</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>log_file</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("mi_xmlrpc", "log_file", "/var/log/abyss.log")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>reply_option</varname> (integer)</title>
|
|
<para>
|
|
Given the xmlrpc response specifications that a methodResponse can
|
|
contain a single params section with a single param section, there is
|
|
the possibility to choose between a string built response or an
|
|
array built one.
|
|
</para>
|
|
<para>
|
|
For a 0 value, a single string parameter will be replied (merging the
|
|
whole response). For non-0 value, each line from the response will be
|
|
encoded as an element into an array of strings.
|
|
</para>
|
|
<para>
|
|
<emphasis>The default option is a string built response (0).</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>reply_option</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("mi_xmlrpc", "reply_option", 0)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>buffer_size</varname> (integer)</title>
|
|
<para>
|
|
It specifies the maximum length of the buffer used to write in the MI
|
|
tree node information in order to build the xmlrpc response.
|
|
</para>
|
|
<para>
|
|
<emphasis> The default value is 8192.</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>reply_option</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("mi_xmlrpc", "buffer_size", 8192)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Functions</title>
|
|
<para>
|
|
No function exported to be used from configuration file.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Example</title>
|
|
<para>
|
|
This is an example showing the xmlrpc format for the
|
|
<quote>get_statistics dialog: tm:</quote> MI commad:
|
|
response.
|
|
</para>
|
|
<example>
|
|
<title>XMLRPC request</title>
|
|
<programlisting format="linespecific">
|
|
<![CDATA[
|
|
|
|
POST /RPC2 HTTP/1.0
|
|
Host: 127.0.0.1
|
|
Connection: close
|
|
User-Agent: OpenSIPg XML_RPC Client
|
|
Content-Type: text/xml
|
|
Content-Length: 1000
|
|
|
|
<?xml version="1.0" ?>
|
|
<methodCall>
|
|
<methodName>get_statistics</methodName>
|
|
<params>
|
|
<param>
|
|
<value><string>dialog:</string></value>
|
|
</param>
|
|
<param>
|
|
<value><string>tm:</string></value>
|
|
</param>
|
|
</params>
|
|
</methodCall>
|
|
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
|
|
</section>
|
|
|
|
|
|
</chapter>
|
|
|