/****************************************************************** * $Id: soap-env.h,v 1.13 2006/02/18 20:14:36 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 #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) @param out the result envelope out parameter like follows @returns H_OK if success
   
      

	 
	  ...
	  ...
	  ...
	  ..
	 

      
   
   
   
*/ herror_t soap_env_new_with_fault(fault_code_t faultcode, const char *faultstring, const char *faultactor, const char *detail, SoapEnv ** out); /** 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 @param out the result envelope out parameter like follows @returns H_OK if success
   
      

       
       

      
   
   
   
*/ herror_t soap_env_new_with_method(const char *urn, const char *method, SoapEnv ** out); /** 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. @param out the result envelope out paramter like follows @returns H_OK if success
   
      

       
       

      
   
   
   
*/ herror_t soap_env_new_with_response(SoapEnv * req, SoapEnv ** out); /** Creates an envelope from a given libxml2 xmlDoc pointer. @param doc the xml document pointer @param out the output envelope object @returns H_OK if success */ herror_t soap_env_new_from_doc(xmlDocPtr doc, SoapEnv ** out); /** Create an envelop object from a string. The string must be in xml format. @param buffer The string to parse into a envelope. @param out the output envelope object @returns H_OK if success */ herror_t soap_env_new_from_buffer(const char *buffer, SoapEnv ** out); /** Create an envelope from input stream @param in the input stream object to read from @param out the output envelope object @returns H_OK if success */ herror_t soap_env_new_from_stream(http_input_stream_t * in, SoapEnv ** out); /* --------------------------------------------------- */ /* XML Serializer functions and typedefs */ /* --------------------------------------------------- */ typedef void (*XmlSerializerCallback) (void * /* obj */ , const xmlChar * /* root_element_name */ , void (*OnStartElement) (const xmlChar * element_name, int attr_count, xmlChar ** keys, xmlChar ** values, void *userData), void (*OnCharacters) (const xmlChar * element_name, const xmlChar * chars, void *userData), void (*OnEndElement) (const xmlChar * 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); /** Adds attachment href node to the envelope current parent.
    
   
@param env The envelope object @param name Name of the xml node @param href href. A CID string filled by soap_ctx_add_attachment() @returns The added xmlNode pointer. @see soap_ctx_add_file tutorial */ xmlNodePtr soap_env_add_attachment(SoapEnv * env, const char *name, const char *href); /** 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); char * soap_env_find_urn(SoapEnv * env); char * soap_env_find_methodname(SoapEnv * env); #endif