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

NAME

6       RPC::XML - A set of classes for core data, message and XML handling
7

SYNOPSIS

9           use RPC::XML;
10
11           $req = RPC::XML::request->new('fetch_prime_factors',
12                                         RPC::XML::int->new(985_120_528));
13           ...
14           $resp = RPC::XML::ParserFactory->new()->parse(STREAM);
15           if (ref($resp))
16           {
17               return $resp->value->value;
18           }
19           else
20           {
21               die $resp;
22           }
23

DESCRIPTION

25       The RPC::XML package is an implementation of the XML-RPC standard. The
26       package as a whole provides classes for data, for clients, for servers
27       and for parsers (based on the XML::Parser and XML::LibXML packages from
28       CPAN).
29
30       This module provides a set of classes for creating values to pass to
31       the constructors for requests and responses. These are lightweight
32       objects, most of which are implemented as blessed scalar references so
33       as to associate specific type information with the value. Classes are
34       also provided for requests, responses and faults (errors).
35
36       This module does not actually provide any transport implementation or
37       server basis. For these, see RPC::XML::Client and RPC::XML::Server,
38       respectively.
39

SUBROUTINES/METHODS

41       At present, two subroutines are available for import. They must be
42       explicitly imported as part of the "use" statement, or with a direct
43       call to "import":
44
45       time2iso8601([$time])
46           Convert the integer time value in $time (which defaults to calling
47           the built-in "time" if not present) to a (pseudo) ISO 8601 string
48           in the UTC time zone. This is a convenience function for occassions
49           when the return value needs to be of the dateTime.iso8601 type, but
50           the value on hand is the return from the "time" built-in. Note that
51           the format of this string is not strictly compliant with ISO 8601
52           due to the way the dateTime.iso8601 data-type was defined in the
53           specification. See "DATES AND TIMES", below.
54
55       smart_encode(@args)
56           Converts the passed-in arguments to datatype objects. Any that are
57           already encoded as such are passed through unchanged. The routine
58           is called recursively on hash and array references. Note that this
59           routine can only deduce a certain degree of detail about the values
60           passed. Boolean values will be wrongly encoded as integers. Pretty
61           much anything not specifically recognizable will get encoded as a
62           string object. Thus, for types such as "fault", the ISO time value,
63           base-64 data, etc., the program must still explicitly encode it.
64           However, this routine will hopefully simplify things a little bit
65           for a majority of the usage cases.
66
67           If an argument is a blessed reference (an object), smart_encode
68           will generally treat it as a non-blessed reference of the
69           underlying type. That is, objects based on hash references will be
70           encoded as if they are unblessed hash references (becoming
71           RPC::XML::struct objects), objects based on array references are
72           encoded as array references (RPC::XML::array), etc.  Only hash
73           references, array references and scalar references are treated in
74           this fashion; any other blessed references cannot be down-graded
75           and will cause an exception to be thrown.
76
77           The exception to this are objects of the DateTime class: this
78           package does not utilize DateTime directly, but if you pass in a
79           reference to an existing object of that class, it is properly
80           converted to an object of the RPC::XML::datetime_iso8601 class.
81
82       In addition to these, the following "helper" functions are also
83       available. They may be imported explicitly, or all may be imported via
84       the tag ":types":
85
86           RPC_BOOLEAN RPC_INT RPC_I4 RPC_I8 RPC_DOUBLE
87           RPC_DATETIME_ISO8601 RPC_BASE64 RPC_STRING RPC_NIL
88
89       Each creates a data object of the appropriate type from a single value
90       (or, in the case of RPC_NIL, from no value). They are merely short-
91       hand for calling the constructors of the data classes directly.
92
93       All of the above (helpers and the first two functions) may be imported
94       via the tag ":all".
95

CLASSES

97       The classes provided by this module are broken into two groups: data
98       classes and message classes.
99
100   Data Classes
101       The following data classes are provided by this library. Each of these
102       provide at least the set of methods below. Note that these classes are
103       designed to create throw-away objects. There is currently no mechanism
104       for changing the value stored within one of these object after the
105       constructor returns. It is assumed that a new object would be created,
106       instead.
107
108       The common methods to all data classes are:
109
110       new($value)
111           Constructor. The value passed in is the value to be encapsulated in
112           the new object.
113
114       value
115           Returns the value kept in the object. Processes recursively for
116           "array" and "struct" objects.
117
118       as_string
119           Returns the value as a XML-RPC fragment, with the proper tags, etc.
120
121       serialize($filehandle)
122           Send the stringified rendition of the data to the given file
123           handle. This allows messages with arbitrarily-large base-64 data
124           within them to be sent without having to hold the entire message
125           within process memory.
126
127       length
128           Returns the length, in bytes, of the object when serialized into
129           XML. This is used by the client and server classes to calculate
130           message length.
131
132       type
133           Returns the type of data being stored in an object. The type
134           matches the XML-RPC specification, so the normalized form
135           "datetime_iso8601" comes back as "dateTime.iso8601".
136
137       is_fault
138           All types except the fault class return false for this. This is to
139           allow consistent testing of return values for fault status, without
140           checking for a hash reference with specific keys defined.
141
142       The classes themselves are:
143
144       RPC::XML::int
145           Creates an integer value. Constructor expects the integer value as
146           an argument.
147
148       RPC::XML::i4
149           This is like the "int" class. Note that services written in
150           strictly-typed languages such as C, C++ or Java may consider the
151           "i4" and "int" types as distinct and different.
152
153       RPC::XML::i8
154           This represents an 8-byte integer, and is not officially supported
155           by the XML-RPC specification. This has been added to accommodate
156           services already in use that have chosen to add this extension.
157
158       RPC::XML::double
159           Creates a floating-point value.
160
161       RPC::XML::string
162           Creates an arbitrary string. No special encoding is done to the
163           string (aside from XML document encoding, covered later) with the
164           exception of the "<", ">" and "&" characters, which are XML-escaped
165           during object creation, and then reverted when the "value" method
166           is called.
167
168       RPC::XML::boolean
169           Creates a boolean value. The value returned will always be either
170           of 1 or 0, for true or false, respectively. When calling the
171           constructor, the program may specify any of: 0, "no", "false", 1,
172           "yes", "true".
173
174       RPC::XML::datetime_iso8601
175           Creates an instance of the XML-RPC "dateTime.iso8601" type. The
176           specification for ISO 8601 may be found elsewhere. No processing is
177           done to the data. Note that the XML-RPC specification actually got
178           the format of an ISO 8601 date slightly wrong. Because this is what
179           is in the published spec, this package produces dates that match
180           the XML-RPC spec, not the the ISO 8601 spec. However, it will read
181           date-strings in proper ISO 8601 format. See "DATES AND TIMES",
182           below.
183
184       RPC::XML::nil
185           Creates a "nil" value. The value returned will always be undef. No
186           value should be passed when calling the constructor.
187
188           Note that nil is an extension to XML-RPC, which is not supported by
189           all implementations. $RPC::XML::ALLOW_NIL must be set to a non-
190           false value before objects of this type can be constructed. See
191           "GLOBAL VARIABLES". However, even if $RPC::XML::ALLOW_NIL is set to
192           a false value, the parsers will recognize the "<nil />" tag and
193           construct an object.
194
195           In practice, this type is only useful to denote the equivalent of a
196           "void" return value from a function. The type itself is not
197           interchangeable with any of the other data-types.
198
199       RPC::XML::base64
200           Creates an object that encapsulates a chunk of data that will be
201           treated as base-64 for transport purposes. The value may be passed
202           in as either a string or as a scalar reference. Additionally, a
203           second (optional) parameter may be passed, that if true identifies
204           the data as already base-64 encoded. If so, the data is decoded
205           before storage. The "value" method returns decoded data, and the
206           "as_string" method encodes it before stringification.
207
208           Alternately, the constructor may be given an open filehandle
209           argument instead of direct data. When this is the case, the data is
210           never read into memory in its entirety, unless the "value" or
211           "as_string" methods are called. This allows the manipulation of
212           arbitrarily-large Base-64-encoded data chunks. In these cases, the
213           flag (optional second argument) is still relevant, but the data is
214           not pre-decoded if it currently exists in an encoded form. It is
215           only decoded as needed. Note that the filehandle passed must be
216           open for reading, at least. It will not be written to, but it will
217           be read from. The position within the file will be preserved
218           between operations.
219
220           Because of this, this class supports a special method called
221           "to_file", that takes one argument. The argument may be either an
222           open, writable filehandle or a string. If it is a string, "to_file"
223           will attempt to open it as a file and write the decoded data to it.
224           If the argument is a an open filehandle, the data will be written
225           to it without any pre- or post-adjustment of the handle position
226           (nor will it be closed upon completion). This differs from the
227           "serialize" method in that it always writes the decoded data (where
228           the other always writes encoded data), and in that the XML opening
229           and closing tags are not written. The return value of "to_file" is
230           the size of the data written in bytes.
231
232       RPC::XML::array
233           Creates an array object. The constructor takes zero or more data-
234           type instances as arguments, which are inserted into the array in
235           the order specified. "value" returns an array reference of native
236           Perl types. If a non-null value is passed as an argument to
237           "value()", then the array reference will contain datatype objects
238           (a shallow rather than deep copy).
239
240       RPC::XML::struct
241           Creates a struct object, the analogy of a hash table in Perl. The
242           keys are ordinary strings, and the values must all be data-type
243           objects. The "value" method returns a hash table reference, with
244           native Perl types in the values.  Key order is not preserved. Key
245           strings are now encoded for special XML characters, so the use of
246           such ("<", ">", etc.) should be transparent to the user. If a non-
247           null value is passed as an argument to "value()", then the hash
248           reference will contain the datatype objects rather than native Perl
249           data (a shallow vs. deep copy, as with the array type above).
250
251           When creating RPC::XML::struct objects, there are two ways to pass
252           the content in for the new object: Either an existing hash
253           reference may be passed, or a series of key/value pairs may be
254           passed. If a reference is passed, the existing data is copied (the
255           reference is not re-blessed), with the values encoded into new
256           objects as needed.
257
258       RPC::XML::fault
259           A fault object is a special case of the struct object that checks
260           to ensure that there are two keys, "faultCode" and "faultString".
261
262           As a matter of convenience, since the contents of a RPC::XML::fault
263           structure are specifically defined, the constructor may be called
264           with exactly two arguments, the first of which will be taken as the
265           code, and the second as the string. They will be converted to
266           RPC::XML types automatically and stored by the pre-defined key
267           names.
268
269           Also as a matter of convenience, the fault class provides the
270           following accessor methods for directly retrieving the integer code
271           and error string from a fault object:
272
273           code
274           string
275
276           Both names should be self-explanatory. The values returned are Perl
277           values, not RPC::XML class instances.
278
279   Message Classes
280       The message classes are used both for constructing messages for
281       outgoing communication as well as representing the parsed contents of a
282       received message. Both implement the following methods:
283
284       new This is the constructor method for the two message classes. The
285           response class may have only a single value (as a response is
286           currently limited to a single return value), and requests may have
287           as many arguments as appropriate. In both cases, the arguments are
288           passed to the exported "smart_encode" routine described earlier.
289
290       as_string
291           Returns the message object expressed as an XML document. The
292           document will be lacking in linebreaks and indention, as it is not
293           targeted for human reading.
294
295       serialize($filehandle)
296           Serialize the message to the given file-handle. This avoids
297           creating the entire XML message within memory, which may be
298           relevant if there is especially-large Base-64 data within the
299           message.
300
301       length
302           Returns the total size of the message in bytes, used by the client
303           and server classes to set the Content-Length header.
304
305       The two message-object classes are:
306
307       RPC::XML::request
308           This creates a request object. A request object expects the first
309           argument to be the name of the remote routine being called, and all
310           remaining arguments are the arguments to that routine. Request
311           objects have the following methods (besides "new" and "as_string"):
312
313           name
314               The name of the remote routine that the request will call.
315
316           args
317               Returns a list reference with the arguments that will be
318               passed. No arguments will result in a reference to an empty
319               list.
320
321       RPC::XML::response
322           The response object is much like the request object in most ways.
323           It may take only one argument, as that is all the specification
324           allows for in a response. Responses have the following methods (in
325           addition to "new" and "as_string"):
326
327           value
328               The value the response is returning. It will be a RPC::XML
329               data-type.
330
331           is_fault
332               A boolean test whether or not the response is signalling a
333               fault. This is the same as taking the "value" method return
334               value and testing it, but is provided for clarity and
335               simplicity.
336

DATES AND TIMES

338       The XML-RPC specification refers to the date/time values as ISO 8601,
339       but unfortunately got the syntax slightly wrong in the examples.
340       However, since this is the published specification it is necessary to
341       produce time-stamps that conform to this format. The specification
342       implies that the only format for date/time values is:
343
344           YYYYMMDDThh:mm:ss
345
346       (Here, the "T" is literal, the rest represent elements of the date and
347       time.)  However, the ISO 8601 specification does not allow this
348       particular format, and in generally is considerably more flexible than
349       this.  Yet there are implementations of the XML-RPC standard in other
350       languages that rely on a strict interpretation of this format.
351
352       To accommodate this, the RPC::XML package only produces
353       dateTime.iso8601 values in the format given in the spec, with the
354       possible addition of timezone information if the string used to create
355       a RPC::XML::datetime_iso8601 instance included a timezone offset. The
356       string passed in to the constructor for that class must match:
357
358           \d\d\d\d-?\d\d-?\d\dT?\d\d:\d\d:\d\d([.,]\d+)?(Z|[-+]\d\d:\d\d)?
359
360       This pattern is also used by smart_encode to distinguish a date/time
361       string from a regular string. Note that the "T" is optional here, as it
362       is in the ISO 8601 spec. The timezone is optional, and if it is not
363       given then UTC is assumed. The XML-RPC specification says not to assume
364       anything about the timezone in the absence of one, but the format of
365       ISO 8601 declares that that absence of an explicit timezone dictates
366       UTC.
367
368       If you have DateTime::Format::ISO8601 installed, then
369       RPC::XML::datetime_iso8601 will fall back on it to try and parse any
370       input strings that do not match the above pattern. If the string cannot
371       be parsed by the DateTime::Format::ISO8601 module, then the constructor
372       returns undef and $RPC::XML::ERROR is set.
373

DIAGNOSTICS

375       All constructors (in all data classes) return "undef" upon failure,
376       with the error message available in the package-global variable
377       $RPC::XML::ERROR.
378

GLOBAL VARIABLES

380       The following global variables may be changed to control certain
381       behavior of the library. All variables listed below may be imported
382       into the application namespace when you "use" RPC::XML:
383
384       $ENCODING
385           This variable controls the character-set encoding reported in
386           outgoing XML messages. It defaults to "us-ascii", but may be set to
387           any value recognized by XML parsers.
388
389       $FORCE_STRING_ENCODING
390           By default, "smart_encode" uses heuristics to determine what
391           encoding is required for a data type. For example, 123 would be
392           encoded as "int", where 3.14 would be encoded as "double". In some
393           situations it may be handy to turn off all these heuristics, and
394           force encoding of "string" on all data types encountered during
395           encoding. Setting this flag to "true" will do just that.
396
397           Defaults to "false".
398
399       $ALLOW_NIL
400           By default, the XML-RPC "nil" extension is not supported. Set this
401           to a non-false value to allow use of nil values. Data objects that
402           are "nil" are represented as undef by Perl. See "The nil Datatype".
403

CAVEATS

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

BUGS

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

SUPPORT

418       ·   RT: CPAN's request tracker
419
420           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>
421
422       ·   AnnoCPAN: Annotated CPAN documentation
423
424           <http://annocpan.org/dist/RPC-XML>
425
426       ·   CPAN Ratings
427
428           <http://cpanratings.perl.org/d/RPC-XML>
429
430       ·   Search CPAN
431
432           <http://search.cpan.org/dist/RPC-XML>
433
434       ·   MetaCPAN
435
436           <https://metacpan.org/release/RPC-XML>
437
438       ·   Source code on GitHub
439
440           <http://github.com/rjray/rpc-xml>
441
443       This file and the code within are copyright (c) 2011 by Randy J. Ray.
444
445       Copying and distribution are permitted under the terms of the Artistic
446       License 2.0
447       (<http://www.opensource.org/licenses/artistic-license-2.0.php>) or the
448       GNU LGPL 2.1 (<http://www.opensource.org/licenses/lgpl-2.1.php>).
449

CREDITS

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

SEE ALSO

456       RPC::XML::Client, RPC::XML::Server
457

AUTHOR

459       Randy J. Ray <rjray@blackperl.com>
460
461
462
463perl v5.32.0                      2020-07-28                       RPC::XML(3)
Impressum