The What
The xmlrpc module is a pure JavaScript XML-RPC server and client for node.js.
Pure JavaScript means that the XML parsing
and XML building use pure JavaScript
libraries, so no extra C dependencies or build requirements. The xmlrpc module
can be used as an XML-RPC server, receiving method calls and responding with
method responses, or as an XML-RPC client, making method calls and receiving
method responses, or as both.
The How
To Install
npm install xmlrpc
To Use
The file client_server.js in the example directory has a nicely commented
example of using xmlrpc as an XML-RPC server and client (they even talk to each
other!).
A brief example:
var xmlrpc = require('xmlrpc')
var server = xmlrpc.createServer({ host: 'localhost', port: 9090 })
server.on('NotFound', function(method, params) {
console.log('Method ' + method + ' does not exist');
})
server.on('anAction', function (err, params, callback) {
console.log('Method call params for \'anAction\': ' + params)
callback(null, 'aResult')
})
console.log('XML-RPC server listening on port 9091')
setTimeout(function () {
var client = xmlrpc.createClient({ host: 'localhost', port: 9090, path: '/'})
client.methodCall('anAction', ['aParam'], function (error, value) {
console.log('Method response for \'anAction\': ' + value)
})
}, 1000)
Output from the example:
XML-RPC server listening on port 9090
Method call params for 'anAction': aParam
Method response for 'anAction': aResult
Date/Time Formatting
XML-RPC dates are formatted according to ISO 8601. There are a number of
formatting options within the boundaries of the standard. The decoder detects
those formats and parses them automatically, but for encoding dates to ISO
8601 some options can be specified to match your specific implementation.
The formatting options can be set through
xmlrpc.dateFormatter.setOpts(options);
, where the options
parameter is an object, with the following (optional) boolean members:
colons
- enables/disables formatting the time portion with a colon as
separator (default: true
)hyphens
- enables/disables formatting the date portion with a hyphen
as separator (default: false
)local
- encode as local time instead of UTC (true
= local,
false
= utc, default: true
)ms
- enables/disables output of milliseconds (default: false
)offset
- enables/disables output of UTC offset in case of local time
(default: false
)
Default format: 20140101T11:20:00
UTC Example:
xmlrpc.dateFormatter.setOpts({
colons: true
, hyphens: true
, local: false
, ms: true
})
Local date + offset example:
xmlrpc.dateFormatter.setOpts({
colons: true
, hyphens: true
, local: true
, ms: false
, offset: true
})
Cookies support
It is possible to turn on cookies support for XML-RPC client by special options
flag. If turned on then all the cookies received from server will be bounced
back with subsequent calls to the server. You also may manipulate cookies
manually by the setCookie/getCookie call.
var client = xmlrpc.createClient({
host: 'localhost',
port: 9090,
cookies: true
});
client.setCookie('login', 'bilbo');
client.methodCall('someAction', [], function(error, value) {
console.log(client.getCookie('session'));
});
Custom Types
If you need to parse to a specific format or need to handle custom data types
that are not supported by default, it is possible to extend the serializer
with a user-defined type for your specific needs.
A custom type can be defined as follows:
var xmlrpc = require('xmlrpc');
var util = require('util');
var YourType = function (raw) {
xmlrpc.CustomType.call(this, raw);
};
util.inherits(YourType, xmlrpc.CustomType);
YourType.prototype.tagName = 'yourType';
YourType.prototype.serialize = function (xml) {
var value = somefunction(this.raw);
return xml.ele(this.tagName).txt(value);
}
and then make your method calls, wrapping your variables inside your new type
definition:
var client = xmlrpc.createClient('YOUR_ENDPOINT');
client.methodCall('YOUR_METHOD', [new YourType(yourVariable)], yourCallback);
To Debug (client-side)
Error callbacks on the client are enriched with request and response
information and the returned body as long as a http connection was made,
to aide with request debugging. Example:
var client = xmlrpc.createClient({ host: 'example.com', port: 80 });
client.methodCall('FAULTY_METHOD', [], function (error, value) {
if (error) {
console.log('error:', error);
console.log('req headers:', error.req && error.req._header);
console.log('res code:', error.res && error.res.statusCode);
console.log('res body:', error.body);
} else {
console.log('value:', value);
}
});
To Test
![Build
Status](https://secure.travis-ci.org/baalexander/node-xmlrpc.png)
XML-RPC must be precise so there are an extensive set of test cases in the test
directory. Vows is the testing framework and Travis
CI is used for Continuous
Integration.
To run the test suite:
npm test
If submitting a bug fix, please update the appropriate test file too.
The License (MIT)
Released under the MIT license. See the LICENSE file for the complete wording.
Contributors
Thank you to all the
authors and
everyone who has filed an issue to help make xmlrpc better.