A.1 RPC::XMLSimple

This is the lightest-weight of the three toolkits. It relies on the presence of the LWP and XML::Parser modules from CPAN.

The following is based on Release 1.0 of RPC::XMLSimple .

A.1.1 RPC::XMLSimple

This class is rarely loaded directly into an application. Usually, the application uses one of the client or server classes, each of which load this module. The class provides the following methods :

new( optional key/value pairs )

The constructor that returns new object instances of the encoder object, which is the object class this package provides. The options are passed as key/value pairs (not a hash reference). Recognized options are:

encoding

Provides a specific encoding for the documents that are created. If this isn't given, the default encoding for XML (UTF-8) is assumed.

use_objects

If this is passed with a value that is non-zero , the encoder returns data from parsed documents only as objects, rather than native Perl values. See the explanation of the data object classes later in this section.

encode_call( method, optional list of arguments )

Using the method name in the first argument and any additional arguments, creates the XML fragment for the methodCall portion of a request message and returns it.

encode_response( result value )

Creates a methodResponse XML fragment, using the return value passed as the argument.

encode_fault( code, message string )

Creates a methodResponse XML fragment using the passed code and string as the values for an XML-RPC fault.

serve( request message, method table )

Decodes the first argument as a XML-RPC request message, and attempts to look up the named method in the hash-table reference passed as the second argument. The hash reference should map method names to subroutine references. If the name is found in the table, the code reference is invoked with the arguments extracted from the request message. The return value of the routed call is returned by this method. If the named method isn't found, or if a fatal error occurs in the dispatched subroutine, a fatal exception is thrown in the form of die .

decode( message )

This method converts a XML-RPC message to a Perl structure that represents it in terms of native Perl data. The return value is a hash reference with three keys:

method_name

This field has data only when the decoded message was a request. In such a case, the value is the name of the method being called.

type

One of call , fault , or response . This field identifies the type of message that was decoded.

value

An array reference of the values in the message. When the message is a response or a fault , the array has only one element (in the case of faults, the element is always a hash reference with keys faultCode and faultString ). When the message is a request, the array contains all the parameters to the call (which also means it may be empty).

base64 , boolean , double , int , string , date_time

Each method returns a new data object containing the value passed in as an argument. The corresponding data classes are listed next . The return value is an object reference that can call a method named value to retrieve the underlying Perl value encapsulated within.

Here are the data classes RPC::XMLSimple manages :

RPC::XMLSimple::Base64

RPC::XMLSimple::Boolean

RPC::XMLSimple::Double

RPC::XMLSimple::Integer

RPC::XMLSimple::String

RPC::XMLSimple::DateTime::ISO8601

The correlation between the classes and the shortcut methods earlier should be clear. Each class implements the following two methods:

new( value )

Creates a new object of the class, with the given value.

value

Returns the value encapsulated by the object.

In practice, the convenience methods provided by the basic class as well as the client class should be sufficient. Direct use of these classes shouldn't be necessary. Note that the classes don't cover the array and structure types; these are identified by their reference status (as either array or hash references).

A.1.2 RPC::XMLSimple::Client

This class is used for developing client applications with the toolkit. The following methods set up the object and enable it to communicate transparently with a remote server.

new( optional key/value pairs )

This is the class constructor, returning a new instance object. The arguments are passed key/value pairs (not a hash reference). Here are the recognized arguments:

url

This argument is required. It specifies the remote address of the server the client is going to connect to.

proxy

If given, specifies a URL through which connections to the server are proxied .

encoding

Specifies a character encoding to use for outgoing messages. If not given, the XML default (UTF-8) remains.

use_objects

If passed with a non-zero value, all values from remote calls are returned to the application as data objects rather than native Perl values.

debug

If set to a non-zero value, causes the serialized XML request and response to be sent to the terminal.

call( method name, arguments list )

Attempts to call the named method with the given list of arguments on the remote server that was specified at object creation time. The return value from the request becomes the return value of this method. The data will be a Perl data, unless use_objects was set when the client object was created. In that case, the return value will be one of the data classes detailed earlier (or one of an array or hash reference).

base64 , boolean , double , int , string , date_time

These are convenience methods to make the data-wrapper classes available at the client level without instantiating an object of the RPC::XMLSimple class. Their function is identical to that of the earlier methods by the same name.

A.1.3 RPC::XMLSimple::Daemon

Server objects are created from this class. It provides only the constructor shown here, which goes immediately into the socket's listen-accept loop after procession the input arguments.

new( optional key/value pairs )

Creates a new object of the class, and drops into the accept-loop for the underlying IO::Socket::INET object. Like the previous classes, the arguments are passed as ordinary key/value pairs, not a hash reference. All the arguments are passed to the IO::Socket::INET super-class constructor unchanged. The only option recognized locally by the class is the following:

methods

This parameter takes a hash reference as the value. The hash reference maps RPC method names to subroutines references (which may also be anonymous subroutines or closures). The keys in the hash table are the names by which the routines will be called by remote clients . The values are used for indirect function calls, with all request arguments passed in their native Perl form. No other special processing is done.

Any arguments valid for IO::Socket::INET may be used here, such as LocalPort , ReuseAddr , etc.