mi_xmlrpc Module

Lavinia-Andreea Andrei

   voice-system.ro

Edited by

Lavinia-Andreea Andrei

Juha Heinanen

   Copyright  2006 voice-system.ro
     __________________________________________________________

   Table of Contents
   1. User's Guide

        1.1. Overview
        1.2. To-do
        1.3. Dependencies

              1.3.1. OpenSER Modules
              1.3.2. External Libraries or Applications

        1.4. Exported Parameters

              1.4.1. port(integer)
              1.4.2. log_file(string)
              1.4.3. reply_option (integer)
              1.4.4. buffer_size (integer)

        1.5. Exported Functions
        1.6. Example

   2. Developer's Guide
   3. Frequently Asked Questions

   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. User's Guide

1.1. Overview

   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 OpenSER 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.
     __________________________________________________________

1.2. To-do

   Features to be added in the future:

     * possibility to select the listening IP address
     * multiple ports per IP address
     __________________________________________________________

1.3. Dependencies

1.3.1. OpenSER Modules

   The following modules must be loaded before this module:

     * No dependencies on other OpenSER modules.
     __________________________________________________________

1.3.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSER with this module loaded:

     * libxml.
     * libxmlrpc-c3 version 0.9.10.
     * libxmlrpc-c3-dev version 0.9.10.

   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. In both cases, keep in mind to use the 0.9.10
   version!!.
     __________________________________________________________

1.4. Exported Parameters

1.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)
...
     __________________________________________________________

1.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")
...
     __________________________________________________________

1.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)
...
     __________________________________________________________

1.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)
...
     __________________________________________________________

1.5. Exported Functions

   No function exported to be used from configuration file.
     __________________________________________________________

1.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>
     __________________________________________________________

Chapter 2. Developer's Guide

   The module does not provide any API to use in other OpenSER
   modules.
     __________________________________________________________

Chapter 3. Frequently Asked Questions

   3.1. Where can I find more about XMLRPC library?
   3.2. Where can I find more about OpenSER?
   3.3. Where can I post a question about this module?
   3.4. How can I report a bug?

   3.1. Where can I find more about XMLRPC library?

   Visit the official site of XMLRPC project at
   http://xmlrpc-c.sourceforge.net/

   3.2. Where can I find more about OpenSER?

   Take a look at http://openser.org/.

   3.3. Where can I post a question about this module?

   First at all check if your question was already answered on one
   of our mailing lists:

     * User Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/users
     * Developer Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/devel

   E-mails regarding any stable OpenSER release should be sent to
   <users@openser.org> and e-mails regarding development versions
   should be sent to <devel@openser.org>.

   If you want to keep the mail private, send it to
   <team@openser.org>.

   3.4. How can I report a bug?

   Please follow the guidelines provided at:
   http://sourceforge.net/tracker/?group_id=139143.
