/ 
Frontier-RPC-0.07b4p1
River stage one • 8 direct dependents • 9 total dependents
/ Frontier::Client

NAME

Frontier::Client - issue Frontier XML RPC requests to a server

SYNOPSIS

use Frontier::Client;

$server = Frontier::Client->new( I<OPTIONS> );

$result = $server->call($method, @args);

$boolean = $server->boolean($value);
$date_time = $server->date_time($value);
$base64 = $server->base64($value);

$value = $boolean->value;
$value = $date_time->value;
$value = $base64->value;

DESCRIPTION

Frontier::Client is an XML-RPC client over HTTP. Frontier::Client instances are used to make calls to XML-RPC servers and as shortcuts for creating XML-RPC special data types.

METHODS

new( OPTIONS )

Returns a new instance of Frontier::Client and associates it with an XML-RPC server at a URL. OPTIONS may be a list of key, value pairs or a hash containing the following parameters:

url

The URL of the server. This parameter is required. For example:

$server = Frontier::Client->new( 'url' => 'http://betty.userland.com/RPC2' );
proxy

A URL of a proxy to forward XML-RPC calls through.

encoding

The XML encoding to be specified in the XML declaration of outgoing RPC requests. Incoming results may have a different encoding specified; XML::Parser will convert incoming data to UTF-8. The default outgoing encoding is none, which uses XML 1.0's default of UTF-8. For example:

$server = Frontier::Client->new( 'url' => 'http://betty.userland.com/RPC2',
                                 '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.

username

Sets the username for basic authentication. If this is not set, basic authentication will be disabled.

password

Sets the password for basic authentication.

debug

If set to a non-zero value will print the encoded XML request and the XML response received.

call($method, @args)

Forward a procedure call to the server, either returning the value returned by the procedure or failing with exception. `$method' is the name of the server method, and `@args' is a list of arguments to pass. Arguments may be Perl hashes, arrays, scalar values, or the XML-RPC special data types below.

boolean( $value )
date_time( $value )
base64( $base64 )

The methods `boolean()', `date_time()', and `base64()' create and return XML-RPC-specific datatypes that can be passed to `call()'. Results from servers may also contain these datatypes. The corresponding package names (for use with `ref()', for example) are `Frontier::RPC2::Boolean', `Frontier::RPC2::DateTime::ISO8601', and `Frontier::RPC2::Base64'.

The value of boolean, date/time, and base64 data can be set or returned using the `value()' method. For example:

# To set a value:
$a_boolean->value(1);

# To retrieve a value
$base64 = $base64_xml_rpc_data->value();

Note: `base64()' does not encode or decode base64 data for you, you must use MIME::Base64 or similar module for that.

int( 42 );
float( 3.14159 );
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 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 = $server->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::RPC2(3)

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

AUTHOR

Ken MacLeod <ken@bitsko.slc.ut.us> Basic authentication patch by Jeff <jeff@freemedsoftware.org>