| /* |
| * 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 |
| * |
| */ |
| |
| #ifndef __CGI_H_ |
| #define __CGI_H_ 1 |
| |
| #include <stdarg.h> |
| #include "util/neo_err.h" |
| #include "util/neo_hdf.h" |
| #include "cs/cs.h" |
| |
| __BEGIN_DECLS |
| |
| extern NERR_TYPE CGIFinished; |
| extern NERR_TYPE CGIUploadCancelled; |
| extern NERR_TYPE CGIParseNotHandled; |
| |
| /* HACK: Set this value if you want to treat empty CGI Query variables as |
| * non-existant. |
| */ |
| extern int IgnoreEmptyFormVars; |
| |
| typedef struct _cgi CGI; |
| |
| typedef int (*UPLOAD_CB)(CGI *, int nread, int expected); |
| typedef NEOERR* (*CGI_PARSE_CB)(CGI *, char *method, char *ctype, void *rock); |
| |
| struct _cgi_parse_cb |
| { |
| char *method; |
| int any_method; |
| char *ctype; |
| int any_ctype; |
| void *rock; |
| CGI_PARSE_CB parse_cb; |
| struct _cgi_parse_cb *next; |
| }; |
| |
| struct _cgi |
| { |
| /* Only public parts of this structure */ |
| void *data; /* you can store your own information here */ |
| HDF *hdf; /* the HDF dataset associated with this CGI */ |
| |
| BOOL ignore_empty_form_vars; |
| |
| UPLOAD_CB upload_cb; |
| |
| int data_expected; |
| int data_read; |
| struct _cgi_parse_cb *parse_callbacks; |
| |
| /* For line oriented reading of form-data input. Used during cgi_init |
| * only */ |
| char *buf; |
| int buflen; |
| int readlen; |
| BOOL found_nl; |
| BOOL unget; |
| char *last_start; |
| int last_length; |
| int nl; |
| |
| /* this is a list of filepointers pointing at files that were uploaded */ |
| /* Use cgi_filehandle to access these */ |
| ULIST *files; |
| |
| /* By default, cgi_parse unlinks uploaded files as it opens them. */ |
| /* If Config.Upload.Unlink is set to 0, the files are not unlinked */ |
| /* and there names are stored in this list. */ |
| /* Use Query.*.FileName to access these */ |
| ULIST *filenames; |
| |
| /* keep track of the time between cgi_init and cgi_render */ |
| double time_start; |
| double time_end; |
| }; |
| |
| |
| /* |
| * Function: cgi_init - Initialize ClearSilver CGI environment |
| * Description: cgi_init initializes the ClearSilver CGI environment, |
| * including creating the HDF data set. It will then import |
| * the standard CGI environment variables into that dataset, |
| * will parse the QUERY_STRING into the data set, and parse |
| * the HTTP_COOKIE into the data set. Note that if the |
| * var xdisplay is in the form data, cgi_init will attempt |
| * to validate the value and launch the configured debugger |
| * on the CGI program. These variables have to be |
| * specified in the hdf_file pointed to by hdf_file. The |
| * default settings do not allow debugger launching for |
| * security reasons. |
| * Input: cgi - a pointer to a CGI pointer |
| * hdf_file - the path to an HDF data set file that will also be |
| * loaded into the dataset. This will likely have to |
| * a be a full path, as the HDF search paths are not |
| * yet set up. Certain things, like |
| * Output: cgi - an allocated CGI struct, including |
| * Return: NERR_PARSE - parse error in CGI input |
| * NERR_NOMEM - unable to allocate memory |
| * NERR_NOT_FOUND - hdf_file doesn't exist |
| */ |
| NEOERR *cgi_init (CGI **cgi, HDF *hdf); |
| |
| /* |
| * Function: cgi_parse - Parse incoming CGI data |
| * Description: We split cgi_init into two sections, one that parses |
| * just the basics, and the second is cgi_parse. cgi_parse |
| * is responsible for parsing the entity body of the HTTP |
| * request. This payload is typically only sent (expected) |
| * on POST/PUT requests, but generally this is called on |
| * all incoming requests. This function walks the list of |
| * registered parse callbacks (see cgi_register_parse_cb), |
| * and if none of those matches or handles the request, it |
| * falls back to the builtin handlers: |
| * POST w/ application/x-www-form-urlencoded |
| * POST w/ application/form-data |
| * PUT w/ any content type |
| * In general, if there is no Content-Length, then |
| * cgi_parse ignores the payload and doesn't raise an |
| * error. |
| * Input: cgi - a pointer to a CGI pointer |
| * Output: Either data populated into files and cgi->hdf, or whatever |
| * other side effects of your own registered callbacks. |
| * Return: NERR_PARSE - parse error in CGI input |
| * NERR_NOMEM - unable to allocate memory |
| * NERR_NOT_FOUND - hdf_file doesn't exist |
| * NERR_IO - error reading HDF file or reading CGI stdin, or |
| * writing data on multipart/form-data file submission |
| * Anything else you raise. |
| */ |
| NEOERR *cgi_parse (CGI *cgi); |
| |
| /* |
| * Function: cgi_register_parse_cb - Register a parse callback |
| * Description: The ClearSilver CGI Kit has built-in functionality to handle |
| * the following methods: |
| * GET -> doesn't have any data except query string, which |
| * is processed for all methods |
| * POST w/ application/x-www-form-urlencoded |
| * POST w/ multipart/form-data |
| * processed as RFC2388 data into files and HDF (see |
| * cgi_filehandle()) |
| * PUT (any type) |
| * The entire data chunk is stored as a file, with meta |
| * data in HDF (similar to single files in RFC2388). |
| * The data is accessible via cgi_filehandle with NULL |
| * for name. |
| * To handle other methods/content types, you have to |
| * register your own parse function. This isn't necessary |
| * if you aren't expecting any data, and technically HTTP |
| * only allows data on PUT/POST requests (and presumably |
| * user defined methods). In particular, if you want to |
| * implement XML-RPC or SOAP, you'll have to register a |
| * callback here to grab the XML data chunk. Usually |
| * you'll want to register POST w/ application/xml or POST |
| * w/ text/xml (you either need to register both or |
| * register POST w/ * and check the ctype yourself, |
| * remember to nerr_raise(CGIParseNotHandled) if you aren't |
| * handling the POST). |
| * In general, your callback should: |
| * Find out how much data is available: |
| * l = hdf_get_value (cgi->hdf, "CGI.ContentLength", NULL); |
| * len = atoi(l); |
| * And read/handle all of the data using cgiwrap_read. |
| * See the builtin handlers for how this is done. Note |
| * that cgiwrap_read is not guarunteed to return all of |
| * the data you request (just like fread(3)) since it |
| * might be reading of a socket. Sorry. |
| * You should be careful when reading the data to watch |
| * for short reads (ie, end of file) and cases where the |
| * client sends you data ad infinitum. |
| * Input: cgi - a CGI struct |
| * method - the HTTP method you want to handle, or * for all |
| * ctype - the HTTP Content-Type you want to handle, or * for all |
| * rock - opaque data that we'll pass to your call back |
| * Output: None |
| * Return: CGIParseNotHandled if your callback doesn't want to handle |
| * this. This causes cgi_parse to continue walking the list of |
| * callbacks. |
| * |
| */ |
| NEOERR *cgi_register_parse_cb(CGI *cgi, const char *method, const char *ctype, |
| void *rock, CGI_PARSE_CB parse_cb); |
| |
| /* |
| * Function: cgi_destroy - deallocate the data associated with a CGI |
| * Description: cgi_destroy will destroy all the data associated with a |
| * CGI, which mostly means the associated HDF and removal |
| * of any files that were uploaded via multipart/form-data. |
| * (Note that even in the event of a crash, these files |
| * will be deleted, as they were unlinked on creation and |
| * only exist because of the open file pointer) |
| * Input: cgi - a pointer to a pointer to a CGI struct |
| * Output: cgi - NULL on output |
| * Return: None |
| */ |
| void cgi_destroy (CGI **cgi); |
| |
| /* |
| * Function: cgi_cs_init - initialize CS parser with the CGI defaults |
| * Description: cgi_cs_init initializes a CS parser with the CGI HDF |
| * context, and registers the standard CGI filters |
| * Input: cgi - a pointer a CGI struct allocated with cgi_init |
| * cs - a pointer to a CS struct pointer |
| * Output: cs - the allocated/initialized CS struct |
| * Return: NERR_NOMEM - no memory was available to render the template |
| */ |
| NEOERR *cgi_cs_init(CGI *cgi, CSPARSE **cs); |
| |
| /* |
| * Function: cgi_display - render and display the CGI output to the user |
| * Description: cgi_display will render the CS template pointed to by |
| * cs_file using the CGI's HDF data set, and send the |
| * output to the user. Note that the output is actually |
| * rendered into memory first. |
| * Input: cgi - a pointer a CGI struct allocated with cgi_init |
| * cs_file - a ClearSilver template file |
| * Output: None |
| * Return: NERR_IO - an IO error occured during output |
| * NERR_NOMEM - no memory was available to render the template |
| */ |
| NEOERR *cgi_display (CGI *cgi, const char *cs_file); |
| |
| /* |
| * Function: cgi_output - display the CGI output to the user |
| * Description: Normally, this is called by cgi_display, but some |
| * people wanted it external so they could call it |
| * directly. |
| * Input: cgi - a pointer a CGI struct allocated with cgi_init |
| * output - the data to send to output from the CGI |
| * Output: None |
| * Return: NERR_IO - an IO error occured during output |
| * NERR_NOMEM - no memory was available to render the template |
| */ |
| NEOERR *cgi_output (CGI *cgi, STRING *output); |
| |
| /* |
| * Function: cgi_filehandle - return a file pointer to an uploaded file |
| * Description: cgi_filehandle will return the stdio FILE pointer |
| * associated with a file that was uploaded using |
| * multipart/form-data. The FILE pointer is positioned at |
| * the start of the file when first available. |
| * Input: cgi - a pointer to a CGI struct allocated with cgi_init |
| * form_name - the form name that the file was uploaded as |
| * (not the filename) (if NULL, we're asking for the |
| * file handle for the PUT upload) |
| * Output: None |
| * Return: A stdio FILE pointer, or NULL if an error occurs (usually |
| * indicates that the form_name wasn't found, but might indicate |
| * a problem with the HDF dataset) |
| */ |
| FILE *cgi_filehandle (CGI *cgi, const char *form_name); |
| |
| /* |
| * Function: cgi_neo_error - display a NEOERR call backtrace |
| * Description: cgi_neo_error will output a 500 error containing the |
| * NEOERR call backtrace. This function is likely to be |
| * removed from future versions in favor of some sort of |
| * user error mechanism. |
| * Input: cgi - a pointer to a CGI struct |
| * err - a NEOERR (see util/neo_err.h for details) |
| * Output: None |
| * Return: None |
| */ |
| void cgi_neo_error (CGI *cgi, NEOERR *err); |
| |
| /* |
| * Function: cgi_error - display an error string to the user |
| * Description: cgi_error will output a 500 error containing the |
| * specified error message. This function is likely to be |
| * removed from future versions in favor of a user error |
| * mechanism. |
| * Input: cgi - a pointer to a CGI struct |
| * fmt - printf style format string and arguments |
| * Output: None |
| * Return: None |
| */ |
| void cgi_error (CGI *cgi, const char *fmt, ...) |
| ATTRIBUTE_PRINTF(2,3); |
| |
| /* |
| * Function: cgi_debug_init - initialize standalone debugging |
| * Description: cgi_debug_init initializes a CGI program for standalone |
| * debugging. By running a ClearSilver CGI program with a |
| * filename on the command line as the first argument, the |
| * CGI program will load that file of the form K=V as a set |
| * of HTTP/CGI environment variables. This allows you to |
| * run the program under a debugger in a reproducible |
| * environment. |
| * Input: argc/argv - the arguments from main |
| * Output: None |
| * Return: None |
| */ |
| void cgi_debug_init (int argc, char **argv); |
| |
| /* |
| * Function: cgi_url_escape - url escape a string |
| * Description: cgi_url_escape will do URL escaping on the passed in |
| * string, and return a newly allocated string that is escaped. |
| * Characters which are escaped include control characters, |
| * %, ?, +, space, =, &, /, and " |
| * Input: buf - a 0 terminated string |
| * Output: esc - a newly allocated string |
| * Return: NERR_NOMEM - no memory available to allocate the escaped string |
| */ |
| NEOERR *cgi_url_escape (const char *buf, char **esc); |
| |
| /* |
| * Function: cgi_url_escape_more - url escape a string |
| * Description: cgi_url_escape_more will do URL escaping on the passed in |
| * string, and return a newly allocated string that is escaped. |
| * Characters which are escaped include control characters, |
| * %, ?, +, space, =, &, /, and " and any characters in |
| * other |
| * Input: buf - a 0 terminated string |
| * other - a 0 terminated string of characters to escape |
| * Output: esc - a newly allocated string |
| * Return: NERR_NOMEM - no memory available to allocate the escaped string |
| */ |
| NEOERR *cgi_url_escape_more (const char *buf, char **esc, const char *other); |
| |
| /* |
| * Function: cgi_url_validate - validate that url is of an allowed format |
| * Description: cgi_url_validate will check that a URL starts with |
| * one of the accepted safe schemes. |
| * If not, it returns "#" as a safe substitute. |
| * Currently accepted schemes are http, https, ftp and mailto. |
| * It then html escapes the entire URL so that it is safe to |
| * insert in an href attribute. |
| * Input: buf - a 0 terminated string |
| * Output: esc - a newly allocated string |
| * Return: NERR_NOMEM - no memory available to allocate the escaped string |
| */ |
| NEOERR *cgi_url_validate (const char *buf, char **esc); |
| |
| /* |
| * Function: cgi_url_unescape - unescape an url encoded string |
| * Description: cgi_url_unescape will do URL unescaping on the passed in |
| * string. This function modifies the string in place |
| * This function will decode any %XX character, and will |
| * decode + as space |
| * Input: buf - a 0 terminated string |
| * Return: pointer to same buf |
| */ |
| char *cgi_url_unescape (char *buf); |
| |
| /* |
| * Function: cgi_redirect - send an HTTP 302 redirect response |
| * Description: cgi_redirect will redirect the user to another page on |
| * your site. This version takes only the path portion of |
| * the URL. As with all printf style commands, you should |
| * not call this with arbitrary input that may contain % |
| * characters, if you are forwarding something directly, |
| * use a format like cgi_redirect (cgi, "%s", buf) |
| * Input: cgi - cgi struct |
| * fmt - printf style format with args |
| * Output: None |
| * Return: None |
| */ |
| void cgi_redirect (CGI *cgi, const char *fmt, ...) |
| ATTRIBUTE_PRINTF(2,3); |
| |
| /* |
| * Function: cgi_redirect_uri - send an HTTP 302 redirect response |
| * Description: cgi_redirect_uri will redirect the user to another page on |
| * your site. This version takes the full URL, including |
| * protocol/domain/port/path. |
| * As with all printf style commands, you should |
| * not call this with arbitrary input that may contain % |
| * characters, if you are forwarding something directly, |
| * use a format like cgi_redirect (cgi, "%s", buf) |
| * Input: cgi - cgi struct |
| * fmt - printf style format with args |
| * Output: None |
| * Return: None |
| */ |
| void cgi_redirect_uri (CGI *cgi, const char *fmt, ...) |
| ATTRIBUTE_PRINTF(2,3); |
| |
| /* |
| * Function: cgi_vredirect - send an HTTP 302 redirect response |
| * Description: cgi_vredirect is mostly used internally, but can be used |
| * if you need a varargs version of the function. |
| * Input: cgi - cgi struct |
| * uri - whether the URL is full (1) or path only (0) |
| * fmt - printf format string |
| * ap - stdarg va_list |
| * Output: None |
| * Return: None |
| */ |
| void cgi_vredirect (CGI *cgi, int uri, const char *fmt, va_list ap); |
| |
| |
| /* |
| * Function: cgi_cookie_authority - determine the cookie authority for a |
| * domain |
| * Description: cgi_cookie_authority will walk the CookieAuthority |
| * portion of the CGI HDF data set, and return the matching |
| * domain if it exists. The purpose of this is so that you |
| * set domain specific cookies. For instance, you might |
| * have |
| * CookieAuthority.0 = neotonic.com |
| * In which case, any webserver using a hostname ending in |
| * neotonic.com will generate a cookie authority of |
| * neotonic.com. |
| * Input: cgi - a CGI struct |
| * host - optional host to match against. If NULL, the function |
| * will use the HTTP.Host HDF variable. |
| * Output: None |
| * Return: The authority domain, or NULL if none found. |
| */ |
| char *cgi_cookie_authority (CGI *cgi, const char *host); |
| |
| /* |
| * Function: cgi_cookie_set - Set a browser Cookie |
| * Description: cgi_cookie_set will issue a Set-Cookie header that |
| * should cause a browser to return a cookie when required. |
| * Note this function does no escaping of anything, you |
| * have to take care of that first. |
| * Input: cgi - a CGI struct |
| * name - the name of the cookie |
| * value - the value to set the cookie to. |
| * path - optional path for which the cookie is valid. Default |
| * is / |
| * domain - optional domain for which the cookie is valid. You |
| * can use cgi_cookie_authority to determine this |
| * domain. Default is none, which is interpreted by |
| * the browser as the sending domain only. |
| * time_str - expiration time string in the following format |
| * Wdy, DD-Mon-YYYY HH:MM:SS GMT. Only used if |
| * persistent. Default is one year from time of call. |
| * persistent - cookie will be stored by the browser between sessions |
| * secure - cookie will only be sent over secure connections |
| * Output: None |
| * Return: NERR_IO |
| */ |
| NEOERR *cgi_cookie_set (CGI *cgi, const char *name, const char *value, |
| const char *path, const char *domain, |
| const char *time_str, int persistent, int secure); |
| |
| /* |
| * Function: cgi_cookie_clear - clear browser cookie |
| * Description: cgi_cookie_clear will send back a Set-Cookie string that |
| * will attempt to stop a browser from continuing to send |
| * back a cookie. Note that the cookie has to match in |
| * name, domain, and path, and the luck of the Irish has to |
| * be with you for this work all the time, but at the least |
| * it will make the browser send back a cookie with no |
| * value, which the ClearSilver cookie parsing code will |
| * ignore. |
| * Input: cgi - a CGI struct |
| * name - the cookie name to clear |
| * domain - the domain to clear, NULL for none |
| * path - the cookie's path |
| * Output: None |
| * Return: NERR_IO |
| */ |
| NEOERR *cgi_cookie_clear (CGI *cgi, const char *name, const char *domain, |
| const char *path); |
| |
| /* not documented *yet* */ |
| NEOERR *cgi_text_html_strfunc(const char *str, char **ret); |
| NEOERR *cgi_html_strip_strfunc(const char *str, char **ret); |
| NEOERR *cgi_html_escape_strfunc(const char *str, char **ret); |
| NEOERR *cgi_js_escape (const char *buf, char **esc); |
| void cgi_html_ws_strip(STRING *str, int level); |
| NEOERR *cgi_register_strfuncs(CSPARSE *cs); |
| |
| /* internal use only */ |
| NEOERR * parse_rfc2388 (CGI *cgi); |
| NEOERR * open_upload(CGI *cgi, int unlink_files, FILE **fpw); |
| |
| __END_DECLS |
| |
| #endif /* __CGI_H_ */ |
