# XML-RPC Server

OI Runtime provides an XML-RPC server which allows other programs to get information about the OI terminal and to view or modify tag values.

The writeTag method is only allowed if the communication adapter is set to permit these functions in OIB.

WARNING

Allowing XML-RPC server to modify tag data can present hazardous situations. We recommend creating a separate adapter which includes only the tags you want to allow external access to.

# OI XML-RPC server methods API

XML-RPC returns 'error' property if request failed and there is no tags to return. Its value has textual description what was wrong.

XML-RPC returns 'ok' property if request was fully or partially successful.

on full success 'ok' property value is 'success'
on partial success 'ok' property value contains textual description what was wrong

# getInfo

XML-RPC input parameters: none

XML-RPC response converted into php using function xmlrpc_decode:

array (
  0 => array (
    'property' => 'ok',
    'value' => 'success',
  ),
  1 => array (
    'property' => 'info',
    'value' => array (
      0 => array (
        'property' => 'oi_version',
        'value' => '1.9',
      ),
      1 => array (
        'property' => 'build',
        'value' => 'Apr 16 2015  14:40:33 UTC',
      ),
      2 => array (
        'property' => 'up_time_sec',
        'value' => 346105,
      ),
      3 => array (
        'property' => 'timestamp',
        'value' => '33250316',
      ),
      4 => array (
        'property' => 'date_time',
        'value' => '2015-04-20 17:02:09',
      ),
      5 => array (
        'property' => 'mode',
        'value' => 'master',
      ),
      6 => array (
        'property' => 'application',
        'value' => array (
          0 => array (
            'property' => 'name',
            'value' => 'unnamed',
          ),
          1 => array (
            'property' => 'desc',
            'value' => '',
          ),
          2 => array (
            'property' => 'file',
            'value' => '/oi/gestamp_alarmtest.oi',
          ),
          3 => array (
            'property' => 'current_screen',
            'value' => 3,
          ),
        ),
      ),
    ),
  ),
)

# getTagList

XML-RPC input parameters: none

XML-RPC response converted into php using function xmlrpc_decode:

array (
  0 => array (
    'property' => 'ok',
    'value' => 'success',
  ),
  1 => array (
    'property' => 'info',
    'value' =>
    array (
            /*  ... the same object as returned by getInfo method ...  */
    )
  ),
  2 => array (  
    'property' => 'drivers',
    'value' => array (  /*  list of all drivers  */
      0 => /* 1st driver */
      array (
        0 =>
        array (
          'property' => 'driver_name',
          'value' => 'dummy',
        ),
        1 =>
        array (
          'property' => 'driver_type',
          'value' => 'Internal Memory',
        ),
        2 =>
        array (
          'property' => 'tags',
          'value' => array (  /*  list of all driver tags  */
            0 => /* 1st tag */
            array (
              0 =>
              array (
                'property' => 'name',
                'value' => 'alarmLoopTrigger',
              ),
              1 =>
              array (
                'property' => 'description',
                'value' => '',
              ),
              2 =>
              array (
                'property' => 'data_type',
                'value' => 4,
              ),
              3 =>
              array (
                'property' => 'address',
                'value' => 'N0:0/0',
              ),
            ),
            1 => /* 2nd tag */
            array (
              0 =>
              array (
                'property' => 'name',
                'value' => 'hideAlarms',
              ),
              1 =>
              array (
                'property' => 'description',
                'value' => '',
              ),
              2 =>
              array (
                'property' => 'data_type',
                'value' => 1,
              ),
              3 =>
              array (
                'property' => 'address',
                'value' => 'N0:2/0',
              ),
            ),
...

Meaning of data_type property:

data_type Data Type Description
0 Undefined undefined type (undefined value)
1 Bit bit
2 BitA bit array
3 Bcd4 bcd4 (0000 - 9999)
4 UInt 16bit unsigned integer
5 Int 16bit signed integer
6 CharA character array
7 Real 32bit IEEE float
8 DInt 32bit signed integer
9 DUInt 32bit unsigned integer

# readTagValue

XML-RPC input parameters: at least 1 parameter, each parameter is name of tag to read (string type) PHP code:

$xml_rpc_params = array();
$xml_rpc_params[] = 'tag1';  // name of OI tag we want to read

XML-RPC response converted into php using function xmlrpc_decode:

array (
  0 =>
  array (
    'property' => 'ok',
    'value' => 'success',
  ),
  1 =>
  array (
    'property' => 'info',
    'value' => array (
            /*  ... the same object as returned by getInfo method ...  */
    ),
  ),
  2 =>
  array (
    'property' => 'tags',
    'value' => array (  /* list of all tags and values */
      0 => /* 1st tag */
      array (
        0 =>
        array (
          'property' => 'name',
          'value' => 'tag_0',
        ),
        1 =>
        array (
          'property' => 'value',
          'value' => '0',
        ),
      ),
      1 => /* 2nd tag */
      array (
        0 =>
        array (
          'property' => 'name',
          'value' => 'tag_1',
        ),
        1 =>
        array (
          'property' => 'value',
          'value' => '0',
        ),
      )
...

# writeTagValue

XML-RPC input parameters: at least 1 parameter, each parameter is struct type.

Struct:

  • member 'name': tag name (string)
  • member 'value': value to write (string)
$xml_rpc_params = array();
$xml_rpc_params[] = array('name'=>'tag1', 'value'=>'1');  // name of OI tag and value we want to write into

XML-RPC response converted into php using function xmlrpc_decode:

array (
  0 =>
  array (
    'property' => 'ok',
    'value' => 'success',
  ),
  1 =>
  array (
    'property' => 'info',
    'value' => array (
            /*  ... the same object as returned by getInfo method ...  */
    ),
  ),
  2 =>
  array (
    'property' => 'tags',
    'value' => array (  /* list of all tags and values */
      0 => /* 1st tag */
      array (
        0 =>
        array (
          'property' => 'name',
          'value' => 'tag_0',
        ),
        1 =>
        array (
          'property' => 'write_value',
          'value' => '10',
        ),
        array (
          'property' => 'read_back_value',
          'value' => '10',  /* this is ok - read value == write value */
        ),
      ),
      1 => /* 2nd tag */
      array (
        0 =>
        array (
          'property' => 'name',
          'value' => 'tag_1',
        ),
        1 =>
        array (
          'property' => 'write_value',
          'value' => '10',
        ),
        array (
          'property' => 'read_back_value',
          'value' => '0',   /* this indicates error - read value != write value */
        ),
      )
...
Last Updated: 7/21/2018, 7:56:32 PM