From 746c3f3076fe5994f08d729aa1b958465231b0c8 Mon Sep 17 00:00:00 2001 From: Aleksey Veresov Date: Tue, 4 Feb 2020 14:57:11 +0300 Subject: [magi] --- readme | 42 +++++++++++++++++++++++++----------------- 1 file changed, 25 insertions(+), 17 deletions(-) (limited to 'readme') diff --git a/readme b/readme index 8cc3b8b..59dfc25 100644 --- a/readme +++ b/readme @@ -2,8 +2,8 @@ Magi Library (libmagi) implements Gateway Interfaces, namely CGI and FastCGI. Overview -Magi is free and open-source software: legal info is in the 'license' file. -It is written in ANSI C, without any dependecies, except for C standard +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 @@ -21,22 +21,30 @@ Running 'make' in the 'examples' directory produces 'append', 'cookie', corresponding source files. Usage -Magi main purpose is to analyse request and provide it in 'struct magi_request' -variable. It is described in 'src/request.h'; to setup defaults before actual -processing run 'magi_request_setup'. Next step is to analyse post-unrelated -part of request via 'magi_request_cgi'. Since post part can be realy big, -it is generally useful to constrain its analysis biased on the rest of request. -Post part analyse is done via 'magi_request_resume_cgi'. You can destroy -request structure via 'magi_request_destroy'. +magi_request analyses incoming request, general workflow is to: +1. Prepare request for analysis, setup defaults via 'magi_request_setup'; +2. Process non-post part of the CGI request via 'magi_request_cgi'; + (The division of post and non-post analysis comes from the fact that + post body can be really huge, so you probably will want to specify + some constraints on it, based on non-post info. For example session id + from non-post part allowes some users (e.g. admins) to load more in post.) +3. Process post part of the CGI request via 'magi_request_resume_cgi'; +4. Now you have the full request analysed, so do your work; +5. And finally, free memory via 'magi_request_destroy'. +For more see 'src/request.h'. -Also magi provide output capabilities via 'struct magi_response'. -Similary to request, 'magi_response_setup' is initialisation of response with -defaults. Content type need to be specified for response, to set it run -'magi_response_content_type'. You can set cookie with 'magi_response_cookie', -as well as discard them with 'magi_response_cookie_discard'. You can set HTTP -headers with 'magi_response_http'. For filling response body use -'magi_response_add' and 'magi_response_add_format'. To send response call -'magi_response_cgi'. Desctruction is provided in 'magi_response_destroy'. +magi_response provides output capabilities. You can form the response with +'magi_response_setup' used to setup defaults, and the following functions to +fill in your data ('...' means 'magi_response_'): + ...content_type: set Content Type (by default XHTML); + ...cookie: set HTTP Cookie; +...cookie_discard: discard HTTP Cookie; + ...http: setup arbitarary HTTP header; + ...add: add something to the body; + ...add_format: add comething to the body, using format (similar to printf); +Outputting itself can be done with 'magi_response_cgi'. +To correctly free all occupied memory call 'magi_response_destroy'. +For more see 'src/response.h'. Motivation Web must be fun. -- cgit v1.2.3