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.

$coder = Frontier::RPC2->new( OPTIONS )

Create a new encoder/decoder. The following option is
supported:

encoding

The XML encoding to be specified in the XML decla
ration 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' );

use_objects

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.

$xml_string = $coder->encode_call($method, @args)

`"encode_call"' converts a method name and it's argu
ments into an RPC2 `"methodCall"' element, returning
the XML fragment.

$xml_string = $coder->encode_response($result)

`"encode_response"' converts the return value of a
procedure into an RPC2 `"methodResponse"' element con
taining the result, returning the XML fragment.

$xml_string = $coder->encode_fault($code, $message)

`"encode_fault"' converts a fault code and message
into an RPC2 `"methodResponse"' element containing a
`"fault"' element, returning the XML fragment.

$call = $coder->decode($xml_string)

`"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 con
taining 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 `"fault
Code"' and `"faultMessage"'.

$response_xml = $coder->serve($request_xml, $methods)

`"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.

$boolean_object = $coder->boolean($boolean);
$date_time_object = $coder->date_time($date_time);
$base64_object = $coder->base64($base64);

These methods create and return XML-RPC-specific
datatypes that can be passed to the encoder. The
decoder may also return these datatypes. The corre
sponding package names (for use with `"ref()"', for
example) are `"Frontier::RPC2::Boolean"', `"Fron
tier::RPC2::DateTime::ISO8601"', and `"Fron
tier::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);

$int_object = $coder->int(42);
$float_object = $coder->float(3.14159);
$string_object = $coder->string("Foo");

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 prob
lems 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>

perl v5.8.0 1999-11-21 Frontier::RPC2(3)