diff options
| author | Aleksey Veresov <aleksey@veresov.pro> | 2021-01-08 00:43:37 +0300 |
|---|---|---|
| committer | Aleksey Veresov <aleksey@veresov.pro> | 2021-01-08 00:43:37 +0300 |
| commit | 26e703e68a0324e7e5bfd3442f3e424c88dd2c42 (patch) | |
| tree | 59302c86415f72fd48cf53c74489ea39c6df7153 | |
| parent | 7d0b4ad61ee1e150c76b9997971582066529b72a (diff) | |
| download | magi-26e703e68a0324e7e5bfd3442f3e424c88dd2c42.tar magi-26e703e68a0324e7e5bfd3442f3e424c88dd2c42.tar.xz magi-26e703e68a0324e7e5bfd3442f3e424c88dd2c42.zip | |
Documentation update started.
| -rw-r--r-- | LICENSE | 2 | ||||
| -rw-r--r-- | examples/hi.c | 16 | ||||
| -rw-r--r-- | include/magi/request.h | 2 | ||||
| -rw-r--r-- | man/magi.3 | 192 | ||||
| -rw-r--r-- | man/magi_request_init.3 | 23 | ||||
| -rw-r--r-- | man/magi_request_param.3 | 29 | ||||
| l--------- | man/magi_request_urlparam.3 | 1 |
7 files changed, 206 insertions, 59 deletions
@@ -1,4 +1,4 @@ -Copyright 2019-2020 Aleksey Veresov +Copyright 2019-2021 Aleksey Veresov This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from diff --git a/examples/hi.c b/examples/hi.c new file mode 100644 index 0000000..9305ad5 --- /dev/null +++ b/examples/hi.c @@ -0,0 +1,16 @@ +#include <magi.h> +#include <stdio.h> + +int main() +{ + struct magi_request request; + magi_request_init(&request); + if (magi_parse(&request)) { + magi_response_default(); + puts("<html><head><title>Hi!</title></head><body>Hi!</body></html>"); + } else { + magi_error_response(request.error); + } + magi_request_free(&request); + return 0; +} diff --git a/include/magi/request.h b/include/magi/request.h index 2d998c7..add7931 100644 --- a/include/magi/request.h +++ b/include/magi/request.h @@ -52,7 +52,7 @@ void magi_request_init(struct magi_request *r); void magi_request_free(struct magi_request *r); -/* Get value of form field param (prioritising body) with name. */ +/* Get value of form field param (prioritizing body) with name. */ char *magi_request_param(const struct magi_request *r, const char *name); /* Get value of form field param with name from url. */ char *magi_request_urlparam(const struct magi_request *r, const char *name); @@ -1,4 +1,4 @@ -.TH MAGI 3 2020-07-14 v0.0.1 "Library Manual" +.TH MAGI 3 2021-01-07 v0.0.1 "Magi Library Manual" .SH NAME .B magi \- Common Gateway Interface (CGI) library @@ -12,16 +12,94 @@ through CGI as described in .IR "RFC 3875" . The library is free and open source software. It is written in ANSI C without any dependencies except C standard library. -.SS Usage overview -A program using +.SH GETTING STARTED +Once you have obtained the sources (from +.I http://git.veresov.xyz/aversey/magi +or other way) run +.P +.RS +.nf +make +.fi +.RE +.P +in order to build the library. The results will be in the +.I build +directory. +.P +To build the examples run: +.P +.RS +.nf +make examples +.fi +.RE +.P +Add any single-file C program using +.B magi +into the +.I examples +directory in order to build it with the same command. +.P +To give you a .B magi -library must be linked with the -.B -lmagi -option. +try here is the minimal program: +.P +.RS +.nf +#include <magi.h> +#include <stdio.h> + +int main() +{ + struct magi_request request; + magi_request_init(&request); + if (magi_parse(&request)) { + magi_response_default(); + puts("<html><head><title>Hi!</title></head><body>Hi!</body></html>"); + } else { + magi_error_response(request.error); + } + magi_request_free(&request); + return 0; +} +.fi +.RE +.P +You can install +.B magi +system-wide once you have got root privileges by running: +.P +.RS +.nf +make install +.fi +.RE +.P +Once you have installed the library system-wide all you need to do to compile +you programs is to specify +.I -lmagi +flag. So to compile +.I some.c +using this library you can run: +.P +.RS +.nf +gcc some.c -lmagi +.fi +.RE .P +Default installation locations are +.I /usr/include +for the headers, +.I /usr/lib +for library binaries and +.I /usr/share/man +for this manual. +.SH OVERVIEW Main task of the .B magi -library is to analyse CGI request and represent it to the user in +library is to analyze CGI request and represent it to the user in .B magi_request data structure. CGI request is passed in environment variables and standard input. @@ -39,10 +117,10 @@ Body can be outputted directly into standard output with any method you want after forming and sending CGI headers via .BR magi_response . .SH REQUEST -Request structure initializtion is done with -.BR magi_request_init . +Request structure initialization is done with +.BR magi_request_init (). Don't forget to free everything in it then the work is done via -.BR magi_request_free . +.BR magi_request_free (). .P .RS .nf @@ -54,9 +132,9 @@ magi_request_free(&request); .RE .P Obtaining of request is done in two parts, i.e. head via -.B magi_parse_head +.BR magi_parse_head () and body via -.BR magi_parse_body . +.BR magi_parse_body (). Analysis of head will fill everything in .B magi_request structure, except @@ -64,10 +142,10 @@ structure, except and .I files fields. -Such separtion has place since body processing can depend on data from head, +Such separation has place since body processing can depend on data from head, e.g. in case of loading files, if file size is defined by user group. If analysis succeeded they will return 1, otherwise 0 as error mark. -More disctinct error code will be placed in +More distinct error code will be placed in .IR request.error . .P .RS @@ -84,9 +162,9 @@ if (magi_parse_body(&request)) { .fi .RE .P -If your case is not as advanced, you can use shortuct -.B magi_parse -to analyse both head and body. +If your case is not as advanced, you can use shortcut +.BR magi_parse () +to analyze both head and body. .BR magi_parse (&request) is literally .BR magi_parse_head (&request) @@ -145,10 +223,10 @@ while HTML form fields values passed in body (except for files, described lower) are stored in .IR body . To get value of parameter by its key use -.BR magi_request_param . +.BR magi_request_param (). This function priorities body params, so if you need specifically parameter from URL use -.B magi_request_urlparam . +.B magi_request_urlparam (). If no parameter was passed with given name, these functions will return null. .P For example, if we build search engine and want to access query passed in @@ -168,16 +246,16 @@ if (query) { .RE .P Note what values returned by -.B magi_request_urlparam +.BR magi_request_urlparam () are decoded from URL encoding, so you don't need to deal with all that percents and pluses. Result of -.B magi_request_param +.BR magi_request_param () is also raw data. .SS Cookies in request Same situation with cookies, stored in .I cookies field, and accessible via -.BR magi_request_cookie . +.BR magi_request_cookie (). .P For example, we can check session ID of user, stored in cookie "sid": .P @@ -186,7 +264,7 @@ For example, we can check session ID of user, stored in cookie "sid": struct awesome_session session; const char *sid = magi_request_cookie(&request, "sid"); if (!sid) { - /* render response for unauthorised user */ + /* render response for unauthorized user */ } else if (session_exists(sid)) { load_session(&session, sid); /* render response for this user */ @@ -201,11 +279,11 @@ While for cookies as described in it's all you need, your server can use Cookie2, as described in .IR "RFC 2965" . In both cases -.B magi_request_cookie +.BR magi_request_cookie () will return the most accurate cookie for this request, however Cookie2 allows more complex behavior, setting and receiving different host and path for cookies. You able to receive all information about cookie using -.BR magi_request_cookie_complex , +.BR magi_request_cookie_complex (), which returns pointer to .B magi_cookie structure. If no cookie is found, result is null. It has fields @@ -214,12 +292,12 @@ structure. If no cookie is found, result is null. It has fields .I path (without '/' at the end), .I domain -(with dot at the begining) and +(with dot at the beginning) and .I max_age (the last one is used only in response). .SS Files in request While ordinary parameters are not very big and don't need special processing, -files can be huge and need specail processing. +files can be huge and need special processing. Due to their size, files shouldn't be loaded into memory in general. The .B magi @@ -247,12 +325,12 @@ magi_loadfiles_free(&rules); .P There .I request -is initialised +is initialized .B magi_request with parsed head and not parsed body. .P To access information about file, use -.B magi_request_file . +.B magi_request_file (). It will get your .B magi_file structure for file loaded from field with passed name. @@ -262,7 +340,7 @@ field. Other parameters (as Content-Type) are in .I params field, accessible with -.BR magi_file_param . +.BR magi_file_param (). .P For example, we can get user feedback, returning Content-Type of loaded file: .P @@ -311,7 +389,7 @@ structure, and .IR addon_len . .P -Files are passed sequantially addon by addon. +Files are passed sequentially addon by addon. At the file end callback will be called with .I addon and @@ -322,7 +400,7 @@ If current is first in current .I file .I newfile -flag will be setted up. +flag will be set up. .P You can load file from field 'file' into current directory with name, as specified by @@ -351,7 +429,7 @@ static void cb(void *userdata, .fi .RE .P -Set it as callback for processing files for initialised +Set it as callback for processing files for initialized .I request with parsed head and not parsed body, and then parse the body: .P @@ -367,35 +445,35 @@ Response headers are formed with .B magi_response structure. It is initiated with -.BR magi_response_init , +.BR magi_response_init (), sent with -.BR magi_response_send , +.BR magi_response_send (), and freed with -.BR magi_response_free . +.BR magi_response_free (). The only defaults are .I text/html as Content-Type and .I 200 Ok as status. You can send them with -.BR magi_response_default . +.BR magi_response_default (). .P -.BR magi_response_content_type , -.B magi_reponse_content_length +.BR magi_response_content_type (), +.BR magi_reponse_content_length () and -.B magi_response_status +.BR magi_response_status () are used to change corresponding headers. Any other header can be only added, not changed with -.BR magi_response_header . +.BR magi_response_header (). Don't use it in cases above. .P For cookies use -.B magi_response_cookie +.BR magi_response_cookie () to set cookies and -.B magi_response_cookie_discard -to discrad them. +.BR magi_response_cookie_discard () +to discard them. In case of Cookie2 use -.BR magi_response_cookie_complex . +.BR magi_response_cookie_complex (). .P Lets send headers for XHTML body, setting cookie 'monster' as 'cookie': .P @@ -413,16 +491,16 @@ magi_response_free(&response); It is described in .IR "RFC 3986" . Briefly it is replacement of every space into plus sign and every not -alpha-numerical or not one of "~-._" character inte percent sign -followed by hexademical representation of given character byte. +alpha-numerical or not one of "~-._" character into percent sign +followed by hexadecimal representation of given character byte. .P The .B magi library provides functions to form url-encoded strings, which is very useful in forming response. Use -.B magi_urlenc_size +.BR magi_urlenc_size () to find what the size of code will be and then call -.B magi_urlenc +.BR magi_urlenc () for encoding itself. .P For example, lets form URL to search in DuckDuckGo for provided char @@ -443,11 +521,11 @@ url[prelen + urlencsize] = 0; .RE .P Note that second argument of -.B magi_urlenc +.BR magi_urlenc () which is encoding destination should be at least size of -.B magi_urlenc_size +.BR magi_urlenc_size () of plain data, and that -.B magi_urlenc +.BR magi_urlenc () doesn't write zero to form null-terminated string in its output. .SH ERRORS If function is returning pointer, error is only in case of null returned. @@ -457,15 +535,15 @@ as success mark it will be null only in case of error, and one otherwise. Exact .B magi_error code is in -.B error +.I error field of .B magi_request structure. For other modules error codes seem to be overkill. .P You can access default error message with -.B magi_error_message +.BR magi_error_message () or send default error page with -.BR magi_error_response . +.BR magi_error_response (). .SH DEBUGGING To debug your CGI scripts with .I gdb @@ -508,7 +586,7 @@ continue .fi .RE .SH COMPATIBILTY -Sine +Since .B magi only uses C standard library and the C language itself it should be able to run on every environment with them, i.e. Linux, OpenBSD, FreeBSD, macOS, @@ -529,7 +607,7 @@ which is a shortcut for include of .I magi.h wrapped in 'extern "C"' construct. .SH AUTHORS AND LICENSE -Copyrigth 2019-2020 +Copyright 2019-2021 .B Aleksey Veresov .RI < aleksey@veresov.pro > .P diff --git a/man/magi_request_init.3 b/man/magi_request_init.3 new file mode 100644 index 0000000..d0a1d6b --- /dev/null +++ b/man/magi_request_init.3 @@ -0,0 +1,23 @@ +.TH MAGI_REQUEST_INIT 3 2021-01-07 v0.0.1 "Magi Library Manual" +.SH NAME +.B magi_request_init +\- +.B magi_request +initialization +.SH SYNOPSIS +.B #include <magi/request.h> +.P +.RB "void " magi_request_init "(struct magi_request *" r ");" +.SH DESCRIPTION +.BR magi_request_init () +initializes +.I r +with default values. +It is usable for parsing the input after the call. +.P +Defaults are: read buffer of 64KB, unlimited space for cookies and parameters, +no callback for loading files. +.SH SEE ALSO +.BR magi_parse_head (3), +.BR magi_parse_body (3), +.BR magi_parse (3) diff --git a/man/magi_request_param.3 b/man/magi_request_param.3 new file mode 100644 index 0000000..3b5fb58 --- /dev/null +++ b/man/magi_request_param.3 @@ -0,0 +1,29 @@ +.TH MAGI_REQUEST_PARAM 3 2021-01-07 v0.0.1 "Magi Library Manual" +.SH NAME +.BR magi_request_param , +.B magi_request_urlparam +\- get a parameter from request +.SH SYNOPSIS +.B #include <magi/request.h> +.P +.RB "char *" magi_request_param "(struct magi_request *" r , +.RB "const char *" name ");" +.P +.RB "char *" magi_request_urlparam "(struct magi_request *" r , +.RB "const char *" name ");" +.SH DESCRIPTION +.BR magi_request_param () +gets the parameter from both request body and URL query, +prioritizing parameters from the body. +.P +.BR magi_request_urlparam () +gets the parameter from URL query. +.SH RETURN VALUE +.BR magi_request_param () +and +.BR magi_request_urlparam () +return value of found parameter with +.I name +as URL-decoded string, or +.B 0 +in case such parameter is not found. diff --git a/man/magi_request_urlparam.3 b/man/magi_request_urlparam.3 new file mode 120000 index 0000000..de9f38d --- /dev/null +++ b/man/magi_request_urlparam.3 @@ -0,0 +1 @@ +magi_request_param.3
\ No newline at end of file |