CMake/Utilities/cmxmlrpc/xmlrpc_server.h

180 lines
8.0 KiB
C

/* Copyright (C) 2001 by First Peer, Inc. All rights reserved.
**
** Redistribution and use in source and binary forms, with or without
** modification, are permitted provided that the following conditions
** are met:
** 1. Redistributions of source code must retain the above copyright
** notice, this list of conditions and the following disclaimer.
** 2. Redistributions in binary form must reproduce the above copyright
** notice, this list of conditions and the following disclaimer in the
** documentation and/or other materials provided with the distribution.
** 3. The name of the author may not be used to endorse or promote products
** derived from this software without specific prior written permission.
**
** THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
** ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
** IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
** ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
** FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
** DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
** OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
** HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
** LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
** OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
** SUCH DAMAGE. */
#ifndef _XMLRPC_SERVER_H_
#define _XMLRPC_SERVER_H_ 1
#include <cmxmlrpc/xmlrpc.h>
#ifdef __cplusplus
extern "C" {
#endif
/*=========================================================================
** XML-RPC Server Method Registry
**=========================================================================
** A method registry maintains a list of functions, and handles
** dispatching. To build an XML-RPC server, just add an XML-RPC protocol
** driver.
**
** Methods are C functions which take some combination of the following
** parameters. All pointers except user_data belong to the library, and
** must not be freed by the callback or used after the callback returns.
**
** env: An XML-RPC error-handling environment. No faults will be
** set when the function is called. If an error occurs,
** set an appropriate fault and return NULL. (If a fault is
** set, the NULL return value will be enforced!)
** host: The 'Host:' header passed by the XML-RPC client, or NULL,
** if no 'Host:' header has been provided.
** method_name: The name used to call this method.
** user_data: The user_data used to register this method.
** param_array: The parameters passed to this function, stored in an
** XML-RPC array. You are *not* responsible for calling
** xmlrpc_DECREF on this array.
**
** Return value: If no fault has been set, the function must return a
** valid xmlrpc_value. This will be serialized, returned
** to the caller, and xmlrpc_DECREF'd.
*/
/* A function to call before invoking a method for doing things like access
** control or sanity checks. If a fault is set from this function, the
** method will not be called and the fault will be returned. */
typedef void
(*xmlrpc_preinvoke_method)(xmlrpc_env * env,
const char * method_name,
xmlrpc_value * param_array,
void * user_data);
/* An ordinary method. */
typedef xmlrpc_value *
(*xmlrpc_method)(xmlrpc_env * env,
xmlrpc_value * param_array,
void * user_data);
/* A default method to call if no method can be found. */
typedef xmlrpc_value *
(*xmlrpc_default_method)(xmlrpc_env * env,
const char * host,
const char * method_name,
xmlrpc_value * param_array,
void * user_data);
/* Our registry structure. This has no public members. */
typedef struct _xmlrpc_registry xmlrpc_registry;
/* Create a new method registry. */
xmlrpc_registry *
xmlrpc_registry_new(xmlrpc_env * env);
/* Delete a method registry. */
void
xmlrpc_registry_free(xmlrpc_registry * registry);
/* Disable introspection. The xmlrpc_registry has introspection
** capability built-in. If you want to make nosy people work harder,
** you can turn this off. */
void
xmlrpc_registry_disable_introspection(xmlrpc_registry * registry);
/* Register a method. The host parameter must be NULL (for now). You
** are responsible for owning and managing user_data. The registry
** will make internal copies of any other pointers it needs to
** keep around. */
void
xmlrpc_registry_add_method(xmlrpc_env * env,
xmlrpc_registry * registry,
const char * host,
const char * method_name,
xmlrpc_method method,
void * user_data);
/* As above, but allow the user to supply introspection information.
**
** Signatures use their own little description language. It consists
** of one-letter type code (similar to the ones used in xmlrpc_parse_value)
** for the result, a colon, and zero or more one-letter type codes for
** the parameters. For example:
** i:ibdsAS86
** If a function has more than one possible prototype, separate them with
** commas:
** i:,i:s,i:ii
** If the function signature can't be represented using this language,
** pass a single question mark:
** ?
** Help strings are ASCII text, and may contain HTML markup. */
void
xmlrpc_registry_add_method_w_doc(xmlrpc_env * env,
xmlrpc_registry * registry,
const char * host,
const char * method_name,
xmlrpc_method method,
void * user_data,
const char * signature,
const char * help);
/* Given a registry, a host name, and XML data; parse the <methodCall>,
** find the appropriate method, call it, serialize the response, and
** return it as an xmlrpc_mem_block. Most errors will be serialized
** as <fault> responses. If a *really* bad error occurs, set a fault and
** return NULL. (Actually, we currently give up with a fatal error,
** but that should change eventually.)
** The caller is responsible for destroying the memory block. */
xmlrpc_mem_block *
xmlrpc_registry_process_call(xmlrpc_env * const envP,
xmlrpc_registry * const registryP,
const char * const host,
const char * const xml_data,
size_t const xml_len);
/* Define a default method for the specified registry. This will be invoked
** if no other method matches. The user_data pointer is property of the
** application, and will not be freed or manipulated by the registry. */
void
xmlrpc_registry_set_default_method(xmlrpc_env * env,
xmlrpc_registry * registry,
xmlrpc_default_method handler,
void * user_data);
/* Define a preinvoke method for the specified registry. This function will
** be called before any method (either the default or a registered one) is
** invoked. Applications can use this to do things like access control or
** sanity checks. The user_data pointer is property of the application,
** and will not be freed or manipulated by the registry. */
void
xmlrpc_registry_set_preinvoke_method(xmlrpc_env * env,
xmlrpc_registry * registry,
xmlrpc_preinvoke_method method,
void * user_data);
#ifdef __cplusplus
}
#endif
#endif