.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "RPC::XML::Client 3pm" .TH RPC::XML::Client 3pm "2021-01-10" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" RPC::XML::Client \- An XML\-RPC client class .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& require RPC::XML; \& require RPC::XML::Client; \& \& $cli = RPC::XML::Client\->new(\*(Aqhttp://www.localhost.net/RPCSERV\*(Aq); \& $resp = $cli\->send_request(\*(Aqsystem.listMethods\*(Aq); \& \& print ref $resp ? join(\*(Aq, \*(Aq, @{$resp\->value}) : "Error: $resp"; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This is an XML-RPC client built upon the \fB\s-1RPC::XML\s0\fR data classes, and using \&\fBLWP::UserAgent\fR and \fBHTTP::Request\fR for the communication layer. This client supports the full XML-RPC specification. .SH "SUBROUTINES/METHODS" .IX Header "SUBROUTINES/METHODS" The following methods are available: .IP "new (\s-1URI\s0 [, \s-1ARGS\s0])" 4 .IX Item "new (URI [, ARGS])" Creates a new client object that will route its requests to the \s-1URL\s0 provided. The constructor creates a \fBHTTP::Request\fR object and a \fBLWP::UserAgent\fR 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 \f(CW\*(C`URI\*(C'\fR argument may be a string or an object from the \fB\s-1URI\s0\fR class from \s-1CPAN.\s0 .Sp Any additional arguments are treated as key-value pairs. Most are attached to the object itself without change. The following are recognized by \f(CW\*(C`new\*(C'\fR and treated specially: .RS 4 .IP "parser" 4 .IX Item "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 \fBnew\fR method of the \&\fBRPC::XML::ParserFactory\fR\-generated object that the client object caches for its use. See the \fBRPC::XML::ParserFactory\fR manual page for a list of recognized parameters to the constructor. .IP "useragent" 4 .IX Item "useragent" This is similar to the \f(CW\*(C`parser\*(C'\fR argument above, and also expects an array reference to follow it. The contents are passed to the constructor of the \&\fBLWP::UserAgent\fR class when creating that component of the client object. See the manual page for \fBLWP::UserAgent\fR for supported values. .IP "error_handler" 4 .IX Item "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). .IP "fault_handler" 4 .IX Item "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 \fBRPC::XML::fault\fR 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). .IP "combined_handler" 4 .IX Item "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 \fBRPC::XML::fault\fR 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. .IP "message_file_thresh" 4 .IX Item "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 \fBRPC::XML::base64\fR 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. .IP "message_temp_dir" 4 .IX Item "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 \f(CW\*(C`tmpdir\*(C'\fR method from the \fBFile::Spec\fR package is used, instead. .IP "request_as_string" 4 .IX Item "request_as_string" For aiding in debugging, you can pass this key with a non-false value to enable a step in each request cycle that saves a stringified version of the request \&\s-1XML\s0 as a private key on the client object. The request will be saved to the key \f(CW\*(C`_xmlrpc_request_as_string\*(C'\fR, and will endure until the next request is made by the client object. .RE .RS 4 .Sp See the section on the effects of callbacks on return values, below. .RE .IP "uri ([\s-1URI\s0])" 4 .IX Item "uri ([URI])" Returns the \fB\s-1URI\s0\fR that the invoking object is set to communicate with for requests. If a string or \f(CW\*(C`URI\*(C'\fR class object is passed as an argument, then the \s-1URI\s0 is set to the new value. In either case, the pre-existing value is returned. .IP "useragent" 4 .IX Item "useragent" Returns the \fBLWP::UserAgent\fR 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. .IP "request" 4 .IX Item "request" Returns the \fBHTTP::Request\fR 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. .IP "simple_request (\s-1ARGS\s0)" 4 .IX Item "simple_request (ARGS)" This is a somewhat friendlier wrapper around the next routine (\f(CW\*(C`send_request\*(C'\fR) that returns Perl-level data rather than an object reference. The arguments may be the same as one would pass to the \fBRPC::XML::request\fR 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 \f(CW\*(C`undef\*(C'\fR, an error has occurred and \&\f(CW\*(C`simple_request\*(C'\fR has placed the error message in the global variable \&\f(CW\*(C`\f(CB$RPC::XML::ERROR\f(CW\*(C'\fR. .IP "send_request (\s-1ARGS\s0)" 4 .IX Item "send_request (ARGS)" Sends a request to the server and attempts to parse the returned data. The argument may be an object of the \fBRPC::XML::request\fR 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 \s-1RPC\s0 request itself, then the call will return a \&\f(CW\*(C`RPC::XML::fault\*(C'\fR value rather than an error string. .Sp If the return value from \f(CW\*(C`send_request\*(C'\fR 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 \f(CW\*(C`is_fault\*(C'\fR that may be easily used to determine if the \*(L"successful\*(R" return value is actually a \f(CW\*(C`RPC::XML::fault\*(C'\fR without the need to use \&\f(CW\*(C`UNIVERSAL::ISA\*(C'\fR. .IP "error_handler ([\s-1CODEREF\s0])" 4 .IX Item "error_handler ([CODEREF])" .PD 0 .IP "fault_handler ([\s-1CODEREF\s0])" 4 .IX Item "fault_handler ([CODEREF])" .IP "combined_handler ([\s-1CODEREF\s0])" 4 .IX Item "combined_handler ([CODEREF])" .PD These accessor methods get (and possibly set, if \s-1CODEREF\s0 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). .IP "credentials (\s-1REALM, USERNAME, PASSWORD\s0)" 4 .IX Item "credentials (REALM, USERNAME, PASSWORD)" This sets the username and password for a given authentication realm at the location associated with the current request \s-1URL.\s0 Needed if the \s-1RPC\s0 location is protected by Basic Authentication. Note that changing the target \s-1URL\s0 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 \f(CW$realm\fR is identical at both locations). .IP "timeout ([\s-1INTEGER\s0])" 4 .IX Item "timeout ([INTEGER])" Get or set the current time-out value on the underlying \fBLWP::UserAgent\fR object that this object uses for sending requests. This is just a proxy through to the method of the same name in the \fBLWP::UserAgent\fR class. The return value is the current time-out value (prior to change, if a new value is given). .IP "message_file_thresh" 4 .IX Item "message_file_thresh" .PD 0 .IP "message_temp_dir" 4 .IX Item "message_temp_dir" .PD These methods may be used to retrieve or alter the values of the given keys as defined earlier for the \f(CW\*(C`new\*(C'\fR method. .SS "Support for Content Compression" .IX Subsection "Support for Content Compression" The \fBRPC::XML::Server\fR class supports compression of requests and responses via the \fBCompress::Zlib\fR module available from \s-1CPAN.\s0 Accordingly, this class also supports compression. The methods used for communicating compression support should be compatible with the server and client classes from the \&\fBXMLRPC::Lite\fR class that is a part of the \fBSOAP::Lite\fR package (also available from \s-1CPAN\s0). .PP Compression support is enabled (or not) behind the scenes; if the Perl installation has \fBCompress::Zlib\fR, then \fBRPC::XML::Client\fR 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. .IP "compress_requests(\s-1BOOL\s0)" 4 .IX Item "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. .IP "compress_thresh([\s-1MIN_LIMIT\s0])" 4 .IX Item "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). .SS "Callbacks and Return Values" .IX Subsection "Callbacks and Return Values" If a callback is installed for errors or faults, it will be called before either of \f(CW\*(C`send_request\*(C'\fR or \f(CW\*(C`simple_request\*(C'\fR return. If the callback calls \&\fBdie\fR 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 (\f(CW\*(C`send_request\*(C'\fR or \&\f(CW\*(C`simple_request\*(C'\fR). 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. .SH "DIAGNOSTICS" .IX Header "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 \f(CW\*(C`simple_request\*(C'\fR. .SH "CAVEATS" .IX Header "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. .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests to \&\f(CW\*(C`bug\-rpc\-xml at rt.cpan.org\*(C'\fR, or through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. .SH "SUPPORT" .IX Header "SUPPORT" .IP "\(bu" 4 \&\s-1RT: CPAN\s0's request tracker .Sp .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .IP "\(bu" 4 Search \s-1CPAN\s0 .Sp .IP "\(bu" 4 MetaCPAN .Sp .IP "\(bu" 4 Source code on GitHub .Sp .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" This file and the code within are copyright (c) 2011 by Randy J. Ray. .PP Copying and distribution are permitted under the terms of the Artistic License 2.0 () or the \s-1GNU LGPL 2.1\s0 (). .SH "CREDITS" .IX Header "CREDITS" The \fBXML-RPC\fR standard is Copyright (c) 1998\-2001, UserLand Software, Inc. See for more information about the \fBXML-RPC\fR specification. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\s-1RPC::XML\s0, RPC::XML::Server .SH "AUTHOR" .IX Header "AUTHOR" Randy J. Ray \f(CW\*(C`\*(C'\fR