added documentation

4 files changed, 301 insertions, 7 deletions

diff --git a/libcsoap/soap-client.h b/libcsoap/soap-client.h
index 690808c..f3529d4 100644
--- a/libcsoap/soap-client.h
+++ b/libcsoap/soap-client.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: soap-client.h,v 1.1 2004/02/03 08:10:05 snowdrop Exp $
+ *  $Id: soap-client.h,v 1.2 2004/02/10 09:51:10 snowdrop Exp $
  *
  * CSOAP Project:  A SOAP client/server library in C
  * Copyright (C) 2003  Ferhat Ayaz
@@ -27,6 +27,18 @@
 #include <libcsoap/soap-env.h>
 
 
+/**
+   Establish connection to the soap server and send 
+   the given envelope. 
+
+   @param env envelope to send
+   @param url url to the soap server
+   @soap_action value for "SoapAction:" in the 
+    HTTP request header.
+
+    @returns the result envelope. In case of failure,
+     this function return an envelope with a fault object.
+ */
 SoapEnv* soap_client_invoke(SoapEnv *env, 
 			    const char *url,
 			    const char *soap_action);
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);
 
diff --git a/libcsoap/soap-router.h b/libcsoap/soap-router.h
index 34de257..b0a2536 100644
--- a/libcsoap/soap-router.h
+++ b/libcsoap/soap-router.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: soap-router.h,v 1.1 2004/02/03 08:10:05 snowdrop Exp $
+ *  $Id: soap-router.h,v 1.2 2004/02/10 09:51:10 snowdrop Exp $
  *
  * CSOAP Project:  A SOAP client/server library in C
  * Copyright (C) 2003  Ferhat Ayaz
@@ -27,6 +27,10 @@
 
 #include <libcsoap/soap-service.h>
 
+/**
+   The router object. A router can store a set of 
+   services. A service is a C function. 
+ */
 typedef struct _SoapRouter
 {
   SoapServiceNode *service_head;
@@ -34,18 +38,53 @@ typedef struct _SoapRouter
 }SoapRouter;
 
 
+/**
+   Creates a new router object. Create a router if
+   you are implementing a soap server. Then register
+   the services to this router. 
+   <P>A router points also to http url context.
+
+   @returns Soap router 
+   @see soap_router_free
+ */
 SoapRouter *soap_router_new();
 
+
+/**
+   Registers a SOAP service (in this case a C function)
+   to the router.
+   
+   @param router The router object
+   @param func Function to register as a soap service
+   @param method Method name to call the function from 
+    the client side.
+   @param urn The urn for this service
+ */
 void soap_router_register_service(SoapRouter *router,
 				  SoapServiceFunc func,
 				  const char* method,
 				  const char* urn);
 
 
+/**
+   Searches for a registered soap service.
+
+   @param router The router object
+   @param urn URN of the service
+   @param method The name under which the service was registered.
+
+   @return The service if found, NULL otherwise.
+ */
 SoapService* soap_router_find_service(SoapRouter *router, 
 				      const char* urn,
 				      const char* method);
 
+
+/**
+   Frees the router object.
+
+   @param router The router object to free
+ */
 void soap_router_free(SoapRouter *router);
 
 #endif
diff --git a/libcsoap/soap-server.h b/libcsoap/soap-server.h
index c3f29f3..8f0391b 100644
--- a/libcsoap/soap-server.h
+++ b/libcsoap/soap-server.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: soap-server.h,v 1.1 2004/02/03 08:10:05 snowdrop Exp $
+ *  $Id: soap-server.h,v 1.2 2004/02/10 09:51:10 snowdrop Exp $
  *
  * CSOAP Project:  A SOAP client/server library in C
  * Copyright (C) 2003  Ferhat Ayaz
@@ -28,9 +28,49 @@
 #include <libcsoap/soap-router.h>
 
 
+/**
+   Initializes the soap server with commandline arguments.
+
+   <TABLE border=1>
+   <TR><TH>Argument</TH><TH>Description</TH></TR>
+   <TR><TD>-NHTTPport [port]</TD><TD>Port to listen (default: 10000)</TD></TR>
+   </TABLE>
+
+   @param argc commandline arg count
+   @param argv commandline arg vector
+
+   @returns 1 if success, 0 otherwise
+ */
 int soap_server_init_args(int argc, char *argv[]);
+
+
+/**
+   Register a router to the soap server. 
+
+   <P>http://<I>host</I>:<I>port</I>/<B>[context]</B>
+
+
+   @param router The router to register
+   @param context the url context 
+   @returns 1 if success, 0 otherwise
+   
+   @see soap_router_new
+   @see soap_router_register_service
+
+ */
 int soap_server_register_router(SoapRouter *router, const char* context);
+
+
+/**
+   Enters the server loop and starts to listen to 
+   http requests.
+ */
 int soap_server_run();
+
+
+/**
+   Frees the soap server.
+ */
 void soap_server_destroy();