artdaq_node_server  v1_00_09
 All Classes Namespaces Files Variables Pages
src/node_modules/xmlrpc/README.md
1 ## The What
2 
3 The xmlrpc module is a pure JavaScript XML-RPC server and client for node.js.
4 
5 Pure JavaScript means that the [XML parsing](https://github.com/isaacs/sax-js)
6 and [XML building](https://github.com/robrighter/node-xml) use pure JavaScript
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.
11 
12 
13 ## The How
14 
15 ### To Install
16 
17 ```bash
18 npm install xmlrpc
19 ```
20 
21 ### To Use
22 
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
25 other!).
26 
27 A brief example:
28 
29 ```javascript
30 var xmlrpc = require('xmlrpc')
31 
32 // Creates an XML-RPC server to listen to XML-RPC method calls
33 var server = xmlrpc.createServer({ host: 'localhost', port: 9090 })
34 // Handle methods not found
35 server.on('NotFound', function(method, params) {
36  console.log('Method ' + method + ' does not exist');
37 })
38 // Handle method calls by listening for events with the method call name
39 server.on('anAction', function (err, params, callback) {
40  console.log('Method call params for \'anAction\': ' + params)
41 
42  // ...perform an action...
43 
44  // Send a method response with a value
45  callback(null, 'aResult')
46 })
47 console.log('XML-RPC server listening on port 9091')
48 
49 // Waits briefly to give the XML-RPC server time to start up and start
50 // listening
51 setTimeout(function () {
52  // Creates an XML-RPC client. Passes the host information on where to
53  // make the XML-RPC calls.
54  var client = xmlrpc.createClient({ host: 'localhost', port: 9090, path: '/'})
55 
56  // Sends a method call to the XML-RPC server
57  client.methodCall('anAction', ['aParam'], function (error, value) {
58  // Results of the method response
59  console.log('Method response for \'anAction\': ' + value)
60  })
61 
62 }, 1000)
63 ```
64 
65 Output from the example:
66 
67 ```
68 XML-RPC server listening on port 9090
69 Method call params for 'anAction': aParam
70 Method response for 'anAction': aResult
71 ```
72 
73 ### Date/Time Formatting
74 
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.
79 
80 
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:
84 
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```)
94 
95 
96 Default format: 20140101T11:20:00
97 
98 
99 UTC Example:
100 ```javascript
101 xmlrpc.dateFormatter.setOpts({
102  colons: true
103 , hyphens: true
104 , local: false
105 , ms: true
106 }) // encoding output: '2014-01-01T16:20:00.000Z'
107 ```
108 
109 Local date + offset example:
110 ```javascript
111 xmlrpc.dateFormatter.setOpts({
112  colons: true
113 , hyphens: true
114 , local: true
115 , ms: false
116 , offset: true
117 }) // encoding output: '2014-01-01T11:20:00-05:00'
118 ```
119 
120 ### Cookies support
121 
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.
126 
127 ```javascript
128 var client = xmlrpc.createClient({
129  host: 'localhost',
130  port: 9090,
131  cookies: true
132 });
133 
134 client.setCookie('login', 'bilbo');
135 
136 //This call will send provided cookie to the server
137 client.methodCall('someAction', [], function(error, value) {
138  //Here we may get cookie received from server if we know its name
139  console.log(client.getCookie('session'));
140 });
141 
142 ```
143 
144 ### Custom Types
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.
148 
149 A custom type can be defined as follows:
150 ```javascript
151 var xmlrpc = require('xmlrpc');
152 var util = require('util');
153 
154 // create your custom class
155 var YourType = function (raw) {
156  xmlrpc.CustomType.call(this, raw);
157 };
158 
159 // inherit everything
160 util.inherits(YourType, xmlrpc.CustomType);
161 
162 // set a custom tagName (defaults to 'customType')
163 YourType.prototype.tagName = 'yourType';
164 
165 // optionally, override the serializer
166 YourType.prototype.serialize = function (xml) {
167  var value = somefunction(this.raw);
168  return xml.ele(this.tagName).txt(value);
169 }
170 ```
171 
172 and then make your method calls, wrapping your variables inside your new type
173 definition:
174 
175 ```javascript
176 var client = xmlrpc.createClient('YOUR_ENDPOINT');
177 client.methodCall('YOUR_METHOD', [new YourType(yourVariable)], yourCallback);
178 ```
179 
180 ### To Debug (client-side)
181 
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:
185 
186 ```javascript
187 var client = xmlrpc.createClient({ host: 'example.com', port: 80 });
188 client.methodCall('FAULTY_METHOD', [], function (error, value) {
189  if (error) {
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);
194  } else {
195  console.log('value:', value);
196  }
197 });
198 
199 // error: [Error: Unknown XML-RPC tag 'TITLE']
200 // req headers: POST / HTTP/1.1
201 // User-Agent: NodeJS XML-RPC Client
202 // ...
203 // res code: 200
204 // res body: <!doctype html>
205 // ...
206 ```
207 
208 ### To Test
209 
210 [![Build
211 Status](https://secure.travis-ci.org/baalexander/node-xmlrpc.png)](http://travis-ci.org/baalexander/node-xmlrpc)
212 
213 XML-RPC must be precise so there are an extensive set of test cases in the test
214 directory. [Vows](http://vowsjs.org/) is the testing framework and [Travis
215 CI](http://travis-ci.org/baalexander/node-xmlrpc) is used for Continuous
216 Integration.
217 
218 To run the test suite:
219 
220 `npm test`
221 
222 If submitting a bug fix, please update the appropriate test file too.
223 
224 
225 ## The License (MIT)
226 
227 Released under the MIT license. See the LICENSE file for the complete wording.
228 
229 
230 ## Contributors
231 
232 Thank you to all [the
233 authors](https://github.com/baalexander/node-xmlrpc/graphs/contributors) and
234 everyone who has filed an issue to help make xmlrpc better.
235