Utilities/cmxmlrpc/xmlrpc_server.h

   1 /* Copyright (C) 2001 by First Peer, Inc. All rights reserved.
   2 **
   3 ** Redistribution and use in source and binary forms, with or without
   4 ** modification, are permitted provided that the following conditions
   5 ** are met:
   6 ** 1. Redistributions of source code must retain the above copyright
   7 **    notice, this list of conditions and the following disclaimer.
   8 ** 2. Redistributions in binary form must reproduce the above copyright
   9 **    notice, this list of conditions and the following disclaimer in the
  10 **    documentation and/or other materials provided with the distribution.
  11 ** 3. The name of the author may not be used to endorse or promote products
  12 **    derived from this software without specific prior written permission.
  13 **
  14 ** THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 ** ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 ** IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 ** ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 ** FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 ** DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 ** OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 ** HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 ** LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 ** OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 ** SUCH DAMAGE. */
  25
  26
  27 #ifndef  _XMLRPC_SERVER_H_
  28 #define  _XMLRPC_SERVER_H_ 1
  29
  30 #include <cmxmlrpc/xmlrpc.h>
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /*=========================================================================
  37 **  XML-RPC Server Method Registry
  38 **=========================================================================
  39 **  A method registry maintains a list of functions, and handles
  40 **  dispatching. To build an XML-RPC server, just add an XML-RPC protocol
  41 **  driver.
  42 **
  43 **  Methods are C functions which take some combination of the following
  44 **  parameters. All pointers except user_data belong to the library, and
  45 **  must not be freed by the callback or used after the callback returns.
  46 **
  47 **  env:          An XML-RPC error-handling environment. No faults will be
  48 **                set when the function is called. If an error occurs,
  49 **                set an appropriate fault and return NULL. (If a fault is
  50 **                set, the NULL return value will be enforced!)
  51 **  host:         The 'Host:' header passed by the XML-RPC client, or NULL,
  52 **                if no 'Host:' header has been provided.
  53 **  method_name:  The name used to call this method.
  54 **  user_data:    The user_data used to register this method.
  55 **  param_array:  The parameters passed to this function, stored in an
  56 **                XML-RPC array. You are *not* responsible for calling
  57 **                xmlrpc_DECREF on this array.
  58 **
  59 **  Return value: If no fault has been set, the function must return a
  60 **                valid xmlrpc_value. This will be serialized, returned
  61 **                to the caller, and xmlrpc_DECREF'd.
  62 */
  63
  64 /* A function to call before invoking a method for doing things like access
  65 ** control or sanity checks.  If a fault is set from this function, the
  66 ** method will not be called and the fault will be returned. */
  67 typedef void
  68 (*xmlrpc_preinvoke_method)(xmlrpc_env *   env,
  69                            const char *   method_name,
  70                            xmlrpc_value * param_array,
  71                            void *         user_data);
  72
  73 /* An ordinary method. */
  74 typedef xmlrpc_value *
  75 (*xmlrpc_method)(xmlrpc_env *   env,
  76                  xmlrpc_value * param_array,
  77                  void *         user_data);
  78
  79 /* A default method to call if no method can be found. */
  80 typedef xmlrpc_value *
  81 (*xmlrpc_default_method)(xmlrpc_env *   env,
  82                          const char *   host,
  83                          const char *   method_name,
  84                          xmlrpc_value * param_array,
  85                          void *         user_data);
  86
  87 /* Our registry structure. This has no public members. */
  88 typedef struct _xmlrpc_registry xmlrpc_registry;
  89
  90 /* Create a new method registry. */
  91 xmlrpc_registry *
  92 xmlrpc_registry_new(xmlrpc_env * env);
  93
  94 /* Delete a method registry. */
  95 void
  96 xmlrpc_registry_free(xmlrpc_registry * registry);
  97
  98 /* Disable introspection.  The xmlrpc_registry has introspection
  99 ** capability built-in.  If you want to make nosy people work harder,
 100 ** you can turn this off. */
 101 void
 102 xmlrpc_registry_disable_introspection(xmlrpc_registry * registry);
 103
 104 /* Register a method. The host parameter must be NULL (for now). You
 105 ** are responsible for owning and managing user_data. The registry
 106 ** will make internal copies of any other pointers it needs to
 107 ** keep around. */
 108 void
 109 xmlrpc_registry_add_method(xmlrpc_env *      env,
 110                            xmlrpc_registry * registry,
 111                            const char *      host,
 112                            const char *      method_name,
 113                            xmlrpc_method     method,
 114                            void *            user_data);
 115
 116 /* As above, but allow the user to supply introspection information.
 117 **
 118 ** Signatures use their own little description language. It consists
 119 ** of one-letter type code (similar to the ones used in xmlrpc_parse_value)
 120 ** for the result, a colon, and zero or more one-letter type codes for
 121 ** the parameters. For example:
 122 **   i:ibdsAS86
 123 ** If a function has more than one possible prototype, separate them with
 124 ** commas:
 125 **   i:,i:s,i:ii
 126 ** If the function signature can't be represented using this language,
 127 ** pass a single question mark:
 128 **   ?
 129 ** Help strings are ASCII text, and may contain HTML markup. */
 130 void
 131 xmlrpc_registry_add_method_w_doc(xmlrpc_env *      env,
 132                                  xmlrpc_registry * registry,
 133                                  const char *      host,
 134                                  const char *      method_name,
 135                                  xmlrpc_method     method,
 136                                  void *            user_data,
 137                                  const char *      signature,
 138                                  const char *      help);
 139
 140 /* Given a registry, a host name, and XML data; parse the <methodCall>,
 141 ** find the appropriate method, call it, serialize the response, and
 142 ** return it as an xmlrpc_mem_block. Most errors will be serialized
 143 ** as <fault> responses. If a *really* bad error occurs, set a fault and
 144 ** return NULL. (Actually, we currently give up with a fatal error,
 145 ** but that should change eventually.)
 146 ** The caller is responsible for destroying the memory block. */
 147 xmlrpc_mem_block *
 148 xmlrpc_registry_process_call(xmlrpc_env *      const envP,
 149                              xmlrpc_registry * const registryP,
 150                              const char *      const host,
 151                              const char *      const xml_data,
 152                              size_t            const xml_len);
 153
 154 /* Define a default method for the specified registry.  This will be invoked
 155 ** if no other method matches.  The user_data pointer is property of the
 156 ** application, and will not be freed or manipulated by the registry. */
 157 void
 158 xmlrpc_registry_set_default_method(xmlrpc_env *          env,
 159                                    xmlrpc_registry *     registry,
 160                                    xmlrpc_default_method handler,
 161                                    void *                user_data);
 162
 163 /* Define a preinvoke method for the specified registry.  This function will
 164 ** be called before any method (either the default or a registered one) is
 165 ** invoked.  Applications can use this to do things like access control or
 166 ** sanity checks.  The user_data pointer is property of the application,
 167 ** and will not be freed or manipulated by the registry. */
 168 void
 169 xmlrpc_registry_set_preinvoke_method(xmlrpc_env *            env,
 170                                      xmlrpc_registry *       registry,
 171                                      xmlrpc_preinvoke_method method,
 172                                      void *                  user_data);
 173
 174
 175 #ifdef __cplusplus
 176 }
 177 #endif
 178
 179 #endif