diff options
Diffstat (limited to 'ext/xmlrpc/libxmlrpc/xmlrpc_introspection.c')
| -rw-r--r-- | ext/xmlrpc/libxmlrpc/xmlrpc_introspection.c | 591 |
1 files changed, 591 insertions, 0 deletions
diff --git a/ext/xmlrpc/libxmlrpc/xmlrpc_introspection.c b/ext/xmlrpc/libxmlrpc/xmlrpc_introspection.c new file mode 100644 index 0000000000..5b15d4b071 --- /dev/null +++ b/ext/xmlrpc/libxmlrpc/xmlrpc_introspection.c @@ -0,0 +1,591 @@ +/* + This file is part of libXMLRPC - a C library for xml-encoded function calls. + + Author: Dan Libby (dan@libby.com) + Epinions.com may be contacted at feedback@epinions-inc.com +*/ + +/* + Copyright 2001 Epinions, Inc. + + Subject to the following 3 conditions, Epinions, Inc. permits you, free + of charge, to (a) use, copy, distribute, modify, perform and display this + software and associated documentation files (the "Software"), and (b) + permit others to whom the Software is furnished to do so as well. + + 1) The above copyright notice and this permission notice shall be included + without modification in all copies or substantial portions of the + Software. + + 2) THE SOFTWARE IS PROVIDED "AS IS", WITHOUT ANY WARRANTY OR CONDITION OF + ANY KIND, EXPRESS, IMPLIED OR STATUTORY, INCLUDING WITHOUT LIMITATION ANY + IMPLIED WARRANTIES OF ACCURACY, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE OR NONINFRINGEMENT. + + 3) IN NO EVENT SHALL EPINIONS, INC. BE LIABLE FOR ANY DIRECT, INDIRECT, + SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES OR LOST PROFITS ARISING OUT + OF OR IN CONNECTION WITH THE SOFTWARE (HOWEVER ARISING, INCLUDING + NEGLIGENCE), EVEN IF EPINIONS, INC. IS AWARE OF THE POSSIBILITY OF SUCH + DAMAGES. + +*/ + + +/****h* ABOUT/xmlrpc_introspection + * AUTHOR + * Dan Libby, aka danda (dan@libby.com) + * HISTORY + * 4/10/2001 -- danda -- initial introspection support + * TODO + * NOTES + *******/ + + +#include "queue.h" +#include "xmlrpc.h" +#include "xmlrpc_private.h" +#include "xmlrpc_introspection_private.h" +#include <string.h> +#include <stdlib.h> +#include <stdarg.h> + + +/* forward declarations for static (non public, non api) funcs */ +static XMLRPC_VALUE xi_system_describe_methods_cb(XMLRPC_SERVER server, XMLRPC_REQUEST input, void* userData); +static XMLRPC_VALUE xi_system_list_methods_cb(XMLRPC_SERVER server, XMLRPC_REQUEST input, void* userData); +static XMLRPC_VALUE xi_system_method_signature_cb(XMLRPC_SERVER server, XMLRPC_REQUEST input, void* userData); +static XMLRPC_VALUE xi_system_method_help_cb(XMLRPC_SERVER server, XMLRPC_REQUEST input, void* userData); + + +/*-********************************** +* Introspection Callbacks (methods) * +************************************/ + +/* iterates through a list of structs and finds the one with key "name" matching + * needle. slow, would benefit from a struct key hash. + */ +inline XMLRPC_VALUE find_named_value(XMLRPC_VALUE list, const char* needle) { + XMLRPC_VALUE xIter = XMLRPC_VectorRewind(list); + while(xIter) { + const char* name = XMLRPC_VectorGetStringWithID(xIter, xi_token_name); + if(name && !strcmp(name, needle)) { + return xIter; + } + xIter = XMLRPC_VectorNext(list); + } + return NULL; +} + + +/* iterates through docs callbacks and calls any that have not yet been called */ +static void check_docs_loaded(XMLRPC_SERVER server, void* userData) { + if(server) { + q_iter qi = Q_Iter_Head_F(&server->docslist); + while( qi ) { + doc_method* dm = Q_Iter_Get_F(qi); + if(dm && !dm->b_called) { + dm->method(server, userData); + dm->b_called = 1; + } + qi = Q_Iter_Next_F(qi); + } + } +} + + +/* utility function for xi_system_describe_methods_cb */ +inline void describe_method(XMLRPC_SERVER server, XMLRPC_VALUE vector, const char* method) { + if(method) { + server_method* sm = find_method(server, method); + if(sm) { + XMLRPC_AddValueToVector(vector, sm->desc); + } + } +} + + + +/* system.describeMethods() callback */ +static XMLRPC_VALUE xi_system_describe_methods_cb(XMLRPC_SERVER server, XMLRPC_REQUEST input, void* userData) { + XMLRPC_VALUE xParams = XMLRPC_VectorRewind(XMLRPC_RequestGetData(input)); + XMLRPC_VALUE xResponse = XMLRPC_CreateVector(NULL, xmlrpc_vector_struct); + XMLRPC_VALUE xMethodList = XMLRPC_CreateVector("methodList", xmlrpc_vector_array); + XMLRPC_VALUE xTypeList = NULL; + int bAll = 1; + + /* lazy loading of introspection data */ + check_docs_loaded(server, userData); + + xTypeList = XMLRPC_VectorGetValueWithID(server->xIntrospection, "typeList"); + + XMLRPC_AddValueToVector(xResponse, xTypeList); + XMLRPC_AddValueToVector(xResponse, xMethodList); + + /* check if we have any param */ + if(xParams) { + /* check if string or vector (1 or n) */ + XMLRPC_VALUE_TYPE type = XMLRPC_GetValueType(xParams); + if(type == xmlrpc_string) { + /* just one. spit it out. */ + describe_method(server, xMethodList, XMLRPC_GetValueString(xParams)); + bAll = 0; + } + else if(type == xmlrpc_vector) { + /* multiple. spit all out */ + XMLRPC_VALUE xIter = XMLRPC_VectorRewind(xParams); + while(xIter) { + describe_method(server, xMethodList, XMLRPC_GetValueString(xIter)); + xIter = XMLRPC_VectorNext(xParams); + } + bAll = 0; + } + } + + /* otherwise, default to sending all methods */ + if(bAll) { + q_iter qi = Q_Iter_Head_F(&server->methodlist); + while( qi ) { + server_method* sm = Q_Iter_Get_F(qi); + if(sm) { + XMLRPC_AddValueToVector(xMethodList, sm->desc); + } + qi = Q_Iter_Next_F(qi); + } + } + + return xResponse; +} + +/* this complies with system.listMethods as defined at http://xmlrpc.usefulinc.com/doc/reserved.html */ +static XMLRPC_VALUE xi_system_list_methods_cb(XMLRPC_SERVER server, XMLRPC_REQUEST input, void* userData) { + XMLRPC_VALUE xResponse = XMLRPC_CreateVector(NULL, xmlrpc_vector_array); + + q_iter qi = Q_Iter_Head_F(&server->methodlist); + while( qi ) { + server_method* sm = Q_Iter_Get_F(qi); + if(sm) { + XMLRPC_VectorAppendString(xResponse, 0, sm->name, 0); + } + qi = Q_Iter_Next_F(qi); + } + return xResponse; +} + +/* this complies with system.methodSignature as defined at + * http://xmlrpc.usefulinc.com/doc/sysmethodsig.html + */ +static XMLRPC_VALUE xi_system_method_signature_cb(XMLRPC_SERVER server, XMLRPC_REQUEST input, void* userData) { + const char* method = XMLRPC_GetValueString(XMLRPC_VectorRewind(XMLRPC_RequestGetData(input))); + XMLRPC_VALUE xResponse = NULL; + + /* lazy loading of introspection data */ + check_docs_loaded(server, userData); + + if(method) { + server_method* sm = find_method(server, method); + if(sm && sm->desc) { + XMLRPC_VALUE xTypesArray = XMLRPC_CreateVector(NULL, xmlrpc_vector_array); + XMLRPC_VALUE xIter, xParams, xSig, xSigIter; + const char* type; + + /* array of possible signatures. */ + xResponse = XMLRPC_CreateVector(NULL, xmlrpc_vector_array); + + /* find first signature */ + xSig = XMLRPC_VectorGetValueWithID(sm->desc, xi_token_signatures); + xSigIter = XMLRPC_VectorRewind( xSig ); + + /* iterate through sigs */ + while(xSigIter) { + /* first type is the return value */ + type = XMLRPC_VectorGetStringWithID(XMLRPC_VectorRewind( + XMLRPC_VectorGetValueWithID(xSigIter, xi_token_returns)), + xi_token_type); + XMLRPC_AddValueToVector(xTypesArray, + XMLRPC_CreateValueString(NULL, + type ? type : type_to_str(xmlrpc_none, 0), + 0)); + + /* the rest are parameters */ + xParams = XMLRPC_VectorGetValueWithID(xSigIter, xi_token_params); + xIter = XMLRPC_VectorRewind(xParams); + + /* iter through params, adding to types array */ + while(xIter) { + XMLRPC_AddValueToVector(xTypesArray, + XMLRPC_CreateValueString(NULL, + XMLRPC_VectorGetStringWithID(xIter, xi_token_type), + 0)); + xIter = XMLRPC_VectorNext(xParams); + } + + /* add types for this signature */ + XMLRPC_AddValueToVector(xResponse, xTypesArray); + + xSigIter = XMLRPC_VectorNext( xSig ); + } + } + } + + return xResponse; +} + +/* this complies with system.methodHelp as defined at + * http://xmlrpc.usefulinc.com/doc/sysmethhelp.html + */ +static XMLRPC_VALUE xi_system_method_help_cb(XMLRPC_SERVER server, XMLRPC_REQUEST input, void* userData) { + const char* method = XMLRPC_GetValueString(XMLRPC_VectorRewind(XMLRPC_RequestGetData(input))); + XMLRPC_VALUE xResponse = NULL; + + /* lazy loading of introspection data */ + check_docs_loaded(server, userData); + + if(method) { + server_method* sm = find_method(server, method); + if(sm && sm->desc) { + const char* help = XMLRPC_VectorGetStringWithID(sm->desc, xi_token_purpose); + + /* returns a documentation string, or empty string */ + xResponse = XMLRPC_CreateValueString(NULL, help ? help : xi_token_empty, 0); + } + } + + return xResponse; +} + +/*-************************************** +* End Introspection Callbacks (methods) * +****************************************/ + + +/*-************************ +* Introspection Utilities * +**************************/ + +/* performs registration of introspection methods */ +void xi_register_system_methods(XMLRPC_SERVER server) { + XMLRPC_ServerRegisterMethod(server, xi_token_system_list_methods, xi_system_list_methods_cb); + XMLRPC_ServerRegisterMethod(server, xi_token_system_method_help, xi_system_method_help_cb); + XMLRPC_ServerRegisterMethod(server, xi_token_system_method_signature, xi_system_method_signature_cb); + XMLRPC_ServerRegisterMethod(server, xi_token_system_describe_methods, xi_system_describe_methods_cb); +} + +/* describe a value (param, return, type) */ +static XMLRPC_VALUE describeValue_worker(const char* type, const char* id, const char* desc, int optional, const char* default_val, XMLRPC_VALUE sub_params) { + XMLRPC_VALUE xParam = NULL; + if(id || desc) { + xParam = XMLRPC_CreateVector(NULL, xmlrpc_vector_struct); + XMLRPC_VectorAppendString(xParam, xi_token_name, id, 0); + XMLRPC_VectorAppendString(xParam, xi_token_type, type, 0); + XMLRPC_VectorAppendString(xParam, xi_token_description, desc, 0); + if(optional != 2) { + XMLRPC_VectorAppendInt(xParam, xi_token_optional, optional); + } + if(optional == 1 && default_val) { + XMLRPC_VectorAppendString(xParam, xi_token_default, default_val, 0); + } + XMLRPC_AddValueToVector(xParam, sub_params); + } + return xParam; +} + + +/* convert an xml tree conforming to spec <url tbd> to XMLRPC_VALUE + * suitable for use with XMLRPC_ServerAddIntrospectionData + */ +XMLRPC_VALUE xml_element_to_method_description(xml_element* el, XMLRPC_ERROR err) { + XMLRPC_VALUE xReturn = NULL; + + if(el->name) { + const char* name = NULL; + const char* type = NULL; + const char* basetype = NULL; + const char* desc = NULL; + const char* def = NULL; + int optional = 0; + xml_element_attr* attr_iter = Q_Head(&el->attrs); + + /* grab element attributes up front to save redundant while loops */ + while(attr_iter) { + if(!strcmp(attr_iter->key, "name")) { + name = attr_iter->val; + } + else if(!strcmp(attr_iter->key, "type")) { + type = attr_iter->val; + } + else if(!strcmp(attr_iter->key, "basetype")) { + basetype = attr_iter->val; + } + else if(!strcmp(attr_iter->key, "desc")) { + desc = attr_iter->val; + } + else if(!strcmp(attr_iter->key, "optional")) { + if(attr_iter->val && !strcmp(attr_iter->val, "yes")) { + optional = 1; + } + } + else if(!strcmp(attr_iter->key, "default")) { + def = attr_iter->val; + } + attr_iter = Q_Next(&el->attrs); + } + + /* value and typeDescription behave about the same */ + if(!strcmp(el->name, "value") || !strcmp(el->name, "typeDescription")) { + XMLRPC_VALUE xSubList = NULL; + const char* ptype = !strcmp(el->name, "value") ? type : basetype; + if(ptype) { + if(Q_Size(&el->children) && + !strcmp(ptype, "array") || !strcmp(ptype, "struct") || !strcmp(ptype, "mixed")) { + xSubList = XMLRPC_CreateVector("member", xmlrpc_vector_array); + + if(xSubList) { + xml_element* elem_iter = Q_Head(&el->children); + while(elem_iter) { + XMLRPC_AddValueToVector(xSubList, + xml_element_to_method_description(elem_iter, err)); + elem_iter = Q_Next(&el->children); + } + } + } + xReturn = describeValue_worker(ptype, name, (desc ? desc : (xSubList ? NULL : el->text.str)), optional, def, xSubList); + } + } + + /* these three kids are about equivalent */ + else if(!strcmp(el->name, "params") || + !strcmp(el->name, "returns") || + !strcmp(el->name, "signature")) { + if(Q_Size(&el->children)) { + xml_element* elem_iter = Q_Head(&el->children); + xReturn = XMLRPC_CreateVector(!strcmp(el->name, "signature") ? NULL : el->name, xmlrpc_vector_struct); + + + while(elem_iter) { + XMLRPC_AddValueToVector(xReturn, + xml_element_to_method_description(elem_iter, err)); + elem_iter = Q_Next(&el->children); + } + } + } + + + else if(!strcmp(el->name, "methodDescription")) { + xml_element* elem_iter = Q_Head(&el->children); + xReturn = XMLRPC_CreateVector(NULL, xmlrpc_vector_struct); + + XMLRPC_VectorAppendString(xReturn, xi_token_name, name, 0); + + while(elem_iter) { + XMLRPC_AddValueToVector(xReturn, + xml_element_to_method_description(elem_iter, err)); + elem_iter = Q_Next(&el->children); + } + } + + /* items are slightly special */ + else if(!strcmp(el->name, "item")) { + xReturn = XMLRPC_CreateValueString(name, el->text.str, el->text.len); + } + + /* sure. we'll let any ol element with children through */ + else if(Q_Size(&el->children)) { + xml_element* elem_iter = Q_Head(&el->children); + xReturn = XMLRPC_CreateVector(el->name, xmlrpc_vector_mixed); + + while(elem_iter) { + XMLRPC_AddValueToVector(xReturn, + xml_element_to_method_description(elem_iter, err)); + elem_iter = Q_Next(&el->children); + } + } + + /* or anything at all really, so long as its got some text. + * no reason being all snotty about a spec, right? + */ + else if(el->name && el->text.len) { + xReturn = XMLRPC_CreateValueString(el->name, el->text.str, el->text.len); + } + } + + return xReturn; +} + +/*-**************************** +* End Introspection Utilities * +******************************/ + + + +/*-****************** +* Introspection API * +********************/ + + +/****f* VALUE/XMLRPC_IntrospectionCreateDescription + * NAME + * XMLRPC_IntrospectionCreateDescription + * SYNOPSIS + * XMLRPC_VALUE XMLRPC_IntrospectionCreateDescription(const char* xml, XMLRPC_ERROR err) + * FUNCTION + * converts raw xml describing types and methods into an + * XMLRPC_VALUE suitable for use with XMLRPC_ServerAddIntrospectionData() + * INPUTS + * xml - xml data conforming to introspection spec at <url tbd> + * err - optional pointer to error struct. filled in if error occurs and not NULL. + * RESULT + * XMLRPC_VALUE - newly created value, or NULL if fatal error. + * BUGS + * Currently does little or no validation of xml. + * Only parse errors are currently reported in err, not structural errors. + * SEE ALSO + * XMLRPC_ServerAddIntrospectionData () + * SOURCE + */ +XMLRPC_VALUE XMLRPC_IntrospectionCreateDescription(const char* xml, XMLRPC_ERROR err) { + XMLRPC_VALUE xReturn = NULL; + xml_element* root = xml_elem_parse_buf(xml, 0, 0, err ? &err->xml_elem_error : NULL); + + if(root) { + xReturn = xml_element_to_method_description(root, err); + + xml_elem_free(root); + } + + return xReturn; + +} +/*******/ + + +/****f* SERVER/XMLRPC_ServerAddIntrospectionData + * NAME + * XMLRPC_ServerAddIntrospectionData + * SYNOPSIS + * int XMLRPC_ServerAddIntrospectionData(XMLRPC_SERVER server, XMLRPC_VALUE desc) + * FUNCTION + * updates server with additional introspection data + * INPUTS + * server - target server + * desc - introspection data, should be a struct generated by + * XMLRPC_IntrospectionCreateDescription () + * RESULT + * int - 1 if success, else 0 + * NOTES + * - function will fail if neither typeList nor methodList key is present in struct. + * - if method or type already exists, it will be replaced. + * - desc is never freed by the server. caller is responsible for cleanup. + * BUGS + * - horribly slow lookups. prime candidate for hash improvements. + * - uglier and more complex than I like to see for API functions. + * SEE ALSO + * XMLRPC_ServerAddIntrospectionData () + * XMLRPC_ServerRegisterIntrospectionCallback () + * XMLRPC_CleanupValue () + * SOURCE + */ +int XMLRPC_ServerAddIntrospectionData(XMLRPC_SERVER server, XMLRPC_VALUE desc) { + int bSuccess = 0; + if(server && desc) { + XMLRPC_VALUE xNewTypes = XMLRPC_VectorGetValueWithID(desc, "typeList"); + XMLRPC_VALUE xNewMethods = XMLRPC_VectorGetValueWithID(desc, "methodList"); + XMLRPC_VALUE xServerTypes = XMLRPC_VectorGetValueWithID(server->xIntrospection, "typeList"); + + if(xNewMethods) { + XMLRPC_VALUE xMethod = XMLRPC_VectorRewind(xNewMethods); + + while(xMethod) { + const char* name = XMLRPC_VectorGetStringWithID(xMethod, xi_token_name); + server_method* sm = find_method(server, name); + + if(sm) { + if(sm->desc) { + XMLRPC_CleanupValue(sm->desc); + } + sm->desc = XMLRPC_CopyValue(xMethod); + bSuccess = 1; + } + + xMethod = XMLRPC_VectorNext(xNewMethods); + } + } + if(xNewTypes) { + if(!xServerTypes) { + if(!server->xIntrospection) { + server->xIntrospection = XMLRPC_CreateVector(NULL, xmlrpc_vector_struct); + } + + XMLRPC_AddValueToVector(server->xIntrospection, xNewTypes); + bSuccess = 1; + } + else { + XMLRPC_VALUE xIter = XMLRPC_VectorRewind(xNewTypes); + while(xIter) { + /* get rid of old values */ + XMLRPC_VALUE xPrev = find_named_value(xServerTypes, XMLRPC_VectorGetStringWithID(xIter, xi_token_name)); + if(xPrev) { + XMLRPC_VectorRemoveValue(xServerTypes, xPrev); + } + XMLRPC_AddValueToVector(xServerTypes, xIter); + bSuccess = 1; + xIter = XMLRPC_VectorNext(xNewTypes); + } + } + } + } + return bSuccess; +} +/*******/ + + +/****f* SERVER/XMLRPC_ServerRegisterIntrospectionCallback + * NAME + * XMLRPC_ServerRegisterIntrospectionCallback + * SYNOPSIS + * int XMLRPC_ServerRegisterIntrospectionCallback(XMLRPC_SERVER server, XMLRPC_IntrospectionCallback cb) + * FUNCTION + * registers a callback for lazy generation of introspection data + * INPUTS + * server - target server + * cb - callback that will generate introspection data + * RESULT + * int - 1 if success, else 0 + * NOTES + * parsing xml and generating introspection data is fairly expensive, thus a + * server may wish to wait until this data is actually requested before generating + * it. Any number of callbacks may be registered at any time. A given callback + * will only ever be called once, the first time an introspection request is + * processed after the time of callback registration. + * SEE ALSO + * XMLRPC_ServerAddIntrospectionData () + * XMLRPC_IntrospectionCreateDescription () + * SOURCE + */ +int XMLRPC_ServerRegisterIntrospectionCallback(XMLRPC_SERVER server, XMLRPC_IntrospectionCallback cb) { + int bSuccess = 0; + if(server && cb) { + + doc_method* dm = calloc(1, sizeof(doc_method)); + + if(dm) { + dm->method = cb; + dm->b_called = 0; + + if(Q_PushTail(&server->docslist, dm)) { + bSuccess = 1; + } + else { + my_free(dm); + } + } + } + return 0; +} +/*******/ + +/*-********************** +* End Introspection API * +************************/ + + + |