diff options
Diffstat (limited to 'include/magi')
| -rw-r--r-- | include/magi/cgi.h | 14 | ||||
| -rw-r--r-- | include/magi/cookie.h | 44 | ||||
| -rw-r--r-- | include/magi/error.h | 5 | ||||
| -rw-r--r-- | include/magi/fastcgi.h | 5 | ||||
| -rw-r--r-- | include/magi/file.h | 40 | ||||
| -rw-r--r-- | include/magi/loadfile.h | 49 | ||||
| -rw-r--r-- | include/magi/param.h | 40 | ||||
| -rw-r--r-- | include/magi/request.h | 67 | ||||
| -rw-r--r-- | include/magi/response.h | 10 | ||||
| -rw-r--r-- | include/magi/urlenc.h | 19 |
10 files changed, 126 insertions, 167 deletions
diff --git a/include/magi/cgi.h b/include/magi/cgi.h index 8a13240..0de637e 100644 --- a/include/magi/cgi.h +++ b/include/magi/cgi.h @@ -1,23 +1,17 @@ #ifndef MAGI_INCLUDED_CGI #define MAGI_INCLUDED_CGI -/** @file cgi.h - * @brief blah... - * - * blah-blah... +/* Common Gateway Interface implementation */ #include "request.h" -/** Analyses non-post part of request from environment. - * @return 1 if ok, 0 if error. */ +/* Analyses non-post part of request from environment. True if ok. */ int magi_cgi_head(magi_request *request); -/** Complete request with post body from standard input. - * @return 1 if ok, 0 if error. */ +/* Complete request with post body from standard input. True if ok. */ int magi_cgi_body(magi_request *request); -/** Shortcut for analysing both head and body of request. - * @return 1 if ok, 0 if error. */ +/* Shortcut for analysing both head and body of request. True if ok. */ int magi_cgi(magi_request *request); diff --git a/include/magi/cookie.h b/include/magi/cookie.h index 8e1c6fc..96e4273 100644 --- a/include/magi/cookie.h +++ b/include/magi/cookie.h @@ -1,48 +1,36 @@ #ifndef MAGI_INCLUDED_COOKIE #define MAGI_INCLUDED_COOKIE -/** @file cookie.h - * @brief HTTP Cookie. - * +/* HTTP Cookie * Described in RFC 6265. */ -/** HTTP Cookie. */ typedef struct magi_cookie { - char *name; /**< Cookie name. */ - char *data; /**< Cookie value. */ - char *path; /**< Path on wich cookie is set. - * Without '/' at the end. */ - char *domain; /**< Domain in wich cookie is set. + char *name; /* Cookie name. */ + char *data; /* Cookie value. */ + char *path; /* Path on which cookie is set. Without '/' at the end. */ + char *domain; /* Domain in wich cookie is set. * With dot at the begining. */ - char *max_age; /**< In seconds until discard (response only). */ + char *max_age; /* In seconds until discard (response only). */ } magi_cookie; -/** HTTP cookies collection. - * Implemented as a linked list. */ +/* HTTP cookies collection, implemented as a linked list. */ typedef struct magi_cookies { - struct magi_cookies *next; /**< Pointer to next cookies. */ - magi_cookie item; /**< Cookie on top. */ + struct magi_cookies *next; /* Pointer to next cookies. */ + magi_cookie item; /* Cookie on top. */ } magi_cookies; -/** Add @p newitem to @p cookies. - * @param[in,out] cookies to add into. - * @param[in] newitem to add onto top of @p cookies. */ +/* Free memory used by cookies. */ +void magi_cookies_free(magi_cookies *cookies); + +/* Add newitem onto top of cookies. */ void magi_cookies_add(magi_cookies **cookies, magi_cookie *newitem); -/** Get 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] cookies to search in. - * @param[in] name of needed cookie. - * @return the last from top of @p cookies cookie with @p name, - * null only if no such cookie. */ +/* Get last from top of cookies cookie with name, null if no such cookie. + * Cookies are in reversed request order, and first cookie from request is + * the most accurate in terms of domain and path. */ magi_cookie *magi_cookies_get(magi_cookies *cookies, const char *name); -/** 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/error.h b/include/magi/error.h index 31e2c26..e928ed2 100644 --- a/include/magi/error.h +++ b/include/magi/error.h @@ -1,9 +1,6 @@ #ifndef MAGI_INCLUDED_ERROR #define MAGI_INCLUDED_ERROR -/** @file error.h - * @brief blah... - * - * blah-blah... +/* Error codes and messages */ diff --git a/include/magi/fastcgi.h b/include/magi/fastcgi.h index ee7114c..fb1f2e5 100644 --- a/include/magi/fastcgi.h +++ b/include/magi/fastcgi.h @@ -1,9 +1,6 @@ #ifndef MAGI_INCLUDED_FASTCGI #define MAGI_INCLUDED_FASTCGI -/** @file fastcgi.h - * @brief blah... - * - * blah-blah... +/* Fast CGI implementation */ /* * * TODO * * */ diff --git a/include/magi/file.h b/include/magi/file.h index 1b1fb35..d4c5e98 100644 --- a/include/magi/file.h +++ b/include/magi/file.h @@ -1,47 +1,43 @@ #ifndef MAGI_INCLUDED_FILE #define MAGI_INCLUDED_FILE -/** @file file.h - * @brief Form field of file with its parameters. +/* Form field of file with its parameters. */ #include "param.h" -/** Form field of file with its parameters. */ typedef struct magi_file { - char *field; /**< Name of form field. */ - char *filename; /**< File name on user's computer. */ - magi_params *params; /**< Multipart params (e.g. type). */ + char *field; /* Name of form field. */ + char *filename; /* File name on user's computer. */ + magi_params *params; /* Multipart params (e.g. type). */ } magi_file; -/** Form files collection. - * Implemented as a linked list. */ +/* Form files collection, implemented as a linked list. */ typedef struct magi_files { - struct magi_files *next; /**< Pointer to next files. */ - magi_file item; /**< File on top. */ + struct magi_files *next; /* Pointer to next files. */ + magi_file item; /* File on top. */ } magi_files; -/** Add @p newitem to @p files. - * @param[in,out] files to add into. - * @param[in] newitem to add onto top of @p files. */ +/* Free memory used by files. */ +void magi_files_free(magi_files *files); + +/* Add newitem onto top of files. */ void magi_files_add(magi_files **files, magi_file *newitem); -/** 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. */ +/* Get first from top of files file with name, null if no such file. */ magi_file *magi_files_get(magi_files *files, const char *name); -/** Free memory used by @p files. - * @param[in,out] files to be destructed. */ -void magi_files_free(magi_files *files); - +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Callback to load files while analysing request. + * addon_len is not null if something to add is in addon + * and null if file_to_add_into is ended. + * Files are passed sequentialy, one by one. */ typedef void (*magi_file_callback_act)(void *userdata, magi_file *file_to_add_into, char *addon, int addon_len); + typedef struct magi_file_callback { magi_file_callback_act act; void *userdata; diff --git a/include/magi/loadfile.h b/include/magi/loadfile.h index 04e5c2c..bf3421c 100644 --- a/include/magi/loadfile.h +++ b/include/magi/loadfile.h @@ -1,52 +1,47 @@ #ifndef MAGI_INCLUDED_LOADFILE #define MAGI_INCLUDED_LOADFILE -/** @file loadfile.h - * @brief Simple callback to load files. +/* 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. + * 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_loadfiles_set. * - * @note This module is optional. + * This module is optional. */ #include "request.h" -/** Rule of loading single file. +/* Rule of loading single file. * There is no need to form or edit it directly. */ typedef struct magi_loadfile { - const char *name; /**< Form field to load file from. */ - const char *path; /**< Path to load file in. */ - int max; /**< Limit in bytes. Null means unlimited. */ + const char *name; /* Form field to load file from. */ + const char *path; /* Path to load file in. */ + int max; /* Limit in bytes. Null means unlimited. */ } magi_loadfile; -/** Table of rules for loading files. - * Set @c count and @c files as null to initialize. */ +/* Table of rules for loading files. + * Set count and files as null to initialize. */ typedef struct magi_loadfiles { - int count; /**< Size of @c files.*/ - magi_loadfile *files; /**< Dynamic array of rules to load files. */ + int count; /* Size of files array.*/ + magi_loadfile *files; /* Dynamic array of rules to load files. */ } magi_loadfiles; -/** 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). */ +/* Free memory used by table. Request using table will become invalid. */ +void magi_loadfiles_free(magi_loadfiles *table); + +/* Add entity into table. + * Specify form field to load file from with name, + * wnated loaction to load file with path, + * and file size limit in bytes with max (pass null to unlimit). */ void magi_loadfiles_add(magi_loadfiles *table, const char *name, const char *path, int max); -/** 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 @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. */ +/* Setup request to use loadfiles callback with table. */ void magi_loadfiles_set(magi_request *request, magi_loadfiles *table); diff --git a/include/magi/param.h b/include/magi/param.h index b9dbde1..589db9f 100644 --- a/include/magi/param.h +++ b/include/magi/param.h @@ -1,45 +1,35 @@ #ifndef MAGI_INCLUDED_PARAM #define MAGI_INCLUDED_PARAM -/** @file param.h - * @brief Parameter as name-value pair. +/* Parameter as name-value pair. */ -/** Parameter as name-value pair. */ typedef struct magi_param { - char *name; /**< Cannot be null. */ - char *data; /**< Cannot be null. */ + char *name; /* Cannot be null. */ + char *data; /* Cannot be null. */ } magi_param; -/** Parameters collection. - * Implemented as a linked list. */ +/* Parameters collection, implemented as a linked list. */ typedef struct magi_params { - struct magi_params *next; /**< Pointer to next parameters. */ - magi_param item; /**< Parameter on top. */ + struct magi_params *next; /* Pointer to next parameters. */ + magi_param item; /* Parameter on top. */ } magi_params; -/** Add @p newitem to @p params. - * @param[in,out] params to add into. - * @param[in] newitem to add onto top of @p params. */ +/* Free memory used by params. */ +void magi_params_free(magi_params *params); + +/* Add newitem onto top of params. */ void magi_params_add(magi_params **params, magi_param *newitem); -/** Set @p newitem in @p params. - * @param[in,out] params to add into. - * @param[in] newitem to replace item in @p params with same name - or to add, if no param with same name is in @p params. */ +/* Set newitem in params. + * If param with name of newitem is in params it will be replaced with newitem, + * otherwise newitem will be added into the end of params. */ void magi_params_set(magi_params **params, magi_param *newitem); -/** 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 such parameter. */ +/* Get data of the first from top of params parameter with name, + * null if no such parameter. */ char *magi_params_get(magi_params *params, const char *name); -/** Free memory used by @p params. - * @param[in,out] params to be destructed. */ -void magi_params_free(magi_params *params); - #endif diff --git a/include/magi/request.h b/include/magi/request.h index 64e688d..3d0d48a 100644 --- a/include/magi/request.h +++ b/include/magi/request.h @@ -1,9 +1,14 @@ #ifndef MAGI_INCLUDED_REQUEST #define MAGI_INCLUDED_REQUEST -/** @file request.h - * @brief blah... +/* Request handler * - * blah-blah... + * Can be created via magi_{gateway interface name}_head, but will have + * nullified POST-related fields (params & files). Reason is unlimited + * POST body size, with possible dependence of wanted limits from data of + * headers (e.g. session id from cookies, enabling some users to load more). + * To proceed POST use magi_{gateway interface name}_body, specifying + * settings if necessary. + * Or just use shortcut magi_{gateway interface name} to do both parts. */ #include "cookie.h" #include "error.h" @@ -11,6 +16,7 @@ #include "param.h" +/* Limits on possibly enormous structures. Null means unlimited. */ typedef struct magi_request_limits { int cookies; int params_meta; @@ -18,54 +24,55 @@ typedef struct magi_request_limits { int params_body; } magi_request_limits; - -/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /** - * Request handler. - * - * Can be created via 'magi_{gateway interface name}_head', but will have - * nullified 'POST'-related fields ('params' & 'files'). Reason is unlimited - * 'POST' body size, with possible dependence of wanted limits from data of - * headers (e.g. session id from cookies, enabling some users to load more). - * To proceed 'post' use 'magi_{gateway interface name}_body', specifying - * settings if necessary. - * - * Or just use shortcut 'magi_{gateway interface_name}' to do both parts. */ typedef struct magi_request { magi_error error; - magi_cookies *cookies; - magi_params *meta; - magi_params *head; - magi_params *body; - magi_files *files; - - char *document_root; - char *method; - int is_secure; - char *host; - int port; - char *script; - char *path; - - magi_file_callback callback; + magi_cookies *cookies; /* Passed HTTP cookies. */ + magi_params *meta; /* Request parameters. */ + magi_params *head; /* Form field values from URL. */ + magi_params *body; /* Form field values from body. */ + magi_files *files; /* Form field files metadatas. */ + + char *document_root; /* Server's document root (e.g. /var/www/htdocs). */ + char *method; /* Request method (GET, HEAD, POST, etc...). */ + int is_secure; /* Means requested via HTTPS standard port (443). */ + char *host; /* Host name (e.g. example.com). */ + int port; /* Port (e.g. 80 or 443). */ + char *script; /* Script path in URL (e.g. /cgi-bin/script). */ + char *path; /* Path requested for the script (e.g. /login). */ + /* URL has form 'http[s]://{host}:{port}{script}{path}'. */ + + magi_file_callback callback; /* Callback to actually load files. */ magi_request_limits limits; + /* Implementation of response for this request. + * Especially helpful in case of FastCGI, + * when you can handle many requests simultaniously, + * and need to know how to response each of them. */ struct magi_response_implementation *response; } magi_request; +/* Request initialiser, setup defaults. */ void magi_request_init(magi_request *r); +/* Free memory used by request. */ void magi_request_free(magi_request *r); +/* Get value of meta-param with name. */ char *magi_request_meta(magi_request *r, const char *name); +/* Get value of form field param (prioritising body) with name. */ char *magi_request_param(magi_request *r, const char *name); +/* Get value of form field param with name from url. */ char *magi_request_urlparam(magi_request *r, const char *name); +/* Get metadata structure of file from file field with name. */ magi_file *magi_request_file(magi_request *r, const char *name); +/* Get value of cookie with name. */ char *magi_request_cookie(magi_request *r, const char *name); +/* Get cookie with name. */ magi_cookie *magi_request_cookie_complex(magi_request *r, const char *name); diff --git a/include/magi/response.h b/include/magi/response.h index a9854d4..756e2bd 100644 --- a/include/magi/response.h +++ b/include/magi/response.h @@ -1,20 +1,20 @@ #ifndef MAGI_INCLUDED_RESPONSE #define MAGI_INCLUDED_RESPONSE -/** @file response.h - * @brief General response functionality for magi_request. +/* General response functionality for magi_request. * * There are two parts of response, namely header and body. * You can directly dive into filling the body, since default headers are set. * Defult content-type is XHTML, status is 200 (Ok). * - * @warning Use body related functions only after dealing with headers. - * (Since storing possibly large body in memory is a bad idea, - * all headers should be sent before anything from the body.) + * Use body related functions only after dealing with headers. + * (Since storing possibly large body in memory is a bad idea, + * all headers should be sent before anything from the body.) */ #include "request.h" #include <stdio.h> +/* * * TODO * * */ typedef void (*magi_response_method_head)(void *ud, magi_param *header); typedef void (*magi_response_method_start_body)(void *ud); typedef void (*magi_response_method_body)(void *ud, const char *data, int len); diff --git a/include/magi/urlenc.h b/include/magi/urlenc.h index 0eff58b..dadebe7 100644 --- a/include/magi/urlenc.h +++ b/include/magi/urlenc.h @@ -1,29 +1,24 @@ #ifndef MAGI_INCLUDED_URLENC #define MAGI_INCLUDED_URLENC -/** @file urlenc.h - * @brief Realisation of URL-encoding. +/* Realisation of URL-encoding. * - * 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 + * 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. + * This module is optional. */ -/** 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. */ +/* Count URL-code size for plain. */ int magi_urlenc_size(const char *plain); -/** 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. */ +/* Encode plain to url-code code. + * code must be at least size of magi_urlenc_size(plain). */ void magi_urlenc(const char *plain, char *code); |