diff options
Diffstat (limited to 'libcsoap/soap-env.h')
| -rw-r--r-- | libcsoap/soap-env.h | 470 |
1 files changed, 238 insertions, 232 deletions
diff --git a/libcsoap/soap-env.h b/libcsoap/soap-env.h index 2da9528..b73bb38 100644 --- a/libcsoap/soap-env.h +++ b/libcsoap/soap-env.h @@ -1,5 +1,5 @@ /****************************************************************** - * $Id: soap-env.h,v 1.16 2006/11/21 20:59:02 m0gg Exp $ + * $Id: soap-env.h,v 1.17 2006/11/23 15:27:33 m0gg Exp $ * * CSOAP Project: A SOAP client/server library in C * Copyright (C) 2003 Ferhat Ayaz @@ -21,300 +21,306 @@ * * Email: ayaz@jprogrammer.net ******************************************************************/ -#ifndef cSOAP_ENV_H -#define cSOAP_ENV_H +#ifndef __csoap_env_h +#define __csoap_env_h /** - The SOAP envelope object. + * + * The SOAP envelope namespace + * */ -typedef struct _SoapEnv +static const char * const soap_env_ns = "http://schemas.xmlsoap.org/soap/envelope/"; + +/** + * + * The SOAP envelope object. + * + */ +struct SoapEnv { xmlNodePtr root; /** Pointer to the firts xml element (envelope) */ xmlNodePtr header; xmlNodePtr body; xmlNodePtr cur; /** Pointer to the current xml element. (stack) */ -} SoapEnv; +}; + +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); #ifdef __cplusplus extern "C" { #endif - -/* -------------------------------------------------------------- */ -/* 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 - - <pre> - <SOAP-ENV:Envelope xmlns:SOAP-ENV="..." SOAP-ENV:encoding="..." - xmlns:xsi="..." - xmlns:xsd="..."> - <SOAP-ENV:Body> - - <Fault> - <faultcode>...</faultcode> - <faultstring>...</faultstring> - <faultactor>...</faultactor> - <faultdetail>..</faultdetail> - </Fault> - - </SOAP-ENV:Body> - </SOAP-ENV:Envelope> - - </pre> - + * + * 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 + * + * <pre> + * <SOAP-ENV:Envelope xmlns:SOAP-ENV="..." SOAP-ENV:encoding="..." + * xmlns:xsi="..." + * xmlns:xsd="..."> + * <SOAP-ENV:Body> + * + * <Fault> + * <faultcode>...</faultcode> + * <faultstring>...</faultstring> + * <faultactor>...</faultactor> + * <faultdetail>..</faultdetail> + * </Fault> + * + * </SOAP-ENV:Body> + * </SOAP-ENV:Envelope> + * </pre> + * + * @returns H_OK if success + * + * @see soap_fault_new + * */ -herror_t -soap_env_new_with_fault(int faultcode, - const char *faultstring, - const char *faultactor, - const char *detail, SoapEnv ** out); +extern herror_t soap_env_new_with_fault(int faultCode, const char *faultString, const char *faultActor, const char *detail, struct 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 - - <pre> - <SOAP-ENV:Envelope xmlns:SOAP-ENV="..." SOAP-ENV:encoding="..." - xmlns:xsi="..." - xmlns:xsd="..."> - <SOAP-ENV:Body> - - <m:[method] xmlns:m="[urn]"> - </m:[method]> - - </SOAP-ENV:Body> - </SOAP-ENV:Envelope> - - </pre> - + * + * 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 + * + * <pre> + * <SOAP-ENV:Envelope xmlns:SOAP-ENV="..." SOAP-ENV:encoding="..." + * xmlns:xsi="..." + * xmlns:xsd="..."> + * <SOAP-ENV:Body> + * + * <m:[method] xmlns:m="[urn]"> + * </m:[method]> + * + * </SOAP-ENV:Body> + * </SOAP-ENV:Envelope> + * + * </pre> + * */ -herror_t -soap_env_new_with_method(const char *urn, const char *method, SoapEnv ** out); - +extern herror_t soap_env_new_with_method(const char *urn, const char *method, struct 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 - - <pre> - <SOAP-ENV:Envelope xmlns:SOAP-ENV="..." SOAP-ENV:encoding="..." - xmlns:xsi="..." - xmlns:xsd="..."> - <SOAP-ENV:Body> - - <m:[req-method]Response xmlns:m="[req-urn]"> - </m:[req-method]> - - </SOAP-ENV:Body> - </SOAP-ENV:Envelope> - - </pre> - - + * + * 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 + * + * <pre> + * <SOAP-ENV:Envelope xmlns:SOAP-ENV="..." SOAP-ENV:encoding="..." + * xmlns:xsi="..." + * xmlns:xsd="..."> + * <SOAP-ENV:Body> + * + * <m:[req-method]Response xmlns:m="[req-urn]"> + * </m:[req-method]> + * + * </SOAP-ENV:Body> + * </SOAP-ENV:Envelope> + * + * </pre> + * + * */ -herror_t soap_env_new_with_response(SoapEnv * req, SoapEnv ** out); - +extern herror_t soap_env_new_with_response(struct SoapEnv * req, struct 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 - + * + * Creates an envelope from a given libxml2 xmlDocPtr. + * + * @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); - +extern herror_t soap_env_new_from_doc(xmlDocPtr doc, struct 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 + * + * 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); - - -/* --------------------------------------------------- */ -/* 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 */ -/* ------------------------------------------------------ */ - +extern herror_t soap_env_new_from_buffer(const char *buffer, struct SoapEnv ** out); /** - Adds a new xml node under the current parent. - - <pre> - <m:[name] type=[type]>[value]</m:[name]> - </pre> - - @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 + * + * Adds a new xml node under the current parent. + * + * <pre> + * <m:[name] type=[type]>[value]</m:[name]> + * </pre> + * + * @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); - +extern xmlNodePtr soap_env_add_item(struct SoapEnv * env, const char *type, const char *name, const char *value); /** - Adds attachment href node to the envelope current parent. - - <pre> - <m:[name] href=[href]/> - </pre> - - @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 + * + * Adds attachment href node to the envelope current parent. + * + * <pre> + * <m:[name] href=[href]/> + * </pre> + * + * @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); - +extern xmlNodePtr +soap_env_add_attachment(struct SoapEnv * env, const char *name, const char *href); /** - Serialize and adds obj to the envelope. - TODO: Document this function ! - <br> - <b>Important: </b> - + * + * Serialize and adds obj to the envelope. + * TODO: Document this function ! + * <br> + * <b>Important: </b> + * */ -void -soap_env_add_custom(SoapEnv * env, void *obj, XmlSerializerCallback cb, - const char *type, const char *name); +extern void soap_env_add_custom(struct 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. - <br> - <b>Important: </b> The totally length of value (incl. args) - must be lower the 1054. - - @see soap_env_add_item + * + * Same as soap_env_add_item() with c style arguments + * like in printf(). "value" is the format string. + * <br> + * <b>Important: </b> 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, ...); - +extern xmlNodePtr +soap_env_add_itemf(struct 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: - - <pre> - 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); - </pre> - - This will create the xml like follows. - - <pre> - <Person type="my:custom"> - <name>Mickey</name> - <lastname>Mouse</lastname> - </Person> - </pre> - - @returns The added xmlNode pointer. - - @see tutorial + * + * Push the current xml node in the soap envelope one level + * deeper. Here an example: + * + * <pre> + * 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); + * </pre> + * + * This will create the xml like follows. + * + * <pre> + * <Person type="my:custom"> + * <name>Mickey</name> + * <lastname>Mouse</lastname> + * </Person> + * </pre> + * + * @returns The added xmlNode pointer. + * + * @see tutorial + * */ -xmlNodePtr soap_env_push_item(SoapEnv * env, const char *type, const char *name); +extern xmlNodePtr soap_env_push_item(struct 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 + * + * Sets the xml pointer 1 level higher. + * + * @param env The envelope object + * + * @see soap_env_push_item */ -void soap_env_pop_item(SoapEnv * env); +extern void soap_env_pop_item(struct SoapEnv * env); /** - Free the envelope. - - @param env The envelope object + * + * Free the envelope. + * + * @param env The envelope object + * */ -void soap_env_free(SoapEnv * env); - - -/* --------------------------------------------------- */ -/* XML node finder functions */ -/* --------------------------------------------------- */ - +extern void soap_env_free(struct SoapEnv * env); /** - Gets the xml node pointing to SOAP Body. + * + * Gets the xml node pointing to SOAP Body. + * */ -xmlNodePtr soap_env_get_body(SoapEnv * env); +extern xmlNodePtr soap_env_get_body(struct SoapEnv * env); /** - Get the xml node pointing to SOAP method (call) + * + * Get the xml node pointing to SOAP method (call) + * */ -xmlNodePtr soap_env_get_method(SoapEnv * env); - +extern xmlNodePtr soap_env_get_method(struct SoapEnv * env); /** - Get the xml node pointing to SOAP Fault + * + * Get the xml node pointing to SOAP Fault + * */ -xmlNodePtr soap_env_get_fault(SoapEnv * env); - +extern xmlNodePtr soap_env_get_fault(struct SoapEnv * env); /** - Get the xml node pointing to SOAP Header + * + * Get the xml node pointing to SOAP Header + * */ -xmlNodePtr soap_env_get_header(SoapEnv * env); +extern xmlNodePtr soap_env_get_header(struct SoapEnv * env); +/** + * + * Get the URN of the message. + * + */ +extern const char *soap_env_find_urn(struct SoapEnv * env); -char * soap_env_find_urn(SoapEnv * env); -char * soap_env_find_methodname(SoapEnv * env); +/** + * + * Get the method of the message. + * + */ +extern const char *soap_env_find_methodname(struct SoapEnv * env); #ifdef __cplusplus } |