1RPC::XML::Client(3) User Contributed Perl Documentation RPC::XML::Client(3)
2
6 RPC::XML::Client - An XML-RPC client class
7
9 require RPC::XML;
10 require RPC::XML::Client;
11 $cli = RPC::XML::Client->new('http://www.localhost.net/RPCSERV');
13 $resp = $cli->send_request('system.listMethods');
14 print ref $resp ? join(', ', @{$resp->value}) : "Error: $resp";
16
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
23 The following methods are available:
24 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 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 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 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 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 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 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 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 threshold, 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 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 request_as_string
100 For aiding in debugging, you can pass this key with a non-false
101 value to enable a step in each request cycle that saves a
102 stringified version of the request XML as a private key on the
103 client object. The request will be saved to the key
104 "_xmlrpc_request_as_string", and will endure until the next
105 request is made by the client object.
106 See the section on the effects of callbacks on return values,
108 below.
109 uri ([URI])
111 Returns the URI that the invoking object is set to communicate with
112 for requests. If a string or "URI" class object is passed as an
113 argument, then the URI is set to the new value. In either case, the
114 pre-existing value is returned.
115 useragent
117 Returns the LWP::UserAgent object instance stored on the client
118 object. It is not possible to assign a new such object, though
119 direct access to it should allow for any header modifications or
120 other needed operations.
121 request
123 Returns the HTTP::Request object. As with the above, it is not
124 allowed to assign a new object, but access to this value should
125 allow for any needed operations.
126 simple_request (ARGS)
128 This is a somewhat friendlier wrapper around the next routine
129 ("send_request") that returns Perl-level data rather than an object
130 reference. The arguments may be the same as one would pass to the
131 RPC::XML::request constructor, or there may be a single request
132 object as an argument. The return value will be a native Perl
133 value. If the return value is "undef", an error has occurred and
134 "simple_request" has placed the error message in the global
135 variable "$RPC::XML::ERROR".
136 send_request (ARGS)
138 Sends a request to the server and attempts to parse the returned
139 data. The argument may be an object of the RPC::XML::request class,
140 or it may be the arguments to the constructor for the request
141 class. The return value will be either an error string or a data-
142 type object. If the error encountered was a run-time error within
143 the RPC request itself, then the call will return a
144 "RPC::XML::fault" value rather than an error string.
145 If the return value from "send_request" is not a reference, then it
147 can only mean an error on the client-side (a local problem with the
148 arguments and/or syntax, or a transport problem). All data-type
149 classes now support a method called "is_fault" that may be easily
150 used to determine if the "successful" return value is actually a
151 "RPC::XML::fault" without the need to use "UNIVERSAL::ISA".
152 error_handler ([CODEREF])
154 fault_handler ([CODEREF])
155 combined_handler ([CODEREF])
156 These accessor methods get (and possibly set, if CODEREF is passed)
157 the specified callback/handler. The return value is always the
158 current handler, even when setting a new one (allowing for later
159 restoration, if desired).
160 credentials (REALM, USERNAME, PASSWORD)
162 This sets the username and password for a given authentication
163 realm at the location associated with the current request URL.
164 Needed if the RPC location is protected by Basic Authentication.
165 Note that changing the target URL of the client object to a
166 different (protected) location would require calling this with new
167 credentials for the new realm (even if the value of $realm is
168 identical at both locations).
169 timeout ([INTEGER])
171 Get or set the current time-out value on the underlying
172 LWP::UserAgent object that this object uses for sending requests.
173 This is just a proxy through to the method of the same name in the
174 LWP::UserAgent class. The return value is the current time-out
175 value (prior to change, if a new value is given).
176 message_file_thresh
178 message_temp_dir
179 These methods may be used to retrieve or alter the values of the
180 given keys as defined earlier for the "new" method.
181 Support for Content Compression
183 The RPC::XML::Server class supports compression of requests and
184 responses via the Compress::Zlib module available from CPAN.
185 Accordingly, this class also supports compression. The methods used for
186 communicating compression support should be compatible with the server
187 and client classes from the XMLRPC::Lite class that is a part of the
188 SOAP::Lite package (also available from CPAN).
189 Compression support is enabled (or not) behind the scenes; if the Perl
191 installation has Compress::Zlib, then RPC::XML::Client can deal with
192 compressed responses. However, since outgoing messages are sent before
193 a client generally has the chance to see if a server supports
194 compression, these are not compressed by default.
195 compress_requests(BOOL)
197 If a client is communicating with a server that is known to support
198 compressed messages, this method can be used to tell the client
199 object to compress any outgoing messages that are longer than the
200 threshold setting in bytes.
201 compress_thresh([MIN_LIMIT])
203 With no arguments, returns the current compression threshold;
204 messages smaller than this number of bytes will not be compressed,
205 regardless of the above method setting. If a number is passed, this
206 is set to the new lower-limit. The default value is 4096 (4k).
207 Callbacks and Return Values
209 If a callback is installed for errors or faults, it will be called
210 before either of "send_request" or "simple_request" return. If the
211 callback calls die or otherwise interrupts execution, then there is no
212 need to worry about the effect on return values. Otherwise, the return
213 value of the callback becomes the return value of the original method
214 ("send_request" or "simple_request"). Thus, all callbacks are expected,
215 if they return at all, to return exactly one value. It is recommended
216 that any callback return values conform to the expected return values.
217 That is, an error callback would return a string, a fault callback
218 would return the fault object.
219
221 All methods return some type of reference on success, or an error
222 string on failure. Non-reference return values should always be
223 interpreted as errors, except in the case of "simple_request".
224
226 This began as a reference implementation in which clarity of process
227 and readability of the code took precedence over general efficiency. It
228 is now being maintained as production code, but may still have parts
229 that could be written more efficiently.
230
232 Please report any bugs or feature requests to "bug-rpc-xml at
233 rt.cpan.org", or through the web interface at
234 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RPC-XML>. I will be
235 notified, and then you'll automatically be notified of progress on your
236 bug as I make changes.
237
239 • RT: CPAN's request tracker
240 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>
242 • AnnoCPAN: Annotated CPAN documentation
244 <http://annocpan.org/dist/RPC-XML>
246 • CPAN Ratings
248 <http://cpanratings.perl.org/d/RPC-XML>
250 • Search CPAN
252 <http://search.cpan.org/dist/RPC-XML>
254 • MetaCPAN
256 <https://metacpan.org/release/RPC-XML>
258 • Source code on GitHub
260 <http://github.com/rjray/rpc-xml>
262
264 This file and the code within are copyright (c) 2011 by Randy J. Ray.
265 Copying and distribution are permitted under the terms of the Artistic
267 License 2.0
268 (<http://www.opensource.org/licenses/artistic-license-2.0.php>) or the
269 GNU LGPL 2.1 (<http://www.opensource.org/licenses/lgpl-2.1.php>).
270
272 The XML-RPC standard is Copyright (c) 1998-2001, UserLand Software,
273 Inc. See <http://www.xmlrpc.com> for more information about the XML-
274 RPC specification.
275
277 RPC::XML, RPC::XML::Server
278
280 Randy J. Ray "<rjray@blackperl.com>"
281perl v5.38.0 2023-07-21 RPC::XML::Client(3)