C++ CGI Variable Wrapper

CGI C++ Variable Wrapper: Documentation

C++ CGI Wrapper Documentation -- http://www.purplepixie.org/cgi

* REFERENCE: Wrapper Software Reference *

---------------------------------------------------------------

The actual data is stored as a linked list of CGI_Variableclass nodes. The actual definition of this class and it'smembers etc is not of important to the user generally. Ifyou wish to use it directly I would encourage you to have alook at the source code.

The user-interface class is CGI_Interface and it is definedwith the following public members and methods:

The PrintError flag determines if a routine (such asAutoLoad for example) should print textual error outputto the screen as well as returning it's error value. Thiscan be useful for debugging when you are not bothingto test the return values of methods.

The ReturnValidPointer flag and the associated chararray NullString are included as of version 2.5 andaddress a niggle of having to check a Fetch() resultagainst 0 before entering a string based evaluation.

With ReturnValidPointer set (it is not by default), apointer to NullString will be returned if Fetch failsto find a matching variable. You can differentiatebetween a found and null-length variable and an unfoundvariable by comparing the pointer returned by Fetchand NullString. Alternatively you may like to setNullString to a meaningful value. It defaults to thesize set by LENMAX_VAR_NULLSTRING (2 as shipped) andthe constructor fills the string with zeros.

Fetch also takes a bool UseReturnValidPointer whichis a default parameter set to true. Passing false willoverride the ReturnValidPointer flag and always return0 if the variable is not found.

Each method and it's uses are detailed as follows:

CGI_Interface(bool pError=false);

The default constructor. Do NOT call this functiondirectly. It will be used by the new operator, anda wrapper should be initialisd with a call such as:CGI_Wrapper *cgi=new CGI_Wrapper(ERROR_VALUE) whereERROR_VALUE is a boolean variable to set the initialvalue of the PrintError flag. This is not a necessaryargument and will default to false.

int AutoLoad(void);

The AutoLoad method is the normal method used to loaddata into the list. AutoLoad will first of all determinethe method with which the CGI is called (GET or POST)then act appropriately. POST data is read into a bufferfrom stdin (as of version 1.01 limited to 32k) with thisdata being gained from QUERY_STRING for a GET. Once ithas filled the input buffer from the relevant source,StringLoad is called for this input. AutoLoad returnsthe value returned from StringLoad namely a -1 foran error or the number of variables found and addedto the list. AutoLoad will return a -1 before callingStringLoad if it is unable to determine the methodused. With the PrintError flag set a textual descriptionof the error will be output for debugging purposes.

int CookieLoad(void)

The CookieLoad method loads variables into the list fromthe HTTP_COOKIE environment variable (if it exists). Thesewill be decoded as normal and appended/replaced into thelist. The return integer is the number of variables foundand loaded in the HTTP_COOKIE variable.

void PrintDump(void);

PrintDump will (regardless of the PrintError flag)output a full list of all the variable names and valuesstored in it's list. This method is provided for debugpurposes primarily.

int StringLoad(const char *input);

The StringLoad method parses a URLEncoded string forvariables and values. Very basically it parses from startto finish building the variable name, finding an equal,building the variable value and then finding an ampersandwhere it adds the values to the list and starts again orEOL upon which it finishes. StringLoad returns a -1 onerror (text is output if the PrintError flag is set) orthe number of variables found and added to the list (0would mean a valid string etc but no content found). Thisfunction also handles URL decoding and CAN ONLY deal withURL encoded strings. If a 'normal' string is parsed anda percent, ampersand or equals is found in the normal textthings will go horribly wrong.

char* Fetch(const char *name, bool UseReturnValidPointer);

The Fetch method is called by passing the case sensitivename of the variable. If the variable is found in the lista char* pointer to the contents is returned (see below).When the variable is not in the list the return behaviouris controlled by use of the ReturnValidPointer flag in theCGI_Interface class. If this flag is set (it is false bydefault) then Fetch will return a pointer to the chararray NullString which (as mentioned above) is filled with0's. You can then operate on this string or check itspointer against NullString's. When this flag is not setan empty string being returned by Fetch means the varibledoes exist in the list but has the null string as a value.

You can override the operation of ReturnValidPointer bypassing false as the UseReturnValidPointer parameter (thisdefaults to true and is optional). If UseReturnValidPointeris false then Fetch will return the variable contents ora 0 as if ReturnValidPointer was itself false.

Please note that the pointer returned is the actual pointerto the char array in the linked list containing the variablevalue. This is probably not too safe but make's life a biteasier. You should never really change the content of thispointer as things can go badly wrong - use the Set methodinstead.

int Set(const char *name, const char *value);

Does what it says on the tin - sets a variable with thevalue. Please remember that the variable name is casesensitive. If the variable exists then it is updatedand if not, created and added to the list. Currentlythe function returns just a 1 upon success (and itwon't fail as it doesn't test anything). I think theidea of returning an integer was to be able to showif the result was an updated variable or a totally newone but this wasn't actually implemented.

int HiddenDump(void);

This function is designed to be used with a form topersist the data as <input type=hidden> fields. Wheninvoked it will output to stdout a complete list ofall variables and values. The output is not URL encodedbut is parsed for quotation marks which are replacedwith the %22 code. Use of this feature would involve yourcode outputting a <form> tag before calling this, alongside any other inputs your wish and then a </form> tag.The method returns the number of variables found in thelist and outputted to stdout.

int GetDump(void);

This method outputs a list of variable names and valuesin URL format (please note only the value is URL Encodedas all variable names must be URL-safe). This will outputto stdout a list of the form:VarOneName=Var+One+Content&VarTwoName=Var+Two+ContentSuitable for use in, for example, an a href statement orfor direct GET input. Although this function can be usedwith a form with a get or post method as part of theaction to persist data, it is suggested you use theHiddenDump() method for this.

~CGI_Interface();

The destructor. It is always important to properlydestroy the CGI_Interface instantiation to delete allthe nodes of the linked list and avoid memory leakageproblems. Do not call this directly, rather use theC++ delete instruction with a line such as:delete i;

** USING COOKIES **

Versions 2.06 and later support rudimentary cookies.Cookies are set using the SetCookie global function(from the cookie.h include file). Cookies are loadedinto the list using the CookieLoad method. Please seethe COOKIE document for more information.

If something is not covered in the reference and youwould like it added please visit the website forcontact information and request it.