/****************************************************************** * $Id: soap-env.h,v 1.5 2004/06/08 12:54:09 snowdrop Exp $ * * CSOAP Project: A SOAP client/server library in C * Copyright (C) 2003 Ferhat Ayaz * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public * License as published by the Free Software Foundation; either * version 2 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. * * You should have received a copy of the GNU Library General Public * License along with this library; if not, write to the * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. * * Email: ayaz@jprogrammer.net ******************************************************************/ #ifndef cSOAP_ENV_H #define cSOAP_ENV_H #include #include /** The SOAP envelope object. */ typedef struct _SoapEnv { xmlNodePtr root; /** Pointer to the firts xml element (envelope) */ xmlNodePtr cur; /** Pointer to the current xml element. (stack) */ }SoapEnv; /* -------------------------------------------------------------- */ /* Envelope creation methods */ /* -------------------------------------------------------------- */ /** Creates an envelope with a fault object. @param faultcode The fault code @see fault_code_t @param faultstring A fault message @param faultactor The fault actor (This can be NULL) @param detail The detail of the error (This can be NULL) @returns A Soap envelope object like follows
   
      

	 
	  ...
	  ...
	  ...
	  ..
	 

      
   
   
   
*/ SoapEnv *soap_env_new_with_fault(fault_code_t faultcode, const char *faultstring, const char *faultactor, const char *detail); /** Creates an envelope with a method to invoke a soap service. Use this function to create a client call. @param urn The urn of the soap service to invoke @param method The method name of the soap service @returns A Soap envelope object like follows
   
      

       
       

      
   
   
   
*/ SoapEnv *soap_env_new_with_method(const char *urn, const char *method); /** Creates a soap envelope with a response. Use this function to create a response envelope object for a request. This function is only relevant for soap service implementors. @see example csoap/simpleserver.c @param req The request object. A response object will be created to this request. @returns A Soap envelope object like follows
   
      

       
       

      
   
   
   
*/ SoapEnv *soap_env_new_with_response(SoapEnv *req); /** Creates an envelope from a given libxml2 xmlDoc pointer. @param doc the xml document pointer @returns A Soap envelop object if success, NULL otherwise. */ SoapEnv *soap_env_new_from_doc(xmlDocPtr doc); /** Create an envelop object from a string. The string must be in xml format. @param buffer The string to parse into a envelope. @returns A soap envelope object if success or NULL if the string can not be parsed or the string does not represent an soap envelope in xml format. */ SoapEnv *soap_env_new_from_buffer(const char* buffer); /* --------------------------------------------------- */ /* XML Serializer functions and typedefs */ /* --------------------------------------------------- */ typedef void (*XmlSerializerCallback) (void* /*obj*/, const char * /*root_element_name*/, void (*OnStartElement)(const char* element_name, int attr_count, char **keys, char **values, void* userData), void (*OnCharacters)(const char* element_name, const char* chars, void* userData), void (*OnEndElement)(const char* element_name, void* userData), void* /* userdata*/); /* ------------------------------------------------------ */ /* XML build and stack function */ /* ------------------------------------------------------ */ /** Adds a new xml node under the current parent.
    [value]
   
@param env The envelope object @param type Type of the parameter. Something like "xsd:string" or "xsd:int" or custom types. @param name Name of the xml node @param value Text value of the xml node @returns The added xmlNode pointer. @see tutorial */ xmlNodePtr soap_env_add_item(SoapEnv* env, const char *type, const char *name, const char *value); /** Serialize and adds obj to the envelope. TODO: Document this function !
Important: */ void soap_env_add_custom(SoapEnv* env, void *obj, XmlSerializerCallback cb, const char *type, const char *name); /** Same as soap_env_add_item() with c style arguments like in printf(). "value" is the format string.
Important: The totally length of value (incl. args) must be lower the 1054. @see soap_env_add_item */ xmlNodePtr soap_env_add_itemf(SoapEnv* env, const char *type, const char *name, const char *value, ...); /** Push the current xml node in the soap envelope one level deeper. Here an example:
   soap_env_push_item(env, "my:custom", "Person");
    soap_env_add_item(env, "xsd:string", "name", "Mickey");
    soap_env_add_item(env, "xsd:string", "lastname", "Mouse");
   soap_env_pop_item(env);
   
This will create the xml like follows.
   
    Mickey
    Mouse
   
   
@returns The added xmlNode pointer. @see tutorial */ xmlNodePtr soap_env_push_item(SoapEnv *env, const char *type, const char *name); /** Sets the xml pointer 1 level higher. @param env The envelope object @see soap_env_push_item */ void soap_env_pop_item(SoapEnv* env); /** Free the envelope. @param env The envelope object */ void soap_env_free(SoapEnv *env); /* --------------------------------------------------- */ /* XML node finder functions */ /* --------------------------------------------------- */ /** Gets the xml node pointing to SOAP Body. */ xmlNodePtr soap_env_get_body(SoapEnv* env); /** Get the xml node pointing to SOAP method (call) */ xmlNodePtr soap_env_get_method(SoapEnv* env); /** Get the xml node pointing to SOAP Fault */ xmlNodePtr soap_env_get_fault(SoapEnv* env); /** Get the xml node pointing to SOAP Header */ xmlNodePtr soap_env_get_header(SoapEnv* env); int soap_env_find_urn(SoapEnv *env, char *urn); int soap_env_find_methodname(SoapEnv *env, char *methodname); #endif