/*
* Copyright 2001-2004 Brandon Long
* All Rights Reserved.
*
* ClearSilver Templating System
*
* This code is made available under the terms of the ClearSilver License.
* http://www.clearsilver.net/license.hdf
*
*/
/*
* cgiwrap.h
* The purpose of the cgiwrap is to abstract the CGI interface to allow
* for other than the default implementation. The default
* implementation is of course based on environment variables and stdio,
* but this can be used with server modules which can substitute their
* own implementation of these functions.
*/
#ifndef __CGIWRAP_H_
#define __CGIWRAP_H_ 1
#include <stdarg.h>
#include "util/neo_err.h"
__BEGIN_DECLS
typedef int (*READ_FUNC)(void *, char *, int);
typedef int (*WRITEF_FUNC)(void *, const char *, va_list);
typedef int (*WRITE_FUNC)(void *, const char *, int);
typedef char *(*GETENV_FUNC)(void *, const char *);
typedef int (*PUTENV_FUNC)(void *, const char *, const char *);
typedef int (*ITERENV_FUNC)(void *, int, char **, char **);
/*
* Function: cgiwrap_init_std - Initialize cgiwrap with default functions
* Description: cgiwrap_init_std will initialize the cgiwrap subsystem
* to use the default CGI functions, ie
* getenv/putenv/stdio. In reality, all this is doing is
* setting up the data for the cgiwrap_iterenv() function.
* Input: the arguments to main, namely argc/argv/envp
* Output: None
* Returns: None
*/
void cgiwrap_init_std (int argc, char **argv, char **envp);
/*
* Function: cgiwrap_init_emu - initialize cgiwrap for emulated use
* Description: cgiwrap_init_emu sets up the cgiwrap subsystem for use
* in an emulated environment where you are providing
* routines to use in place of the standard routines, ie
* when used to interface with a server or scripting
* language.
* See cgi/cgiwrap.h for the exact definitions of the
* callback functions.
* Input: data - user data to be passed to the specified callbacks
* read_cb - a cb to replace fread(stdin)
* writef_cb - a cb to repalce fprintf(stdout)
* write_cb - a cb to replace fwrite(stdout)
* getenv_cb - a cb to replace getenv
* putenv_cb - a cb to replace putenv
* iterenv_cb - a cb to replace the default environment iteration
* function (which just wraps walking the envp array)
* Output: None
* Returns: None
*/
void cgiwrap_init_emu (void *data, READ_FUNC read_cb,
WRITEF_FUNC writef_cb, WRITE_FUNC write_cb, GETENV_FUNC getenv_cb,
PUTENV_FUNC putenv_cb, ITERENV_FUNC iterenv_cb);
/*
* Function: cgiwrap_getenv - the wrapper for getenv
* Description: cgiwrap_getenv wraps the getenv function for access to
* environment variables, which are used to pass data to
* CGI scripts. This version differs from the system
* getenv in that it makes a copy of the value it returns,
* which gets around problems when wrapping this routine in
* garbage collected/reference counted languages by
* moving the ownership of the data to the calling
* function.
* Input: k - the environment variable to lookup
* Output: v - a newly allocated copy of the value of that variable, or
* NULL if not found.
* Returns: NERR_NOMEM if there isn't memory available to allocate the result
*/
NEOERR *cgiwrap_getenv (const char *k, char **v);
/*
* Function: cgiwrap_putenv - wrap the putenv call
* Description: cgiwrap_putenv wraps the putenv call. This is mostly
* used by the cgi_debug_init function to create an
* artificial environment. This version differs from the
* system version by having separate arguments for the
* variable name and value, which makes life easier for the
* caller (usually), and keeps most wrapping callbacks from
* having to implement a parser to separate them.
* Input: k - the env var name
* v - the new value for env var k
* Output: None
* Returns: NERR_NOMEM
*/
NEOERR *cgiwrap_putenv (const char *k, const char *v);
/*
* Function: cgiwrap_iterenv - iterater for env vars
* Description: cgiwrap_iterenv allows a program to iterate over all the
* environment variables. This is probably mostly used by
* the default debug output.
* Input: n - variable to return. This should start at 0 and increment
* until you receive a NULL return value.
* Output: k - a malloc'd copy of the variable name
* v - a malloc'd copy of the variable value
* Returns: NERR_NOMEM
*/
NEOERR *cgiwrap_iterenv (int n, char **k, char **v);
/*
* Function: cgiwrap_writef - a wrapper for printf
* Description: cgiwrap_writef is the formatted output command that
* replaces printf or fprintf(stdout) in a standard CGI
* Input: fmt - standard printf fmt string and args
* Output: None
* Returns: NERR_SYSTEM
*/
NEOERR *cgiwrap_writef (const char *fmt, ...)
ATTRIBUTE_PRINTF(1,2);
/*
* Function: cgiwrap_writevf - a wrapper for vprintf
* Description: cgiwrap_writevf is the formatted output command that
* replaces vprintf or fvprintf(stdout) in a standard CGI
* It is also used by cgiwrap_writef (the actual wrapped
* function is a v type function)
* Input: fmt - standard printf fmt string
* ap - stdarg argument pointer
* Output: None
* Returns: NERR_SYSTEM
*/
NEOERR *cgiwrap_writevf (const char *fmt, va_list ap);
/*
* Function: cgiwrap_write - wrapper for the fwrite(stdout)
* Description: cgiwrap_write is the block data output function for
* cgiwrap that replaces fwrite(stdout) in regular CGIs
* Input: buf - a character buffer
* buf_len - the length of the buffer in buf
* Output: None
* Returns: NERR_IO
*/
NEOERR *cgiwrap_write (const char *buf, int buf_len);
/*
* Function: cgiwrap_read - cgiwrap input function
* Description: cgiwrap_read is used to read incoming data from the
* client, usually from a POST or PUT HTTP request. It
* wraps the part of fread(stdin).
* Input: buf - a pre-allocated buffer to read the data into
* buf_len - the size of the pre-allocated buffer
* Output: read_len - the number of bytes read into buf
* Returns: None
*/
void cgiwrap_read (char *buf, int buf_len, int *read_len);
__END_DECLS
#endif /* __CGIWRAP_H_ */