Documentation enhancements

7 files changed, 184 insertions, 124 deletions

diff --git a/nanohttp/nanohttp-admin.h b/nanohttp/nanohttp-admin.h
index fcaad17..80e4c8e 100644
--- a/nanohttp/nanohttp-admin.h
+++ b/nanohttp/nanohttp-admin.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: nanohttp-admin.h,v 1.1 2006/11/19 09:40:14 m0gg Exp $
+ *  $Id: nanohttp-admin.h,v 1.2 2006/11/24 17:28:07 m0gg Exp $
  *
  * CSOAP Project:  A SOAP client/server library in C
  * Copyright (C) 2003  Ferhat Ayaz
@@ -24,7 +24,19 @@
 #ifndef __nanohttp_admin_h
 #define __nanohttp_admin_h
 
-#define NHTTPD_ARG_ENABLE_ADMIN	"-NHTTPDadmin"
+/**
+ *
+ * Commandline argument to enabled the nanoHTTP admin interface.
+ *
+ */
+#define NHTTPD_ARG_ENABLE_ADMIN		"-NHTTPDadmin"
+
+/**
+ *
+ * Context of the nanoHTTP admin interface.
+ *
+ */
+#define NHTTPD_ADMIN_CONTEXT		"/nhttp"
 
 #define NHTTPD_ADMIN_QUERY_SERVICES	"services"
 #define NHTTPD_ADMIN_QUERY_STATISTICS	"statistics"
@@ -35,15 +47,20 @@ extern "C" {
 
 /**
  *
- * Initializes the nanohttp admin HTTP interface with commandline arguments.
+ * Initializes the nanoHTTP admin interface with commandline arguments, if
+ * NHTTPD_ARG_ENABLED_ADMIN was specified in the commandline arguments. This
+ * service will be reachable via the NHTTP_ADMIN_CONTEXT of the nanohttp server.
  *
  * @param argc commandline arg count
  * @param argv commandline arg vector
  *
  * @returns H_OK on success
  *
+ * @see NHTTPD_ADMIN_CONTEXT
+ * @see NHTTPD_ARG_ENABLE_ADMIN
+ *
  */
-herror_t httpd_admin_init_args(int argc, char *argv[]);
+extern herror_t httpd_admin_init_args(int argc, char **argv);
 
 #ifdef __cplusplus
 }
diff --git a/nanohttp/nanohttp-client.c b/nanohttp/nanohttp-client.c
index f8efeaf..b475d65 100644
--- a/nanohttp/nanohttp-client.c
+++ b/nanohttp/nanohttp-client.c
@@ -1,5 +1,5 @@
 /******************************************************************
-*  $Id: nanohttp-client.c,v 1.44 2006/11/23 15:27:33 m0gg Exp $
+*  $Id: nanohttp-client.c,v 1.45 2006/11/24 17:28:07 m0gg Exp $
 *
 * CSOAP Project:  A http client/server library in C
 * Copyright (C) 2003  Ferhat Ayaz
@@ -122,14 +122,13 @@ httpc_new(void)
   if ((status = hsocket_init(res->sock)) != H_OK)
   {
     log_warn2("hsocket_init failed (%s)", herror_message(status));
+    free(res);
     return NULL;
   }
 
   res->header = NULL;
   res->version = HTTP_1_1;
   res->out = NULL;
-  res->_dime_package_nr = 0;
-  res->_dime_sent_bytes = 0;
   res->id = counter++;
 
   return res;
@@ -372,7 +371,7 @@ If success, this function will return 0.
 >0 otherwise.
 ----------------------------------------------------*/
 static herror_t
-httpc_talk_to_server(hreq_method_t method, httpc_conn_t * conn,
+_httpc_talk_to_server(hreq_method_t method, httpc_conn_t * conn,
                      const char *urlstr)
 {
 
@@ -447,43 +446,42 @@ httpc_talk_to_server(hreq_method_t method, httpc_conn_t * conn,
   return H_OK;
 }
 
-/*--------------------------------------------------
-FUNCTION: httpc_get
-DESC:
-----------------------------------------------------*/
 herror_t
-httpc_get(httpc_conn_t * conn, hresponse_t ** out, const char *urlstr)
+httpc_get(httpc_conn_t *conn, hresponse_t **out, const char *urlstr)
 {
   herror_t status;
 
-  if ((status = httpc_talk_to_server(HTTP_REQUEST_GET, conn, urlstr)) != H_OK)
+  if ((status = _httpc_talk_to_server(HTTP_REQUEST_GET, conn, urlstr)) != H_OK)
+  {
+    log_error2("_httpc_talk_to_server failed (%s)", herror_message(status));
     return status;
+  }
 
   if ((status = hresponse_new_from_socket(conn->sock, out)) != H_OK)
+  {
+    log_error2("hresponse_new_from_socket failed (%s)", herror_message(status));
     return status;
+  }
 
   return H_OK;
 }
 
-
-/*--------------------------------------------------
-FUNCTION: httpc_post_begin
-DESC: Returns H_OK if success
-----------------------------------------------------*/
 herror_t
 httpc_post_begin(httpc_conn_t * conn, const char *url)
 {
   herror_t status;
 
-  if ((status = httpc_talk_to_server(HTTP_REQUEST_POST, conn, url)) != H_OK)
+  if ((status = _httpc_talk_to_server(HTTP_REQUEST_POST, conn, url)) != H_OK)
+  {
+    log_error2("_httpc_talk_to_server failed (%s)", herror_message(status));
     return status;
+  }
 
   conn->out = http_output_stream_new(conn->sock, conn->header);
 
   return H_OK;
 }
 
-
 /*--------------------------------------------------
 FUNCTION: httpc_post_begin
 DESC: End a "POST" method and receive the response.
diff --git a/nanohttp/nanohttp-client.h b/nanohttp/nanohttp-client.h
index 7a1cc79..b74130d 100644
--- a/nanohttp/nanohttp-client.h
+++ b/nanohttp/nanohttp-client.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: nanohttp-client.h,v 1.26 2006/11/23 15:27:33 m0gg Exp $
+ *  $Id: nanohttp-client.h,v 1.27 2006/11/24 17:28:07 m0gg Exp $
  *
  * CSOAP Project:  A http client/server library in C
  * Copyright (C) 2003  Ferhat Ayaz
@@ -30,25 +30,17 @@ typedef struct httpc_conn
   hpair_t *header;
   hurl_t url;
   http_version_t version;
-  /* 
-     -1 : last dime package 0 : no dime connection >0 : dime package number */
-  int _dime_package_nr;
-  long _dime_sent_bytes;
+
   int errcode;
   char errmsg[150];
   struct http_output_stream_t *out;
   int id;                       /* uniq id */
 } httpc_conn_t;
 
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/* --------------------------------------------------------------
- HTTP CLIENT MODULE RELATED FUNCTIONS
- ---------------------------------------------------------------*/
-
 /**
  *
  * Initializes the httpc_* module. This is called from
@@ -61,7 +53,7 @@ extern "C" {
  *
  * @see httpc_destroy, herror_t, soap_client_init_args
  */
-herror_t httpc_init(int argc, char **argv);
+extern herror_t httpc_init(int argc, char **argv);
 
 /**
  *
@@ -70,14 +62,18 @@ herror_t httpc_init(int argc, char **argv);
  * @see httpc_init
  *
  */
-void httpc_destroy(void);
+extern void httpc_destroy(void);
 
 /**
  *
  * Creates a new connection.
  *
+ * @return A pointer to a httpc_conn_t structure on success, NULL on error.
+ *
+ * @see httpc_conn_t
+ *
  */
-httpc_conn_t *httpc_new(void);
+extern httpc_conn_t *httpc_new(void);
 
 /**
  *
@@ -87,16 +83,17 @@ httpc_conn_t *httpc_new(void);
  * @see httpc_close_free
  *
  */
-void httpc_free(httpc_conn_t * conn);
+extern void httpc_free(httpc_conn_t * conn);
 
 /**
  *
  * Close and release a connection
  *
- * @see httpc_close, httpc_free
+ * @see httpc_close
+ * @see httpc_free
  *
  */
-void httpc_close_free(httpc_conn_t * conn);
+extern void httpc_close_free(httpc_conn_t * conn);
 
 /**
  *
@@ -104,10 +101,11 @@ void httpc_close_free(httpc_conn_t * conn);
  *
  * @return 0 on success or failure (yeah!), 1 if a (key,value) pair was replaced.
  *
- * @see httpc_add_header, httpc_add_headers
+ * @see httpc_add_header
+ * @see httpc_add_headers
  *
  */
-int httpc_set_header(httpc_conn_t * conn, const char *key, const char *value);
+extern int httpc_set_header(httpc_conn_t * conn, const char *key, const char *value);
 
 /**
  *
@@ -115,19 +113,21 @@ int httpc_set_header(httpc_conn_t * conn, const char *key, const char *value);
  *
  * @return 0 on success, -1 on failure.
  *
- * @see httpc_set_header, httpc_add_headers
+ * @see httpc_set_header
+ * @see httpc_add_headers
  *
  */
-int httpc_add_header(httpc_conn_t *conn, const char *key, const char *value);
+extern int httpc_add_header(httpc_conn_t *conn, const char *key, const char *value);
 
 /**
  *
  * Adds a list of (key, value) pairs.
  *
- * @see httpc_set_header, httpc_add_header
+ * @see httpc_set_header
+ * @see httpc_add_header
  *
  */
-void httpc_add_headers(httpc_conn_t *conn, const hpair_t *values);
+extern void httpc_add_headers(httpc_conn_t *conn, const hpair_t *values);
 
 /**
  *
@@ -137,10 +137,11 @@ void httpc_add_headers(httpc_conn_t *conn, const hpair_t *values);
  * @param user		The username.
  * @param password	The password.
  *
- * @see httpc_set_header, HEADER_AUTHORIZATION
+ * @see httpc_set_header
+ * @see HEADER_AUTHORIZATION
  *
  */
-int httpc_set_basic_authorization(httpc_conn_t *conn, const char *user, const char *password);
+extern int httpc_set_basic_authorization(httpc_conn_t *conn, const char *user, const char *password);
 
 /**
  *
@@ -150,79 +151,83 @@ int httpc_set_basic_authorization(httpc_conn_t *conn, const char *user, const ch
  * @param user		The username.
  * @param password	The password.
  *
- * @see httpc_set_header, HEADER_PROXY_AUTHORIZATION
+ * @see httpc_set_header
+ * @see HEADER_PROXY_AUTHORIZATION
+ *
  */
-int httpc_set_basic_proxy_authorization(httpc_conn_t *conn, const char *user, const char *password);
+extern int httpc_set_basic_proxy_authorization(httpc_conn_t *conn, const char *user, const char *password);
 
 /**
-  Invoke a "GET" method request and receive the response
-*/
-herror_t httpc_get(httpc_conn_t * conn, hresponse_t ** out, const char *urlstr);
+ *
+ * Invoke a "GET" method request and receive the response
+ *
+ * @return H_OK on success
+ *
+ */
+extern herror_t httpc_get(httpc_conn_t * conn, hresponse_t ** out, const char *urlstr);
 
 /**
-  Start a "POST" method request
-  Returns: HSOCKET_OK  or error flag
-*/
-herror_t httpc_post_begin(httpc_conn_t * conn, const char *url);
+ *
+ * Start a "POST" method request
+ *
+ * @return H_OK on success or error flag
+ *
+ */
+extern herror_t httpc_post_begin(httpc_conn_t * conn, const char *url);
 
 /**
-  End a "POST" method and receive the response.
-  You MUST call httpc_post_end() before!
-*/
-herror_t httpc_post_end(httpc_conn_t * conn, hresponse_t ** out);
-
-
-/* --------------------------------------------------------------
- DIME RELATED FUNCTIONS
- ---------------------------------------------------------------*/
-
-/*
-  DIME support httpc_dime_* function set
-*/
-/*
-int httpc_dime_begin(httpc_conn_t *conn, const char *url);
-int httpc_dime_next(httpc_conn_t* conn, long content_length, 
-                    const char *content_type, const char *id,
-                    const char *dime_options, int last);
-hresponse_t* httpc_dime_end(httpc_conn_t *conn);
-*/
-
-/* --------------------------------------------------------------
- MIME RELATED FUNCTIONS
- ---------------------------------------------------------------*/
-/*
-  MIME support httpc_mime_* function set
-*/
+ *
+ * End a "POST" method and receive the response.
+ * You MUST call httpc_post_end() before!
+ *
+ * @return H_OK on success
+ *
+ * @see httpc_post_end
+ *
+ */
+extern herror_t httpc_post_end(httpc_conn_t * conn, hresponse_t ** out);
 
 /**
-  Begin MIME multipart/related POST request
-  Returns: HSOCKET_OK  or error flag
-*/
-herror_t httpc_mime_begin(httpc_conn_t * conn, const char *url,
+ *
+ * Begin MIME multipart/related POST request
+ *
+ * @return H_OK on success or error flag
+ *
+ */
+extern herror_t httpc_mime_begin(httpc_conn_t * conn, const char *url,
                           const char *related_start,
                           const char *related_start_info,
                           const char *related_type);
 
 /**
-  Send boundary and part header and continue 
-  with next part
-*/
-herror_t httpc_mime_next(httpc_conn_t * conn,
+ *
+ * Send boundary and part header and continue with next part
+ *
+ * @return H_OK on success
+ *
+ */
+extern herror_t httpc_mime_next(httpc_conn_t * conn,
                          const char *content_id,
                          const char *content_type,
                          const char *transfer_encoding);
 
 /**
-  Finish MIME request and get the response
-*/
-herror_t httpc_mime_end(httpc_conn_t * conn, hresponse_t ** out);
+ *
+ * Finish MIME request and get the response
+ *
+ * @return H_OK on success
+ *
+ */
+extern herror_t httpc_mime_end(httpc_conn_t * conn, hresponse_t ** out);
 
 /**
-  Send boundary and part header and continue 
-  with next part
-*/
-
-herror_t httpc_mime_send_file(httpc_conn_t * conn,
+ *
+ * Send boundary and part header and continue with next part
+ *
+ * @return H_OK on success
+ *
+ */
+extern herror_t httpc_mime_send_file(httpc_conn_t * conn,
                               const char *content_id,
                               const char *content_type,
                               const char *transfer_encoding,
diff --git a/nanohttp/nanohttp-common.c b/nanohttp/nanohttp-common.c
index ebba360..5e13755 100644
--- a/nanohttp/nanohttp-common.c
+++ b/nanohttp/nanohttp-common.c
@@ -1,5 +1,5 @@
 /******************************************************************
-*  $Id: nanohttp-common.c,v 1.31 2006/11/19 09:40:14 m0gg Exp $
+*  $Id: nanohttp-common.c,v 1.32 2006/11/24 17:28:07 m0gg Exp $
 *
 * CSOAP Project:  A http client/server library in C
 * Copyright (C) 2003  Ferhat Ayaz
@@ -151,7 +151,11 @@ hpairnode_new(const char *key, const char *value, hpair_t * next)
   hpair_t *pair;
 
   log_verbose3("new pair ('%s','%s')", SAVE_STR(key), SAVE_STR(value));
-  pair = (hpair_t *) malloc(sizeof(hpair_t));
+  if (!(pair = (hpair_t *) malloc(sizeof(hpair_t))))
+  {
+    log_error2("malloc failed (%s)", strerror(errno));
+    return NULL;
+  }
 
   if (key != NULL)
   {
@@ -254,6 +258,8 @@ hpairnode_dump(hpair_t * pair)
   }
   log_verbose5("(%p)['%s','%s','%p']", pair,
                SAVE_STR(pair->key), SAVE_STR(pair->value), pair->next);
+
+  return;
 }
 
 
@@ -272,6 +278,8 @@ hpairnode_dump_deep(hpair_t * pair)
   }
 
   log_verbose1("-- END dump hpairnode_t --\n");
+
+  return;
 }
 
 
@@ -285,6 +293,8 @@ hpairnode_free(hpair_t * pair)
   free(pair->value);
 
   free(pair);
+
+  return;
 }
 
 
@@ -299,6 +309,8 @@ hpairnode_free_deep(hpair_t * pair)
     hpairnode_free(pair);
     pair = tmp;
   }
+
+  return;
 }
 
 char *
diff --git a/nanohttp/nanohttp-socket.h b/nanohttp/nanohttp-socket.h
index a9e4ef6..d68da0a 100644
--- a/nanohttp/nanohttp-socket.h
+++ b/nanohttp/nanohttp-socket.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: nanohttp-socket.h,v 1.31 2006/11/23 15:27:33 m0gg Exp $
+ *  $Id: nanohttp-socket.h,v 1.32 2006/11/24 17:28:07 m0gg Exp $
  *
  * CSOAP Project:  A http client/server library in C
  * Copyright (C) 2003  Ferhat Ayaz
@@ -26,9 +26,11 @@
 
 #define	HSOCKET_FREE	-1
 
-/*
-  Socket definition
-*/
+/**
+ *
+ * Socket definition
+ *
+ */
 struct hsocket_t
 {
 #ifdef WIN32
@@ -175,7 +177,6 @@ extern herror_t hsocket_accept(struct hsocket_t *sock, struct hsocket_t *dest);
  */
 extern herror_t hsocket_nsend(struct hsocket_t *sock, const unsigned char *bytes, int size);
 
-
 /**
  *
  * Sends a string throught the socket
diff --git a/nanohttp/nanohttp-ssl.h b/nanohttp/nanohttp-ssl.h
index f796356..1b23be8 100644
--- a/nanohttp/nanohttp-ssl.h
+++ b/nanohttp/nanohttp-ssl.h
@@ -1,5 +1,5 @@
 /******************************************************************
-*  $Id: nanohttp-ssl.h,v 1.20 2006/11/23 15:27:33 m0gg Exp $
+*  $Id: nanohttp-ssl.h,v 1.21 2006/11/24 17:28:07 m0gg Exp $
 *
 * CSOAP Project:  A http client/server library in C
 * Copyright (C) 2001-2005  Rochester Institute of Technology
@@ -48,34 +48,67 @@ extern "C"
 
 /**
  *
- * Initialization and shutdown of the SSL module
+ * Initialization of the SSL module
+ *
+ * @return H_OK on success
  *
  */
 extern herror_t hssl_module_init(int argc, char **argv);
+
+/**
+ *
+ * Shutdown of the SSL module.
+ *
+ */
 extern void hssl_module_destroy(void);
 
 extern void hssl_set_certificate(char *c);
 extern void hssl_set_certpass(char *c);
 extern void hssl_set_ca(char *c);
 
+/**
+ *
+ * Enabled SSL in the nanoHTTP server. You have to call this function before
+ * calling httpd_run.
+ *
+ * @see httpd_run
+ *
+ */
 extern void hssl_enable(void);
 
+/**
+ *
+ * Check if SSL is enabled in the nanoHTTP server.
+ *
+ * @return 1 if enabled, 0 if disabled.
+ *
+ */
 extern int hssl_enabled(void);
 
 /**
  *
- * Socket initialization and shutdown
+ * SSL client socket initialization.
+ *
+ * @return H_OK on success.
  *
  */
 extern herror_t hssl_client_ssl(struct hsocket_t * sock);
-extern herror_t hssl_server_ssl(struct hsocket_t * sock);
 
-extern void hssl_cleanup(struct hsocket_t * sock);
+/**
+ *
+ * SSL server socket initialization.
+ *
+ * @return H_OK on success.
+ *
+ */
+extern herror_t hssl_server_ssl(struct hsocket_t * sock);
 
-/*
- * Callback for password checker
+/**
+ *
+ * SSL socket cleanup.
+ *
  */
-/* static int pw_cb(char* buf, int num, int rwflag, void *userdata); */
+extern void hssl_cleanup(struct hsocket_t * sock);
 
 /*
  * Quick function for verifying a portion of the cert
@@ -86,12 +119,12 @@ extern void hssl_cleanup(struct hsocket_t * sock);
 
 extern int verify_sn(X509 * cert, int who, int nid, char *str);
 
-/*
- * Called by framework for verify
+/**
+ *
+ * Called by framework for verification of client or server supplied
+ * certificate.
+ *
  */
-
-/* static int verify_cb(int prev_ok, X509_STORE_CTX* ctx); */
-
 extern void hssl_set_user_verify(int func(X509 * cert));
 
 #ifdef __cplusplus
diff --git a/nanohttp/nanohttp-stream.c b/nanohttp/nanohttp-stream.c
index 09d06b2..821c279 100755
--- a/nanohttp/nanohttp-stream.c
+++ b/nanohttp/nanohttp-stream.c
@@ -1,5 +1,5 @@
 /******************************************************************
-*  $Id: nanohttp-stream.c,v 1.15 2006/11/23 15:27:33 m0gg Exp $
+*  $Id: nanohttp-stream.c,v 1.16 2006/11/24 17:28:07 m0gg Exp $
 *
 * CSOAP Project:  A http client/server library in C
 * Copyright (C) 2003-2004  Ferhat Ayaz
@@ -85,9 +85,6 @@ http_input_stream_new(struct hsocket_t *sock, hpair_t * header)
   struct http_input_stream_t *result;
   char *content_length;
 
-  /* Paranoya check */
-  /* if (header == NULL) return NULL; */
-  /* Create object */
   if (!(result = (struct http_input_stream_t *) malloc(sizeof(struct http_input_stream_t))))
   {
     log_error2("malloc failed (%s)", strerror(errno));
@@ -160,9 +157,6 @@ http_input_stream_new_from_file(const char *filename)
   return result;
 }
 
-/**
-  Free input stream
-*/
 void
 http_input_stream_free(struct http_input_stream_t * stream)
 {