aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--include/magi/loadfile.h56
-rw-r--r--include/magi/param.h50
-rw-r--r--include/magi/urlenc.h23
3 files changed, 89 insertions, 40 deletions
diff --git a/include/magi/loadfile.h b/include/magi/loadfile.h
index 942c298..b485ea1 100644
--- a/include/magi/loadfile.h
+++ b/include/magi/loadfile.h
@@ -1,29 +1,55 @@
#ifndef MAGI_INCLUDED_LOADFILE
#define MAGI_INCLUDED_LOADFILE
-
+/** @file loadfile.h
+ * @brief Simple callback to load files.
+ *
+ * Generally satisfies task of receiving files. Fill #magi_loadfiles table
+ * via #magi_loadfiles_add, specifying which file-parameter to load into which
+ * path, and what are size limitations for it. When table is complete setup
+ * your request to use this callback with #magi_request_setup_loadfiles.
+ *
+ * @note This module is optional.
+ */
#include "request.h"
-typedef struct magi_loadfile {
- const char *param_name; /* Form field name, in which file is expected. */
- const char *location; /* Location to load file in. */
- int maximum; /* Limit in bytes. Null <=> unlimited. */
-} magi_loadfile;
-
-typedef struct magi_loadfiles {
- int count;
- magi_loadfile *files;
-} magi_loadfiles;
-
+/** @brief Rule of loading single file.
+ *
+ * There is no need to form or edit it directly. */
+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;
+
+/** @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;
+
+/** @brief Add entity into @p table.
+ * @param[in,out] table is the table to add into.
+ * @param[in] name is the form field name to load file from.
+ * @param[in] path to load file in.
+ * @param[in] max is limit in bytes (give null to unlimit). */
void magi_loadfiles_add(magi_loadfiles *table,
const char *name,
const char *path,
int max);
-void magi_loadfiles_destroy(magi_loadfiles *table);
+/** @brief Free memmory used by @p table.
+ * @warning Request using @p table will become invalid.
+ * @param[in,out] table to be destructed. */
+void magi_loadfiles_free(magi_loadfiles *table);
-/* Setup request callback with files loaded into corresponding to their
- * parameter names locations; paths are in magi_loadfiles struct. */
+/** @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);
diff --git a/include/magi/param.h b/include/magi/param.h
index 6fd3b67..de39ff6 100644
--- a/include/magi/param.h
+++ b/include/magi/param.h
@@ -1,33 +1,41 @@
#ifndef MAGI_INCLUDED_PARAM
#define MAGI_INCLUDED_PARAM
/** @file param.h
- * @brief blah...
- *
- * blah-blah...
+ * @brief Parameter as name-value pair.
*/
-typedef struct magi_param {
- /* All pointers must be valid as 'free' arguments. */
- char *name;
- char *data;
-} magi_param;
-
-typedef struct magi_param_list {
- struct magi_param_list *next; /* Must be valid as 'free' argument. */
- magi_param item;
-} magi_param_list;
-
+/** @brief Parameter as name-value pair. */
+struct magi_param {
+ char *name; /**<@brief Cannot be null. */
+ char *data; /**<@brief Cannot be null. */
+};
+typedef struct magi_param magi_param;
-/* Addition of item to top of list. Null <=> error. */
-int magi_param_list_add(magi_param_list **list,
- magi_param *item);
-
-/* Data of the first node in list: node.name == name; else null. */
-char *magi_param_list_get(magi_param_list *list, const char *name);
+/** @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;
+
+
+/** @brief Add @p newitem to @p params.
+ * @param[in,out] params to add into.
+ * @param[in] newitem to add onto top of @p params. */
+void magi_params_add(magi_params **params, magi_param *newitem);
+
+/** @brief Get data of parameter from @p params with @p name.
+ * @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);
/* Freeing and invalidation of list. */
-void magi_param_list_destroy(magi_param_list *list);
+void magi_params_free(magi_params *params);
#endif
diff --git a/include/magi/urlenc.h b/include/magi/urlenc.h
index 10fee1d..aa21f3e 100644
--- a/include/magi/urlenc.h
+++ b/include/magi/urlenc.h
@@ -1,14 +1,29 @@
#ifndef MAGI_INCLUDED_URLENC
#define MAGI_INCLUDED_URLENC
/** @file urlenc.h
- * @brief Realisation of url-encoding.
+ * @brief Realisation of URL-encoding.
*
- * Can be helpful in forming urls in response.
+ * Can be helpful in forming urls in response. Use #magi_urlenc for
+ * encoding itself and #magi_urlenc_size to find what the size of code
+ * will be.
+ *
+ * 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.
*/
-/* 'code' from urlenc must have size of at least magi_urlenc_size(plain). */
-int magi_urlenc_size(const char *plain);
+/** @brief Count URL-code size for @p plain.
+ * @param[in] plain is a text to count code size for.
+ * @return size of URL-code of @p plain. */
+int magi_urlenc_size(const char *plain);
+
+/** @brief Encode @p plain to url-code @p code.
+ * @warning @p code must be at least size of #magi_urlenc_size(@p plain).
+ * @param[in] plain is a text to be encoded.
+ * @param[out] code will be filled with URL-code of @p plain. */
void magi_urlenc(const char *plain, char *code);