-
Notifications
You must be signed in to change notification settings - Fork 4
/
xmlrpc_js.xml
367 lines (290 loc) · 14.5 KB
/
xmlrpc_js.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
<?xml version="1.0" encoding="ISO-8859-1"?>
<?xml-stylesheet href="docbook-css/driver.css" type="text/css"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!--
JS-XMLRPC User manual
-->
<book lang="en">
<title>JS-XMLRPC</title>
<subtitle>version 0.6.2</subtitle>
<bookinfo>
<date>19 12 2012</date>
<author>
<surname>Gaetano Giunta</surname>
</author>
<copyright>
<year>2007-2022 G. Giunta</year>
</copyright>
</bookinfo>
<chapter>
<title>Introduction</title>
<para>This collection of Javascript classes provides a framework for writing XML-RPC and JSON-RPC clients.</para>
<para>Main goals of the project are ease of use, flexibility and completeness. And of course, full API compatibility
with the <ulink url="https://github.com/gggeek/phpxmlrpc">PHP-XMLRPC</ulink> library.</para>
<para>XML-RPC is a format devised by <ulink url="http://www.userland.com/">Userland Software</ulink> for achieving
remote procedure call via XML using HTTP as the transport. XML-RPC has its own web site, <ulink
url="http://www.xmlrpc.com/">www.xmlrpc.com.</ulink></para>
<para><ulink url="https://www.json.org/">JSON</ulink> is a format devised to ease serialization and deserialization
of common data types without incurring the overhead that is normally associated with XML. It is a subset of the
Javascript language, and as such it is easily manipulated within web browsers.</para>
<para><ulink url="https://www.jsonrpc.org">JSON-RPC</ulink> is a remote procedure call protocol that uses HTTP for
transport and a json syntax extremely similar to the xml-rpc one.</para>
<para>Many thanks to the original author of the PHP-XMLRPC library: Edd Dumbill of <ulink
url="http://usefulinc.com/">Useful Information Company</ulink>, to Jan-Klaas Kollhof for the Jsolait library and to
the Yahoo! YUI team, for building such an incredible toolkit.</para>
</chapter>
<chapter>
<title>What's new</title>
<sect1>
<para>For all releases after 0.4, see the release info on GitHub at <ulink
url="https://github.com/gggeek/jsxmlrpc/releases">https://github.com/gggeek/jsxmlrpc/releases</ulink></para>
</sect1>
<sect1>
<title>version 0.4</title>
<para><itemizedlist>
<listitem>
<para>added method setUserCredentials to xmlrpc_client, as the
'parent' php lib does in its latest version</para>
</listitem>
<listitem>
<para>added support for the <ex:nil/> tag from the apache
library, both in input and output (output regulated by the
xmlrpc_null_apache_encoding variable, input by
thexmlrpc_null_extension one)</para>
</listitem>
<listitem>
<para>base64_decode now trims whitespace</para>
</listitem>
<listitem>
<para>updated bundled yui to version 2.5.0</para>
</listitem>
<listitem>
<para>fixed a bug in error log handler when using
firefox+firebug</para>
</listitem>
<listitem>
<para>fixed a bug in xmlrpc_decode with structs</para>
</listitem>
<listitem>
<para>fixed a bug in parsing cookie headers in http
responses</para>
</listitem>
<listitem>
<para>allow lib to work in Windows Scripting Host
environments</para>
</listitem>
<listitem>
<para>added two demo files, for WSH and VB</para>
</listitem>
</itemizedlist></para>
</sect1>
<sect1>
<title>version 0.3</title>
<para><itemizedlist>
<listitem>
<para>A lot of bugs have been fixed in all areas of encoding and
decoding xmlrpc values</para>
</listitem>
<listitem>
<para>The debug and error logging mechanism has been rewritten,
and will take advantage of Firebug when detected</para>
</listitem>
<listitem>
<para>There is better support for Firefox when setting debug mode
to clients, and for Safari when the port is not specified in the
server url</para>
</listitem>
<listitem>
<para>The function <function>wrap_xmlrpc_server</function> (from
the original PHP api) has been implemented, and a couple of bugs
fixed in <function>wrap_xmlrpc_method</function></para>
</listitem>
</itemizedlist></para>
</sect1>
<sect1>
<title>version 0.2</title>
<para><itemizedlist>
<listitem>
<para><methodname>client.send()</methodname> supports async calls.
In order to activate this functionality, pass a function as third
parameter. Note that the timeout parameter only has effect in
async calls.</para>
</listitem>
<listitem>
<para>the <function>wrap_xmlrpc_method</function>() function is
finally working. It makes the wrapping of remote webservicesinto
native javascript functions (a.k.a. proxying) a snap</para>
</listitem>
<listitem>
<para>the debugger can nowgenerate example code for invocation of
remote methods</para>
</listitem>
<listitem>
<para>minor assorted bugfixes, especially for Internet
Explorer</para>
</listitem>
<listitem>
<para>a minified (ie. compact) version of the library has been
included in the distribution. It can be used instead of the
standard version on webservers where bandwidth savings are
important</para>
</listitem>
<listitem>
<para>better documentation has been included in the distribution,
most notably the (almost complete) API specification</para>
</listitem>
</itemizedlist></para>
</sect1>
<sect1>
<title>version 0.1</title>
<para>Initial release of the library. Many "nice bits" are still missing
(see <link linkend="Chapter5">Chapter 5</link> below), but the basic
encoding/decoding functionality should be ok.</para>
</sect1>
</chapter>
<chapter>
<title>System requirements</title>
<para>Any browser or Javascript host with support for ECMAScript 6 including XMLHttpRequest and DOMParser. That
should include NodeJS version v12.20.0 or v14.13.0 or later and Chrome 61, Edge 16, Firefox 60, Opera 48, Safari 11,
Chrome Android 108, Firefox for Android 107, Opera Mobile 72, Safari on iOS 11, Samsung Internet 8.2.</para>
<para>Your mileage may vary on other browsers / javascript hosts.</para>
</chapter>
<chapter>
<title>Files in the distribution</title>
<para><itemizedlist>
<listitem>
<para><filename>lib/xmlrpc_lib.js</filename>: the XML_RPC classes.
This is the core library needed by all other files</para>
</listitem>
<listitem>
<para><filename>lib/jsonrpc_lib.js</filename>: the JSON-RPC classes</para>
</listitem>
<listitem>
<para><filename>lib/xmlrpc_wrappers.js</filename>: helper functions to "automagically" convert calls to remote
webservices into javascript classes / functions</para>
</listitem>
<listitem>
<para><filename>lib/index.js</filename>: this file contains all module exports from the 3 files listed above,
making it easy to import everything from a single `import` line</para>
</listitem>
<listitem>
<para><filename>debugger/debugger.html</filename>: a graphical webservice debugger</para>
</listitem>
<listitem>
<para><filename>debugger/visualeditor.html</filename>,
<filename>debugger/visualeditor.css</filename>,
<filename>debugger/xmlrpc_display.js</filename>,
<filename>debugger/xmlrpc_tree.css</filename>, plus all the other files (taken from the YUI distribution):
visual editor component for creating arbitrarily nested xml-rpc/json-rpc values. It can be used as part of the
js-xmlrpc debugger, as well as in the debugger that comes with the PHP-XMLRPC library or the docxmlrpcserver
class part of phpxmlrpc/extras php package</para>
</listitem>
<listitem>
<para><filename>doc/xmlrpc_js.xml</filename>: the docbook source file for this manual</para>
</listitem>
<listitem>
<para><filename>doc/manual/*.html</filename>,
<filename>doc/manual/*.css</filename>: this manual, in HTML format</para>
</listitem>
<listitem>
<para><filename>README.md</filename>; <filename>NEWS.md</filename>: as the name implies, useful
information bits</para>
</listitem>
</itemizedlist></para>
</chapter>
<chapter>
<title id="Chapter5">Known bugs and limitations</title>
<para>Missing functionality that is part of the PHP-XMLRPC library include: handling of charset encoding (where
explicitly requested by the user); timeout in send() methods for the sync calls; compression of requests; handling
of compression, chunked encoding in parseResponseHeaders (the response body is decoded correctly by the browser);
encoding/decoding of anonymous js classes via an xml attribute (since it is hard to recover a class name, we could
encode instead all methods as code); allow username/password auth be specified in URL when creating a client object;
using client credentials for https auth</para>
<para>Other: demo cases, reduce JSLint warnings, a testsuite and speed tests</para>
</chapter>
<chapter>
<title>Support</title>
<para>JS-XMLRPC is offered "as-is" without any warranty or commitment to support. However, informal advice and help
is available via the JS-XMLRPC website.</para>
<itemizedlist>
<listitem>
<para>The <emphasis>JS-XMLRPC</emphasis> development is hosted on <ulink
url="https://github.com/gggeek/jsxmlrpc">github.com/gggeek/jsxmlrpc</ulink>. Bugs, feature requests and patches
can be posted to the <ulink url="https://github.com/gggeek/jsxmlrpc/issues">project's website</ulink>.</para>
</listitem>
</itemizedlist>
</chapter>
<chapter>
<title>Class documentation</title>
<para>Where's the meat?</para>
<para>Unfortunately, the documentation of the API exposed by the library
has not (yet) really been integrated into the manual.</para>
<para>Luckily, it is available in HTML format online at: <ulink url="???">...</ulink>. You can build it locally
too if so inclined</para>
<para>For more details, the manual that comes with the php-xmlrpc library might prove helpful: after all the two
libraries share the exact same API (except for a handful of small quirks due to differences in the underlying
language, detailed in Apendix A). It is available online at <ulink
url="https://gggeek.github.io/phpxmlrpc/doc-2/">https://gggeek.github.io/phpxmlrpc/doc-2/</ulink></para>
</chapter>
<appendix>
<title>Known differences from the PHP-XMLRPC API</title>
<para>Although the library is designed to implent the same programming interfaces of the php-xmlrpc library,
differences in the languages (javascript vs. pgp) and underlying platform (browser vs. php engine) prevent a complete
match. This list details the known differences in the behaviour of the two libraries. Please note that most of the
discrepancies deal with private members of objects, unusual usage patterns and little known corner cases, and are
mostly of interest to people that wish to extend / modify the library rather than just use it.</para>
<para><itemizedlist>
<listitem>
<para>the internal, private structure of the xmlrpcval objects is slightly different</para>
</listitem>
<listitem>
<para>xmlrpcresp.serialize() produces a complete xml chunk, including the xml prologue. In php-xmlrpc the
prologue is omitted</para>
</listitem>
<listitem>
<para>adding data to a struct value using the same keys of elements that already exist in the struct might
produce different results</para>
</listitem>
<listitem>
<para>xmlrpcresp objects have no private member 'content-type'</para>
</listitem>
<listitem>
<para>the values of the global object 'xmlrpcTypes' (an array in php) differ (although the keys are the same)
</para>
</listitem>
<listitem>
<para>the method <methodname>xmlrpcval::addScalar()</methodname> does not coerce values to the appropriate
type when declaring them as boolean</para>
</listitem>
<listitem>
<para>the method <methodname>xmlrpcmsg::parseResponse()</methodname> can take a string as second parameter
(which is assumed to be the full http response headers text)</para>
</listitem>
<listitem>
<para>all classes have an <methodname>init()</methodname> constructor method (used for subclassing)</para>
</listitem>
<listitem>
<para>when using a browser as javascript host, the client object by default inherits the browser settings with
regard to http connections, eg. it can have keepalive ON, make use of HTTP 1.1 and will support receiving
compressed content and content in many charsets (the browser taking care of the transcoding)</para>
</listitem>
<listitem>
<para>the client object by default will send to the server any cookie received in previous requests. In
php-xmlrpc all cookie handling has to be done by hand</para>
</listitem>
<listitem>
<para>the client object does not support setting ssl certificates, proxies, ntlm authorization</para>
</listitem>
<listitem>
<para>all output generated by the lib is performed by two functions:
<function>xmlrpc_error_log</function> and
<function>xmlrpc_debug_log</function> (for which the user can set up a message handler), whereas in php it
is sent to stdout and stderr</para>
</listitem>
<listitem>
<para>method names are case sensitive in javascript, and this lib respects camelCase convention</para>
</listitem>
</itemizedlist></para>
</appendix>
</book>