1 /*
2 This file is part of libXMLRPC - a C library for xml-encoded function calls.
3
4 Author: Dan Libby (dan@libby.com)
5 Epinions.com may be contacted at feedback@epinions-inc.com
6 */
7
8 /*
9 Copyright 2001 Epinions, Inc.
10
11 Subject to the following 3 conditions, Epinions, Inc. permits you, free
12 of charge, to (a) use, copy, distribute, modify, perform and display this
13 software and associated documentation files (the "Software"), and (b)
14 permit others to whom the Software is furnished to do so as well.
15
16 1) The above copyright notice and this permission notice shall be included
17 without modification in all copies or substantial portions of the
18 Software.
19
20 2) THE SOFTWARE IS PROVIDED "AS IS", WITHOUT ANY WARRANTY OR CONDITION OF
21 ANY KIND, EXPRESS, IMPLIED OR STATUTORY, INCLUDING WITHOUT LIMITATION ANY
22 IMPLIED WARRANTIES OF ACCURACY, MERCHANTABILITY, FITNESS FOR A PARTICULAR
23 PURPOSE OR NONINFRINGEMENT.
24
25 3) IN NO EVENT SHALL EPINIONS, INC. BE LIABLE FOR ANY DIRECT, INDIRECT,
26 SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES OR LOST PROFITS ARISING OUT
27 OF OR IN CONNECTION WITH THE SOFTWARE (HOWEVER ARISING, INCLUDING
28 NEGLIGENCE), EVEN IF EPINIONS, INC. IS AWARE OF THE POSSIBILITY OF SUCH
29 DAMAGES.
30
31 */
32
33
34 /****h* ABOUT/system_methods
35 * AUTHOR
36 * Dan Libby, aka danda (dan@libby.com)
37 * HISTORY
38 * $Log$
39 * Revision 1.7 2001/09/29 21:58:05 danda
40 * adding cvs log to history section
41 *
42 * 4/28/2001 -- danda -- adding system.multicall and separating out system methods.
43 * TODO
44 * NOTES
45 *******/
46
47
48 #include "queue.h"
49 #include "xmlrpc.h"
50 #include "xmlrpc_private.h"
51 #include "xmlrpc_introspection_private.h"
52 #include "system_methods_private.h"
53 #include <string.h>
54 #include <stdlib.h>
55 #include <stdarg.h>
56
57
58 static const char* xsm_introspection_xml =
59 "<?xml version='1.0' ?>"
60
61 "<introspection version='1.0'>"
62 "<typeList>"
63
64 "<typeDescription name='system.value' basetype='struct' desc='description of a value'>"
65 "<value type='string' name='name' optional='yes'>value identifier</value>"
66 "<value type='string' name='type'>value's xmlrpc or user-defined type</value>"
67 "<value type='string' name='description'>value's textual description</value> "
68 "<value type='boolean' name='optional'>true if value is optional, else it is required</value> "
69 "<value type='any' name='member' optional='yes'>a child of this element. n/a for scalar types</value> "
70 "</typeDescription>"
71
72 "<typeDescription name='system.valueList' basetype='array' desc='list of value descriptions'>"
73 "<value type='system.value'/>"
74 "</typeDescription>"
75
76 "<typeDescription name='system.stringList' basetype='array' desc='list of strings'>"
77 "<value type='string'/>"
78 "</typeDescription>"
79
80
81 "</typeList>"
82
83 "<methodList>"
84
85 "<!-- system.describeMethods -->"
86 "<methodDescription name='system.describeMethods'>"
87 "<author>Dan Libby</author>"
88 "<purpose>fully describes the methods and types implemented by this XML-RPC server.</purpose>"
89 "<version>1.1</version>"
90 "<signatures>"
91 "<signature>"
92 "<params>"
93 "<value type='array' name='methodList' optional='yes' desc='a list of methods to be described. if omitted, all are described.'>"
94 "<value type='string'>a valid method name</value>"
95 "</value>"
96 "</params>"
97 "<returns>"
98 "<value type='struct' desc='contains methods list and types list'>"
99 "<value type='array' name='methodList' desc='a list of methods'>"
100 "<value type='struct' desc='representation of a single method'>"
101 "<value type='string' name='name'>method name</value>"
102 "<value type='string' name='version' optional='yes'>method version</value>"
103 "<value type='string' name='author' optional='yes'>method author</value>"
104 "<value type='string' name='purpose' optional='yes'>method purpose</value>"
105 "<value type='array' name='signatures' desc='list of method signatures'>"
106 "<value type='struct' desc='representation of a single signature'>"
107 "<value type='system.valueList' name='params' optional='yes'>parameter list</value>"
108 "<value type='system.valueList' name='returns' optional='yes'>return value list</value>"
109 "</value>"
110 "</value>"
111 "<value type='system.stringList' name='bugs' optional='yes'>list of known bugs</value>"
112 "<value type='system.stringList' name='errors' optional='yes'>list of possible errors and error codes</value>"
113 "<value type='system.stringList' name='examples' optional='yes'>list of examples</value>"
114 "<value type='system.stringList' name='history' optional='yes'>list of modifications</value>"
115 "<value type='system.stringList' name='notes' optional='yes'>list of notes</value>"
116 "<value type='system.stringList' name='see' optional='yes'>see also. list of related methods</value>"
117 "<value type='system.stringList' name='todo' optional='yes'>list of unimplemented features</value>"
118 "</value>"
119 "</value>"
120 "<value type='array' name='typeList' desc='a list of type descriptions. Typically used for referencing complex types'>"
121 "<value type='system.value'>a type description</value>"
122 "</value>"
123 "</value>"
124 "</returns>"
125 "</signature>"
126 "</signatures>"
127 "<see>"
128 "<item name='system.listMethods' />"
129 "<item name='system.methodSignature' />"
130 "<item name='system.methodHelp' />"
131 "</see>"
132 "<example/>"
133 "<error/>"
134 "<note/>"
135 "<bug/>"
136 "<todo/>"
137 "</methodDescription>"
138
139 "<!-- system.listMethods -->"
140 "<methodDescription name='system.listMethods'>"
141 "<author>Dan Libby</author>"
142 "<purpose>enumerates the methods implemented by this XML-RPC server.</purpose>"
143 "<version>1.0</version>"
144 "<signatures>"
145 "<signature>"
146 "<returns>"
147 "<value type='array' desc='an array of strings'>"
148 "<value type='string'>name of a method implemented by the server.</value>"
149 "</value>"
150 "</returns>"
151 "</signature>"
152 "</signatures>"
153 "<see>"
154 "<item name='system.describeMethods' />"
155 "<item name='system.methodSignature' />"
156 "<item name='system.methodHelp' />"
157 "</see>"
158 "<example/>"
159 "<error/>"
160 "<note/>"
161 "<bug/>"
162 "<todo/>"
163 "</methodDescription>"
164
165 "<!-- system.methodHelp -->"
166 "<methodDescription name='system.methodHelp'>"
167 "<author>Dan Libby</author>"
168 "<purpose>provides documentation string for a single method</purpose>"
169 "<version>1.0</version>"
170 "<signatures>"
171 "<signature>"
172 "<params>"
173 "<value type='string' name='methodName'>name of the method for which documentation is desired</value>"
174 "</params>"
175 "<returns>"
176 "<value type='string'>help text if defined for the method passed, otherwise an empty string</value>"
177 "</returns>"
178 "</signature>"
179 "</signatures>"
180 "<see>"
181 "<item name='system.listMethods' />"
182 "<item name='system.methodSignature' />"
183 "<item name='system.methodHelp' />"
184 "</see>"
185 "<example/>"
186 "<error/>"
187 "<note/>"
188 "<bug/>"
189 "<todo/>"
190 "</methodDescription>"
191
192 "<!-- system.methodSignature -->"
193 "<methodDescription name='system.methodSignature'>"
194 "<author>Dan Libby</author>"
195 "<purpose>provides 1 or more signatures for a single method</purpose>"
196 "<version>1.0</version>"
197 "<signatures>"
198 "<signature>"
199 "<params>"
200 "<value type='string' name='methodName'>name of the method for which documentation is desired</value>"
201 "</params>"
202 "<returns>"
203 "<value type='array' desc='a list of arrays, each representing a signature'>"
204 "<value type='array' desc='a list of strings. the first element represents the method return value. subsequent elements represent parameters.'>"
205 "<value type='string'>a string indicating the xmlrpc type of a value. one of: string, int, double, base64, datetime, array, struct</value>"
206 "</value>"
207 "</value>"
208 "</returns>"
209 "</signature>"
210 "</signatures>"
211 "<see>"
212 "<item name='system.listMethods' />"
213 "<item name='system.methodHelp' />"
214 "<item name='system.describeMethods' />"
215 "</see>"
216 "<example/>"
217 "<error/>"
218 "<note/>"
219 "<bug/>"
220 "<todo/>"
221 "</methodDescription>"
222
223 "<!-- system.multiCall -->"
224 "<methodDescription name='system.multiCall'>"
225 "<author>Dan Libby</author>"
226 "<purpose>executes multiple methods in sequence and returns the results</purpose>"
227 "<version>1.0</version>"
228 "<signatures>"
229 "<signature>"
230 "<params>"
231 "<value type='array' name='methodList' desc='an array of method call structs'>"
232 "<value type='struct' desc='a struct representing a single method call'>"
233 "<value type='string' name='methodName' desc='name of the method to be executed'/>"
234 "<value type='array' name='params' desc='an array representing the params to a method. sub-elements should match method signature'/>"
235 "</value>"
236 "</value>"
237 "</params>"
238 "<returns>"
239 "<value type='array' desc='an array of method responses'>"
240 "<value type='array' desc='an array containing a single value, which is the method's response'/>"
241 "</value>"
242 "</returns>"
243 "</signature>"
244 "</signatures>"
245 "<see>"
246 "<item name='system.listMethods' />"
247 "<item name='system.methodHelp' />"
248 "<item name='system.describeMethods' />"
249 "</see>"
250 "<example/>"
251 "<error/>"
252 "<note/>"
253 "<bug/>"
254 "<todo/>"
255 "</methodDescription>"
256
257 "<!-- system.getCapabilities -->"
258 "<methodDescription name='system.getCapabilities'>"
259 "<author>Dan Libby</author>"
260 "<purpose>returns a list of capabilities supported by this server</purpose>"
261 "<version>1.0</version>"
262 "<notes><item>spec url: http://groups.yahoo.com/group/xml-rpc/message/2897</item></notes>"
263 "<signatures>"
264 "<signature>"
265 "<returns>"
266 "<value type='struct' desc='list of capabilities, each with a unique key defined by the capability's spec'>"
267 "<value type='struct' desc='definition of a single capability'>"
268 "<value type='string' name='specURL'>www address of the specification defining this capability</value>"
269 "<value type='int' name='specVersion'>version of the spec that this server's implementation conforms to</value>"
270 "</value>"
271 "</value>"
272 "</returns>"
273 "</signature>"
274 "</signatures>"
275 "<see>"
276 "<item name='system.listMethods' />"
277 "<item name='system.methodHelp' />"
278 "<item name='system.describeMethods' />"
279 "</see>"
280 "<example/>"
281 "<error/>"
282 "<note/>"
283 "<bug/>"
284 "<todo/>"
285 "</methodDescription>"
286
287 "</methodList>"
288 "</introspection>";
289
290
291 /* forward declarations for static (non public, non api) funcs */
292 static XMLRPC_VALUE xsm_system_multicall_cb(XMLRPC_SERVER server, XMLRPC_REQUEST input, void* userData);
293 static XMLRPC_VALUE xsm_system_get_capabilities_cb(XMLRPC_SERVER server, XMLRPC_REQUEST input, void* userData);
294
295 /*-*******************
296 * System Methods API *
297 *********************/
298
xsm_lazy_doc_methods_cb(XMLRPC_SERVER server,void * userData)299 static void xsm_lazy_doc_methods_cb(XMLRPC_SERVER server, void* userData) {
300 XMLRPC_VALUE xDesc = XMLRPC_IntrospectionCreateDescription(xsm_introspection_xml, NULL);
301 XMLRPC_ServerAddIntrospectionData(server, xDesc);
302 XMLRPC_CleanupValue(xDesc);
303 }
304
xsm_register(XMLRPC_SERVER server)305 void xsm_register(XMLRPC_SERVER server) {
306 xi_register_system_methods(server);
307
308 XMLRPC_ServerRegisterMethod(server, xsm_token_system_multicall, xsm_system_multicall_cb);
309 XMLRPC_ServerRegisterMethod(server, xsm_token_system_get_capabilities, xsm_system_get_capabilities_cb);
310
311 /* callback for documentation generation should it be requested */
312 XMLRPC_ServerRegisterIntrospectionCallback(server, xsm_lazy_doc_methods_cb);
313 }
314
xsm_system_multicall_cb(XMLRPC_SERVER server,XMLRPC_REQUEST input,void * userData)315 XMLRPC_VALUE xsm_system_multicall_cb(XMLRPC_SERVER server, XMLRPC_REQUEST input, void* userData) {
316 XMLRPC_VALUE xArray = XMLRPC_VectorRewind(XMLRPC_RequestGetData(input));
317 XMLRPC_VALUE xReturn = XMLRPC_CreateVector(0, xmlrpc_vector_array);
318
319 if (xArray) {
320 XMLRPC_VALUE xMethodIter = XMLRPC_VectorRewind(xArray);
321
322 while (xMethodIter) {
323 XMLRPC_REQUEST request = XMLRPC_RequestNew();
324 if(request) {
325 const char* methodName = XMLRPC_VectorGetStringWithID(xMethodIter, "methodName");
326 XMLRPC_VALUE params = XMLRPC_VectorGetValueWithID(xMethodIter, "params");
327
328 if(methodName && params) {
329 XMLRPC_VALUE xRandomArray = XMLRPC_CreateVector(0, xmlrpc_vector_array);
330 XMLRPC_RequestSetMethodName(request, methodName);
331 XMLRPC_RequestSetData(request, params);
332 XMLRPC_RequestSetRequestType(request, xmlrpc_request_call);
333
334 XMLRPC_AddValueToVector(xRandomArray,
335 XMLRPC_ServerCallMethod(server, request, userData));
336
337 XMLRPC_AddValueToVector(xReturn, xRandomArray);
338 }
339 XMLRPC_RequestFree(request, 1);
340 }
341 xMethodIter = XMLRPC_VectorNext(xArray);
342 }
343 }
344 return xReturn;
345 }
346
347
xsm_system_get_capabilities_cb(XMLRPC_SERVER server,XMLRPC_REQUEST input,void * userData)348 XMLRPC_VALUE xsm_system_get_capabilities_cb(XMLRPC_SERVER server, XMLRPC_REQUEST input, void* userData) {
349 XMLRPC_VALUE xReturn = XMLRPC_CreateVector(0, xmlrpc_vector_struct);
350 XMLRPC_VALUE xFaults = XMLRPC_CreateVector("faults_interop", xmlrpc_vector_struct);
351 XMLRPC_VALUE xIntro = XMLRPC_CreateVector("introspection", xmlrpc_vector_struct);
352
353 /* support for fault spec */
354 XMLRPC_VectorAppendString(xFaults, "specURL", "http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php", 0);
355 XMLRPC_VectorAppendInt(xFaults, "specVersion", 20010516);
356
357 /* support for introspection spec */
358 XMLRPC_VectorAppendString(xIntro, "specURL", "http://xmlrpc-epi.sourceforge.net/specs/rfc.introspection.php", 0);
359 XMLRPC_VectorAppendInt(xIntro, "specVersion", 20010516);
360
361 XMLRPC_AddValuesToVector(xReturn,
362 xFaults,
363 xIntro,
364 NULL);
365
366 return xReturn;
367
368 }
369
370 /*-***********************
371 * End System Methods API *
372 *************************/
373
