1RPC::XML::Client(3)   User Contributed Perl Documentation  RPC::XML::Client(3)
2
3
4

NAME

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

SYNOPSIS

9           require RPC::XML;
10           require RPC::XML::Client;
11
12           $cli = RPC::XML::Client->new('http://www.localhost.net/RPCSERV');
13           $resp = $cli->send_request('system.listMethods');
14
15           print ref $resp ? join(', ', @{$resp->value}) : "Error: $resp";
16

DESCRIPTION

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

SUBROUTINES/METHODS

23       The following methods are available:
24
25       new (URI [, ARGS])
26           Creates a new client object that will route its requests to the URL
27           provided.  The constructor creates a HTTP::Request object and a
28           LWP::UserAgent object, which are stored on the client object. When
29           requests are made, these objects are ready to go, with the headers
30           set appropriately. The return value of this method is a reference
31           to the new object. The "URI" argument may be a string or an object
32           from the URI class from CPAN.
33
34           Any additional arguments are treated as key-value pairs. Most are
35           attached to the object itself without change. The following are
36           recognized by "new" and treated specially:
37
38           parser
39               If this parameter is passed, the value following it is expected
40               to be an array reference. The contents of that array are passed
41               to the new method of the RPC::XML::ParserFactory-generated
42               object that the client object caches for its use. See the
43               RPC::XML::ParserFactory manual page for a list of recognized
44               parameters to the constructor.
45
46           useragent
47               This is similar to the "parser" argument above, and also
48               expects an array reference to follow it. The contents are
49               passed to the constructor of the LWP::UserAgent class when
50               creating that component of the client object.  See the manual
51               page for LWP::UserAgent for supported values.
52
53           error_handler
54               If passed, the value must be a code reference that will be
55               invoked when a request results in a transport-level error. The
56               closure will receive a single argument, the text of the error
57               message from the failed communication attempt. It is expected
58               to return a single value (assuming it returns at all).
59
60           fault_handler
61               If passed, the value must be a code reference. This one is
62               invoked when a request results in a fault response from the
63               server. The closure will receive a single argument, a
64               RPC::XML::fault instance that can be used to retrieve the code
65               and text-string of the fault. It is expected to return a single
66               value (if it returns at all).
67
68           combined_handler
69               If this parameter is specified, it too must have a code
70               reference as a value.  It is installed as the handler for both
71               faults and errors. Should either of the other parameters be
72               passed in addition to this one, they will take precedence over
73               this (more-specific wins out over less). As a combined handler,
74               the closure will get a string (non-reference) in cases of
75               errors, and an instance of RPC::XML::fault in cases of faults.
76               This allows the developer to install a simple default handler,
77               while later providing a more specific one by means of the
78               methods listed below.
79
80           message_file_thresh
81               If this key is passed, the value associated with it is assumed
82               to be a numerical limit to the size of in-memory messages. Any
83               out-bound request that would be larger than this when
84               stringified is instead written to an anonynous temporary file,
85               and spooled from there instead. This is useful for cases in
86               which the request includes RPC::XML::base64 objects that are
87               themselves spooled from file-handles. This test is independent
88               of compression, so even if compression of a request would drop
89               it below this threshhold, it will be spooled anyway. The file
90               itself is created via File::Temp with UNLINK=>1, so once it is
91               freed the disk space is immediately freed.
92
93           message_temp_dir
94               If a message is to be spooled to a temporary file, this key can
95               define a specific directory in which to open those files. If
96               this is not given, then the "tmpdir" method from the File::Spec
97               package is used, instead.
98
99           See the section on the effects of callbacks on return values,
100           below.
101
102       uri ([URI])
103           Returns the URI that the invoking object is set to communicate with
104           for requests. If a string or "URI" class object is passed as an
105           argument, then the URI is set to the new value. In either case, the
106           pre-existing value is returned.
107
108       useragent
109           Returns the LWP::UserAgent object instance stored on the client
110           object.  It is not possible to assign a new such object, though
111           direct access to it should allow for any header modifications or
112           other needed operations.
113
114       request
115           Returns the HTTP::Request object. As with the above, it is not
116           allowed to assign a new object, but access to this value should
117           allow for any needed operations.
118
119       simple_request (ARGS)
120           This is a somewhat friendlier wrapper around the next routine
121           ("send_request") that returns Perl-level data rather than an object
122           reference. The arguments may be the same as one would pass to the
123           RPC::XML::request constructor, or there may be a single request
124           object as an argument. The return value will be a native Perl
125           value. If the return value is "undef", an error has occurred and
126           "simple_request" has placed the error message in the global
127           variable "$RPC::XML::ERROR".
128
129       send_request (ARGS)
130           Sends a request to the server and attempts to parse the returned
131           data. The argument may be an object of the RPC::XML::request class,
132           or it may be the arguments to the constructor for the request
133           class. The return value will be either an error string or a data-
134           type object. If the error encountered was a run-time error within
135           the RPC request itself, then the call will return a
136           "RPC::XML::fault" value rather than an error string.
137
138           If the return value from "send_request" is not a reference, then it
139           can only mean an error on the client-side (a local problem with the
140           arguments and/or syntax, or a transport problem). All data-type
141           classes now support a method called "is_fault" that may be easily
142           used to determine if the "successful" return value is actually a
143           "RPC::XML::fault" without the need to use "UNIVERSAL::ISA".
144
145       error_handler ([CODEREF])
146       fault_handler ([CODEREF])
147       combined_handler ([CODEREF])
148           These accessor methods get (and possibly set, if CODEREF is passed)
149           the specified callback/handler. The return value is always the
150           current handler, even when setting a new one (allowing for later
151           restoration, if desired).
152
153       credentials (REALM, USERNAME, PASSWORD)
154           This sets the username and password for a given authentication
155           realm at the location associated with the current request URL.
156           Needed if the RPC location is protected by Basic Authentication.
157           Note that changing the target URL of the client object to a
158           different (protected) location would require calling this with new
159           credentials for the new realm (even if the value of $realm is
160           identical at both locations).
161
162       timeout ([INTEGER])
163           Get or set the current time-out value on the underlying
164           LWP::UserAgent object that this object uses for sending requests.
165           This is just a proxy through to the method of the same name in the
166           LWP::UserAgent class. The return value is the current time-out
167           value (prior to change, if a new value is given).
168
169       message_file_thresh
170       message_temp_dir
171           These methods may be used to retrieve or alter the values of the
172           given keys as defined earlier for the "new" method.
173
174   Support for Content Compression
175       The RPC::XML::Server class supports compression of requests and
176       responses via the Compress::Zlib module available from CPAN.
177       Accordingly, this class also supports compression. The methods used for
178       communicating compression support should be compatible with the server
179       and client classes from the XMLRPC::Lite class that is a part of the
180       SOAP::Lite package (also available from CPAN).
181
182       Compression support is enabled (or not) behind the scenes; if the Perl
183       installation has Compress::Zlib, then RPC::XML::Client can deal with
184       compressed responses. However, since outgoing messages are sent before
185       a client generally has the chance to see if a server supports
186       compression, these are not compressed by default.
187
188       compress_requests(BOOL)
189           If a client is communicating with a server that is known to support
190           compressed messages, this method can be used to tell the client
191           object to compress any outgoing messages that are longer than the
192           threshhold setting in bytes.
193
194       compress_thresh([MIN_LIMIT])
195           With no arguments, returns the current compression threshhold;
196           messages smaller than this number of bytes will not be compressed,
197           regardless of the above method setting. If a number is passed, this
198           is set to the new lower-limit. The default value is 4096 (4k).
199
200   Callbacks and Return Values
201       If a callback is installed for errors or faults, it will be called
202       before either of "send_request" or "simple_request" return. If the
203       callback calls die or otherwise interrupts execution, then there is no
204       need to worry about the effect on return values. Otherwise, the return
205       value of the callback becomes the return value of the original method
206       ("send_request" or "simple_request"). Thus, all callbacks are expected,
207       if they return at all, to return exactly one value. It is recommended
208       that any callback return values conform to the expected return values.
209       That is, an error callback would return a string, a fault callback
210       would return the fault object.
211

DIAGNOSTICS

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

CAVEATS

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

BUGS

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

SUPPORT

231       ·   RT: CPAN's request tracker
232
233           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>
234
235       ·   AnnoCPAN: Annotated CPAN documentation
236
237           <http://annocpan.org/dist/RPC-XML>
238
239       ·   CPAN Ratings
240
241           <http://cpanratings.perl.org/d/RPC-XML>
242
243       ·   Search CPAN
244
245           <http://search.cpan.org/dist/RPC-XML>
246
247       ·   MetaCPAN
248
249           <https://metacpan.org/release/RPC-XML>
250
251       ·   Source code on GitHub
252
253           <http://github.com/rjray/rpc-xml>
254
256       This file and the code within are copyright (c) 2011 by Randy J. Ray.
257
258       Copying and distribution are permitted under the terms of the Artistic
259       License 2.0
260       (<http://www.opensource.org/licenses/artistic-license-2.0.php>) or the
261       GNU LGPL 2.1 (<http://www.opensource.org/licenses/lgpl-2.1.php>).
262

CREDITS

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

SEE ALSO

269       RPC::XML, RPC::XML::Server
270

AUTHOR

272       Randy J. Ray "<rjray@blackperl.com>"
273
274
275
276perl v5.30.1                      2020-01-30               RPC::XML::Client(3)
Impressum