From d5600e2ebe6b8b146daa685c189315cd320c25a2 Mon Sep 17 00:00:00 2001 From: snowdrop Date: Tue, 10 Feb 2004 09:51:10 +0000 Subject: added documentation --- libcsoap/soap-client.h | 14 +++- libcsoap/soap-env.h | 211 ++++++++++++++++++++++++++++++++++++++++++++++++- libcsoap/soap-router.h | 41 +++++++++- libcsoap/soap-server.h | 42 +++++++++- 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 +/** + 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 +/** + 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 + + 
+   
+      
+
+	 
+	  ...
+	  ...
+	  ...
+	  ..
+	 
+
+      
+   
+   
+
+ + */ 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 + + 
+   
+      
+
+       
+       
+
+      
+   
+   
+
+ + */ 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 + + 
+   
+      
+
+       
+       
+
+      
+   
+   
+
+ + + */ +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. + + 
+    [value]
+
+ + @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. +
+ Important: 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: + + 
+   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);
+
+ + This will create the xml like follows. + + 
+   
+    Mickey
+    Mouse
+   
+
+ + @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 +/** + 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. +

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 +/** + Initializes the soap server with commandline arguments. + + + + +
ArgumentDescription
-NHTTPport [port]Port to listen (default: 10000)
+ + @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. + +

http://host:port/[context] + + + @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(); -- cgit v1.1-32-gdbae