Annotation of embedaddon/php/ext/xmlrpc/libxmlrpc/system_methods.c, revision 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>