3 The xmlrpc module is a pure JavaScript XML-RPC server and client
for node.js.
5 Pure JavaScript means that the [XML parsing](https:
6 and [XML building](https:
7 libraries, so no extra C dependencies or build requirements. The xmlrpc module
8 can be used as an XML-RPC server, receiving method calls and responding with
9 method responses, or as an XML-RPC client, making method calls and receiving
10 method responses, or as both.
23 The file client_server.js in the example directory has a nicely commented
24 example of
using xmlrpc as an XML-RPC server and client (they even talk to each
30 var xmlrpc = require(
'xmlrpc')
33 var server = xmlrpc.createServer({ host:
'localhost', port: 9090 })
35 server.on(
'NotFound',
function(method, params) {
36 console.log(
'Method ' + method +
' does not exist');
39 server.on(
'anAction', function (err, params, callback) {
40 console.log(
'Method call params for \'anAction\': ' + params)
45 callback(null,
'aResult')
47 console.log(
'XML-RPC server listening on port 9091')
51 setTimeout(
function () {
54 var client = xmlrpc.createClient({ host:
'localhost', port: 9090, path:
'/'})
57 client.methodCall(
'anAction', [
'aParam'], function (error, value) {
59 console.log(
'Method response for \'anAction\': ' + value)
65 Output from the example:
68 XML-RPC server listening on port 9090
69 Method call params
for 'anAction': aParam
70 Method response
for 'anAction': aResult
73 ### Date/Time Formatting
75 XML-RPC dates are formatted according to ISO 8601. There are a number of
76 formatting options within the boundaries of the standard. The decoder detects
77 those formats and parses them automatically, but
for encoding dates to ISO
78 8601 some options can be specified to match your specific implementation.
81 The formatting options can be set through
82 ```xmlrpc.dateFormatter.setOpts(options);```, where the ```options```
83 parameter is an object, with the following (optional) boolean members:
85 * ```colons``` - enables/disables formatting the time portion with a colon as
86 separator (default: ```true```)
87 * ```hyphens``` - enables/disables formatting the date portion with a hyphen
88 as separator (default: ```false```)
89 * ```local``` - encode as local time instead of UTC (```true``` = local,
90 ```false``` = utc, default: ```true```)
91 * ```ms``` - enables/disables output of milliseconds (default: ```false```)
92 * ```offset``` - enables/disables output of UTC offset in case of local time
93 (default: ```false```)
96 Default format: 20140101T11:20:00
101 xmlrpc.dateFormatter.setOpts({
109 Local date + offset example:
111 xmlrpc.dateFormatter.setOpts({
122 It is possible to turn on cookies support
for XML-RPC client by special options
123 flag. If turned on then all the cookies received from server will be bounced
124 back with subsequent calls to the server. You also may manipulate cookies
125 manually by the setCookie/getCookie call.
128 var client = xmlrpc.createClient({
134 client.setCookie(
'login',
'bilbo');
137 client.methodCall(
'someAction', [],
function(error, value) {
139 console.log(client.getCookie(
'session'));
145 If you need to parse to a specific format or need to handle custom data types
146 that are not supported by
default, it is possible to extend the serializer
147 with a user-defined type
for your specific needs.
149 A custom type can be defined as follows:
151 var xmlrpc = require(
'xmlrpc');
152 var util = require(
'util');
155 var YourType =
function (raw) {
156 xmlrpc.CustomType.call(
this, raw);
160 util.inherits(YourType, xmlrpc.CustomType);
163 YourType.prototype.tagName =
'yourType';
166 YourType.prototype.serialize =
function (xml) {
167 var value = somefunction(this.raw);
168 return xml.ele(this.tagName).txt(value);
172 and then make your method calls, wrapping your variables inside your
new type
176 var client = xmlrpc.createClient(
'YOUR_ENDPOINT');
177 client.methodCall(
'YOUR_METHOD', [
new YourType(yourVariable)], yourCallback);
180 ### To Debug (client-side)
182 Error callbacks on the client are enriched with request and response
183 information and the returned body as
long as a http connection was made,
184 to aide with request debugging. Example:
187 var client = xmlrpc.createClient({ host:
'example.com', port: 80 });
188 client.methodCall(
'FAULTY_METHOD', [],
function (error, value) {
190 console.log(
'error:', error);
191 console.log(
'req headers:', error.req && error.req._header);
192 console.log(
'res code:', error.res && error.res.statusCode);
193 console.log(
'res body:', error.body);
195 console.log(
'value:', value);
213 XML-RPC must be precise so there are an extensive set of test cases in the test
214 directory. [Vows](http:
218 To run the test suite:
222 If submitting a bug fix, please update the appropriate test file too.
227 Released under the MIT license. See the LICENSE file for the complete wording.
232 Thank you to all [the
234 everyone who has filed an issue to help make xmlrpc better.