Annotation of embedaddon/php/ext/xmlrpc/libxmlrpc/system_methods.c, revision 1.1.1.1
1.1 misho 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:
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:
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:
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:
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:
374:
375:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>