[magi]

7 files changed, 95 insertions, 84 deletions

diff --git a/include/magi.h b/include/magi.h
index 60f0cc9..c14f8b6 100644
--- a/include/magi.h
+++ b/include/magi.h
@@ -1,5 +1,5 @@
-#ifndef MAGI_INCLUDED
-#define MAGI_INCLUDED
+#ifndef MAGI_INCLUDED_EVERYTHING
+#define MAGI_INCLUDED_EVERYTHING
 /** @file magi.h
  * @brief All headers are included here.
  *
@@ -14,10 +14,4 @@
 #include "magi/request.h"
 #include "magi/response.h"
 #include "magi/urlenc.h"
-
-
-/** @mainpage Magi Gateway Interfaces Library
- */
-
-
 #endif
diff --git a/include/magi/cgi.h b/include/magi/cgi.h
index c365f2f..4d182b7 100644
--- a/include/magi/cgi.h
+++ b/include/magi/cgi.h
@@ -11,24 +11,25 @@
 
 
 /** @brief Analyses non-post part of request from environment.
- * @return Returns null only in case of error. */
+ * @return 1 if ok, 0 if error. */
 int magi_request_cgi_head(magi_request *request);
 
-/** @brief Complete request with post data from standard input.
- * @return Returns null only in case of error. */
+/** @brief Complete request with post body from standard input.
+ * @return 1 if ok, 0 if error. */
 int magi_request_cgi_body(magi_request *request);
 
-/** @brief Shortcut for analysing both head and body of request. */
+/** @brief Shortcut for analysing both head and body of request.
+ * @return 1 if ok, 0 if error. */
 int magi_request_cgi(magi_request *request);
 
 
 /** @brief Sends response to standard output and destroys it.
- * @return Returns null only in case of error. */
+ * @return 1 if ok, 0 if error. */
 int magi_response_cgi(magi_response *response);
 
 
 /** @brief Sends a standard response of Bad Request error.
- * @return Returns null only in case of error. */
+ * @return 1 if ok, 0 if error. */
 int magi_error_cgi(magi_error error);
 
 
diff --git a/include/magi/cookie.h b/include/magi/cookie.h
index 485b6d9..e6a5c4f 100644
--- a/include/magi/cookie.h
+++ b/include/magi/cookie.h
@@ -1,37 +1,48 @@
 #ifndef MAGI_INCLUDED_COOKIE
 #define MAGI_INCLUDED_COOKIE
 /** @file cookie.h
- * @brief blah...
+ * @brief HTTP Cookie.
  *
- * blah-blah...
+ * Described in RFC 6265.
  */
 
 
+/** @brief HTTP Cookie. */
 typedef struct magi_cookie {
-    /* All pointers must be valid as 'free' arguments. */
-    char *name;
-    char *data;
-    char *path;    /* Without '/' at the end. */
-    char *domain;  /* With dot at the begining. */
-    char *max_age; /* In seconds until discard, used only in response. */
+    char *name;     /**<@brief Cookie name. */
+    char *data;     /**<@brief Cookie value. */
+    char *path;     /**<@brief Path on wich cookie is set.
+                     * Without '/' at the end. */
+    char *domain;   /**<@brief Domain in wich cookie is set.
+                     * With dot at the begining. */
+    char *max_age;  /**<@brief In seconds until discard (response only). */
 } magi_cookie;
 
-typedef struct magi_cookie_list {
-    struct magi_cookie_list *next; /* Must be valid as 'free' arguments. */
-    magi_cookie              item;
-} magi_cookie_list;
-
-
-/* Addition of item to top of list. Null <=> error. */
-int magi_cookie_list_add(magi_cookie_list **list, magi_cookie *item);
-
-/* Data of last cookie in list: cookie.name == name, returns null if no such;
- * Last cookie in list is first from request, and from RFC 2109 we know that
- * first cookie is the most accurate for request's domain and path. */
-char *magi_cookie_list_get(magi_cookie_list *list, const char *name);
-
-/* Freeing and invalidation of list. */
-void magi_cookie_list_destroy(magi_cookie_list *list);
+/** @ brief HTTP cookies collection.
+ *
+ * Implemented as a linked list. */
+typedef struct magi_cookies {
+    struct magi_cookies *next;  /**<@brief Pointer to next cookies. */
+    magi_cookie          item;  /**<@brief Cookie on top. */
+} magi_cookies;
+
+/** @brief Add @p newitem to @p cookies.
+ * @param[in,out] cookies to add into.
+ * @param[in] newitem to add onto top of @p cookies. */
+void magi_cookies_add(magi_cookies **cookies, magi_cookie *newitem);
+
+/** @brief Get data of cookie from @p cookies with @p name.
+ * @note Cookies in @p cookies are in reverse request order, and first cookie
+ *       from request is the most accurate in terms of domain and path.
+ * @param[in] params to search in.
+ * @param[in] name of needed parameter.
+ * @return data of the last from top of @p cookies cookie with @p name,
+ *         null only if no such parameter. */
+char *magi_cookies_get(magi_cookies *cookies, const char *name);
+
+/** @brief Free memory used by @p cookies.
+ * @param[in,out] cookies to be destructed. */
+void magi_cookies_free(magi_cookies *cookies);
 
 
 #endif
diff --git a/include/magi/file.h b/include/magi/file.h
index 57b88f0..474913d 100644
--- a/include/magi/file.h
+++ b/include/magi/file.h
@@ -1,34 +1,42 @@
 #ifndef MAGI_INCLUDED_FILE
 #define MAGI_INCLUDED_FILE
 /** @file file.h
- * @brief blah...
- *
- * blah-blah...
+ * @brief Form field of file with its parameters.
  */
 #include "param.h"
 
 
+/** @brief Form field of file with its parameters. */
 typedef struct magi_file {
-    /* All pointers must be valid as 'free' arguments. */
-    char            *param_name; /* Name of corresponding form field */
-    char            *file_name;  /* File name on user's computer */
-    magi_param_list *params;     /* Multipart params (e.g. type) */
+    char        *field;     /**<@brief Name of form field. */
+    char        *filename;  /**<@brief File name on user's computer. */
+    magi_params *params;    /**<@brief Multipart params (e.g. type). */
 } magi_file;
 
-typedef struct magi_file_list {
-    struct magi_file_list *next; /* Must be valid as 'free' argument. */
-    magi_file              item;
-} magi_file_list;
-
-
-/* Addition of item to top of list. Null <=> error. */
-int magi_file_list_add(magi_file_list **list, magi_file *item);
-
-/* First node in list: node.param_name == name; else null. */
-magi_file *magi_file_list_get(magi_file_list *list, const char *name);
-
-/* Freeing and invalidation of list. */
-void magi_file_list_destroy(magi_file_list *list);
+/** @brief Form files collection.
+ *
+ * Implemented as a linked list. */
+typedef struct magi_files {
+    struct magi_files *next;  /**<@brief Pointer to next files. */
+    magi_file          item;  /**<@brief File on top. */
+} magi_files;
+
+
+/** @brief Add @p newitem to @p files.
+ * @param[in,out] files to add into.
+ * @param[in] newitem to add onto top of @p files. */
+void magi_files_add(magi_files **files, magi_file *newitem);
+
+/** @brief Get file with @p name from @p files.
+ * @param[in] files to search in.
+ * @param[in] name of needed file.
+ * @return first from top of @p files file with @p name,
+           null only if no such file. */
+magi_file *magi_files_get(magi_files *files, const char *name);
+
+/** @brief Free memory used by @p files.
+ * @param[in,out] files to be destructed. */
+void magi_files_free(magi_files *files);
 
 
 #endif
diff --git a/include/magi/loadfile.h b/include/magi/loadfile.h
index b485ea1..41622d8 100644
--- a/include/magi/loadfile.h
+++ b/include/magi/loadfile.h
@@ -14,23 +14,22 @@
 
 
 /** @brief Rule of loading single file.
- * 
+ *
  * There is no need to form or edit it directly. */
-struct magi_loadfile {
+typedef struct magi_loadfile {
     const char *name;  /**<@brief Form field to load file from. */
     const char *path;  /**<@brief Path to load file in. */
     int         max;   /**<@brief Limit in bytes. Null means unlimited. */
-};
-typedef struct magi_loadfile magi_loadfile;
+} magi_loadfile;
 
 /** @brief Table of rules for loading files.
- * 
+ *
  * Set @c count and @c files as null to initialize. */
-struct magi_loadfiles {
-    int            count; /**<@brief Size of @c files.*/
-    magi_loadfile *files; /**<@brief Dynamic array of rules to load files. */
-};
-typedef struct magi_loadfiles magi_loadfiles;
+typedef struct magi_loadfiles {
+    int            count;  /**<@brief Size of @c files.*/
+    magi_loadfile *files;  /**<@brief Dynamic array of rules to load files. */
+} magi_loadfiles;
+
 
 /** @brief Add entity into @p table.
  * @param[in,out] table is the table to add into.
@@ -50,8 +49,7 @@ void magi_loadfiles_free(magi_loadfiles *table);
 /** @brief Setup @p request to use loadfiles callback with @p table.
  * @param[in,out] request to setup using loadfiles callback.
  * @param[in] table to use in loadfiles callback. */
-void magi_request_setup_loadfiles(magi_request   *request,
-                                  magi_loadfiles *table);
+void magi_loadfiles_set(magi_request *request, magi_loadfiles *table);
 
 
 #endif
diff --git a/include/magi/param.h b/include/magi/param.h
index de39ff6..7e1262b 100644
--- a/include/magi/param.h
+++ b/include/magi/param.h
@@ -6,20 +6,18 @@
 
 
 /** @brief Parameter as name-value pair. */
-struct magi_param {
+typedef struct magi_param {
     char *name;  /**<@brief Cannot be null. */
     char *data;  /**<@brief Cannot be null. */
-};
-typedef struct magi_param magi_param;
+} magi_param;
 
 /** @brief Parameters collection.
  *
- * Implemented as linked list. */
-struct magi_params {
-    struct magi_params *next;  /**<@brief Pointer to next parameter. */
-    magi_param          item;  /**<@brief Top parameter. */
-};
-typedef struct magi_params magi_params;
+ * Implemented as a linked list. */
+typedef struct magi_params {
+    struct magi_params *next;  /**<@brief Pointer to next parameters. */
+    magi_param          item;  /**<@brief Parameter on top. */
+} magi_params;
 
 
 /** @brief Add @p newitem to @p params.
@@ -31,10 +29,11 @@ void magi_params_add(magi_params **params, magi_param *newitem);
  * @param[in] params to search in.
  * @param[in] name of needed parameter.
  * @return data of the first from top of @p params parameter with @p name,
- *         null only if no parameter with @p name is in @p params. */
-char *magi_params_get(magi_param_list *params, const char *name);
+ *         null only if no such parameter. */
+char *magi_params_get(magi_params *params, const char *name);
 
-/* Freeing and invalidation of list. */
+/** @brief Free memory used by @p params.
+ * @param[in,out] params to be destructed. */
 void magi_params_free(magi_params *params);
 
 
diff --git a/include/magi/urlenc.h b/include/magi/urlenc.h
index aa21f3e..99f7bbe 100644
--- a/include/magi/urlenc.h
+++ b/include/magi/urlenc.h
@@ -10,7 +10,7 @@
  * RFC 3986 describes URL-encoding.  Briefly it is changing every space into
  * plus sign and every not alpha-numerical and not @c "~-._" character into
  * percent sign followed by hexadecimal representation of given character.
- * 
+ *
  * @note This module is optional.
  */