source: tags/0.58/cgic205/cgic.h @ 9

Last change on this file since 9 was 9, checked in by willem, 11 years ago

willem

File size: 7.2 KB
Line 
1/* The CGI_C library, by Thomas Boutell, version 2.01. CGI_C is intended
2        to be a high-quality API to simplify CGI programming tasks. */
3
4/* Make sure this is only included once. */
5
6#ifndef CGI_C
7#define CGI_C 1
8
9/* Bring in standard I/O since some of the functions refer to
10        types defined by it, such as FILE *. */
11
12#include <stdio.h>
13
14/* The various CGI environment variables. Instead of using getenv(),
15        the programmer should refer to these, which are always
16        valid null-terminated strings (they may be empty, but they
17        will never be null). If these variables are used instead
18        of calling getenv(), then it will be possible to save
19        and restore CGI environments, which is highly convenient
20        for debugging. */
21
22extern char *cgiServerSoftware;
23extern char *cgiServerName;
24extern char *cgiGatewayInterface;
25extern char *cgiServerProtocol;
26extern char *cgiServerPort;
27extern char *cgiRequestMethod;
28extern char *cgiPathInfo;
29extern char *cgiPathTranslated;
30extern char *cgiScriptName;
31extern char *cgiQueryString;
32extern char *cgiRemoteHost;
33extern char *cgiRemoteAddr;
34extern char *cgiAuthType;
35extern char *cgiRemoteUser;
36extern char *cgiRemoteIdent;
37extern char *cgiContentType;
38extern char *cgiAccept;
39extern char *cgiUserAgent;
40extern char *cgiReferrer;
41
42/* Cookies as sent to the server. You can also get them
43        individually, or as a string array; see the documentation. */
44extern char *cgiCookie;
45
46/* A macro providing the same incorrect spelling that is
47        found in the HTTP/CGI specifications */
48#define cgiReferer cgiReferrer
49
50/* The number of bytes of data received.
51        Note that if the submission is a form submission
52        the library will read and parse all the information
53        directly from cgiIn; the programmer need not do so. */
54
55extern int cgiContentLength;
56
57/* Pointer to CGI output. The cgiHeader functions should be used
58        first to output the mime headers; the output HTML
59        page, GIF image or other web document should then be written
60        to cgiOut by the programmer. In the standard CGIC library,
61        cgiOut is always equivalent to stdout. */
62
63extern FILE *cgiOut;
64
65/* Pointer to CGI input. The programmer does not read from this.
66        We have continued to export it for backwards compatibility
67        so that cgic 1.x applications link properly. */
68
69extern FILE *cgiIn;
70
71/* Possible return codes from the cgiForm family of functions (see below). */
72
73typedef enum {
74        cgiFormSuccess,
75        cgiFormTruncated,
76        cgiFormBadType,
77        cgiFormEmpty,
78        cgiFormNotFound,
79        cgiFormConstrained,
80        cgiFormNoSuchChoice,
81        cgiFormMemory,
82        cgiFormNoFileName,
83        cgiFormNoContentType,
84        cgiFormNotAFile,
85        cgiFormOpenFailed,
86        cgiFormIO,
87        cgiFormEOF
88} cgiFormResultType;
89
90/* These functions are used to retrieve form data. See
91        cgic.html for documentation. */
92
93extern cgiFormResultType cgiFormString(
94        char *name, char *result, int max);
95
96extern cgiFormResultType cgiFormStringNoNewlines(
97        char *name, char *result, int max);
98
99
100extern cgiFormResultType cgiFormStringSpaceNeeded(
101        char *name, int *length);
102
103
104extern cgiFormResultType cgiFormStringMultiple(
105        char *name, char ***ptrToStringArray);
106
107extern void cgiStringArrayFree(char **stringArray);
108
109extern cgiFormResultType cgiFormInteger(
110        char *name, int *result, int defaultV);
111
112extern cgiFormResultType cgiFormIntegerBounded(
113        char *name, int *result, int min, int max, int defaultV);
114
115extern cgiFormResultType cgiFormDouble(
116        char *name, double *result, double defaultV);
117
118extern cgiFormResultType cgiFormDoubleBounded(
119        char *name, double *result, double min, double max, double defaultV);
120
121extern cgiFormResultType cgiFormSelectSingle(
122        char *name, char **choicesText, int choicesTotal, 
123        int *result, int defaultV);     
124
125
126extern cgiFormResultType cgiFormSelectMultiple(
127        char *name, char **choicesText, int choicesTotal, 
128        int *result, int *invalid);
129
130/* Just an alias; users have asked for this */
131#define cgiFormSubmitClicked cgiFormCheckboxSingle
132
133extern cgiFormResultType cgiFormCheckboxSingle(
134        char *name);
135
136extern cgiFormResultType cgiFormCheckboxMultiple(
137        char *name, char **valuesText, int valuesTotal, 
138        int *result, int *invalid);
139
140extern cgiFormResultType cgiFormRadio(
141        char *name, char **valuesText, int valuesTotal, 
142        int *result, int defaultV);     
143
144/* The paths returned by this function are the original names of files
145        as reported by the uploading web browser and shoult NOT be
146        blindly assumed to be "safe" names for server-side use! */
147extern cgiFormResultType cgiFormFileName(
148        char *name, char *result, int max);
149
150/* The content type of the uploaded file, as reported by the browser.
151        It should NOT be assumed that browsers will never falsify
152        such information. */
153extern cgiFormResultType cgiFormFileContentType(
154        char *name, char *result, int max);
155
156extern cgiFormResultType cgiFormFileSize(
157        char *name, int *sizeP);
158
159typedef struct cgiFileStruct *cgiFilePtr;
160
161extern cgiFormResultType cgiFormFileOpen(
162        char *name, cgiFilePtr *cfpp);
163
164extern cgiFormResultType cgiFormFileRead(
165        cgiFilePtr cfp, char *buffer, int bufferSize, int *gotP);
166
167extern cgiFormResultType cgiFormFileClose(
168        cgiFilePtr cfp);
169
170extern cgiFormResultType cgiCookieString(
171        char *name, char *result, int max);
172
173extern cgiFormResultType cgiCookieInteger(
174        char *name, int *result, int defaultV);
175
176cgiFormResultType cgiCookies(
177        char ***ptrToStringArray);
178
179/* path can be null or empty in which case a path of / (entire site) is set.
180        domain can be a single web site; if it is an entire domain, such as
181        'boutell.com', it should begin with a dot: '.boutell.com' */
182extern void cgiHeaderCookieSetString(char *name, char *value, 
183        int secondsToLive, char *path, char *domain);
184extern void cgiHeaderCookieSetInteger(char *name, int value,
185        int secondsToLive, char *path, char *domain);
186extern void cgiHeaderLocation(char *redirectUrl);
187extern void cgiHeaderStatus(int status, char *statusMessage);
188extern void cgiHeaderContentType(char *mimeType);
189
190typedef enum {
191        cgiEnvironmentIO,
192        cgiEnvironmentMemory,
193        cgiEnvironmentSuccess,
194        cgiEnvironmentWrongVersion
195} cgiEnvironmentResultType;
196
197extern cgiEnvironmentResultType cgiWriteEnvironment(char *filename);
198extern cgiEnvironmentResultType cgiReadEnvironment(char *filename);
199
200extern int cgiMain();
201
202extern cgiFormResultType cgiFormEntries(
203        char ***ptrToStringArray);
204
205/* Output string with the <, &, and > characters HTML-escaped.
206        's' is null-terminated. Returns cgiFormIO in the event
207        of error, cgiFormSuccess otherwise. */
208cgiFormResultType cgiHtmlEscape(char *s);
209
210/* Output data with the <, &, and > characters HTML-escaped.
211        'data' is not null-terminated; 'len' is the number of
212        bytes in 'data'. Returns cgiFormIO in the event
213        of error, cgiFormSuccess otherwise. */
214cgiFormResultType cgiHtmlEscapeData(char *data, int len);
215
216/* Output string with the " character HTML-escaped, and no
217        other characters escaped. This is useful when outputting
218        the contents of a tag attribute such as 'href' or 'src'.
219        's' is null-terminated. Returns cgiFormIO in the event
220        of error, cgiFormSuccess otherwise. */
221cgiFormResultType cgiValueEscape(char *s);
222
223/* Output data with the " character HTML-escaped, and no
224        other characters escaped. This is useful when outputting
225        the contents of a tag attribute such as 'href' or 'src'.
226        'data' is not null-terminated; 'len' is the number of
227        bytes in 'data'. Returns cgiFormIO in the event
228        of error, cgiFormSuccess otherwise. */
229cgiFormResultType cgiValueEscapeData(char *data, int len);
230
231#endif /* CGI_C */
232
Note: See TracBrowser for help on using the repository browser.