summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorGravatar snowdrop2004-02-10 09:51:10 +0000
committerGravatar snowdrop2004-02-10 09:51:10 +0000
commitd5600e2ebe6b8b146daa685c189315cd320c25a2 (patch)
tree7f55bcc4441e73b0b4ee6e36e836bdc75464afbe
parentcd9698cdee9fe0de0794289198dbdc9251951d94 (diff)
downloadcsoap-d5600e2ebe6b8b146daa685c189315cd320c25a2.tar.gz
csoap-d5600e2ebe6b8b146daa685c189315cd320c25a2.tar.bz2
added documentation
-rw-r--r--libcsoap/soap-client.h14
-rw-r--r--libcsoap/soap-env.h211
-rw-r--r--libcsoap/soap-router.h41
-rw-r--r--libcsoap/soap-server.h42
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();