kamailio/modules/mi_xmlrpc/README

mi_xmlrpc Module

Lavinia-Andreea Andrei

   Voice Sistem SRL

Edited by

Lavinia-Andreea Andrei

Edited by

Juha Heinanen

   Copyright © 2006 Voice Sistem SRL
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. To-do
        3. Dependencies

              3.1. Kamailio Modules
              3.2. External Libraries or Applications

        4. Parameters

              4.1. port(integer)
              4.2. log_file(string)
              4.3. reply_option (integer)
              4.4. buffer_size (integer)

        5. Functions
        6. Example

   List of Examples

   1.1. Set port parameter
   1.2. Set log_file parameter
   1.3. Set reply_option parameter
   1.4. Set reply_option parameter
   1.5. XMLRPC request

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. To-do
   3. Dependencies

        3.1. Kamailio Modules
        3.2. External Libraries or Applications

   4. Parameters

        4.1. port(integer)
        4.2. log_file(string)
        4.3. reply_option (integer)
        4.4. buffer_size (integer)

   5. Functions
   6. Example

1. Overview

   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.

   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.

   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.

   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.

2. To-do

   Features to be added in the future:
     * possibility to select the listening IP address
     * multiple ports per IP address

3. Dependencies

   3.1. Kamailio Modules
   3.2. External Libraries or Applications

3.1. Kamailio Modules

   The following modules must be loaded before this module:
     * No dependencies on other Kamailio modules.

3.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * libxml.
     * libxmlrpc-c3 version 0.9.10 or version 1.06.[10-30].
     * libxmlrpc-c3-dev version 0.9.10 or version 1.06.[10-30].

   If libxmlrpc-c3[-dev] package is not available on your system, you may
   check if packages for your OS are not available on the
   "xmlrpc-c"project ( http://xmlrpc-c.sourceforge.net/). Otherwise you
   need to install the library and devel headers from the sources.

4. Parameters

   4.1. port(integer)
   4.2. log_file(string)
   4.3. reply_option (integer)
   4.4. buffer_size (integer)

4.1. port(integer)

   The port number used by the XMLRPX server to listen for incoming
   requests.

   The default value is 8080. Ports lower than 1024 are not accepted.

   Example 1.1. Set port parameter
...
modparam("mi_xmlrpc", "port", 8000)
...

4.2. log_file(string)

   A log file to be used by the internal Abyss html server used by the
   XMLRPX library.

   The default values NONE (no logging).

   Example 1.2. Set log_file parameter
...
modparam("mi_xmlrpc", "log_file", "/var/log/abyss.log")
...

4.3. reply_option (integer)

   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.

   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.

   The default option is a string built response (0).

   Example 1.3. Set reply_option parameter
...
modparam("mi_xmlrpc", "reply_option", 0)
...

4.4. buffer_size (integer)

   It specifies the maximum length of the buffer used to write in the MI
   tree node information in order to build the xmlrpc response.

   The default value is 8192.

   Example 1.4. Set reply_option parameter
...
modparam("mi_xmlrpc", "buffer_size", 8192)
...

5. Functions

   No function exported to be used from configuration file.

6. Example

   This is an example showing the xmlrpc format for the "get_statistics
   dialog: tm:" MI commad: response.

   Example 1.5. XMLRPC request
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>