aboutsummaryrefslogtreecommitdiff
path: root/src/cgi.h
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/cgi.h196
1 files changed, 196 insertions, 0 deletions
diff --git a/src/cgi.h b/src/cgi.h
new file mode 100644
index 0000000..8e9a584
--- /dev/null
+++ b/src/cgi.h
@@ -0,0 +1,196 @@
1/**\file cgi.h
2 * Describes extra params needed to use the Cgi class as well as the class
3 * itself.
4 *@author Mike Buland
5 */
6
7#include "linkedlist.h"
8#include "hashtable.h"
9#include "hashfunctionstring.h"
10
11#define VAR_STDINPUT 0x01 /**< Variable came from stdinput, web form */
12#define VAR_COOKIE 0x02 /**< Variable came from a cookie */
13#define VAR_CMDLINE 0x04 /**< Variable came from commandline / uri */
14#define VAR_ANY 0xFF /**< Mask including all other types */
15
16/**
17 * Cgi header processor originally designed for apache cgi programs. When used
18 * from apache with what I beleive are some sort of standard set of command
19 * line parameters and environment variables. This always worked for all of my
20 * purposes. This class will automatically extract all data from the system
21 * that you need and places it into tables and things for easy access.
22 * There are three types of input that data can come from, StandardInput,
23 * CommandLine, and Cookies. StandardInput is when you get formdata in
24 * multi-part forms, Cookies should usually be cookies that you set, and
25 * command line is everything after the question mark in the URL.
26 * This also contains some simple helpers for putting templated data into the
27 * HTTP data feed.
28 *@author Mike Buland
29 */
30class Cgi
31{
32public:
33 /**
34 * Create a complete CGI object, this object will automatically read data
35 * from all available sources and be ready for use on the very next line!
36 * If strSource is filled in it will also automatically read in a content
37 * file, which is a simple file format containing named blocks of reusable
38 * templates.
39 *@param strSource Set to a filename in order to load up a content file.
40 */
41 Cgi( const char *strSource = NULL );
42
43 /**
44 * Destroy the cgi object.
45 */
46 ~Cgi( );
47
48 /**
49 * Get's the value for a variable as a character string. The name is the
50 * name that was given on the URL or in the form or cookie. Skip can be
51 * set to any value above zero to retreive subsequent variables with the
52 * same name. The most obvious use of this is when dealing with file
53 * uploads, each file upload sends you three variables with the same name
54 * and different content. Finally the variable type determines where you
55 * will accept this variable from. This is generally a bit of a security
56 * thing, if you store login info in a cookie and don't want people getting
57 * in by faking the appropriate URL.
58 *@param name The name of the variable you wish to retreive.
59 *@param skip THe number of variables with the given name to skip before
60 * returning something meaningful. The only way to determine how many
61 * variables with the same name there are is to skip until you get a NULL
62 * value returned.
63 *@param type Can be set to any combination of VAR_STDINPUT, VAR_COOKIE,
64 * VAR_CMDLINE, or just VAR_ANY. This takes bitflags, so you can or the
65 * values together. If a variable is found but came from the wrong source
66 * it won't match any other criteria and will be treated as though it
67 * doesn't exist.
68 *@returns A null-terminated string representing the value of the requested
69 * variable, or NULL if the variable did not exist. If a variable does
70 * exist but has no value the string returned will start with a NULL char,
71 * but be a valid string.
72 */
73 char *getVarValue( const char *name, int skip=0, unsigned char type=VAR_ANY );
74
75 /**
76 * This functions identically in every way to getVarValue, except that
77 * instead of returning a pointer to the variable's value, it returns the
78 * length of the variable's value string. The params are the same and so
79 * a call to both functions with the same params should yeild a value and
80 * a corresponding length.
81 *@param name The name of the variable you wish to retreive.
82 *@param skip THe number of variables with the given name to skip before
83 * returning something meaningful. The only way to determine how many
84 * variables with the same name there are is to skip until you get a NULL
85 * value returned.
86 *@param type Can be set to any combination of VAR_STDINPUT, VAR_COOKIE,
87 * VAR_CMDLINE, or just VAR_ANY. This takes bitflags, so you can or the
88 * values together. If a variable is found but came from the wrong source
89 * it won't match any other criteria and will be treated as though it
90 * doesn't exist.
91 *@returns The length of the value-string of the requested variable. If
92 * the requested variable is not found, -1 is returned.
93 */
94 int getVarLength( const char *name, int skip=0, unsigned char type=VAR_ANY );
95
96 /**
97 * A handy little function that writes a load of debug info related to
98 * parsing CGI params to the standard output in html. This is generally
99 * best used at the end of a page.
100 */
101 void writeDebugInfo();
102
103 /**
104 * Write a content header to the standard output. This should also be the
105 * first thing that you do (except for writing cookies) after initializing
106 * the Cgi class. You can select a type of header or content from the
107 * header enum, and a properly formatted header will show up on the
108 * standard output.
109 *@param type Any value from the header enum in this class. The default is
110 * to write an html header, probably the most common as well.
111 */
112 void writeContentHeader( int type=headerHTML );
113
114 /**
115 * Write content to the stnadard output. The content variable should have
116 * been loaded during construction of the Cgi object or with the
117 * loadContent function. The content variable should be formatted just like
118 * a printf string, so that anything you want to put into it will have a %
119 * symbol replacement code, like %s, %d, etc. Since this actually uses a
120 * type of printf function everything from those docs work here.
121 *@param name The name of the content variable to format and write to
122 * stnadard output.
123 *@param ... As many params as you want to include, ala printf.
124 */
125 void writeContent( const char *name, ...);
126
127 /**
128 * Load a content file. I don't want to describe the format here, you can
129 * just read the code or find an example for now. Sorry.
130 *@param strSource The name of the file to open and read in to get the
131 * content loaded.
132 */
133 void loadContent( const char *strSource = NULL );
134
135 /**
136 * Write a cookie-set header to the output stream. This should be done
137 * before any other content-headers are written. The specifics of this
138 * function are very simple, since I rely on the user's understanding of
139 * how standard HTTP/1.1 or HTTP/1.0 cookie syntax works. If you don't
140 * care then just use the name and value and the defaults should keep you
141 * in good stead for a long time.
142 *@param name The name of the cookie variable to set.
143 *@param value The value to set to that variable.
144 *@param expires The formatted string value for the date and time this
145 * cookie should expire. A NULL here will put a "until the browser closes"
146 * tag in.
147 *@param path The path (URL) that this cookie belongs to. If you run a lot
148 * of hosted servers or sub-sites that may have some shared URL bits then
149 * you may want to set this. The cookie should only be sent to URL's that
150 * match this as their first part.
151 *@param domain The domain that is allowed to read this, if not set, it's
152 * the domain the web browser contacted when they got the cookie.
153 *@param secure I'm not sure, I think it's something to tell if the cookie
154 * is safe to keep because any potentially valuable data is encypted or
155 * otherwise unusable. I could be wrong.
156 */
157 void writeCookie( char const *name, char const *value, char const *expires=NULL, char const *path=NULL, char const *domain=NULL, bool secure=false );
158
159 /**
160 * A simple helper class to contain variable data.
161 */
162 class Item
163 {
164 public:
165 /**
166 * Build an empty Item.
167 */
168 Item( )
169 {
170 name = NULL;
171 value = NULL;
172 len = 0;
173 type = 0;
174 }
175 /** The name of the item. */
176 char *name;
177 /** The value of the item. */
178 char *value;
179 /** The length of the item's value. */
180 unsigned long len;
181 /** The type of the item (where it came from). */
182 unsigned char type;
183 };
184
185 /** Header values */
186 enum
187 {
188 headerHTML
189 };
190
191private:
192 /** Keeps track of all contained variables. */
193 LinkedList aVars;
194 /** Keeps track of all content variables. */
195 HashTable aContent;
196};