Provided by: librpc-xml-perl_0.80-1_all bug

NAME

       RPC::XML::Client - An XML-RPC client class

SYNOPSIS

           require RPC::XML;
           require RPC::XML::Client;

           $cli = RPC::XML::Client->new('http://www.localhost.net/RPCSERV');
           $resp = $cli->send_request('system.listMethods');

           print ref $resp ? join(', ', @{$resp->value}) : "Error: $resp";

DESCRIPTION

       This is an XML-RPC client built upon the RPC::XML data classes, and using LWP::UserAgent
       and HTTP::Request for the communication layer. This client supports the full XML-RPC
       specification.

SUBROUTINES/METHODS

       The following methods are available:

       new (URI [, ARGS])
           Creates a new client object that will route its requests to the URL provided.  The
           constructor creates a HTTP::Request object and a LWP::UserAgent object, which are
           stored on the client object. When requests are made, these objects are ready to go,
           with the headers set appropriately. The return value of this method is a reference to
           the new object. The "URI" argument may be a string or an object from the URI class
           from CPAN.

           Any additional arguments are treated as key-value pairs. Most are attached to the
           object itself without change. The following are recognized by "new" and treated
           specially:

           parser
               If this parameter is passed, the value following it is expected to be an array
               reference. The contents of that array are passed to the new method of the
               RPC::XML::ParserFactory-generated object that the client object caches for its
               use. See the RPC::XML::ParserFactory manual page for a list of recognized
               parameters to the constructor.

           useragent
               This is similar to the "parser" argument above, and also expects an array
               reference to follow it. The contents are passed to the constructor of the
               LWP::UserAgent class when creating that component of the client object.  See the
               manual page for LWP::UserAgent for supported values.

           error_handler
               If passed, the value must be a code reference that will be invoked when a request
               results in a transport-level error. The closure will receive a single argument,
               the text of the error message from the failed communication attempt. It is
               expected to return a single value (assuming it returns at all).

           fault_handler
               If passed, the value must be a code reference. This one is invoked when a request
               results in a fault response from the server. The closure will receive a single
               argument, a RPC::XML::fault instance that can be used to retrieve the code and
               text-string of the fault. It is expected to return a single value (if it returns
               at all).

           combined_handler
               If this parameter is specified, it too must have a code reference as a value.  It
               is installed as the handler for both faults and errors. Should either of the other
               parameters be passed in addition to this one, they will take precedence over this
               (more-specific wins out over less). As a combined handler, the closure will get a
               string (non-reference) in cases of errors, and an instance of RPC::XML::fault in
               cases of faults. This allows the developer to install a simple default handler,
               while later providing a more specific one by means of the methods listed below.

           message_file_thresh
               If this key is passed, the value associated with it is assumed to be a numerical
               limit to the size of in-memory messages. Any out-bound request that would be
               larger than this when stringified is instead written to an anonynous temporary
               file, and spooled from there instead. This is useful for cases in which the
               request includes RPC::XML::base64 objects that are themselves spooled from file-
               handles. This test is independent of compression, so even if compression of a
               request would drop it below this threshold, it will be spooled anyway. The file
               itself is created via File::Temp with UNLINK=>1, so once it is freed the disk
               space is immediately freed.

           message_temp_dir
               If a message is to be spooled to a temporary file, this key can define a specific
               directory in which to open those files. If this is not given, then the "tmpdir"
               method from the File::Spec package is used, instead.

           See the section on the effects of callbacks on return values, below.

       uri ([URI])
           Returns the URI that the invoking object is set to communicate with for requests. If a
           string or "URI" class object is passed as an argument, then the URI is set to the new
           value. In either case, the pre-existing value is returned.

       useragent
           Returns the LWP::UserAgent object instance stored on the client object.  It is not
           possible to assign a new such object, though direct access to it should allow for any
           header modifications or other needed operations.

       request
           Returns the HTTP::Request object. As with the above, it is not allowed to assign a new
           object, but access to this value should allow for any needed operations.

       simple_request (ARGS)
           This is a somewhat friendlier wrapper around the next routine ("send_request") that
           returns Perl-level data rather than an object reference. The arguments may be the same
           as one would pass to the RPC::XML::request constructor, or there may be a single
           request object as an argument. The return value will be a native Perl value. If the
           return value is "undef", an error has occurred and "simple_request" has placed the
           error message in the global variable "$RPC::XML::ERROR".

       send_request (ARGS)
           Sends a request to the server and attempts to parse the returned data. The argument
           may be an object of the RPC::XML::request class, or it may be the arguments to the
           constructor for the request class. The return value will be either an error string or
           a data-type object. If the error encountered was a run-time error within the RPC
           request itself, then the call will return a "RPC::XML::fault" value rather than an
           error string.

           If the return value from "send_request" is not a reference, then it can only mean an
           error on the client-side (a local problem with the arguments and/or syntax, or a
           transport problem). All data-type classes now support a method called "is_fault" that
           may be easily used to determine if the "successful" return value is actually a
           "RPC::XML::fault" without the need to use "UNIVERSAL::ISA".

       error_handler ([CODEREF])
       fault_handler ([CODEREF])
       combined_handler ([CODEREF])
           These accessor methods get (and possibly set, if CODEREF is passed) the specified
           callback/handler. The return value is always the current handler, even when setting a
           new one (allowing for later restoration, if desired).

       credentials (REALM, USERNAME, PASSWORD)
           This sets the username and password for a given authentication realm at the location
           associated with the current request URL. Needed if the RPC location is protected by
           Basic Authentication. Note that changing the target URL of the client object to a
           different (protected) location would require calling this with new credentials for the
           new realm (even if the value of $realm is identical at both locations).

       timeout ([INTEGER])
           Get or set the current time-out value on the underlying LWP::UserAgent object that
           this object uses for sending requests. This is just a proxy through to the method of
           the same name in the LWP::UserAgent class. The return value is the current time-out
           value (prior to change, if a new value is given).

       message_file_thresh
       message_temp_dir
           These methods may be used to retrieve or alter the values of the given keys as defined
           earlier for the "new" method.

   Support for Content Compression
       The RPC::XML::Server class supports compression of requests and responses via the
       Compress::Zlib module available from CPAN. Accordingly, this class also supports
       compression. The methods used for communicating compression support should be compatible
       with the server and client classes from the XMLRPC::Lite class that is a part of the
       SOAP::Lite package (also available from CPAN).

       Compression support is enabled (or not) behind the scenes; if the Perl installation has
       Compress::Zlib, then RPC::XML::Client can deal with compressed responses. However, since
       outgoing messages are sent before a client generally has the chance to see if a server
       supports compression, these are not compressed by default.

       compress_requests(BOOL)
           If a client is communicating with a server that is known to support compressed
           messages, this method can be used to tell the client object to compress any outgoing
           messages that are longer than the threshold setting in bytes.

       compress_thresh([MIN_LIMIT])
           With no arguments, returns the current compression threshold; messages smaller than
           this number of bytes will not be compressed, regardless of the above method setting.
           If a number is passed, this is set to the new lower-limit. The default value is 4096
           (4k).

   Callbacks and Return Values
       If a callback is installed for errors or faults, it will be called before either of
       "send_request" or "simple_request" return. If the callback calls die or otherwise
       interrupts execution, then there is no need to worry about the effect on return values.
       Otherwise, the return value of the callback becomes the return value of the original
       method ("send_request" or "simple_request"). Thus, all callbacks are expected, if they
       return at all, to return exactly one value. It is recommended that any callback return
       values conform to the expected return values. That is, an error callback would return a
       string, a fault callback would return the fault object.

DIAGNOSTICS

       All methods return some type of reference on success, or an error string on failure. Non-
       reference return values should always be interpreted as errors, except in the case of
       "simple_request".

CAVEATS

       This began as a reference implementation in which clarity of process and readability of
       the code took precedence over general efficiency. It is now being maintained as production
       code, but may still have parts that could be written more efficiently.

BUGS

       Please report any bugs or feature requests to "bug-rpc-xml at rt.cpan.org", or through the
       web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RPC-XML>. I will be
       notified, and then you'll automatically be notified of progress on your bug as I make
       changes.

SUPPORT

       •   RT: CPAN's request tracker

           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>

       •   AnnoCPAN: Annotated CPAN documentation

           <http://annocpan.org/dist/RPC-XML>

       •   CPAN Ratings

           <http://cpanratings.perl.org/d/RPC-XML>

       •   Search CPAN

           <http://search.cpan.org/dist/RPC-XML>

       •   MetaCPAN

           <https://metacpan.org/release/RPC-XML>

       •   Source code on GitHub

           <http://github.com/rjray/rpc-xml>

LICENSE AND COPYRIGHT

       This file and the code within are copyright (c) 2011 by Randy J. Ray.

       Copying and distribution are permitted under the terms of the Artistic License 2.0
       (<http://www.opensource.org/licenses/artistic-license-2.0.php>) or the GNU LGPL 2.1
       (<http://www.opensource.org/licenses/lgpl-2.1.php>).

CREDITS

       The XML-RPC standard is Copyright (c) 1998-2001, UserLand Software, Inc.  See
       <http://www.xmlrpc.com> for more information about the XML-RPC specification.

SEE ALSO

       RPC::XML, RPC::XML::Server

AUTHOR

       Randy J. Ray "<rjray@blackperl.com>"