Main Page   Alphabetical List   Data Structures   File List   Data Fields   Globals  

cgi.h File Reference

Declares functions to intercept request, generate html or gif answers, and to compose HTTP resonses. More...

Go to the source code of this file.

Defines

#define CGI_H_VERSION   "$Id: cgi.h,v 2.0 2002/06/04 14:34:21 jongfoster Exp $"

Functions

http_response * dispatch_cgi (struct client_state *csp)
http_response * error_response (struct client_state *csp, const char *templatename, int err)
http_response * alloc_http_response (void)
void free_http_response (struct http_response *rsp)
http_response * finish_http_response (struct http_response *rsp)
map * default_exports (const struct client_state *csp, const char *caller)
jb_err map_block_killer (struct map *exports, const char *name)
jb_err map_block_keep (struct map *exports, const char *name)
jb_err map_conditional (struct map *exports, const char *name, int choose_first)
jb_err template_load (struct client_state *csp, char **template_ptr, const char *templatename, int recursive)
jb_err template_fill (char **template_ptr, const struct map *exports)
jb_err template_fill_for_cgi (struct client_state *csp, const char *templatename, struct map *exports, struct http_response *rsp)
void cgi_init_error_messages (void)
http_response * cgi_error_memory (void)
jb_err cgi_error_no_template (struct client_state *csp, struct http_response *rsp, const char *template_name)
jb_err cgi_error_bad_param (struct client_state *csp, struct http_response *rsp)
jb_err cgi_error_unknown (struct client_state *csp, struct http_response *rsp, jb_err error_to_report)
jb_err get_number_param (struct client_state *csp, const struct map *parameters, char *name, unsigned *pvalue)
jb_err get_string_param (const struct map *parameters, const char *param_name, const char **pparam)
char get_char_param (const struct map *parameters, const char *param_name)
void get_http_time (int time_offset, char *buf)
char * add_help_link (const char *item, struct configuration_spec *config)
char * make_menu (const char *self)
char * dump_map (const struct map *the_map)

Variables

const char image_pattern_data []
const size_t image_pattern_length
const char image_blank_data []
const size_t image_blank_length
const char cgi_rcs []
const char cgi_h_rcs []

Detailed Description

Declares functions to intercept request, generate html or gif answers, and to compose HTTP resonses.

Functions declared include:

Log:
cgi.h,v
Revision 2.0 2002/06/04 14:34:21 jongfoster Moving source files to src/

Revision 1.29 2002/05/19 11:33:21 jongfoster If a CGI error was not handled, and propogated back to dispatch_known_cgi(), then it was assumed to be "out of memory". This gave a very misleading error message.

Now other errors will cause a simple message giving the error number and asking the user to report a bug.

Bug report: http://sourceforge.net/tracker/index.php?func=detail &aid=557905&group_id=11118&atid=111118

Revision 1.28 2002/04/26 12:54:03 oes New function add_help_link

Revision 1.27 2002/04/24 02:16:51 oes Moved get_char_param, get_string_param and get_number_param here from cgiedit.c

Revision 1.26 2002/04/10 13:38:35 oes load_template signature changed

Revision 1.25 2002/04/08 20:50:25 swa fixed JB spelling

Revision 1.24 2002/03/26 22:29:54 swa we have a new homepage!

Revision 1.23 2002/03/24 16:18:15 jongfoster Removing old logo

Revision 1.22 2002/03/24 13:25:43 swa name change related issues

Revision 1.21 2002/03/07 03:48:38 oes

Revision 1.20 2002/03/04 17:53:22 oes Fixed compiled warning

Revision 1.19 2002/01/21 00:33:52 jongfoster Adding map_block_keep() to save a few bytes in the edit-actions-list HTML.

Revision 1.18 2001/11/16 00:46:31 jongfoster Fixing compiler warnings

Revision 1.17 2001/10/23 21:48:19 jongfoster Cleaning up error handling in CGI functions - they now send back a HTML error page and should never cause a FATAL error. (Fixes one potential source of "denial of service" attacks).

CGI actions file editor that works and is actually useful.

Ability to toggle Junkbuster remotely using a CGI call.

You can turn off both the above features in the main configuration file, e.g. if you are running a multi-user proxy.

Revision 1.16 2001/09/16 17:08:54 jongfoster Moving simple CGI functions from cgi.c to new file cgisimple.c

Revision 1.15 2001/09/16 15:02:35 jongfoster Adding i.j.b/robots.txt. Inlining add_stats() since it's only ever called from one place.

Revision 1.14 2001/09/16 11:38:02 jongfoster Splitting fill_template() into 2 functions: template_load() loads the file template_fill() performs the PCRS regexps. This is because the CGI edit interface has a "table row" template which is used many times in the page - this change means it's only loaded from disk once.

Revision 1.13 2001/09/16 11:00:10 jongfoster New function alloc_http_response, for symmetry with free_http_response

Revision 1.12 2001/09/13 23:31:25 jongfoster Moving image data to cgi.c rather than cgi.h.

Revision 1.11 2001/08/05 16:06:20 jongfoster Modifiying "struct map" so that there are now separate header and "map_entry" structures. This means that functions which modify a map no longer need to return a pointer to the modified map. Also, it no longer reverses the order of the entries (which may be important with some advanced template substitutions).

Revision 1.10 2001/08/01 21:19:22 jongfoster Moving file version information to a separate CGI page.

Revision 1.9 2001/08/01 00:17:54 jongfoster Adding prototype for map_conditional

Revision 1.8 2001/07/30 22:08:36 jongfoster Tidying up defines:

Revision 1.7 2001/07/29 18:43:08 jongfoster Changing ifdef _FILENAME_H to FILENAME_H_INCLUDED, to conform to ANSI C rules.

Revision 1.6 2001/06/29 21:45:41 oes Indentation, CRLF->LF, Tab-> Space

Revision 1.5 2001/06/29 13:22:44 oes

Revision 1.4 2001/06/09 10:50:58 jongfoster Changing "show URL info" handler to new style. Adding "extern" to some function prototypes.

Revision 1.3 2001/06/03 19:12:16 oes introduced new cgi handling

No revisions before 1.3

Function Documentation

char* add_help_link (  const char *    item,
struct configuration_spec *    config
) 
 

Produce a copy of the string given as item, embedded in an HTML link to its corresponding section (item name in uppercase) in the actions chapter of the user manual, (whose URL is given in the config and defaults to our web site).

FIXME I currently only work for actions, and would like to be generalized for other topics.

Parameters:
item  item (will NOT be free()d.) It is assumed to be HTML-safe.
config  The current configuration.
Returns:
String with item embedded in link, or NULL on out-of-memory

struct http_response* alloc_http_response (  void    ) 
 

Allocates a new http_response structure.

Parameters : N/A

Returns:
pointer to a new http_response, or NULL.

jb_err cgi_error_bad_param (  struct client_state *    csp,
struct http_response *    rsp
) 
 

CGI function that is called if the parameters (query string) for a CGI were wrong.

Parameters:
csp  Current client state (buffers, headers, etc...)
rsp  http_response data structure for output
CGI Parameters:
None
Returns:
JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error.

struct http_response* cgi_error_memory (  void    ) 
 

Called if a CGI function runs out of memory.

Returns a statically-allocated error response. Parameters : N/A

Returns:
http_response data structure for output. This is statically allocated, for obvious reasons.

jb_err cgi_error_no_template (  struct client_state *    csp,
struct http_response *    rsp,
const char *    template_name
) 
 

Almost-CGI function that is called if a template cannot be loaded.

Note this is not a true CGI, it takes a template name rather than a map of parameters.

Parameters:
csp  Current client state (buffers, headers, etc...)
rsp  http_response data structure for output
template_name  Name of template that could not be loaded.
Returns:
JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error.

jb_err cgi_error_unknown (  struct client_state *    csp,
struct http_response *    rsp,
jb_err    error_to_report
) 
 

Almost-CGI function that is called if an unexpected error occurs in the top-level CGI dispatcher.

In this context, "unexpected" means "anything other than JB_ERR_MEMORY or JB_ERR_CGI_PARAMS" - CGIs are expected to handle all other errors internally, since they can give more relavent error messages that way. Note this is not a true CGI, it takes an error code rather than a map of parameters.

Parameters:
csp  Current client state (buffers, headers, etc...)
rsp  http_response data structure for output
error_to_report  Error code to report.
Returns:
JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error.

void cgi_init_error_messages (  void    ) 
 

Call at the start of the program to initialize the error message used by cgi_error_memory().

Parameters : N/A

Returns:
N/A

struct map* default_exports (  const struct client_state *    csp,
const char *    caller
) 
 

returns a struct map list that contains exports which are common to all CGI functions.

Parameters:
csp  Current client state (buffers, headers, etc...)
caller  name of CGI who calls us and which should be excluded from the generated menu. May be NULL.
Returns:
NULL if no memory, else a new map. Caller frees.

struct http_response* dispatch_cgi (  struct client_state *    csp ) 
 

Checks if a request URL has either the magical hostname CGI_SITE_1_HOST (usually http://p.p/) or matches CGI_SITE_2_HOST CGI_SITE_2_PATH (usually.

http //config.privoxy.org/). If so, it passes the (rest of the) path onto dispatch_known_cgi, which calls the relevant CGI handler function.

Parameters:
csp  Current client state (buffers, headers, etc...)
Returns:
http_response if match, NULL if nonmatch or handler fail

char* dump_map (  const struct map *    the_map ) 
 

HTML-dump a map for debugging (as table).

Parameters:
the_map  map to dump
Returns:
string with HTML

struct http_response* error_response (  struct client_state *    csp,
const char *    templatename,
int    sys_err
) 
 

returns an http_response that explains the reason why a request failed.

Parameters:
csp  Current client state (buffers, headers, etc...)
templatename  Which template should be used for the answer
sys_err  system error number
Returns:
A http_response. If we run out of memory, this will be cgi_error_memory().

struct http_response* finish_http_response (  struct http_response *    rsp ) 
 

Fill in the missing headers in an http response, and flatten the headers to an http head.

Parameters:
rsp  pointer to http_response to be processed
Returns:
A http_response, usually the rsp parameter. On error, free()s rsp and returns cgi_error_memory()

void free_http_response (  struct http_response *    rsp ) 
 

Free the memory occupied by an http_response and its depandant structures.

Parameters:
rsp  pointer to http_response to be freed
Returns:
N/A

char get_char_param (  const struct map *    parameters,
const char *    param_name
) 
 

Get a single-character parameter passed to a CGI function.

Parameters:
parameters  map of cgi parameters
param_name  The name of the parameter to read
Returns:
Uppercase character on success, '\0' on error.

void get_http_time (  int    time_offset,
char *    buf
) 
 

Get the time in a format suitable for use in a HTTP header - e.g.: "Sun, 06 Nov 1994 08:49:37 GMT".

Parameters:
time_offset  Time returned will be current time plus this number of seconds.
buf  Destination for result. Must be long enough to hold 29 characters plus a trailing zero.
Returns:
N/A

jb_err get_number_param (  struct client_state *    csp,
const struct map *    parameters,
char *    name,
unsigned *    pvalue
) 
 

Get a non-negative integer from the parameters passed to a CGI function.

Parameters:
csp  Current client state (buffers, headers, etc...)
parameters  map of cgi parameters
name  Name of CGI parameter to read
pvalue  destination for value. Set to -1 on error.
Returns:
JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory JB_ERR_CGI_PARAMS if the parameter was not specified or is not valid.

jb_err get_string_param (  const struct map *    parameters,
const char *    param_name,
const char **    pparam
) 
 

Get a string paramater, to be used as an ACTION_STRING or ACTION_MULTI paramater.

Validates the input to prevent stupid/malicious users from corrupting their action file.

Parameters:
parameters  map of cgi parameters
param_name  The name of the parameter to read
pparam  destination for paramater. Allocated as part of the map "parameters", so don't free it. Set to NULL if not specified.
Returns:
JB_ERR_OK on success, or if the paramater was not specified. JB_ERR_MEMORY on out-of-memory. JB_ERR_CGI_PARAMS if the paramater is not valid.

char* make_menu (  const char *    self ) 
 

Returns an HTML-formatted menu of the available unhidden CGIs, excluding the one given in <self> Parameters : self = name of CGI to leave out, can be NULL for complete listing.

Returns:
menu string, or NULL on out-of-memory error.

jb_err map_block_keep (  struct map *    exports,
const char *    name
) 
 

Convenience function.

Removes the markers used by map-block-killer, to save a few bytes. i.e. removes "@if-<name>-start@" and "@if-<name>-end@"

Parameters:
exports  map to extend
name  name of conditional block
Returns:
JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error.

jb_err map_block_killer (  struct map *    exports,
const char *    name
) 
 

Convenience function.

Adds a "killer" for the conditional HTML-template block <name>, i.e. a substitution of the regex "if-<name>-start.*if-<name>-end" to the given export list.

Parameters:
exports  map to extend
name  name of conditional block
Returns:
JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error.

jb_err map_conditional (  struct map *    exports,
const char *    name,
int    choose_first
) 
 

Convenience function.

Adds an "if-then-else" for the conditional HTML-template block <name>, i.e. a substitution of the form: @if-<name>-then@ True text @else-not-<name>@ False text @endif-<name>@ The control structure and one of the alternatives will be hidden.

Parameters:
exports  map to extend
name  name of conditional block
choose_first  nonzero for first, zero for second.
Returns:
JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error.

jb_err template_fill (  char **    template_ptr,
const struct map *    exports
) 
 

CGI support function that fills in a pre-loaded HTML template by replacing @name@ with value using pcrs, for each item in the output map.

Note that a leading '$' charachter in the export map's values will be stripped and toggle on backreference interpretation.

Parameters:
template_ptr  IN: Template to be filled out. Will be free()d.

OUT Filled out template. Caller must free().

exports  map with fill in symbol -> name pairs
Returns:
JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error

jb_err template_fill_for_cgi (  struct client_state *    csp,
const char *    templatename,
struct map *    exports,
struct http_response *    rsp
) 
 

CGI support function that loads a HTML template and fills it in.

Handles file-not-found errors by sending a HTML error message. For convenience, this function also frees the passed "exports" map.

Parameters:
csp  Client state
templatename  name of the HTML template to be used
exports  map with fill in symbol -> name pairs. Will be freed by this function.
rsp  Response structure to fill in.
Returns:
JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error

jb_err template_load (  struct client_state *    csp,
char **    template_ptr,
const char *    templatename,
int    recursive
) 
 

CGI support function that loads a given HTML template from the confdir, ignoring comment lines and following include statements up to a depth of 1.

Parameters:
csp  Current client state (buffers, headers, etc...)
template_ptr  Destination for pointer to loaded template text.
templatename  name of the HTML template to be used
recursive  Flag set if this function calls itself following an include statament
Returns:
JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error. JB_ERR_FILE if the template file cannot be read

Variable Documentation

const char cgi_h_rcs[]
 

Version information about cgi.h.

const char cgi_rcs[]
 

Version information about cgi.c.

const char image_blank_data[]
 

1x1 transparant GIF.

const size_t image_blank_length
 

The size of the image_blank, in bytes.

const char image_pattern_data[]
 

Checkerboard pattern, as a GIF.

const size_t image_pattern_length
 

The size of the image_pattern, in bytes.

Generated on Tue Jun 4 18:54:49 2002 for Privoxy 3.1.1 by doxygen1.2.15