From 82c14810dd1c101f20052c4ab92f33c57a255cc1 Mon Sep 17 00:00:00 2001
From: m0gg
Date: Sat, 25 Nov 2006 15:06:57 +0000
Subject: documentation enhancements and code cleanup
---
nanohttp/nanohttp-common.h | 564 ++++++++++++++++++++++++---------------------
1 file changed, 305 insertions(+), 259 deletions(-)
(limited to 'nanohttp/nanohttp-common.h')
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:
-
- [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:
-
- Example:
-
- 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
}
--
cgit v1.1-32-gdbae