Frontier::RPC2(3)

NAME
Frontier::RPC2 - encode/decode RPC2 format XML

SYNOPSIS
 use Frontier::RPC2;
 $coder = Frontier::RPC2->new;
 $xml_string = $coder->encode_call($method, @args);
 $xml_string = $coder->encode_response($result);
 $xml_string = $coder->encode_fault($code, $message);
 $call = $coder->decode($xml_string);
 $response_xml = $coder->serve($request_xml, $methods);
 $boolean_object = $coder->boolean($boolean);
 $date_time_object = $coder->date_time($date_time);
 $base64_object = $coder->base64($base64);
 $int_object = $coder->int(42);
 $float_object = $coder->float(3.14159);
 $string_object = $coder->string("Foo");

DESCRIPTION
Frontier::RPC2 encodes and decodes XML RPC calls. Create a new encoder/decoder. The following option is supported:
    The XML encoding to be specified in the XML declaration of encoded RPC requests or responses. Decoded results may have a different encoding specified; XML::Parser will convert decoded data to UTF-8. The default encoding is none, which uses XML 1.0's default of UTF-8. For example:

     $server = Frontier::RPC2->new( 'encoding' => 'ISO-8859-1' );
    If set to a non-zero value will convert incoming <i4>, <float>, and <string> values to objects instead of scalars. See int(), float(), and string() below for more details.
``encode_call'' converts a method name and it's arguments into an RPC2 ``methodCall'' element, returning the XML fragment. ``encode_response'' converts the return value of a procedure into an RPC2 ``methodResponse'' element containing the result, returning the XML fragment. ``encode_fault'' converts a fault code and message into an RPC2 ``methodResponse'' element containing a ``fault'' element, returning the XML fragment. ``decode'' converts an XML string containing an RPC2 ``methodCall'' or ``methodResponse'' element into a hash containing three members, ``type'', ``value'', and ``method_name''. ``type'' is one of ``call'', ``response'', or ``fault''. ``value'' is array containing the parameters or result of the RPC. For a ``call'' type, ``value'' contains call's parameters and ``method_name'' contains the method being called. For a ``response'' type, the ``value'' array contains call's result. For a ``fault'' type, the ``value'' array contains a hash with the two members ``faultCode'' and ``faultMessage''. ``serve'' decodes ``$request_xml'', looks up the called method name in the ``$methods'' hash and calls it, and then encodes and returns the response as XML. These methods create and return XML-RPC-specific datatypes that can be passed to the encoder. The decoder may also return these datatypes. The corresponding package names (for use with ``ref()'', for example) are ``Frontier::RPC2::Boolean'', ``Frontier::RPC2::DateTime::ISO8601'', and ``Frontier::RPC2::Base64''.

You can change and retrieve the value of boolean, date/time, and base64 data using the ``value'' method of those objects, i.e.:

  $boolean = $boolean_object->value;
  $boolean_object->value(1);
By default, you may pass ordinary Perl values (scalars) to be encoded. RPC2 automatically converts them to XML-RPC types if they look like an integer, float, or as a string. This assumption causes problems when you want to pass a string that looks like "0096", RPC2 will convert that to an <i4> because it looks like an integer. With these methods, you could now create a string object like this:

  $part_num = $coder->string("0096");
and be confident that it will be passed as an XML-RPC string. You can change and retrieve values from objects using value() as described above.

SEE ALSO
perl(1), Frontier::Daemon(3), Frontier::Client(3)

<http://www.scripting.com/frontier5/xml/code/rpc.html>

AUTHOR
Ken MacLeod <ken@bitsko.slc.ut.us>