Commit | Line | Data |
0198fd3c |
1 | /* |
2 | * fcgiapp.h -- |
3 | * |
4 | * Definitions for FastCGI application server programs |
5 | * |
6 | * |
7 | * Copyright (c) 1996 Open Market, Inc. |
8 | * |
9 | * See the file "LICENSE.TERMS" for information on usage and redistribution |
10 | * of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
11 | * |
12 | * $Id: fcgiapp.h,v 1.1 1997/09/16 15:36:32 stanleyg Exp $ |
13 | */ |
14 | |
15 | #ifndef _FCGIAPP_H |
16 | #define _FCGIAPP_H |
17 | |
18 | #ifndef TCL_LIBRARY /* Hack to see if we are building TCL since TCL |
19 | * needs varargs not stdarg |
20 | */ |
21 | #ifdef _WIN32 |
22 | #ifndef DLLAPI |
23 | #define DLLAPI __declspec(dllimport) |
24 | #endif |
25 | #else |
26 | #define DLLAPI |
27 | #endif |
28 | |
29 | #include <stdarg.h> |
30 | #else |
31 | #include <varargs.h> |
32 | #endif /* TCL_LIBARARY */ |
33 | #include "fcgi_config.h" |
34 | |
35 | #if defined (c_plusplus) || defined (__cplusplus) |
36 | extern "C" { |
37 | #endif |
38 | |
39 | /* |
40 | * Error codes. Assigned to avoid conflict with EOF and errno(2). |
41 | */ |
42 | #define FCGX_UNSUPPORTED_VERSION -2 |
43 | #define FCGX_PROTOCOL_ERROR -3 |
44 | #define FCGX_PARAMS_ERROR -4 |
45 | #define FCGX_CALL_SEQ_ERROR -5 |
46 | |
47 | /* |
48 | * This structure defines the state of a FastCGI stream. |
49 | * Streams are modeled after the FILE type defined in stdio.h. |
50 | * (We wouldn't need our own if platform vendors provided a |
51 | * standard way to subclass theirs.) |
52 | * The state of a stream is private and should only be accessed |
53 | * by the procedures defined below. |
54 | */ |
55 | typedef struct FCGX_Stream { |
56 | unsigned char *rdNext; /* reader: first valid byte |
57 | * writer: equals stop */ |
58 | unsigned char *wrNext; /* writer: first free byte |
59 | * reader: equals stop */ |
60 | unsigned char *stop; /* reader: last valid byte + 1 |
61 | * writer: last free byte + 1 */ |
62 | unsigned char *stopUnget; /* reader: first byte of current buffer |
63 | * fragment, for ungetc |
64 | * writer: undefined */ |
65 | int isReader; |
66 | int isClosed; |
67 | int wasFCloseCalled; |
68 | int FCGI_errno; /* error status */ |
69 | void (*fillBuffProc) (struct FCGX_Stream *stream); |
70 | void (*emptyBuffProc) (struct FCGX_Stream *stream, int doClose); |
71 | void *data; |
72 | } FCGX_Stream; |
73 | |
74 | /* |
75 | * An environment (as defined by environ(7)): A NULL-terminated array |
76 | * of strings, each string having the form name=value. |
77 | */ |
78 | typedef char **FCGX_ParamArray; |
79 | |
80 | \f |
81 | /* |
82 | *====================================================================== |
83 | * Control |
84 | *====================================================================== |
85 | */ |
86 | |
87 | /* |
88 | *---------------------------------------------------------------------- |
89 | * |
90 | * FCGX_IsCGI -- |
91 | * |
92 | * Returns TRUE iff this process appears to be a CGI process |
93 | * rather than a FastCGI process. |
94 | * |
95 | *---------------------------------------------------------------------- |
96 | */ |
97 | DLLAPI int FCGX_IsCGI(void); |
98 | |
99 | /* |
100 | *---------------------------------------------------------------------- |
101 | * |
102 | * FCGX_Accept -- |
103 | * |
104 | * Accepts a new request from the HTTP server. |
105 | * |
106 | * Results: |
107 | * 0 for successful call, -1 for error. |
108 | * |
109 | * Side effects: |
110 | * |
111 | * Finishes the request accepted by (and frees any |
112 | * storage allocated by) the previous call to FCGX_Accept. |
113 | * Creates input, output, and error streams and |
114 | * assigns them to *in, *out, and *err respectively. |
115 | * Creates a parameters data structure to be accessed |
116 | * via getenv(3) (if assigned to environ) or by FCGX_GetParam |
117 | * and assigns it to *envp. |
118 | * |
119 | * DO NOT retain pointers to the envp array or any strings |
120 | * contained in it (e.g. to the result of calling FCGX_GetParam), |
121 | * since these will be freed by the next call to FCGX_Finish |
122 | * or FCGX_Accept. |
123 | * |
124 | *---------------------------------------------------------------------- |
125 | */ |
126 | DLLAPI int FCGX_Accept( |
127 | FCGX_Stream **in, |
128 | FCGX_Stream **out, |
129 | FCGX_Stream **err, |
130 | FCGX_ParamArray *envp); |
131 | |
132 | /* |
133 | *---------------------------------------------------------------------- |
134 | * |
135 | * FCGX_Finish -- |
136 | * |
137 | * Finishes the current request from the HTTP server. |
138 | * |
139 | * Side effects: |
140 | * |
141 | * Finishes the request accepted by (and frees any |
142 | * storage allocated by) the previous call to FCGX_Accept. |
143 | * |
144 | * DO NOT retain pointers to the envp array or any strings |
145 | * contained in it (e.g. to the result of calling FCGX_GetParam), |
146 | * since these will be freed by the next call to FCGX_Finish |
147 | * or FCGX_Accept. |
148 | * |
149 | *---------------------------------------------------------------------- |
150 | */ |
151 | DLLAPI void FCGX_Finish(void); |
152 | |
153 | /* |
154 | *---------------------------------------------------------------------- |
155 | * |
156 | * FCGX_StartFilterData -- |
157 | * |
158 | * stream is an input stream for a FCGI_FILTER request. |
159 | * stream is positioned at EOF on FCGI_STDIN. |
160 | * Repositions stream to the start of FCGI_DATA. |
161 | * If the preconditions are not met (e.g. FCGI_STDIN has not |
162 | * been read to EOF) sets the stream error code to |
163 | * FCGX_CALL_SEQ_ERROR. |
164 | * |
165 | * Results: |
166 | * 0 for a normal return, < 0 for error |
167 | * |
168 | *---------------------------------------------------------------------- |
169 | */ |
170 | DLLAPI int FCGX_StartFilterData(FCGX_Stream *stream); |
171 | |
172 | /* |
173 | *---------------------------------------------------------------------- |
174 | * |
175 | * FCGX_SetExitStatus -- |
176 | * |
177 | * Sets the exit status for stream's request. The exit status |
178 | * is the status code the request would have exited with, had |
179 | * the request been run as a CGI program. You can call |
180 | * SetExitStatus several times during a request; the last call |
181 | * before the request ends determines the value. |
182 | * |
183 | *---------------------------------------------------------------------- |
184 | */ |
185 | DLLAPI void FCGX_SetExitStatus(int status, FCGX_Stream *stream); |
186 | \f |
187 | /* |
188 | *====================================================================== |
189 | * Parameters |
190 | *====================================================================== |
191 | */ |
192 | |
193 | /* |
194 | *---------------------------------------------------------------------- |
195 | * |
196 | * FCGX_GetParam -- obtain value of FCGI parameter in environment |
197 | * |
198 | * |
199 | * Results: |
200 | * Value bound to name, NULL if name not present in the |
201 | * environment envp. Caller must not mutate the result |
202 | * or retain it past the end of this request. |
203 | * |
204 | *---------------------------------------------------------------------- |
205 | */ |
206 | DLLAPI char *FCGX_GetParam(const char *name, FCGX_ParamArray envp); |
207 | \f |
208 | /* |
209 | *====================================================================== |
210 | * Readers |
211 | *====================================================================== |
212 | */ |
213 | |
214 | /* |
215 | *---------------------------------------------------------------------- |
216 | * |
217 | * FCGX_GetChar -- |
218 | * |
219 | * Reads a byte from the input stream and returns it. |
220 | * |
221 | * Results: |
222 | * The byte, or EOF (-1) if the end of input has been reached. |
223 | * |
224 | *---------------------------------------------------------------------- |
225 | */ |
226 | DLLAPI int FCGX_GetChar(FCGX_Stream *stream); |
227 | |
228 | /* |
229 | *---------------------------------------------------------------------- |
230 | * |
231 | * FCGX_UnGetChar -- |
232 | * |
233 | * Pushes back the character c onto the input stream. One |
234 | * character of pushback is guaranteed once a character |
235 | * has been read. No pushback is possible for EOF. |
236 | * |
237 | * Results: |
238 | * Returns c if the pushback succeeded, EOF if not. |
239 | * |
240 | *---------------------------------------------------------------------- |
241 | */ |
242 | DLLAPI int FCGX_UnGetChar(int c, FCGX_Stream *stream); |
243 | |
244 | /* |
245 | *---------------------------------------------------------------------- |
246 | * |
247 | * FCGX_GetStr -- |
248 | * |
249 | * Reads up to n consecutive bytes from the input stream |
250 | * into the character array str. Performs no interpretation |
251 | * of the input bytes. |
252 | * |
253 | * Results: |
254 | * Number of bytes read. If result is smaller than n, |
255 | * the end of input has been reached. |
256 | * |
257 | *---------------------------------------------------------------------- |
258 | */ |
259 | DLLAPI int FCGX_GetStr(char *str, int n, FCGX_Stream *stream); |
260 | |
261 | /* |
262 | *---------------------------------------------------------------------- |
263 | * |
264 | * FCGX_GetLine -- |
265 | * |
266 | * Reads up to n-1 consecutive bytes from the input stream |
267 | * into the character array str. Stops before n-1 bytes |
268 | * have been read if '\n' or EOF is read. The terminating '\n' |
269 | * is copied to str. After copying the last byte into str, |
270 | * stores a '\0' terminator. |
271 | * |
272 | * Results: |
273 | * NULL if EOF is the first thing read from the input stream, |
274 | * str otherwise. |
275 | * |
276 | *---------------------------------------------------------------------- |
277 | */ |
278 | DLLAPI char *FCGX_GetLine(char *str, int n, FCGX_Stream *stream); |
279 | |
280 | /* |
281 | *---------------------------------------------------------------------- |
282 | * |
283 | * FCGX_HasSeenEOF -- |
284 | * |
285 | * Returns EOF if end-of-file has been detected while reading |
286 | * from stream; otherwise returns 0. |
287 | * |
288 | * Note that FCGX_HasSeenEOF(s) may return 0, yet an immediately |
289 | * following FCGX_GetChar(s) may return EOF. This function, like |
290 | * the standard C stdio function feof, does not provide the |
291 | * ability to peek ahead. |
292 | * |
293 | * Results: |
294 | * EOF if end-of-file has been detected, 0 if not. |
295 | * |
296 | *---------------------------------------------------------------------- |
297 | */ |
298 | |
299 | DLLAPI int FCGX_HasSeenEOF(FCGX_Stream *stream); |
300 | \f |
301 | /* |
302 | *====================================================================== |
303 | * Writers |
304 | *====================================================================== |
305 | */ |
306 | |
307 | /* |
308 | *---------------------------------------------------------------------- |
309 | * |
310 | * FCGX_PutChar -- |
311 | * |
312 | * Writes a byte to the output stream. |
313 | * |
314 | * Results: |
315 | * The byte, or EOF (-1) if an error occurred. |
316 | * |
317 | *---------------------------------------------------------------------- |
318 | */ |
319 | DLLAPI int FCGX_PutChar(int c, FCGX_Stream *stream); |
320 | |
321 | /* |
322 | *---------------------------------------------------------------------- |
323 | * |
324 | * FCGX_PutStr -- |
325 | * |
326 | * Writes n consecutive bytes from the character array str |
327 | * into the output stream. Performs no interpretation |
328 | * of the output bytes. |
329 | * |
330 | * Results: |
331 | * Number of bytes written (n) for normal return, |
332 | * EOF (-1) if an error occurred. |
333 | * |
334 | *---------------------------------------------------------------------- |
335 | */ |
336 | DLLAPI int FCGX_PutStr(const char *str, int n, FCGX_Stream *stream); |
337 | |
338 | /* |
339 | *---------------------------------------------------------------------- |
340 | * |
341 | * FCGX_PutS -- |
342 | * |
343 | * Writes a null-terminated character string to the output stream. |
344 | * |
345 | * Results: |
346 | * number of bytes written for normal return, |
347 | * EOF (-1) if an error occurred. |
348 | * |
349 | *---------------------------------------------------------------------- |
350 | */ |
351 | DLLAPI int FCGX_PutS(const char *str, FCGX_Stream *stream); |
352 | |
353 | /* |
354 | *---------------------------------------------------------------------- |
355 | * |
356 | * FCGX_FPrintF, FCGX_VFPrintF -- |
357 | * |
358 | * Performs printf-style output formatting and writes the results |
359 | * to the output stream. |
360 | * |
361 | * Results: |
362 | * number of bytes written for normal return, |
363 | * EOF (-1) if an error occurred. |
364 | * |
365 | *---------------------------------------------------------------------- |
366 | */ |
367 | DLLAPI int FCGX_FPrintF(FCGX_Stream *stream, const char *format, ...); |
368 | |
369 | DLLAPI int FCGX_VFPrintF(FCGX_Stream *stream, const char *format, va_list arg); |
370 | |
371 | /* |
372 | *---------------------------------------------------------------------- |
373 | * |
374 | * FCGX_FFlush -- |
375 | * |
376 | * Flushes any buffered output. |
377 | * |
378 | * Server-push is a legitimate application of FCGX_FFlush. |
379 | * Otherwise, FCGX_FFlush is not very useful, since FCGX_Accept |
380 | * does it implicitly. Calling FCGX_FFlush in non-push applications |
381 | * results in extra writes and therefore reduces performance. |
382 | * |
383 | * Results: |
384 | * EOF (-1) if an error occurred. |
385 | * |
386 | *---------------------------------------------------------------------- |
387 | */ |
388 | DLLAPI int FCGX_FFlush(FCGX_Stream *stream); |
389 | \f |
390 | /* |
391 | *====================================================================== |
392 | * Both Readers and Writers |
393 | *====================================================================== |
394 | */ |
395 | |
396 | /* |
397 | *---------------------------------------------------------------------- |
398 | * |
399 | * FCGX_FClose -- |
400 | * |
401 | * Closes the stream. For writers, flushes any buffered |
402 | * output. |
403 | * |
404 | * Close is not a very useful operation since FCGX_Accept |
405 | * does it implicitly. Closing the out stream before the |
406 | * err stream results in an extra write if there's nothing |
407 | * in the err stream, and therefore reduces performance. |
408 | * |
409 | * Results: |
410 | * EOF (-1) if an error occurred. |
411 | * |
412 | *---------------------------------------------------------------------- |
413 | */ |
414 | DLLAPI int FCGX_FClose(FCGX_Stream *stream); |
415 | |
416 | /* |
417 | *---------------------------------------------------------------------- |
418 | * |
419 | * FCGX_GetError -- |
420 | * |
421 | * Return the stream error code. 0 means no error, > 0 |
422 | * is an errno(2) error, < 0 is an FastCGI error. |
423 | * |
424 | *---------------------------------------------------------------------- |
425 | */ |
426 | DLLAPI int FCGX_GetError(FCGX_Stream *stream); |
427 | |
428 | /* |
429 | *---------------------------------------------------------------------- |
430 | * |
431 | * FCGX_ClearError -- |
432 | * |
433 | * Clear the stream error code and end-of-file indication. |
434 | * |
435 | *---------------------------------------------------------------------- |
436 | */ |
437 | DLLAPI void FCGX_ClearError(FCGX_Stream *stream); |
438 | |
439 | |
440 | #if defined (__cplusplus) || defined (c_plusplus) |
441 | } /* terminate extern "C" { */ |
442 | #endif |
443 | |
444 | #endif /* _FCGIAPP_H */ |