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 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
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           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
107           See the section on the effects of callbacks on return values,
108           below.
109
110       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
116       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
122       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
127       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
137       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
146           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
153       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
161       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
170       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
177       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
182   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
190       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
196       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
202       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
208   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

DIAGNOSTICS

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

CAVEATS

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

BUGS

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

SUPPORT

239       •   RT: CPAN's request tracker
240
241           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>
242
243       •   AnnoCPAN: Annotated CPAN documentation
244
245           <http://annocpan.org/dist/RPC-XML>
246
247       •   CPAN Ratings
248
249           <http://cpanratings.perl.org/d/RPC-XML>
250
251       •   Search CPAN
252
253           <http://search.cpan.org/dist/RPC-XML>
254
255       •   MetaCPAN
256
257           <https://metacpan.org/release/RPC-XML>
258
259       •   Source code on GitHub
260
261           <http://github.com/rjray/rpc-xml>
262
264       This file and the code within are copyright (c) 2011 by Randy J. Ray.
265
266       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

CREDITS

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

SEE ALSO

277       RPC::XML, RPC::XML::Server
278

AUTHOR

280       Randy J. Ray "<rjray@blackperl.com>"
281
282
283
284perl v5.38.0                      2023-07-21               RPC::XML::Client(3)
Impressum