← Back to branch summary

~ubuntu-branches/ubuntu/hardy/php5/hardy-updates

« back to all changes in this revision

Viewing changes to ext/xmlrpc/libxmlrpc/system_methods.c

  • Committer: Bazaar Package Importer
  • Author(s): Adam Conrad
  • Date: 2005-10-09 03:14:32 UTC
  • Revision ID: james.westby@ubuntu.com-20051009031432-kspik3lobxstafv9
Tags: upstream-5.0.5
Import upstream version 5.0.5

Show diffs side-by-side

added added

removed removed

Lines of Context:
ext/xmlrpc/libxmlrpc/system_methods.c
 
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: system_methods.c,v $
 
39
 *   Revision 1.2  2002/07/05 04:43:53  danda
 
40
 *   merged in updates from SF project.  bring php repository up to date with xmlrpc-epi version 0.51
 
41
 *
 
42
 *   Revision 1.7  2001/09/29 21:58:05  danda
 
43
 *   adding cvs log to history section
 
44
 *
 
45
 *   4/28/2001 -- danda -- adding system.multicall and separating out system methods.
 
46
 * TODO
 
47
 * NOTES
 
48
 *******/
 
49
 
 
50
 
 
51
#include "queue.h"
 
52
#include "xmlrpc.h"
 
53
#include "xmlrpc_private.h"
 
54
#include "xmlrpc_introspection_private.h"
 
55
#include "system_methods_private.h"
 
56
#include <string.h>
 
57
#include <stdlib.h>
 
58
#include <stdarg.h>
 
59
 
 
60
 
 
61
static const char* xsm_introspection_xml =
 
62
"<?xml version='1.0' ?>"
 
63
 
 
64
"<introspection version='1.0'>"
 
65
 "<typeList>"
 
66
 
 
67
 "<typeDescription name='system.value' basetype='struct' desc='description of a value'>"
 
68
   "<value type='string' name='name' optional='yes'>value identifier</value>"
 
69
   "<value type='string' name='type'>value&apos;s xmlrpc or user-defined type</value>"
 
70
   "<value type='string' name='description'>value&apos;s textual description</value> "
 
71
   "<value type='boolean' name='optional'>true if value is optional, else it is required</value> "
 
72
   "<value type='any' name='member' optional='yes'>a child of this element. n/a for scalar types</value> "
 
73
 "</typeDescription>"
 
74
 
 
75
 "<typeDescription name='system.valueList' basetype='array' desc='list of value descriptions'>"
 
76
   "<value type='system.value'/>"
 
77
 "</typeDescription>"
 
78
 
 
79
 "<typeDescription name='system.stringList' basetype='array' desc='list of strings'>"
 
80
   "<value type='string'/>"
 
81
 "</typeDescription>"
 
82
 
 
83
 
 
84
 "</typeList>"
 
85
 
 
86
 "<methodList>"
 
87
 
 
88
 "<!-- system.describeMethods -->"
 
89
 "<methodDescription name='system.describeMethods'>"
 
90
  "<author>Dan Libby</author>"
 
91
  "<purpose>fully describes the methods and types implemented by this XML-RPC server.</purpose>"
 
92
  "<version>1.1</version>"
 
93
  "<signatures>"
 
94
   "<signature>"
 
95
    "<params>"
 
96
     "<value type='array' name='methodList' optional='yes' desc='a list of methods to be described. if omitted, all are described.'>"
 
97
      "<value type='string'>a valid method name</value>"
 
98
     "</value>"
 
99
    "</params>"
 
100
    "<returns>"
 
101
     "<value type='struct' desc='contains methods list and types list'>"
 
102
      "<value type='array' name='methodList' desc='a list of methods'>"
 
103
       "<value type='struct' desc='representation of a single method'>"
 
104
        "<value type='string' name='name'>method name</value>"
 
105
        "<value type='string' name='version' optional='yes'>method version</value>"
 
106
        "<value type='string' name='author' optional='yes'>method author</value>"
 
107
        "<value type='string' name='purpose' optional='yes'>method purpose</value>"
 
108
        "<value type='array' name='signatures' desc='list of method signatures'>"
 
109
         "<value type='struct' desc='representation of a single signature'>"
 
110
          "<value type='system.valueList' name='params' optional='yes'>parameter list</value>"
 
111
          "<value type='system.valueList' name='returns' optional='yes'>return value list</value>"
 
112
         "</value>"
 
113
        "</value>"
 
114
        "<value type='system.stringList' name='bugs' optional='yes'>list of known bugs</value>"
 
115
        "<value type='system.stringList' name='errors' optional='yes'>list of possible errors and error codes</value>"
 
116
        "<value type='system.stringList' name='examples' optional='yes'>list of examples</value>"
 
117
        "<value type='system.stringList' name='history' optional='yes'>list of modifications</value>"
 
118
        "<value type='system.stringList' name='notes' optional='yes'>list of notes</value>"
 
119
        "<value type='system.stringList' name='see' optional='yes'>see also.  list of related methods</value>"
 
120
        "<value type='system.stringList' name='todo' optional='yes'>list of unimplemented features</value>"
 
121
       "</value>"
 
122
      "</value>"
 
123
      "<value type='array' name='typeList' desc='a list of type descriptions. Typically used for referencing complex types'>"
 
124
       "<value type='system.value'>a type description</value>"
 
125
      "</value>"
 
126
     "</value>"
 
127
    "</returns>"
 
128
   "</signature>"
 
129
  "</signatures>"
 
130
  "<see>"
 
131
   "<item name='system.listMethods' />"
 
132
   "<item name='system.methodSignature' />"
 
133
   "<item name='system.methodHelp' />"
 
134
  "</see>"
 
135
  "<example/>"
 
136
  "<error/>"
 
137
  "<note/>"
 
138
  "<bug/>"
 
139
  "<todo/>"
 
140
 "</methodDescription>"
 
141
 
 
142
 "<!-- system.listMethods -->"
 
143
 "<methodDescription name='system.listMethods'>"
 
144
  "<author>Dan Libby</author>"
 
145
  "<purpose>enumerates the methods implemented by this XML-RPC server.</purpose>"
 
146
  "<version>1.0</version>"
 
147
  "<signatures>"
 
148
   "<signature>"
 
149
    "<returns>"
 
150
     "<value type='array' desc='an array of strings'>"
 
151
      "<value type='string'>name of a method implemented by the server.</value>"
 
152
     "</value>"
 
153
    "</returns>"
 
154
   "</signature>"
 
155
  "</signatures>"
 
156
  "<see>"
 
157
   "<item name='system.describeMethods' />"
 
158
   "<item name='system.methodSignature' />"
 
159
   "<item name='system.methodHelp' />"
 
160
  "</see>"
 
161
  "<example/>"
 
162
  "<error/>"
 
163
  "<note/>"
 
164
  "<bug/>"
 
165
  "<todo/>"
 
166
 "</methodDescription>"
 
167
 
 
168
 "<!-- system.methodHelp -->"
 
169
 "<methodDescription name='system.methodHelp'>"
 
170
  "<author>Dan Libby</author>"
 
171
  "<purpose>provides documentation string for a single method</purpose>"
 
172
  "<version>1.0</version>"
 
173
  "<signatures>"
 
174
   "<signature>"
 
175
    "<params>"
 
176
     "<value type='string' name='methodName'>name of the method for which documentation is desired</value>"
 
177
    "</params>"
 
178
    "<returns>"
 
179
     "<value type='string'>help text if defined for the method passed, otherwise an empty string</value>"
 
180
    "</returns>"
 
181
   "</signature>"
 
182
  "</signatures>"
 
183
  "<see>"
 
184
   "<item name='system.listMethods' />"
 
185
   "<item name='system.methodSignature' />"
 
186
   "<item name='system.methodHelp' />"
 
187
  "</see>"
 
188
  "<example/>"
 
189
  "<error/>"
 
190
  "<note/>"
 
191
  "<bug/>"
 
192
  "<todo/>"
 
193
 "</methodDescription>"
 
194
 
 
195
 "<!-- system.methodSignature -->"
 
196
 "<methodDescription name='system.methodSignature'>"
 
197
  "<author>Dan Libby</author>"
 
198
  "<purpose>provides 1 or more signatures for a single method</purpose>"
 
199
  "<version>1.0</version>"
 
200
  "<signatures>"
 
201
   "<signature>"
 
202
    "<params>"
 
203
     "<value type='string' name='methodName'>name of the method for which documentation is desired</value>"
 
204
    "</params>"
 
205
    "<returns>"
 
206
     "<value type='array' desc='a list of arrays, each representing a signature'>"
 
207
      "<value type='array' desc='a list of strings. the first element represents the method return value. subsequent elements represent parameters.'>"
 
208
       "<value type='string'>a string indicating the xmlrpc type of a value. one of: string, int, double, base64, datetime, array, struct</value>"
 
209
      "</value>"
 
210
     "</value>"
 
211
    "</returns>"
 
212
   "</signature>"
 
213
  "</signatures>"
 
214
  "<see>"
 
215
   "<item name='system.listMethods' />"
 
216
   "<item name='system.methodHelp' />"
 
217
   "<item name='system.describeMethods' />"
 
218
  "</see>"
 
219
  "<example/>"
 
220
  "<error/>"
 
221
  "<note/>"
 
222
  "<bug/>"
 
223
  "<todo/>"
 
224
 "</methodDescription>"
 
225
 
 
226
 "<!-- system.multiCall -->"
 
227
 "<methodDescription name='system.multiCall'>"
 
228
  "<author>Dan Libby</author>"
 
229
  "<purpose>executes multiple methods in sequence and returns the results</purpose>"
 
230
  "<version>1.0</version>"
 
231
  "<signatures>"
 
232
   "<signature>"
 
233
    "<params>"
 
234
     "<value type='array' name='methodList' desc='an array of method call structs'>"
 
235
      "<value type='struct' desc='a struct representing a single method call'>"
 
236
       "<value type='string' name='methodName' desc='name of the method to be executed'/>"
 
237
       "<value type='array' name='params' desc='an array representing the params to a method. sub-elements should match method signature'/>"
 
238
      "</value>"
 
239
     "</value>"
 
240
    "</params>"
 
241
    "<returns>"
 
242
     "<value type='array' desc='an array of method responses'>"
 
243
      "<value type='array' desc='an array containing a single value, which is the method&apos;s response'/>"
 
244
     "</value>"
 
245
    "</returns>"
 
246
   "</signature>"
 
247
  "</signatures>"
 
248
  "<see>"
 
249
   "<item name='system.listMethods' />"
 
250
   "<item name='system.methodHelp' />"
 
251
   "<item name='system.describeMethods' />"
 
252
  "</see>"
 
253
  "<example/>"
 
254
  "<error/>"
 
255
  "<note/>"
 
256
  "<bug/>"
 
257
  "<todo/>"
 
258
 "</methodDescription>"
 
259
 
 
260
 "<!-- system.getCapabilities -->"
 
261
 "<methodDescription name='system.getCapabilities'>"
 
262
  "<author>Dan Libby</author>"
 
263
  "<purpose>returns a list of capabilities supported by this server</purpose>"
 
264
  "<version>1.0</version>"
 
265
  "<notes><item>spec url: http://groups.yahoo.com/group/xml-rpc/message/2897</item></notes>"
 
266
  "<signatures>"
 
267
   "<signature>"
 
268
    "<returns>"
 
269
     "<value type='struct' desc='list of capabilities, each with a unique key defined by the capability&apos;s spec'>"
 
270
      "<value type='struct' desc='definition of a single capability'>"
 
271
       "<value type='string' name='specURL'>www address of the specification defining this capability</value>"
 
272
       "<value type='int' name='specVersion'>version of the spec that this server's implementation conforms to</value>"
 
273
      "</value>"
 
274
     "</value>"
 
275
    "</returns>"
 
276
   "</signature>"
 
277
  "</signatures>"
 
278
  "<see>"
 
279
   "<item name='system.listMethods' />"
 
280
   "<item name='system.methodHelp' />"
 
281
   "<item name='system.describeMethods' />"
 
282
  "</see>"
 
283
  "<example/>"
 
284
  "<error/>"
 
285
  "<note/>"
 
286
  "<bug/>"
 
287
  "<todo/>"
 
288
 "</methodDescription>"
 
289
 
 
290
 "</methodList>"
 
291
"</introspection>";
 
292
 
 
293
 
 
294
/* forward declarations for static (non public, non api) funcs */
 
295
static XMLRPC_VALUE xsm_system_multicall_cb(XMLRPC_SERVER server, XMLRPC_REQUEST input, void* userData);
 
296
static XMLRPC_VALUE xsm_system_get_capabilities_cb(XMLRPC_SERVER server, XMLRPC_REQUEST input, void* userData);
 
297
 
 
298
/*-*******************
 
299
* System Methods API *
 
300
*********************/
 
301
 
 
302
static void xsm_lazy_doc_methods_cb(XMLRPC_SERVER server, void* userData) {
 
303
   XMLRPC_VALUE xDesc = XMLRPC_IntrospectionCreateDescription(xsm_introspection_xml, NULL);
 
304
   XMLRPC_ServerAddIntrospectionData(server, xDesc);
 
305
   XMLRPC_CleanupValue(xDesc);
 
306
}
 
307
 
 
308
void xsm_register(XMLRPC_SERVER server) {
 
309
   xi_register_system_methods(server);
 
310
 
 
311
   XMLRPC_ServerRegisterMethod(server, xsm_token_system_multicall, xsm_system_multicall_cb);
 
312
   XMLRPC_ServerRegisterMethod(server, xsm_token_system_get_capabilities, xsm_system_get_capabilities_cb);
 
313
 
 
314
   /* callback for documentation generation should it be requested */
 
315
   XMLRPC_ServerRegisterIntrospectionCallback(server, xsm_lazy_doc_methods_cb);
 
316
}
 
317
 
 
318
XMLRPC_VALUE xsm_system_multicall_cb(XMLRPC_SERVER server, XMLRPC_REQUEST input, void* userData) {
 
319
   XMLRPC_VALUE xArray = XMLRPC_VectorRewind(XMLRPC_RequestGetData(input));
 
320
   XMLRPC_VALUE xReturn = XMLRPC_CreateVector(0, xmlrpc_vector_array);
 
321
 
 
322
   if (xArray) {
 
323
      XMLRPC_VALUE xMethodIter = XMLRPC_VectorRewind(xArray);
 
324
 
 
325
      while (xMethodIter) {
 
326
         XMLRPC_REQUEST request = XMLRPC_RequestNew();
 
327
         if(request) {
 
328
            const char* methodName = XMLRPC_VectorGetStringWithID(xMethodIter, "methodName");
 
329
            XMLRPC_VALUE params = XMLRPC_VectorGetValueWithID(xMethodIter, "params");
 
330
 
 
331
            if(methodName && params) {
 
332
               XMLRPC_VALUE xRandomArray = XMLRPC_CreateVector(0, xmlrpc_vector_array);
 
333
               XMLRPC_RequestSetMethodName(request, methodName);
 
334
               XMLRPC_RequestSetData(request, params);
 
335
               XMLRPC_RequestSetRequestType(request, xmlrpc_request_call);
 
336
 
 
337
               XMLRPC_AddValueToVector(xRandomArray, 
 
338
                                       XMLRPC_ServerCallMethod(server, request, userData));
 
339
 
 
340
               XMLRPC_AddValueToVector(xReturn, xRandomArray);
 
341
            }
 
342
            XMLRPC_RequestFree(request, 1);
 
343
         }
 
344
         xMethodIter = XMLRPC_VectorNext(xArray);
 
345
      }
 
346
   }
 
347
   return xReturn;
 
348
}
 
349
 
 
350
 
 
351
XMLRPC_VALUE xsm_system_get_capabilities_cb(XMLRPC_SERVER server, XMLRPC_REQUEST input, void* userData) {
 
352
   XMLRPC_VALUE xReturn = XMLRPC_CreateVector(0, xmlrpc_vector_struct);
 
353
   XMLRPC_VALUE xFaults = XMLRPC_CreateVector("faults_interop", xmlrpc_vector_struct);
 
354
   XMLRPC_VALUE xIntro = XMLRPC_CreateVector("introspection", xmlrpc_vector_struct);
 
355
 
 
356
   /* support for fault spec */
 
357
   XMLRPC_VectorAppendString(xFaults, "specURL", "http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php", 0);
 
358
   XMLRPC_VectorAppendInt(xFaults, "specVersion", 20010516);
 
359
 
 
360
   /* support for introspection spec */
 
361
   XMLRPC_VectorAppendString(xIntro, "specURL", "http://xmlrpc-epi.sourceforge.net/specs/rfc.introspection.php", 0);
 
362
   XMLRPC_VectorAppendInt(xIntro, "specVersion", 20010516);
 
363
 
 
364
   XMLRPC_AddValuesToVector(xReturn,
 
365
                            xFaults,
 
366
                            xIntro,
 
367
                            NULL);
 
368
 
 
369
   return xReturn;
 
370
                            
 
371
}
 
372
 
 
373
/*-***********************
 
374
* End System Methods API *
 
375
*************************/
 
376
 
 
377
 
 
378