/**\file cgi.h * Describes extra params needed to use the Cgi class as well as the class * itself. *@author Mike Buland */ #include "linkedlist.h" #include "hashtable.h" #include "hashfunctionstring.h" #define VAR_STDINPUT 0x01 /**< Variable came from stdinput, web form */ #define VAR_COOKIE 0x02 /**< Variable came from a cookie */ #define VAR_CMDLINE 0x04 /**< Variable came from commandline / uri */ #define VAR_ANY 0xFF /**< Mask including all other types */ /** * Cgi header processor originally designed for apache cgi programs. When used * from apache with what I beleive are some sort of standard set of command * line parameters and environment variables. This always worked for all of my * purposes. This class will automatically extract all data from the system * that you need and places it into tables and things for easy access. * There are three types of input that data can come from, StandardInput, * CommandLine, and Cookies. StandardInput is when you get formdata in * multi-part forms, Cookies should usually be cookies that you set, and * command line is everything after the question mark in the URL. * This also contains some simple helpers for putting templated data into the * HTTP data feed. *@author Mike Buland */ class Cgi { public: /** * Create a complete CGI object, this object will automatically read data * from all available sources and be ready for use on the very next line! * If strSource is filled in it will also automatically read in a content * file, which is a simple file format containing named blocks of reusable * templates. *@param strSource Set to a filename in order to load up a content file. */ Cgi( const char *strSource = NULL ); /** * Destroy the cgi object. */ ~Cgi( ); /** * Get's the value for a variable as a character string. The name is the * name that was given on the URL or in the form or cookie. Skip can be * set to any value above zero to retreive subsequent variables with the * same name. The most obvious use of this is when dealing with file * uploads, each file upload sends you three variables with the same name * and different content. Finally the variable type determines where you * will accept this variable from. This is generally a bit of a security * thing, if you store login info in a cookie and don't want people getting * in by faking the appropriate URL. *@param name The name of the variable you wish to retreive. *@param skip THe number of variables with the given name to skip before * returning something meaningful. The only way to determine how many * variables with the same name there are is to skip until you get a NULL * value returned. *@param type Can be set to any combination of VAR_STDINPUT, VAR_COOKIE, * VAR_CMDLINE, or just VAR_ANY. This takes bitflags, so you can or the * values together. If a variable is found but came from the wrong source * it won't match any other criteria and will be treated as though it * doesn't exist. *@returns A null-terminated string representing the value of the requested * variable, or NULL if the variable did not exist. If a variable does * exist but has no value the string returned will start with a NULL char, * but be a valid string. */ char *getVarValue( const char *name, int skip=0, unsigned char type=VAR_ANY ); /** * This functions identically in every way to getVarValue, except that * instead of returning a pointer to the variable's value, it returns the * length of the variable's value string. The params are the same and so * a call to both functions with the same params should yeild a value and * a corresponding length. *@param name The name of the variable you wish to retreive. *@param skip THe number of variables with the given name to skip before * returning something meaningful. The only way to determine how many * variables with the same name there are is to skip until you get a NULL * value returned. *@param type Can be set to any combination of VAR_STDINPUT, VAR_COOKIE, * VAR_CMDLINE, or just VAR_ANY. This takes bitflags, so you can or the * values together. If a variable is found but came from the wrong source * it won't match any other criteria and will be treated as though it * doesn't exist. *@returns The length of the value-string of the requested variable. If * the requested variable is not found, -1 is returned. */ int getVarLength( const char *name, int skip=0, unsigned char type=VAR_ANY ); /** * A handy little function that writes a load of debug info related to * parsing CGI params to the standard output in html. This is generally * best used at the end of a page. */ void writeDebugInfo(); /** * Write a content header to the standard output. This should also be the * first thing that you do (except for writing cookies) after initializing * the Cgi class. You can select a type of header or content from the * header enum, and a properly formatted header will show up on the * standard output. *@param type Any value from the header enum in this class. The default is * to write an html header, probably the most common as well. */ void writeContentHeader( int type=headerHTML ); /** * Write content to the stnadard output. The content variable should have * been loaded during construction of the Cgi object or with the * loadContent function. The content variable should be formatted just like * a printf string, so that anything you want to put into it will have a % * symbol replacement code, like %s, %d, etc. Since this actually uses a * type of printf function everything from those docs work here. *@param name The name of the content variable to format and write to * stnadard output. *@param ... As many params as you want to include, ala printf. */ void writeContent( const char *name, ...); /** * Load a content file. I don't want to describe the format here, you can * just read the code or find an example for now. Sorry. *@param strSource The name of the file to open and read in to get the * content loaded. */ void loadContent( const char *strSource = NULL ); /** * Write a cookie-set header to the output stream. This should be done * before any other content-headers are written. The specifics of this * function are very simple, since I rely on the user's understanding of * how standard HTTP/1.1 or HTTP/1.0 cookie syntax works. If you don't * care then just use the name and value and the defaults should keep you * in good stead for a long time. *@param name The name of the cookie variable to set. *@param value The value to set to that variable. *@param expires The formatted string value for the date and time this * cookie should expire. A NULL here will put a "until the browser closes" * tag in. *@param path The path (URL) that this cookie belongs to. If you run a lot * of hosted servers or sub-sites that may have some shared URL bits then * you may want to set this. The cookie should only be sent to URL's that * match this as their first part. *@param domain The domain that is allowed to read this, if not set, it's * the domain the web browser contacted when they got the cookie. *@param secure I'm not sure, I think it's something to tell if the cookie * is safe to keep because any potentially valuable data is encypted or * otherwise unusable. I could be wrong. */ void writeCookie( char const *name, char const *value, char const *expires=NULL, char const *path=NULL, char const *domain=NULL, bool secure=false ); /** * A simple helper class to contain variable data. */ class Item { public: /** * Build an empty Item. */ Item( ) { name = NULL; value = NULL; len = 0; type = 0; } /** The name of the item. */ char *name; /** The value of the item. */ char *value; /** The length of the item's value. */ unsigned long len; /** The type of the item (where it came from). */ unsigned char type; }; /** Header values */ enum { headerHTML }; private: /** Keeps track of all contained variables. */ LinkedList aVars; /** Keeps track of all content variables. */ HashTable aContent; };