diff options
Diffstat (limited to 'libcsoap/soap-env.h')
| -rw-r--r-- | libcsoap/soap-env.h | 211 |
1 files changed, 207 insertions, 4 deletions
diff --git a/libcsoap/soap-env.h b/libcsoap/soap-env.h index e89f7b4..44858b5 100644 --- a/libcsoap/soap-env.h +++ b/libcsoap/soap-env.h @@ -1,5 +1,5 @@ /****************************************************************** - * $Id: soap-env.h,v 1.2 2004/02/03 08:59:22 snowdrop Exp $ + * $Id: soap-env.h,v 1.3 2004/02/10 09:51:10 snowdrop Exp $ * * CSOAP Project: A SOAP client/server library in C * Copyright (C) 2003 Ferhat Ayaz @@ -28,43 +28,246 @@ #include <libcsoap/soap-fault.h> +/** + The SOAP envelope object. + */ typedef struct _SoapEnv { - xmlNodePtr root; - xmlNodePtr cur; + 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 + + <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> + + */ 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 + + <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> + + */ SoapEnv *soap_env_new_with_method(const char *urn, const char *method); -SoapEnv *soap_env_new_with_response(SoapEnv *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 + + <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> + + + */ +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 build and stack function */ +/* ------------------------------------------------------ */ + + +/** + 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); + + +/** + 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, ...); + + +/** + 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); + +/** + Sets the xml pointer 1 level higher. + + @param env The envelope object + @see soap_env_push_item + */ void soap_env_pop_item(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); |