[magi] Broken to become better.

26 files changed, 118 insertions, 102 deletions

diff --git a/Makefile b/Makefile
index db1fefd..f25e658 100644
--- a/Makefile
+++ b/Makefile
@@ -1,3 +1,4 @@
+### TODO: Partial compilation (e.g. cgi+urlenc, but without fcgi)
 # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
 #     Compilation Options
 # Debug mode (allowing to debug the library via gdb):
diff --git a/examples/Makefile b/examples/Makefile
index 2f57b1e..8f5282c 100644
--- a/examples/Makefile
+++ b/examples/Makefile
@@ -20,7 +20,7 @@ CFLAGS  += -O3
 endif
 
 # Including magi library headers and setting linker to use it:
-INCLUDE  = -I ../src
+INCLUDE  = -I ../include
 LFLAGS   = -L.. -lmagi
 
 # Specification of library file to produce it, if not provided:
diff --git a/examples/upload.c b/examples/upload.c
index 19e045c..1877d39 100644
--- a/examples/upload.c
+++ b/examples/upload.c
@@ -39,7 +39,7 @@ int main(int argc, char const *argv[])
         magi_response response;
         magi_response_setup(&response);
         response_request(&request, &response);
-        magi_response_cgi_clear(&response);
+        magi_response_cgi(&response);
     } else {
         magi_error_cgi(request.error);
     }
diff --git a/include/magi.h b/include/magi.h
new file mode 100644
index 0000000..60f0cc9
--- /dev/null
+++ b/include/magi.h
@@ -0,0 +1,23 @@
+#ifndef MAGI_INCLUDED
+#define MAGI_INCLUDED
+/** @file magi.h
+ * @brief All headers are included here.
+ *
+ * You can include this, if you don't want to think about headers.
+ */
+#include "magi/cgi.h"
+#include "magi/cookie.h"
+#include "magi/error.h"
+#include "magi/fastcgi.h"
+#include "magi/file.h"
+#include "magi/param.h"
+#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
new file mode 100644
index 0000000..c365f2f
--- /dev/null
+++ b/include/magi/cgi.h
@@ -0,0 +1,35 @@
+#ifndef MAGI_INCLUDED_CGI
+#define MAGI_INCLUDED_CGI
+/** @file cgi.h
+ * @brief blah...
+ *
+ * blah-blah...
+ */
+#include "error.h"
+#include "request.h"
+#include "response.h"
+
+
+/** @brief Analyses non-post part of request from environment.
+ * @return Returns null only in case of 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. */
+int magi_request_cgi_body(magi_request *request);
+
+/** @brief Shortcut for analysing both head and body of request. */
+int magi_request_cgi(magi_request *request);
+
+
+/** @brief Sends response to standard output and destroys it.
+ * @return Returns null only in case of 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. */
+int magi_error_cgi(magi_error error);
+
+
+#endif
diff --git a/src/cookie.h b/include/magi/cookie.h
index 7eb3e9d..485b6d9 100644
--- a/src/cookie.h
+++ b/include/magi/cookie.h
@@ -1,5 +1,10 @@
 #ifndef MAGI_INCLUDED_COOKIE
 #define MAGI_INCLUDED_COOKIE
+/** @file cookie.h
+ * @brief blah...
+ *
+ * blah-blah...
+ */
 
 
 typedef struct magi_cookie {
diff --git a/src/error.h b/include/magi/error.h
index 4a91962..31e2c26 100644
--- a/src/error.h
+++ b/include/magi/error.h
@@ -1,5 +1,10 @@
 #ifndef MAGI_INCLUDED_ERROR
 #define MAGI_INCLUDED_ERROR
+/** @file error.h
+ * @brief blah...
+ *
+ * blah-blah...
+ */
 
 
 typedef enum magi_error {
diff --git a/src/fastcgi.h b/include/magi/fastcgi.h
index 0abd152..ee7114c 100644
--- a/src/fastcgi.h
+++ b/include/magi/fastcgi.h
@@ -1,9 +1,13 @@
 #ifndef MAGI_INCLUDED_FASTCGI
 #define MAGI_INCLUDED_FASTCGI
-
-
+/** @file fastcgi.h
+ * @brief blah...
+ *
+ * blah-blah...
+ */
 /* * *   TODO   * * */
 
+
 enum { magi_to_avoid_warning };
 
 
diff --git a/src/file.h b/include/magi/file.h
index 4705031..57b88f0 100644
--- a/src/file.h
+++ b/include/magi/file.h
@@ -1,6 +1,10 @@
 #ifndef MAGI_INCLUDED_FILE
 #define MAGI_INCLUDED_FILE
-
+/** @file file.h
+ * @brief blah...
+ *
+ * blah-blah...
+ */
 #include "param.h"
 
 
diff --git a/src/param.h b/include/magi/param.h
index bebacd7..6fd3b67 100644
--- a/src/param.h
+++ b/include/magi/param.h
@@ -1,5 +1,10 @@
 #ifndef MAGI_INCLUDED_PARAM
 #define MAGI_INCLUDED_PARAM
+/** @file param.h
+ * @brief blah...
+ *
+ * blah-blah...
+ */
 
 
 typedef struct magi_param {
diff --git a/src/request.h b/include/magi/request.h
index 18d6c8e..b15f085 100644
--- a/src/request.h
+++ b/include/magi/request.h
@@ -1,14 +1,18 @@
 #ifndef MAGI_INCLUDED_REQUEST
 #define MAGI_INCLUDED_REQUEST
-
+/** @file request.h
+ * @brief blah...
+ *
+ * blah-blah...
+ */
 #include "cookie.h"
 #include "error.h"
 #include "file.h"
 #include "param.h"
 
 
-/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
- * Request
+/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /**
+ * @brief Request
  *
  * Can be created via 'magi_request_{gateway interface name}', but will have
  * nullified 'post'-related fields ('params' & 'files').  Reason is unlimited
@@ -49,8 +53,6 @@ typedef struct magi_request {
     char *remote_port;     /* REMOTE_PORT */
     char *server_addr;     /* SERVER_ADDR */
     char *server_name;     /* SERVER_NAME */
-    /* server_name can be not a domain name, even if request is done with it.
-     * (Use http_params["HTTP_HOST"] instead.) */
     char *server_port;     /* SERVER_PORT */
     char *server_protocol; /* SERVER_PROTOCOL */
     char *server_software; /* SERVER_COFTWARE */
diff --git a/src/response.h b/include/magi/response.h
index a51d4a4..18f4b63 100644
--- a/src/response.h
+++ b/include/magi/response.h
@@ -1,6 +1,11 @@
 #ifndef MAGI_INCLUDED_RESPONSE
 #define MAGI_INCLUDED_RESPONSE
-
+/** @file response.h
+ * @brief General response functionality.
+ *
+ * blah-blah-blah
+ */
+/* TODO: rewrite in such way, that only headers are in memory. */
 #include "cookie.h"
 #include "param.h"
 
@@ -21,7 +26,6 @@ void magi_response_setup(magi_response *response);
 void magi_response_content_type(magi_response *response, const char *type);
 
 void magi_response_add(magi_response *response, const char *addon);
-void magi_response_add_format(magi_response *response, const char *addon, ...);
 
 void magi_response_cookie(magi_response *response, magi_cookie *cookie);
 
diff --git a/src/urlenc.h b/include/magi/urlenc.h
index edaec08..10fee1d 100644
--- a/src/urlenc.h
+++ b/include/magi/urlenc.h
@@ -1,5 +1,10 @@
 #ifndef MAGI_INCLUDED_URLENC
 #define MAGI_INCLUDED_URLENC
+/** @file urlenc.h
+ * @brief Realisation of url-encoding.
+ *
+ * Can be helpful in forming urls in response.
+ */
 
 
 /* 'code' from urlenc must have size of at least magi_urlenc_size(plain). */
diff --git a/readme b/readme
index 59dfc25..fb36636 100644
--- a/readme
+++ b/readme
@@ -5,9 +5,10 @@ Magi Library (libmagi) implements Gateway Interfaces, namely CGI and FastCGI.
 Magi are free and open-source software: legal info is in the 'license' file.
 They are written in ANSI C, without any dependecies, except for C standard
 library.  All source and header files are located in the 'src' directory.
-Files with 'inner' part in their names are not intended for external use.
-Since filenames in the project are short and simple consider placing
-header files in subdirectory 'magi' of your include.
+The 'include' directory is intended to be used in your include environment.
+Headers themselves are in 'magi' subdirectory of include, due to their short
+and simple names.  If you are not about choosing which header to include and
+just want everything to be included you can use 'magi.h'.
 
     Compiling
 Compilation and its options are described in the 'Makefile'.
diff --git a/src/cgi.c b/src/cgi.c
index c3ac1c6..20df48e 100644
--- a/src/cgi.c
+++ b/src/cgi.c
@@ -274,21 +274,15 @@ void output_cookies(struct magi_cookie_list * list)
 }
 
 
-int magi_response_cgi(struct magi_response * response)
+int magi_response_cgi(struct magi_response *response)
 {
     output_http_params(response->http_params);
     output_cookies(response->cookies);
     fputs(response->content_type, stdout);
     fputs("\r\n\r\n", stdout);
     fputs(response->content, stdout);
-    return 1;
-}
-
-int magi_response_cgi_clear(magi_response *response)
-{
-    int ok = magi_response_cgi(response);
     magi_response_destroy(response);
-    return ok;
+    return 1;
 }
 
 
@@ -308,5 +302,5 @@ int magi_error_cgi(enum magi_error error)
         "</body>"
         "</html>",
         magi_error_message(error));
-    return magi_response_cgi_clear(&res);
+    return magi_response_cgi(&res);
 }
diff --git a/src/cgi.h b/src/cgi.h
deleted file mode 100644
index 7e47ad0..0000000
--- a/src/cgi.h
+++ /dev/null
@@ -1,34 +0,0 @@
-#ifndef MAGI_INCLUDED_CGI
-#define MAGI_INCLUDED_CGI
-
-#include "error.h"
-#include "request.h"
-#include "response.h"
-
-
-/* Constructs non-post part of request from environment;
- * Returns null only in case of error. */
-int magi_request_cgi(magi_request *request);
-
-/* Complete request with post data from standard input;
- * Returns null only in case of error. */
-int magi_request_resume_cgi(magi_request *request);
-
-/* Shortcut for applying both previous. */
-int magi_request_full_cgi(magi_request *request);
-
-
-/* Sends response to standard output;
- * Returns null only in case of error. */
-int magi_response_cgi(magi_response *response);
-
-/* Shortcut for magi_response_cgi with desctruction after it. */
-int magi_response_cgi_clear(magi_response *response);
-
-
-/* Sends a standart response of Bad Request error to standard output;
- * Returns null only in case of error. */
-int magi_error_cgi(magi_error error);
-
-
-#endif
diff --git a/src/inner_cookies.c b/src/cookies.c
index 9dfde7a..9dfde7a 100644
--- a/src/inner_cookies.c
+++ b/src/cookies.c
diff --git a/src/inner_cookies.h b/src/cookies.h
index c336cf7..c336cf7 100644
--- a/src/inner_cookies.h
+++ b/src/cookies.h
diff --git a/src/magi.h b/src/magi.h
deleted file mode 100644
index b7df63c..0000000
--- a/src/magi.h
+++ /dev/null
@@ -1,16 +0,0 @@
-#ifndef MAGI_INCLUDED
-#define MAGI_INCLUDED
-/*     Magi Header Collection
- * You can include this, if you don't want to think about headers.
- */
-#include "cgi.h"
-#include "cookie.h"
-#include "error.h"
-#include "fastcgi.h"
-#include "file.h"
-#include "param.h"
-#include "request.h"
-#include "response.h"
-#include "urlenc.h"
-
-#endif
diff --git a/src/inner_multipart.c b/src/multipart.c
index 0187f7c..0187f7c 100644
--- a/src/inner_multipart.c
+++ b/src/multipart.c
diff --git a/src/inner_multipart.h b/src/multipart.h
index c3f7b65..c3f7b65 100644
--- a/src/inner_multipart.h
+++ b/src/multipart.h
diff --git a/src/response.c b/src/response.c
index 9570cd1..904b855 100644
--- a/src/response.c
+++ b/src/response.c
@@ -1,14 +1,10 @@
 #include "response.h"
 
-#include "inner_tools.h"
-#include <stdarg.h>
+#include "tools.h"
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 
-/* TODO: realise vsnprintf or eliminate need of it. (see musl) */
-int vsnprintf(char *s, size_t n, const char *format, va_list arg);
-
 
 void magi_response_setup(magi_response *response)
 {
@@ -46,24 +42,6 @@ void magi_response_add(magi_response *r, const char *addon)
     r->len += addon_len;
 }
 
-void magi_response_add_format(magi_response *response, const char *addon, ...)
-{
-    char   *act_addon;
-    int     n;
-    va_list args;
-    va_start(args, addon);
-    n = vsnprintf(0, 0, addon, args);
-    va_end(args);
-    if (n >= 0) {
-        act_addon = malloc(n + 1);
-        va_start(args, addon);
-        vsnprintf(act_addon, n + 1, addon, args);
-        va_end(args);
-        magi_response_add(response, act_addon);
-        free(act_addon);
-    }
-}
-
 void magi_response_cookie(magi_response *response, magi_cookie *cookie)
 {
     magi_cookie_list_add(&response->cookies, cookie);
diff --git a/src/inner_tools.c b/src/tools.c
index d958851..d958851 100644
--- a/src/inner_tools.c
+++ b/src/tools.c
diff --git a/src/inner_tools.h b/src/tools.h
index 87489c8..8d66131 100644
--- a/src/inner_tools.h
+++ b/src/tools.h
@@ -1,8 +1,8 @@
-#ifndef MAGI_INCLUDED_INNER_TOOLS
-#define MAGI_INCLUDED_INNER_TOOLS
-/*     Magi Inner Tools
- * This file must not be included in header files intended for external use,
- * it contains some common utility functions for use in source files.
+#ifndef MAGI_INCLUDED_TOOLS
+#define MAGI_INCLUDED_TOOLS
+/* * Collection of helpful functions for internal use.
+ *
+ * blah...
  */
 
 
diff --git a/src/inner_urlencoded.c b/src/urlencoded.c
index e3ea56a..e3ea56a 100644
--- a/src/inner_urlencoded.c
+++ b/src/urlencoded.c
diff --git a/src/inner_urlencoded.h b/src/urlencoded.h
index e07ed6f..e07ed6f 100644
--- a/src/inner_urlencoded.h
+++ b/src/urlencoded.h