.. _xmlrpc:

********************
XML-RPC
********************

.. index:: presentations; XML-RPC

Overview
====================

The XML-RPC presentation allows for interaction with the iDigi Dia
through XML-RPC protocol.

Configuration
====================

A typical XML-RPC configuration block looks like this::

    - name: xmlrpc
      driver: presentations.xmlrpc.xmlrpc:XMLRPC
      settings:
          port: 80
          use_default_httpserver: True

Settings
--------------------

port (optional, default: 80)
    TCP port number.

use_default_httpserver (optional, default: True)
    If this setting is set to True the XML-RPC server will start on its
    own port number.  If false, XML-RPC services will be available on the
    default web server built in to the Digi device.

Usage
====================
The RCIHandler allows for channel dumps, querying a channel, and setting
a channel. It also includes several requests to interact with the logging 
sub-system to read and move inside of a determined log file.

XML-RPC protocol uses XML to encode its calls and HTTP as a transport 
mechanism.

The address of the XML-RPC server will be::

    http://<address of the device>/RPC2

Commands
--------------------
The following commands are supported.  These are analogous to the same
commands in the :ref:`console` presentation:

* ``device_instance_list()``: Receive a list of devices.
* ``channel_list()``: Receive a list of all channels.
* ``channel_get(channel_name)``: Get the current sample on a channel given
  by channel_name.
* ``channel_set(channel_name, timestamp, value, unit, autotimestamp = True)``:
  Set a channel with the values given by the arguments. If autotimestamp
  is being used set timestamp = 0.
* ``channel_info(channel_name)``: Get the channel permissions and options given
  by channel_name.
* ``channel_refresh(channel_name)``: Request that a channel given by channel_name 
  is refreshed.
* ``channel_dump()``: Dump all channels with their current values.
* ``logger_list()``: Receive a list of loggers running.
* ``logger_set(logger_name)``: Sets the logger database for the presentation 
  to use.
* ``logger_dump()``: Dump all channels for the current logger at the point of 
  the current sample in the log file.
* ``logger_next()``: Obtain the next record from current position.
* ``logger_prev()``: Obtain the previous record from current position.
* ``logger_rewind()``: Seek to the first logged record.
* ``logger_seek(self, offset, whence='set', record_number=0)``: Seek to the record specified by the arguments.


