diff options
| -rw-r--r-- | include/magi/loadfile.h | 56 | ||||
| -rw-r--r-- | include/magi/param.h | 50 | ||||
| -rw-r--r-- | include/magi/urlenc.h | 23 |
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); |