summaryrefslogtreecommitdiffstats
path: root/libcsoap/soap-env.h
diff options
context:
space:
mode:
Diffstat (limited to 'libcsoap/soap-env.h')
-rw-r--r--libcsoap/soap-env.h211
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);