aboutsummaryrefslogtreecommitdiff
path: root/readme
blob: cf90f06970a2187c01e8cdd9cd40b4cf07a9c621 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
    Description
Magi Library (libmagi) implements Gateway Interfaces, namely CGI and FastCGI.

    Overview
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 inner header files are located in the 'src' directory.
The 'include' directory is intended to be used in your include environment.
Headers in it contain library interface and its documentation in comments.
They are in subdirectory 'include/magi', due to their short and simple names.
If you are not about choosing which header to include and just want everything
to be included you can '#include <magi.h>'.

    Compiling
Compilation and its options are described in the 'Makefile'.
Running 'make' produces 'libmagi.a' file, which is precompiled library itself,
ready to be statically linked into your project.

    Examples
Compilation and its options are described in the local 'examples/Makefile'.
Running 'make' in the 'examples' directory produces 'append', 'cookie',
'upload', and 'echo' CGI executables.  Descriptions and details are in
corresponding source files.

    Usage
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 'include/magi/request.h'.

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 'include/magi/response.h'.

    Motivation
Web must be fun.