1 /* Copyright and license information is at the end of the file */
3 #ifndef XMLRPC_SERVER_ABYSS_H_INCLUDED
4 #define XMLRPC_SERVER_ABYSS_H_INCLUDED
6 #include "xmlrpc-c/abyss.h"
7 #include "xmlrpc-c/server.h"
11 #endif /* __cplusplus */
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.
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
26 #define XMLRPC_SERVER_ABYSS_NO_FLAGS (0)
31 /*=========================================================================
32 ** Basic Abyss Server Functions
33 **=======================================================================*/
35 typedef void ((*runfirstFn)(void *));
38 const char * config_file_name;
39 /* NULL to use preferred proper API-level interface */
41 xmlrpc_registry * registryP;
43 /* runfirstFn and runfirst_arg are meaningless when
44 config_file_name is NULL
49 unsigned int port_number;
50 const char * log_file_name;
51 unsigned int keepalive_timeout;
52 unsigned int keepalive_max_conn;
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;
62 #define XMLRPC_APSIZE(MBRNAME) \
63 XMLRPC_STRUCTSIZE(xmlrpc_server_abyss_parms, MBRNAME)
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.
73 xmlrpc_server_abyss(xmlrpc_env * const envP,
74 const xmlrpc_server_abyss_parms * const parms,
75 unsigned int const parm_size);
78 xmlrpc_server_abyss_set_handlers2(TServer * const srvP,
79 const char * const filename,
80 xmlrpc_registry * const registryP);
83 xmlrpc_server_abyss_set_handlers(TServer * const serverP,
84 xmlrpc_registry * const registryP);
87 xmlrpc_server_abyss_set_handler(xmlrpc_env * const envP,
88 TServer * const serverP,
89 const char * const filename,
90 xmlrpc_registry * const registryP);
92 /*=========================================================================
93 ** Handy Abyss Extensions
94 **=======================================================================*/
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.
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.
106 ** Once you call this routine, it is illegal to modify the server any
107 ** more, including changing any method registry.
110 xmlrpc_server_abyss_run(void);
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
119 xmlrpc_server_abyss_run_first(void (runfirst(void *)),
120 void * const runfirstArg);
122 /*=========================================================================
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.
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().
139 xmlrpc_server_abyss_init(int const flags,
140 const char * const config_file);
142 /* This is called automatically by xmlrpc_server_abyss_init. */
143 void xmlrpc_server_abyss_init_registry (void);
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.
149 extern xmlrpc_registry *
150 xmlrpc_server_abyss_registry (void);
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,
159 /* As above, but provide documentation (see xmlrpc_registry_add_method_w_doc
160 ** for more information). You should really use this one. */
162 xmlrpc_server_abyss_add_method_w_doc (char *method_name,
163 xmlrpc_method method,
168 /*=========================================================================
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.
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
184 #endif /* __cplusplus */
186 /* Copyright (C) 2001 by First Peer, Inc. All rights reserved.
188 ** Redistribution and use in source and binary forms, with or without
189 ** modification, are permitted provided that the following conditions
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.
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