git.maemo.org Git - xmlrpc-c/blob - include/xmlrpc-c/server_abyss.h

   1 /* Copyright and license information is at the end of the file */
   2
   3 #ifndef  XMLRPC_SERVER_ABYSS_H_INCLUDED
   4 #define  XMLRPC_SERVER_ABYSS_H_INCLUDED
   5
   6 #include "xmlrpc-c/abyss.h"
   7 #include "xmlrpc-c/server.h"
   8
   9 #ifdef __cplusplus
  10 extern "C" {
  11 #endif /* __cplusplus */
  12
  13 /*=========================================================================
  14 **  XML-RPC Server (based on Abyss)
  15 **=========================================================================
  16 **  A simple XML-RPC server based on the Abyss web server. If errors
  17 **  occur during server setup, the server will exit. In general, if you
  18 **  want to use this API, you'll need to be familiar with Abyss.
  19 **
  20 **  There are two ways to use Abyss:
  21 **    1) You can use the handy wrapper functions.
  22 **    2) You can set up Abyss yourself, and install the appropriate
  23 **       handlers manually.
  24 */
  25
  26 #define XMLRPC_SERVER_ABYSS_NO_FLAGS (0)
  27
  28
  29
  30
  31 /*=========================================================================
  32 **  Basic Abyss Server Functions
  33 **=======================================================================*/
  34
  35 typedef void ((*runfirstFn)(void *));
  36
  37 typedef struct {
  38     const char *      config_file_name;
  39         /* NULL to use preferred proper API-level interface */
  40
  41     xmlrpc_registry * registryP;
  42
  43     /* runfirstFn and runfirst_arg are meaningless when
  44        config_file_name is NULL
  45     */
  46     runfirstFn        runfirst;
  47     void *            runfirst_arg;
  48
  49     unsigned int      port_number;
  50     const char *      log_file_name;
  51     unsigned int      keepalive_timeout;
  52     unsigned int      keepalive_max_conn;
  53     unsigned int      timeout;
  54     xmlrpc_bool       dont_advertise;
  55     xmlrpc_bool       socket_bound;
  56     xmlrpc_socket     socket_handle;
  57     const char *      uri_path;
  58     xmlrpc_bool       chunk_response;
  59 } xmlrpc_server_abyss_parms;
  60
  61
  62 #define XMLRPC_APSIZE(MBRNAME) \
  63     XMLRPC_STRUCTSIZE(xmlrpc_server_abyss_parms, MBRNAME)
  64
  65 /* XMLRPC_APSIZE(xyz) is the minimum size a struct xmlrpc_server_abyss_parms
  66    must be to include the 'xyz' member.  This is essential to forward and
  67    backward compatibility, as new members will be added to the end of the
  68    struct in future releases.  This is how the callee knows whether or
  69    not the caller is new enough to have supplied a certain parameter.
  70 */
  71
  72 void
  73 xmlrpc_server_abyss(xmlrpc_env *                      const envP,
  74                     const xmlrpc_server_abyss_parms * const parms,
  75                     unsigned int                      const parm_size);
  76
  77 void
  78 xmlrpc_server_abyss_set_handlers2(TServer *         const srvP,
  79                                   const char *      const filename,
  80                                   xmlrpc_registry * const registryP);
  81
  82 void
  83 xmlrpc_server_abyss_set_handlers(TServer *         const serverP,
  84                                  xmlrpc_registry * const registryP);
  85
  86 void
  87 xmlrpc_server_abyss_set_handler(xmlrpc_env *      const envP,
  88                                 TServer *         const serverP,
  89                                 const char *      const filename,
  90                                 xmlrpc_registry * const registryP);
  91
  92 /*=========================================================================
  93 **  Handy Abyss Extensions
  94 **=======================================================================*/
  95
  96 /* These are functions that have nothing to do with Xmlrpc-c, but provide
  97    convenient Abyss services beyond those provided by the Abyss library.
  98 */
  99
 100 /* Start an Abyss webserver running (previously created and
 101 ** initialized).  Under Unix, this routine will attempt to do a
 102 ** detaching fork, drop root privileges (if any) and create a pid
 103 ** file.  Under Windows, this routine merely starts the server.  This
 104 ** routine never returns.
 105 **
 106 ** Once you call this routine, it is illegal to modify the server any
 107 ** more, including changing any method registry.
 108 */
 109 void
 110 xmlrpc_server_abyss_run(void);
 111
 112 /* Same as xmlrpc_server_abyss_run(), except you get to specify a "runfirst"
 113 ** function.  The server runs this just before executing the actual server
 114 ** function, after any daemonizing.  NULL for 'runfirst' means no runfirst
 115 ** function.  'runfirstArg' is the argument the server passes to the runfirst
 116 ** function.
 117 **/
 118 void
 119 xmlrpc_server_abyss_run_first(void (runfirst(void *)),
 120                               void * const runfirstArg);
 121
 122 /*=========================================================================
 123 **  Method Registry
 124 **=========================================================================
 125    These functions are for the built-in xmlrpc_server_abyss registry.
 126    It's usually simpler to skip all this and use the regular method
 127    registry services (from xmlrpc_server.h) to build a registry and
 128    pass it to xmlrpc_server_abyss.
 129 */
 130
 131 /* Call this function to create a new Abyss webserver with the default
 132 ** options and the built-in method registry.  If you've already
 133 ** initialized Abyss using Abyss functions, you can instead call
 134 ** xmlrpc_server_abyss_init_registry() to make it an Xmlrpc-c server.
 135 ** Or use a regular method registry and call
 136 ** xmlrpc_server_abyss_set_handlers().
 137 **/
 138 void
 139 xmlrpc_server_abyss_init(int          const flags,
 140                          const char * const config_file);
 141
 142 /* This is called automatically by xmlrpc_server_abyss_init. */
 143 void xmlrpc_server_abyss_init_registry (void);
 144
 145 /* Fetch the internal registry, if you happen to need it.
 146    If you're using this, you really shouldn't be using the built-in
 147    registry at all.  It exists today only for backward compatibilty.
 148 */
 149 extern xmlrpc_registry *
 150 xmlrpc_server_abyss_registry (void);
 151
 152 /* A quick & easy shorthand for adding a method. Depending on
 153 ** how you've configured your copy of Abyss, it's probably not safe to
 154 ** call this method after calling xmlrpc_server_abyss_run. */
 155 void xmlrpc_server_abyss_add_method (char *method_name,
 156                                      xmlrpc_method method,
 157                                      void *user_data);
 158
 159 /* As above, but provide documentation (see xmlrpc_registry_add_method_w_doc
 160 ** for more information). You should really use this one. */
 161 extern void
 162 xmlrpc_server_abyss_add_method_w_doc (char *method_name,
 163                                       xmlrpc_method method,
 164                                       void *user_data,
 165                                       char *signature,
 166                                       char *help);
 167
 168 /*=========================================================================
 169 **  Content Handlers
 170 **=======================================================================*/
 171 /* Abyss contents handlers xmlrpc_server_abyss_rpc2_handler()
 172    and xmlrpc_server_abyss_default_handler() were available in older
 173    Xmlrpc-c, but starting with Release 1.01, they are not.  Instead,
 174    call xmlrpc_server_abyss_set_handlers() to install them.
 175
 176    Alternatively, you can write your own handlers that do the same thing.
 177    It's not hard, and if you're writing low enough level Abyss code that
 178    you can't use xmlrpc_server_abyss_set_handlers(), you probably want to
 179    anyway.
 180 */
 181
 182 #ifdef __cplusplus
 183 }
 184 #endif /* __cplusplus */
 185
 186 /* Copyright (C) 2001 by First Peer, Inc. All rights reserved.
 187 **
 188 ** Redistribution and use in source and binary forms, with or without
 189 ** modification, are permitted provided that the following conditions
 190 ** are met:
 191 ** 1. Redistributions of source code must retain the above copyright
 192 **    notice, this list of conditions and the following disclaimer.
 193 ** 2. Redistributions in binary form must reproduce the above copyright
 194 **    notice, this list of conditions and the following disclaimer in the
 195 **    documentation and/or other materials provided with the distribution.
 196 ** 3. The name of the author may not be used to endorse or promote products
 197 **    derived from this software without specific prior written permission.
 198 **
 199 ** THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 200 ** ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 201 ** IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 202 ** ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 203 ** FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 204 ** DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 205 ** OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 206 ** HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 207 ** LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 208 ** OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 209 ** SUCH DAMAGE. */
 210
 211 #endif