xmlrpc.h

The Kannel Open Source WAP and SMS gateway works as both an SMS gateway, for implementing keyword b

/* ==================================================================== 
 * The Kannel Software License, Version 1.0 
 * 
 * Copyright (c) 2001-2004 Kannel Group  
 * Copyright (c) 1998-2001 WapIT Ltd.   
 * 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 end-user documentation included with the redistribution, 
 *    if any, must include the following acknowledgment: 
 *       "This product includes software developed by the 
 *        Kannel Group (http://www.kannel.org/)." 
 *    Alternately, this acknowledgment may appear in the software itself, 
 *    if and wherever such third-party acknowledgments normally appear. 
 * 
 * 4. The names "Kannel" and "Kannel Group" must not be used to 
 *    endorse or promote products derived from this software without 
 *    prior written permission. For written permission, please  
 *    contact [e-mail]. 
 * 
 * 5. Products derived from this software may not be called "Kannel", 
 *    nor may "Kannel" appear in their name, without prior written 
 *    permission of the Kannel Group. 
 * 
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED 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 KANNEL GROUP OR ITS 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. 
 * ==================================================================== 
 * 
 * This software consists of voluntary contributions made by many 
 * individuals on behalf of the Kannel Group.  For more information on  
 * the Kannel Group, please see <http://www.kannel.org/>. 
 * 
 * Portions of this software are based upon software originally written at  
 * WapIT Ltd., Helsinki, Finland for the Kannel project.  
 */ 

/*
 * xmlrpc.h - XML-RPC functions
 *
 * Functions to handle XML-RPC structure - building and parsing
 *
 * XML-RPC is HTTP-based XML defination to handle remote procedure calls,
 * and is defined in http://www.xml-rpc.org
 *
 * The current implementation is not yet ready (it does not, for example,
 *  do any parsing nor building the tree), and is not used for any real use,
 * yet, but probably future interfaces might be able to use this, too
 *
 *
 * Kalle Marjola 2001 for project Kannel
 * Robert Ga砤ch <[e-mail]>
 */

#ifndef __XMLRPC_H
#define __XMLRPC_H

#include "gwlib/gwlib.h"

/*
 * types and structures defined by www.xml-rpc.com
 */
typedef struct xmlrpc_document XMLRPCDocument;
typedef struct xmlrpc_value XMLRPCValue;
typedef struct xmlrpc_scalar XMLRPCScalar;

enum { 
    xr_undefined, xr_scalar, xr_array, xr_struct, 
    xr_string, xr_int, xr_bool, xr_double, xr_date, xr_base64, 
    xr_methodcall, xr_methodresponse 
};

/*
 * status codes while parsing
 */
enum {
    XMLRPC_COMPILE_OK,
    XMLRPC_XMLPARSE_FAILED,
    XMLRPC_PARSING_FAILED
};



/*** DOCUMENTS ***/

/* Create new XMLRPCDocument object of undefined_type  */
XMLRPCDocument *xmlrpc_doc_create(void);
/* Create new MethodCall with given name */
XMLRPCDocument *xmlrpc_doc_create_call(Octstr *name);
/* Create new MethodResponse */
XMLRPCDocument *xmlrpc_doc_create_response(void);
/* Create new fault MethodResponse with given code and fault string */
XMLRPCDocument *xmlrpc_doc_create_faultresponse(long faultcode, Octstr *faultstring);

/* Create new XMLRPCDocument object from given body of text/xml, 
 * d_type is expected document type: xr_methodcall, xr_methodresponse
   or xr_undefined if any
 */
XMLRPCDocument *xmlrpc_doc_parse(Octstr *post_body, int d_type);

/* Destroy XMLRPCDocument object */
void xmlrpc_doc_destroy(XMLRPCDocument *xrdoc, int d_type);

/* Add a scalar param to XMLRPCDocument object.
 * d_type is expected document type: xr_methodcall or xr_methodresponse.
 * Return 0 if ok or -1 if something wrong (e.g. xrdoc is null or faultresponse)
 */
int xmlrpc_doc_add_scalar(XMLRPCDocument *xrdoc, int d_type, int type, void *arg);

/* Add given XMLRPCValue param to XMLRPCDocument object.
 * d_type is expected document type: xr_methodcall or xr_methodresponse.
 * Return 0 if ok or -1 if something wrong.
 * NOTE that value is NOT duplicated 
 */
int xmlrpc_doc_add_value(XMLRPCDocument *xrdoc, int d_type, XMLRPCValue *value);

/* Create Octstr (text/xml string) out of given XMLRPCDocument. 
 * d_type is expected document type. 
 * level is the indent width.
 * Caller must free returned Octstr.
 */
Octstr *xmlrpc_doc_print(XMLRPCDocument *xrdoc, int d_type, int level);

/* Send XMLRPCDocument to given url with given headers. 
 * d_type is expected document type. 
 * Note: adds XML-RPC specified headers into given list if needed. 
 *       and if NULL when this function called, automatically generated
 *
 * Return 0 if all went fine, -1 if failure. As user reference, uses *void
 */
int xmlrpc_doc_send(XMLRPCDocument *xrdoc, int d_type, HTTPCaller *http_ref,
		    Octstr *url, List *headers, void *ref);


/*** METHOD CALLS ***/

/* Create new MethodCall with given name and no params */
#define xmlrpc_create_call(method) \
            xmlrpc_doc_create_call(method)

/* Create new MethodCall from given body of text/xml */
#define xmlrpc_parse_call(post_body) \
            xmlrpc_doc_parse(post_body, xr_methodcall)

/* Destroy MethodCall */
#define xmlrpc_destroy_call(call) \
            xmlrpc_doc_destroy(call, xr_methodcall)

/* Add a scalar param to MethodCall. 
 * type is scalar type: xr_string, xr_int, xr_bool, xr_double, xr_date or xr_base64
 * arg is pointer to value of given type: Octstr*, long*, int*, double*, Octstr* or Octstr*
 * respectively
 * Return 0 if ok or -1 if something wrong.
 */
#define xmlrpc_add_call_scalar(call, type, arg) \
            xmlrpc_doc_add_scalar(call, xr_methodcall, type, arg)

/* Add given XMLRPCValue param to MethodCall.
 * Return 0 if ok or -1 if something wrong.
 * NOTE: value is NOT duplicated 
 */
#define xmlrpc_add_call_value(call, value) \
            xmlrpc_doc_add_value(call, xr_methodcall, value)

/* Create Octstr (text/xml string) out of given MethodCall. Caller
 * must free returned Octstr 
 */
#define xmlrpc_print_call(call) \
            xmlrpc_doc_print(call, xr_methodcall, 0)

/* Send MethodCall to given url with given headers. 
 * d_type is expected document type. 
 * Note: adds XML-RPC specified headers into given list if needed. 
 *       and if NULL when this function called, automatically generated
 *
 * Return 0 if all went fine, -1 if failure. As user reference, uses *void
 */
#define xmlrpc_send_call(call,http_ref, url, headers, ref) \
            xmlrpc_doc_send(call, xr_methodcall, http_ref, url, headers, ref)

/* Return the name of the method requested or NULL if document is not method call */
Octstr *xmlrpc_get_call_name(XMLRPCDocument *call);



/*** METHOD RESPONSES ***/

/* Create a new MethodResponse with no param value */
#define xmlrpc_create_response() \
            xmlrpc_doc_create_response()

/* Create a new fault MethodResponse with given faultcode and faultstring */
#define xmlrpc_create_faultresponse(faultcode, faultstring) \
            xmlrpc_doc_create_faultresponse(faultcode, faultstring)

/* Create a new MethodResponse from given text/xml string */
#define xmlrpc_parse_response(post_body) \
            xmlrpc_doc_parse(post_body, xr_methodresponse)

/* Destroy MethodResponse */
#define xmlrpc_destroy_response(response) \
            xmlrpc_doc_destroy(response, xr_methodresponse)

/* Add a scalar param to MethodResponse. 
 * type is scalar type: xr_string, xr_int, xr_bool, xr_double, xr_date or xr_base64
 * arg is pointer to value of given type: Octstr*, long*, int*, double*, Octstr* or Octstr*
 * respectively
 * Return 0 if ok or -1 if something wrong.
 */
#define xmlrpc_add_response_scalar(response, type, arg) \
            xmlrpc_doc_add_scalar(response, xr_methodresponse, type, arg)

/* Add given XMLRPCValue param to MethodResponse.
 * Return 0 if ok or -1 if something wrong.
 * NOTE: value is NOT duplicated 
 */
#define xmlrpc_add_response_value(response, value) \
            xmlrpc_doc_add_value(response, xr_methodresponse, value)

/* Create Octstr (text/xml string) out of given MethodCall. Caller
 * must free returned Octstr 
 */
#define xmlrpc_print_response(response) \
            xmlrpc_doc_print(response, xr_methodresponse, 0)

/* Send MethodResponse to given url with given headers. 
 * d_type is expected document type. 
 * Note: adds XML-RPC specified headers into given list if needed. 
 *       and if NULL when this function called, automatically generated
 *
 * Return 0 if all went fine, -1 if failure. As user reference, uses *void
 */
#define xmlrpc_send_response(response, http_ref, url, headers, ref) \
            xmlrpc_doc_send(call, xr_methodresponse, http_ref, url, headers, ref)



/*** PARAMS HANDLING ***/

/* Return -1 if XMLRPCDocument can't have params or number of params */
int xmlrpc_count_params(XMLRPCDocument *xrdoc);

/* Return i'th MethodCall/MethodResponse param 
 * or NULL if something wrong
 */
XMLRPCValue *xmlrpc_get_param(XMLRPCDocument *xrdoc, int i);