00001 ## The What
00002
00003 The xmlrpc module is a pure JavaScript XML-RPC server and client for node.js.
00004
00005 Pure JavaScript means that the [XML parsing](https:
00006 and [XML building](https:
00007 libraries, so no extra C dependencies or build requirements. The xmlrpc module
00008 can be used as an XML-RPC server, receiving method calls and responding with
00009 method responses, or as an XML-RPC client, making method calls and receiving
00010 method responses, or as both.
00011
00012
00013 ## The How
00014
00015 ### To Install
00016
00017 ```bash
00018 npm install xmlrpc
00019 ```
00020
00021 ### To Use
00022
00023 The file client_server.js in the example directory has a nicely commented
00024 example of using xmlrpc as an XML-RPC server and client (they even talk to each
00025 other!).
00026
00027 A brief example:
00028
00029 ```javascript
00030 var xmlrpc = require('xmlrpc')
00031
00032
00033 var server = xmlrpc.createServer({ host: 'localhost', port: 9090 })
00034
00035 server.on('NotFound', function(method, params) {
00036 console.log('Method ' + method + ' does not exist');
00037 })
00038
00039 server.on('anAction', function (err, params, callback) {
00040 console.log('Method call params for \'anAction\': ' + params)
00041
00042
00043
00044
00045 callback(null, 'aResult')
00046 })
00047 console.log('XML-RPC server listening on port 9091')
00048
00049
00050
00051 setTimeout(function () {
00052
00053
00054 var client = xmlrpc.createClient({ host: 'localhost', port: 9090, path: '/'})
00055
00056
00057 client.methodCall('anAction', ['aParam'], function (error, value) {
00058
00059 console.log('Method response for \'anAction\': ' + value)
00060 })
00061
00062 }, 1000)
00063 ```
00064
00065 Output from the example:
00066
00067 ```
00068 XML-RPC server listening on port 9090
00069 Method call params for 'anAction': aParam
00070 Method response for 'anAction': aResult
00071 ```
00072
00073 ### Date/Time Formatting
00074
00075 XML-RPC dates are formatted according to ISO 8601. There are a number of
00076 formatting options within the boundaries of the standard. The decoder detects
00077 those formats and parses them automatically, but for encoding dates to ISO
00078 8601 some options can be specified to match your specific implementation.
00079
00080
00081 The formatting options can be set through
00082 ```xmlrpc.dateFormatter.setOpts(options);```, where the ```options```
00083 parameter is an object, with the following (optional) boolean members:
00084
00085 * ```colons``` - enables/disables formatting the time portion with a colon as
00086 separator (default: ```true```)
00087 * ```hyphens``` - enables/disables formatting the date portion with a hyphen
00088 as separator (default: ```false```)
00089 * ```local``` - encode as local time instead of UTC (```true``` = local,
00090 ```false``` = utc, default: ```true```)
00091 * ```ms``` - enables/disables output of milliseconds (default: ```false```)
00092 * ```offset``` - enables/disables output of UTC offset in case of local time
00093 (default: ```false```)
00094
00095
00096 Default format: 20140101T11:20:00
00097
00098
00099 UTC Example:
00100 ```javascript
00101 xmlrpc.dateFormatter.setOpts({
00102 colons: true
00103 , hyphens: true
00104 , local: false
00105 , ms: true
00106 })
00107 ```
00108
00109 Local date + offset example:
00110 ```javascript
00111 xmlrpc.dateFormatter.setOpts({
00112 colons: true
00113 , hyphens: true
00114 , local: true
00115 , ms: false
00116 , offset: true
00117 })
00118 ```
00119
00120 ### Cookies support
00121
00122 It is possible to turn on cookies support for XML-RPC client by special options
00123 flag. If turned on then all the cookies received from server will be bounced
00124 back with subsequent calls to the server. You also may manipulate cookies
00125 manually by the setCookie/getCookie call.
00126
00127 ```javascript
00128 var client = xmlrpc.createClient({
00129 host: 'localhost',
00130 port: 9090,
00131 cookies: true
00132 });
00133
00134 client.setCookie('login', 'bilbo');
00135
00136
00137 client.methodCall('someAction', [], function(error, value) {
00138
00139 console.log(client.getCookie('session'));
00140 });
00141
00142 ```
00143
00144 ### Custom Types
00145 If you need to parse to a specific format or need to handle custom data types
00146 that are not supported by default, it is possible to extend the serializer
00147 with a user-defined type for your specific needs.
00148
00149 A custom type can be defined as follows:
00150 ```javascript
00151 var xmlrpc = require('xmlrpc');
00152 var util = require('util');
00153
00154
00155 var YourType = function (raw) {
00156 xmlrpc.CustomType.call(this, raw);
00157 };
00158
00159
00160 util.inherits(YourType, xmlrpc.CustomType);
00161
00162
00163 YourType.prototype.tagName = 'yourType';
00164
00165
00166 YourType.prototype.serialize = function (xml) {
00167 var value = somefunction(this.raw);
00168 return xml.ele(this.tagName).txt(value);
00169 }
00170 ```
00171
00172 and then make your method calls, wrapping your variables inside your new type
00173 definition:
00174
00175 ```javascript
00176 var client = xmlrpc.createClient('YOUR_ENDPOINT');
00177 client.methodCall('YOUR_METHOD', [new YourType(yourVariable)], yourCallback);
00178 ```
00179
00180 ### To Debug (client-side)
00181
00182 Error callbacks on the client are enriched with request and response
00183 information and the returned body as long as a http connection was made,
00184 to aide with request debugging. Example:
00185
00186 ```javascript
00187 var client = xmlrpc.createClient({ host: 'example.com', port: 80 });
00188 client.methodCall('FAULTY_METHOD', [], function (error, value) {
00189 if (error) {
00190 console.log('error:', error);
00191 console.log('req headers:', error.req && error.req._header);
00192 console.log('res code:', error.res && error.res.statusCode);
00193 console.log('res body:', error.body);
00194 } else {
00195 console.log('value:', value);
00196 }
00197 });
00198
00199
00200
00201
00202
00203
00204
00205
00206 ```
00207
00208 ### To Test
00209
00210 [
00226
00227 Released under the MIT license. See the LICENSE file for the complete wording.
00228
00229
00230 ## Contributors
00231
00232 Thank you to all [the
00233 authors](https:
00234 everyone who has filed an issue to help make xmlrpc better.
00235