CMakeLua/Utilities/cmxmlrpc/xmlrpc_server_abyss.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_ABYSS_H_
  28 #define  _XMLRPC_SERVER_ABYSS_H_ 1
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif /* __cplusplus */
  33
  34 struct _TServer;
  35
  36 /*=========================================================================
  37 **  XML-RPC Server (based on Abyss)
  38 **=========================================================================
  39 **  A simple XML-RPC server based on the Abyss web server. If errors
  40 **  occur during server setup, the server will exit. In general, if you
  41 **  want to use this API, you'll need to be familiar with Abyss.
  42 **
  43 **  There are two ways to use Abyss:
  44 **    1) You can use the handy wrapper functions.
  45 **    2) You can set up Abyss yourself, and install the appropriate
  46 **       handlers manually.
  47 */
  48
  49 #define XMLRPC_SERVER_ABYSS_NO_FLAGS (0)
  50
  51
  52
  53
  54 /*=========================================================================
  55 **  Basic Abyss Server Functions
  56 **=======================================================================*/
  57
  58 typedef void ((*runfirstFn)(void *));
  59
  60 typedef struct {
  61     const char *      config_file_name;
  62     xmlrpc_registry * registryP;
  63     runfirstFn        runfirst;
  64     void *            runfirst_arg;
  65 } xmlrpc_server_abyss_parms;
  66
  67
  68 #define XMLRPC_APSIZE(MBRNAME) \
  69     XMLRPC_STRUCTSIZE(xmlrpc_server_abyss_parms, MBRNAME)
  70
  71 /* XMLRPC_APSIZE(xyz) is the minimum size a struct xmlrpc_server_abyss_parms
  72    must be to include the 'xyz' member.  This is essential to forward and
  73    backward compatbility, as new members will be added to the end of the
  74    struct in future releases.  This is how the callee knows whether or
  75    not the caller is new enough to have supplied a certain parameter.
  76 */
  77
  78 void
  79 xmlrpc_server_abyss(xmlrpc_env *                      const envP,
  80                     const xmlrpc_server_abyss_parms * const parms,
  81                     unsigned int                      const parm_size);
  82
  83 void
  84 xmlrpc_server_abyss_set_handlers(struct _TServer * const srvP,
  85                                  xmlrpc_registry * const registryP);
  86
  87
  88 /*=========================================================================
  89 **  Handy Abyss Extensions
  90 **=======================================================================*/
  91
  92 /* These are functions that have nothing to do with Xmlrpc-c, but provide
  93    convenient Abyss services beyond those provided by the Abyss library.
  94 */
  95
  96 /* Start an Abyss webserver running (previously created and
  97 ** initialized).  Under Unix, this routine will attempt to do a
  98 ** detaching fork, drop root privileges (if any) and create a pid
  99 ** file.  Under Windows, this routine merely starts the server.  This
 100 ** routine never returns.
 101 **
 102 ** Once you call this routine, it is illegal to modify the server any
 103 ** more, including changing any method registry.
 104 */
 105 void
 106 xmlrpc_server_abyss_run(void);
 107
 108 /* Same as xmlrpc_server_abyss_run(), except you get to specify a "runfirst"
 109 ** function.  The server runs this just before executing the actual server
 110 ** function, after any daemonizing.  NULL for 'runfirst' means no runfirst
 111 ** function.  'runfirstArg' is the argument the server passes to the runfirst
 112 ** function.
 113 **/
 114 void
 115 xmlrpc_server_abyss_run_first(void (runfirst(void *)),
 116                               void * const runfirstArg);
 117
 118 /*=========================================================================
 119 **  Method Registry
 120 **=========================================================================
 121    These functions are for the built-in xmlrpc_server_abyss registry.
 122    It's usually simpler to skip all this and use the regular method
 123    registry services (from xmlrpc_server.h) to build a registry and
 124    pass it to xmlrpc_server_abyss.
 125 */
 126
 127 /* Call this function to create a new Abyss webserver with the default
 128 ** options and the built-in method registry.  If you've already
 129 ** initialized Abyss using Abyss functions, you can instead call
 130 ** xmlrpc_server_abyss_init_registry() to make it an Xmlrpc-c server.
 131 ** Or use a regular method registry and call
 132 ** xmlrpc_server_abyss_set_handlers().
 133 **/
 134 void
 135 xmlrpc_server_abyss_init(int          const flags,
 136                          const char * const config_file);
 137
 138 /* This is called automatically by xmlrpc_server_abyss_init. */
 139 void xmlrpc_server_abyss_init_registry (void);
 140
 141 /* Fetch the internal registry, if you happen to need it.
 142    If you're using this, you really shouldn't be using the built-in
 143    registry at all.  It exists today only for backward compatibilty.
 144 */
 145 extern xmlrpc_registry *
 146 xmlrpc_server_abyss_registry (void);
 147
 148 /* A quick & easy shorthand for adding a method. Depending on
 149 ** how you've configured your copy of Abyss, it's probably not safe to
 150 ** call this method after calling xmlrpc_server_abyss_run. */
 151 void xmlrpc_server_abyss_add_method (char *method_name,
 152                                      xmlrpc_method method,
 153                                      void *user_data);
 154
 155 /* As above, but provide documentation (see xmlrpc_registry_add_method_w_doc
 156 ** for more information). You should really use this one. */
 157 extern void
 158 xmlrpc_server_abyss_add_method_w_doc (char *method_name,
 159                                       xmlrpc_method method,
 160                                       void *user_data,
 161                                       char *signature,
 162                                       char *help);
 163
 164 /*=========================================================================
 165 **  Content Handlers
 166 **=======================================================================*/
 167 /* Abyss contents handlers xmlrpc_server_abyss_rpc2_handler()
 168    and xmlrpc_server_abyss_default_handler() were available in older
 169    Xmlrpc-c, but starting with Release 1.01, they are not.  Instead,
 170    call xmlrpc_server_abyss_set_handlers() to install them.
 171
 172    Alternatively, you can write your own handlers that do the same thing.
 173    It's not hard, and if you're writing low enough level Abyss code that
 174    you can't use xmlrpc_server_abyss_set_handlers(), you probably want to
 175    anyway.
 176 */
 177
 178 #ifdef __cplusplus
 179 }
 180 #endif /* __cplusplus */
 181
 182 #endif