documentation enhancements and code cleanup

1 files changed, 305 insertions, 259 deletions

diff --git a/nanohttp/nanohttp-common.h b/nanohttp/nanohttp-common.h
index cc9f8f8..dabdda6 100644
--- a/nanohttp/nanohttp-common.h
+++ b/nanohttp/nanohttp-common.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: nanohttp-common.h,v 1.33 2006/11/23 15:27:33 m0gg Exp $
+ *  $Id: nanohttp-common.h,v 1.34 2006/11/25 15:06:58 m0gg Exp $
  * 
  * CSOAP Project:  A http client/server library in C
  * Copyright (C) 2003-2004  Ferhat Ayaz
@@ -34,10 +34,12 @@
  *
  * There are a few header fields which have general applicability for both
  * request and response messages, but which do not apply to the entity being
- * transferred. These header fields apply only to the message being transmitted. 
- * (see RFC2616)
+ * transferred. These header fields apply only to the message being transmitted.
+ *
+ * @see http://www.ietf.org/rfc/rfc/2616.txt
  *
  */
+
 #define HEADER_CACHE_CONTROL		"Cache-Control"
 #define HEADER_CONNECTION		"Connection"
 #define HEADER_DATE			"Date"
@@ -57,6 +59,8 @@
  * metainformation is OPTIONAL; some might be REQUIRED by portions of this
  * specification. (see RFC2616 7.1)
  *
+ * @see http://www.ietf.org/rfc/rfc2616.txt
+ *
  */
 #define HEADER_ALLOW			"Allow"
 #define HEADER_CONTENT_ENCODING		"Content-Encoding"
@@ -71,7 +75,7 @@
 
 /**
  *
- * Command line arguments for client and server.
+ * Common commandline arguments for client and server.
  *
  */
 #define NHTTP_ARG_CERT		"-NHTTPcert"
@@ -98,71 +102,11 @@
 #define URL_DEFAULT_PORT_HTTPS 81
 #define URL_DEFAULT_PORT_FTP 120
 
-/* Success flag */
-#define H_OK 0
-
-/* File errors */
-#define FILE_ERROR_OPEN 8000
-#define FILE_ERROR_READ 8001
-
-/* Socket errors */
-#define HSOCKET_ERROR_CREATE		1001
-#define HSOCKET_ERROR_GET_HOSTNAME	1002
-#define HSOCKET_ERROR_CONNECT		1003
-#define HSOCKET_ERROR_SEND		1004
-#define HSOCKET_ERROR_RECEIVE		1005
-#define HSOCKET_ERROR_BIND		1006
-#define HSOCKET_ERROR_LISTEN		1007
-#define HSOCKET_ERROR_ACCEPT		1008
-#define HSOCKET_ERROR_NOT_INITIALIZED	1009
-#define HSOCKET_ERROR_IOCTL		1010
-#define HSOCKET_ERROR_SSLCLOSE		1011
-#define HSOCKET_ERROR_SSLCTX		1011
-
-/* URL errors */
-#define URL_ERROR_UNKNOWN_PROTOCOL	1101
-#define URL_ERROR_NO_PROTOCOL		1102
-#define URL_ERROR_NO_HOST		1103
-
-/* Stream errors */
-#define STREAM_ERROR_INVALID_TYPE	1201
-#define STREAM_ERROR_SOCKET_ERROR	1202
-#define STREAM_ERROR_NO_CHUNK_SIZE	1203
-#define STREAM_ERROR_WRONG_CHUNK_SIZE	1204
-
-
-/* MIME errors */
-#define MIME_ERROR_NO_BOUNDARY_PARAM	1301
-#define MIME_ERROR_NO_START_PARAM	1302
-#define MIME_ERROR_PARSE_ERROR		1303
-#define MIME_ERROR_NO_ROOT_PART		1304
-#define MIME_ERROR_NOT_MIME_MESSAGE	1305
-
-
-/* General errors */
-#define GENERAL_INVALID_PARAM		1400
-#define GENERAL_HEADER_PARSE_ERROR	1401
-
-/* Thread errors */
-#define THREAD_BEGIN_ERROR		1500
-
-/* XML Errors */
-#define XML_ERROR_EMPTY_DOCUMENT	1600
-#define XML_ERROR_PARSE			1601
-
-/* SSL Errors */
-#define HSSL_ERROR_CA_LIST		1710
-#define HSSL_ERROR_CONTEXT		1720
-#define HSSL_ERROR_CERTIFICATE		1730
-#define HSSL_ERROR_PEM			1740
-#define HSSL_ERROR_CLIENT		1750
-#define HSSL_ERROR_SERVER		1760
-#define HSSL_ERROR_CONNECT		1770
-
 /**
-  Indicates the version of the 
-  used HTTP protocol.
-*/
+ *
+ * Indicates the version of the used HTTP protocol.
+ *
+ */
 typedef enum _http_version
 {
   HTTP_1_0,
@@ -171,37 +115,124 @@ typedef enum _http_version
 
 
 /**
-  Indicates the used method
-*/
+ *
+ * The set of common methods for HTTP/1.1 is defined below. Although this set
+ * can be expanded, additional methods cannot be assumed to share the same
+ * semantics for separately extended clients and servers.
+ *
+ * The Host request-header field MUST accompany all HTTP/1.1 requests.
+ *
+ * @see HTTP_HEADER_HOST
+ *
+ */
 typedef enum _hreq_method
 {
-  HTTP_REQUEST_POST,
+  /**
+   *
+   * The POST method is used to request that the origin server accept the entity
+   * enclosed in the request as a new subordinate of the resource identified by
+   * the Request-URI in the Request-Line. POST is designed to allow a uniform
+   * method to cover the following functions:
+   * - Annotation of existing resources;
+   * - Posting a message to a bulletin board, newsgroup, mailing list, or
+   *   similar group of articles;
+   * - Providing a block of data, such as the result of submitting a form, to a
+   *   data-handling process;
+   * - Extending a database through an append operation.
+   *
+   */
+ HTTP_REQUEST_POST,
+  /**
+   *
+   * The GET method means retrieve whatever information (in the form of an entity)
+   * is identified by the Request-URI. If the Request-URI refers to a
+   * data-producing process, it is the produced data which shall be returned as
+   * the entity in the response and not the source text of the process, unless
+   * that text happens to be the output of the process.
+   *
+   */
   HTTP_REQUEST_GET,
+  /**
+   *
+   * The OPTIONS method represents a request for information about the
+   * communication options available on the request/response chain identified by
+   * the Request-URI. This method allows the client to determine the options
+   * and/or requirements associated with a resource, or the capabilities of a
+   * server, without implying a resource action or initiating a resource
+   * retrieval.
+   *
+   */
   HTTP_REQUEST_OPTIONS,
+  /**
+   *
+   * The HEAD method is identical to GET except that the server MUST NOT return
+   * a message-body in the response. The metainformation contained in the HTTP
+   * headers in response to a HEAD request SHOULD be identical to the information
+   * sent in response to a GET request. This method can be used for obtaining
+   * metainformation about the entity implied by the request without transferring
+   * the entity-body itself. This method is often used for testing hypertext
+   * links for validity, accessibility, and recent modification.
+   *
+   */
   HTTP_REQUEST_HEAD,
+  /**
+   *
+   * The PUT method requests that the enclosed entity be stored under the
+   * supplied Request-URI. If the Request-URI refers to an already existing
+   * resource, the enclosed entity SHOULD be considered as a modified version of
+   * the one residing on the origin server. If the Request-URI does not point to
+   * an existing resource, and that URI is capable of being defined as a new
+   * resource by the requesting user agent, the origin server can create the
+   * resource with that URI. If a new resource is created, the origin server MUST
+   * inform the user agent via the 201 (Created) response. If an existing
+   * resource is modified, either the 200 (OK) or 204 (No Content) response codes
+   * SHOULD be sent to indicate successful completion of the request. If the
+   * resource could not be created or modified with the Request-URI, an
+   * appropriate error response SHOULD be given that reflects the nature of the
+   * problem. The recipient of the entity MUST NOT ignore any Content-* (e.g.
+   * Content-Range) headers that it does not understand or implement and MUST
+   * return a 501 (Not Implemented) response in such cases.
+   *
+   */
   HTTP_REQUEST_PUT,
+  /**
+   *
+   * The DELETE method requests that the origin server delete the resource
+   * identified by the Request-URI. This method MAY be overridden by human
+   * intervention (or other means) on the origin server. The client cannot be
+   * guaranteed that the operation has been carried out, even if the status code
+   * returned from the origin server indicates that the action has been completed
+   * successfully. However, the server SHOULD NOT indicate success unless, at the
+   * time the response is given, it intends to delete the resource or move it to
+   * an inaccessible location.
+   *
+   */
   HTTP_REQUEST_DELETE,
+  /**
+   *
+   * The TRACE method is used to invoke a remote, application-layer loop-back of
+   * the request message. The final recipient of the request SHOULD reflect the
+   * message received back to the client as the entity-body of a 200 (OK)
+   * response. The final recipient is either the origin server or the first proxy
+   * or gateway to receive a Max-Forwards value of zero (0) in the request (see
+   * section 14.31). A TRACE request MUST NOT include an entity.
+   *
+   */
   HTTP_REQUEST_TRACE,
+  /**
+   *
+   * This specification reserves the method name CONNECT for use with a proxy
+   * that can dynamically switch to being a tunnel (e.g. SSL tunneling [44]).
+   *
+   */
   HTTP_REQUEST_CONNECT,
   HTTP_REQUEST_UNKOWN
 } hreq_method_t;
 
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-typedef void *herror_t;
-
-herror_t herror_new(const char *func, int errcode, const char *format, ...);
-int herror_code(herror_t err);
-char *herror_func(herror_t err);
-char *herror_message(herror_t err);
-void herror_release(herror_t err);
-
-/*
-  hpairnode_t represents a pair (key, value) pair.
-  This is also a linked list.
+/**
+ *
+ * hpairnode_t represents a pair (key, value) pair. This is also a linked list.
+ *
  */
 typedef struct hpair hpair_t;
 struct hpair
@@ -211,122 +242,134 @@ struct hpair
   hpair_t *next;
 };
 
+#ifdef __cplusplus
+extern "C" {
+#endif
 
 /**
-  Creates a new pair with the given parameters. Both strings
-  key and value will be cloned while creating the pair. 
-
-  @param key the key of the (key,value) pair
-  @param value the value of the (key,value) pair
-  @param next next pair node in the linked list
-
-  @returns A newly crated hpair_t object. Use hpair_free() 
-    or hpair_free_deep() to free the pair.
-*/
-hpair_t *hpairnode_new(const char *key, const char *value, hpair_t * next);
-
+ *
+ * Creates a new pair with the given parameters. Both strings key and value will
+ * be cloned while creating the pair. 
+ *
+ * @param key the key of the (key,value) pair
+ * @param value the value of the (key,value) pair
+ * @param next next pair node in the linked list
+ *
+ * @returns A newly crated hpair_t object. Use hpair_free() or hpair_free_deep()
+ *          to free the pair.
+ *
+ */
+extern hpair_t *hpairnode_new(const char *key, const char *value, hpair_t * next);
 
 /**
-  Creates a new pair from a given string. This function 
-  will split 'str' with the found first delimiter 'delim'.
-  The 'value' field  of the newly created pair will have 
-  the value "", if no delimiter was found/
-  Whitespaces (' ') will be removed from the beginnig of 
-  the parsed value.
-
-  @param str A string to parse
-  @param delim a delimiter to use while splitting into key,value 
-  @param next next pair node in the linked list
-
-  @returns A newly crated hpair_t object. Use hpair_free() 
-    or hpair_free_deep() to free the pair.
-*/
-hpair_t *hpairnode_parse(const char *str, const char *delim, hpair_t * next);
-
+ *
+ * Creates a new pair from a given string. This function will split 'str' with
+ * the found first delimiter 'delim'. The 'value' field  of the newly created
+ * pair will have the value "", if no delimiter was found/ Whitespaces (' ') will
+ * be removed from the beginnig of the parsed value.
+ *
+ * @param str A string to parse
+ * @param delim a delimiter to use while splitting into key,value
+ * @param next next pair node in the linked list
+ *
+ * @returns A newly crated hpair_t object. Use hpair_free() or hpair_free_deep()
+ *          to free the pair.
+ *
+ */
+extern hpair_t *hpairnode_parse(const char *str, const char *delim, hpair_t * next);
 
 /**
-  Frees a given pair.
-
-  @param pair the pair to free
-*/
-void hpairnode_free(hpair_t * pair);
-
+ *
+ * Frees a given pair.
+ *
+ * @param pair the pair to free
+ *
+ */
+extern void hpairnode_free(hpair_t * pair);
 
 /**
-  Makes a deep free operation. All pairnodes,
-  beginning with the given pari, in the 
-  linked list will be destroyed. 
-
-  @param pair the pair to start to free the linked list
-*/
-void hpairnode_free_deep(hpair_t * pair);
-
+ *
+ * Makes a deep free operation. All pairnodes, beginning with the given pari, in
+ * the linked list will be destroyed. 
+ *
+ * @param pair the pair to start to free the linked list
+ *
+ */
+extern void hpairnode_free_deep(hpair_t * pair);
 
 /**
-  Returns the (key,value) pair, which key is the 
-  given 'key'.
-
-  @param pair the first pair to start to search from.
-  @param key key to find the in the pair.
-  @returns if a value will be found, this function will 
-    return the value (do not free this string) or NULL
-    if no pair was found with the key 'key'.
-*/
-char *hpairnode_get(hpair_t * pair, const char *key);
-
+ *
+ * Returns the (key,value) pair, which key is the given 'key'.
+ *
+ * @param pair the first pair to start to search from.
+ * @param key key to find the in the pair.
+ * @returns if a value will be found, this function will 
+ *
+ * @return the value (do not free this string) or NULL if no pair was found with
+ *         the key 'key'.
+ *
+ */
+extern char *hpairnode_get(hpair_t * pair, const char *key);
 
 /**
-  Returns the (key,value) pair, which key is the 
-  given 'key'. The case will be ignored while 
-  comparing the key strings.
-
-  @param pair the first pair to start to search from.
-  @param key key to find the in the pair.
-  @returns if a value will be found, this function will 
-    return the value (do not free this string) or NULL
-    if no pair was found with the key 'key'.
-*/
-char *hpairnode_get_ignore_case(hpair_t * pair, const char *key);
-
+ *
+ * Returns the (key,value) pair, which key is the given 'key'. The case will be
+ * ignored while comparing the key strings.
+ *
+ * @param pair the first pair to start to search from.
+ * @param key key to find the in the pair.
+ * @returns if a value will be found, this function will 
+ *
+ * @return the value (do not free this string) or NULL if no pair was found with
+ *         the key 'key'.
+ *
+ */
+extern char *hpairnode_get_ignore_case(hpair_t * pair, const char *key);
 
 /**
-  This function will create a new pair and fills the 
-  (key,value) fields of a given pair. Note that the 'next'
-  field will not be copied.
-
-  @param src the source pair object to copy.
-
-  @returns a newly created pair with the same (key,value) 
-   pairs as in 'src'. This fields will be cloned. The'next'
-   field will be set to NULL.
-
-  @see hpairnode_copy_deep
-*/
-hpair_t *hpairnode_copy(const hpair_t * src);
-
+ *
+ * This function will create a new pair and fills the (key,value) fields of a
+ * given pair. Note that the 'next' field will not be copied.
+ *
+ * @param src the source pair object to copy.
+ *
+ * @returns a newly created pair with the same (key,value) pairs as in 'src'.
+ *          This fields will be cloned. The'next' field will be set to NULL.
+ *
+ * @see hpairnode_copy_deep
+ *
+ */
+extern hpair_t *hpairnode_copy(const hpair_t * src);
 
 /**
-  Clones the hole linked list. 
-
-  @param src the source pair object to copy from
-
-  @returns the first object in the linked list. 
-
-  @see hpairnode_copy
-*/
-hpair_t *hpairnode_copy_deep(const hpair_t * src);
-
-/* Debug functions */
-void hpairnode_dump_deep(hpair_t * pair);
-void hpairnode_dump(hpair_t * pair);
+ *
+ * Clones the hole linked list. 
+ *
+ * @param src the source pair object to copy from
+ *
+ * @return the first object in the linked list. 
+ *
+ * @see hpairnode_copy
+ *
+ */
+extern hpair_t *hpairnode_copy_deep(const hpair_t * src);
 
 /**
-  The protocol types in enumeration 
-  format. Used in some other nanohttp objects
-  like hurl_t.
+ *
+ * Debug functions
+ *
+ */
+extern void hpairnode_dump_deep(hpair_t * pair);
+extern void hpairnode_dump(hpair_t * pair);
 
-  @see hurl_t
-*/
+/**
+ *
+ * The protocol types in enumeration format. Used in some other nanohttp objects
+ * like hurl_t.
+ *
+ * @see hurl_t
+ *
+ */
 typedef enum _hprotocol
 {
   PROTOCOL_HTTP,
@@ -337,12 +380,14 @@ typedef enum _hprotocol
 
 
 /**
-  The URL object. A representation 
-  of an URL like:<P>
-   
-  [protocol]://[host]:[port]/[context]
-
-*/
+ *
+ * The URL object. A representation of an URL like:
+ *
+ * [protocol]://[host]:[port]/[context]
+ *
+ * @see http://www.ietf.org/rfc/rfc2396.txt
+ *
+ */
 typedef struct _hurl
 {
   /**
@@ -367,62 +412,64 @@ typedef struct _hurl
   char context[URL_MAX_CONTEXT_SIZE];
 } hurl_t;
 
+/**
+ *
+ * Parses the given 'urlstr' and fills the given hurl_t object.
+ *
+ * @param obj the destination URL object to fill
+ * @param url the URL in string format
+ *
+ * @returns H_OK on success or one of the following otherwise
+ *          - URL_ERROR_UNKNOWN_PROTOCOL 
+ *          - URL_ERROR_NO_PROTOCOL 
+ *          - URL_ERROR_NO_HOST 
+ *
+ */
+extern herror_t hurl_parse(hurl_t * obj, const char *url);
 
 /**
-  Parses the given 'urlstr' and fills the given hurl_t object.
-
-  @param obj the destination URL object to fill
-  @param url the URL in string format
-
-  @returns H_OK on success or one of the following otherwise
-
-    URL_ERROR_UNKNOWN_PROTOCOL 
-    URL_ERROR_NO_PROTOCOL 
-    URL_ERROR_NO_HOST 
-*/
-herror_t hurl_parse(hurl_t * obj, const char *url);
-
-/*
-  Object representation of the content-type field 
-  in a HTTP header: 
-  <P>
-  Example:<P>
-  
-  text/xml; key="value" key2="value2' ...
-*/
+ *
+ * Object representation of the content-type field in a HTTP header: 
+ *
+ * Example:
+ *
+ * text/xml; key="value" key2="value2' ...
+ *
+ */
 typedef struct _content_type
 {
   char type[128];
   hpair_t *params;
 } content_type_t;
 
-
 /**
-  Parses the given string and creates a new ccontent_type_t
-  object. 
-
-  @param content_type_str the string representation of the
-  content-type field in a HTTP header.
-
-  @returns A newly created content_type_t object. Free this
-    object with content_type_free();
-
-  @see content_type_free
-*/
-content_type_t *content_type_new(const char *content_type_str);
+ *
+ * Parses the given string and creates a new ccontent_type_t object. 
+ *
+ * @param content_type_str the string representation of the content-type field in
+ *        a HTTP header.
+ *
+ * @returns A newly created content_type_t object. Free this object with
+ *          content_type_free();
+ *
+ * @see content_type_free
+ */
+extern content_type_t *content_type_new(const char *content_type_str);
 
 
 /**
-  Frees the given content_type_t object
-*/
-void content_type_free(content_type_t * ct);
-
-
+ *
+ * Frees the given content_type_t object
+ *
+ */
+extern void content_type_free(content_type_t * ct);
 
-/*
-  part. Attachment
-*/
-typedef struct _part
+/**
+ *
+ * part. Attachment
+ *
+ */
+struct part_t
 {
   char id[250];
   char location[250];
@@ -430,39 +477,38 @@ typedef struct _part
   char content_type[128];
   char transfer_encoding[128];
   char filename[250];
-  struct _part *next;
+  struct part_t *next;
   int deleteOnExit;             /* default is 0 */
-} part_t;
-
-
-part_t *part_new(const char *id, const char *filename,
-                 const char *content_type, const char *transfer_encoding,
-                 part_t * next);
-void part_free(part_t * part);
-
+};
 
+extern struct part_t *part_new(const char *id, const char *filename, const char *content_type, const char *transfer_encoding, struct part_t * next);
 
+extern void part_free(struct part_t * part);
 
-/*
-  Attachments
-*/
-typedef struct _attachments
+/**
+ *
+ * Attachments
+ *
+ */
+struct attachments_t
 {
-  part_t *parts;
-  part_t *last;
-  part_t *root_part;
-} attachments_t;
-
-attachments_t *attachments_new(void);       /* should be used internally */
+  struct part_t *parts;
+  struct part_t *last;
+  struct part_t *root_part;
+};
 
-/*
-  Free a attachment. Create attachments with MIME
-  and DIME (DIME is not supported yet).
+extern struct attachments_t *attachments_new(void);       /* should be used internally */
 
-  @see mime_get_attachments
-*/
-void attachments_free(attachments_t * message);
-void attachments_add_part(attachments_t * attachments, part_t * part);
+/**
+ *
+ * Free a attachment. Create attachments with MIME and DIME (DIME is not
+ * supported yet).
+ *
+ * @see mime_get_attachments
+ *
+ */
+extern void attachments_free(struct attachments_t * message);
+extern void attachments_add_part(struct attachments_t * attachments, struct part_t * part);
 
 #ifdef __cplusplus
 }