1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
|
includefile(include/header)
COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::CGI)(3bobcat)(_CurYrs_)(libbobcat-dev__CurVers_)
(CGI interface)
manpagename(FBB::CGI)(handles GET and POST submitted form data)
manpagesynopsis()
bf(#include <bobcat/cgi>)nl()
Linking option: tt(-lbobcat)
manpagedescription()
The class tt(CGI) offers an interface to data submitted by web-forms. The
data is sent to a script handling the data using a tt(<form
action="/path/to/form/script">) stanza. Very often this is indeed a script,
like a Perl script, but there is no need to use a scripting language. The
class tt(CGI) allows bf(C++) programmers to process the form by an executable
usually resulting in faster processing and in construction time benefits from
the type safety offered by bf(C++). The class tt(CGI) automatically handles
data submitted using the tt(GET) method as well as data submitted using the
tt(POST) method.
By default the class's constructor writes the customary tt(Content-type)
header lines to the standard output stream. Additional (html) output of a
reply page must be provided by other code. Therefore, a program processing an
uploaded form will have an organization comparable to the following basic
setup:
verb(
// assume includes and namespace std/FBB were defined
int main()
{
CGI cgi;
cout << "<html><body>\n";
if (parametersOK(cgi))
{
process(cgi);
generateReplyPage();
}
else
generateErrorPage();
cout << "</body></html>\n;
}
)
When errors in the received form-data are detected an error message is
written to the standard output stream and an tt(FBB::Exception) exception is
thrown.
includefile(include/namespace)
manpagesection(INHERITS FROM)
-
manpagesection(TYPEDEF)
itemization(
itb(CGI::MapStringVector)
A shorthand for tt(std::unordered_map<std::string,
std::vector<std::string> >),
which is the data type in which form-variables are stored.
)
manpagesection(ENUMERATIONS)
The tt(CGI::Method) enumeration specifies values indicating the way the
form's data were submitted:
itemization(
itb(CGI::UNDETERMINED)
Used internally indicating that the form's method was neither tt(GET)
nor tt(POST).
itb(CGI::GET)
Indicates that the tt(GET) method was used when submitting the form's
data;
itb(CGI::POST)
Indicates that the tt(POST) method was used when submitting the form's
data.
)
The tt(CGI::Create) enumeration is used to request or suppress creation of
the directory to contain any file uploaded by a form:
itemization(
itb(CGI::DONT_CREATE_PATH)
When uploading files, the destination directory must exist;
itb(CGI::CREATE_PATH)
When uploading files, the destination directory will be created.
)
manpagesection(CONSTRUCTORS)
itemization(
itb(CGI(bool defaultEscape = true,
char const *header = "Content-type: text/html",
std::ostream &out = std::cout))
The default constructor writes the standard content type header to the
standard output stream and will use tt(std::cout) for output. Specifying tt(0)
as header suppresses outputting the tt(Content-type) line. Otherwise the
content type line is also followed by two tt(\r\n) character combinations. By
default all characters in retrieved form-variables are escaped. The overloaded
insertion operators (see below) can be used to modify the default set of
characters to escape. The backslash is used as the escape character. The
escape-prefix is not used if the tt(defaultEscape) value is specified as
tt(false) and if no insertions into the bf(CGI) object were performed.
)
Copy and move constructors (and assignment operators) are available.
manpagesection(OERLOADED OPERATORS)
bf(Note:) the following three insertion operators, defining sets of
characters that should be escaped, can only be used before calling any of the
tt(param, begin) or tt(end) members. As soon as one of these latter three
members has been called the set of characters to be escaped is fixed and
attempts to modify that set is silently ignored.
itemization(
itb(char const *operator[](std::string const &key) const)
The index operator returns the value of the environment variable
specified as the index. 0 is returned if the variable
specified at tt(key) is not defined.
itb(CGI &operator<<(std::string const &accept))
This member's actions are suppressed once tt(param, begin) or
tt(end) (see below) has been called.
The insertion operator can be used to fine-tune the set of characters
that are escaped in strings returned by tt(param) (see
below). Depending on the value of the constructor's tt(defaultEscape)
parameter characters inserted into the tt(CGI) object will or will not
be escaped by a backslash.
If the constructor's tt(defaultEscape) parameter was specified as
tt(true) then the insertion operator can be used to define a set of
characters that are em(not) escaped.
If tt(defaultEscape) was specified as tt(false) then the insertion
operator will define a set of characters that em(will) be
escaped.
The backlash itself is always escaped and a request to use it
unescaped is silently ignored.
The tt(accept) string can be specified as a regular expression
character set, without the usual surrounding square brackets. E.g., an
insertion like tt(cgi << "-a-z0-9") defines the set consisting of the
dash, the lower case letters and the digits.
Individual characters, character ranges (using the dash to specify a
range) and all standard character classes (tt([:alnum:], [:alpha:],
[:cntrl:], [:digit:], [:graph:], [:lower:], [:print:], [:punct:],
[:space:], [:upper:]), and tt([:xdigit:])) can be used to specify a
set of characters. In addition to these standard character classes the
class tt([:cgi:]) can be used to define the set consisting of the
characters tt(" ' ` ;) and tt(\).
Note that standard and tt([:cgi:]) character classes em(do) require
square brackets.
When a series of insertions are performed then the union of the sets
defined by these insertions are used.
bf(Note): using unescaped single quotes, the double quotes, backtick
characters and semicolons in CGI-programs might be risky and is not
advised.
itb(CGI &operator<<(int c))
This member's actions are suppressed once tt(param, begin) or
tt(end) (see below) has been called.
This insertion operator is used to change the default escape handling
of a single character tt(c). The tt(int) parameter is cast internally
to a tt(char).
itb(CGI &operator<<(std::pair<char, char> range))
This member's actions are suppressed once tt(param, begin) or
tt(end) (see below) has been called.
This insertion operator can be used to change the default escape
handling of a range of characters. The pair's second character must be
equal to or exceed the position of the pair's first character in the
ASCII collating sequence or the member will have no effect.
itb(std::ostream &std::operator<<(std::ostream &out, CGI const &cgi))
tt(CGI) objects can be inserted into tt(ostreams) to display the
characters that will appear escaped in strings returned by the
tt(param()) member function. Each character for which tt(isprint())
returns tt(true) will be displayed as character, surrounded by single
quotes. For all other characters their ASCII values are displayed.
Each character is displayed on a line by itself.
)
manpagesection(MEMBER FUNCTIONS)
itemization(
itb(CGI::MapStringVector::const_iterator begin())
Returns the begin iterator of the form's parameter map. Iterator values
unequal to tt(end) (see below) point to a pair of values, the first of
which is the name of a field defined by the form, the second is a
vector of strings containing the field's value(s). See also the
description of the tt(param) member below.
itb(CGI::MapStringVector::const_iterator end())
Returns the end iterator of the form's parameter map.
itb(unsigned long long maxUploadSize() const)
Returns the current maximum file upload size in bytes.
itb(CGI::Method method() const)
Returns the method that was used when the form was submitted (either
tt(CGI::GET) or tt(CGI::POST)).
itb(std::vector<std::string> const ¶m(std::string const &variable))
Returns the value of the form-variable specified by the function's
argument. An empty vector is returned if the variable was not provided
by the form's data.
If the same variable was specified multiple times or if its value
extends over multiple lines (only with tt(multipart/form-data)) then
the vector contains multiple strings.
With tt(GET) and tt(POST) methods not using tt(multipart/form-data)
input fields extending over multiple lines are stored in one string,
using tt(\r\n) combinations between those lines.
When files are uploaded the vectors contain sets of four
strings. The first string provides the path nme of the uploaded file;
the second string provides the file name specified in the form itself
(so it is the name of the file at the remote location); the third
string shows the content type specified by the remote browser (e.g.,
tt(application/octet-stream)), the fourth string contains tt(OK) if
the file was successfully uploaded and tt(truncated) if the file was
truncated. Existing files will not be overwritten. When uploading a
file a usable filename must be found within 100 trials.
itb(std::string param1(std::string const &variable) const)
Returns the first element of the tt(vector<string>) returned by the
tt(param) member or an empty string if tt(variable) was not defined by
the received form.
itb(std::string const &query() const)
Returns the query-string submitted with tt(CGI::GET) or tt(CGI::POST)
forms (if the tt(POST)ed form specified
tt(ENCTYPE="multipart/form-data") the query string is empty).
itb(report+CHAR(40)CHAR(41))
The tt(report) member silently returns if no errors were encountered
while processing form-data. Otherwise, the tt(html) file generated by
the tt(CGI) program displays a line starting with tt(FBB::CGI),
followed by the status report.
The following status report messages are presently defined:
tt(Content-Disposition not recognized in:), which is followed by the
line where the tt(Content-Disposition) was expected. This may occur
when processing tt(multipart/form) data.
tt(Invalid multipart/form-data). This message can be generated when
readling lines while processing tt(multipart/form) data.
tt(GET/POST REQUEST_METHOD not found). This message is shown if the
program couldn't find the form's tt(REQUEST_METHOD) type (i.e.,
tt(GET) or tt(POST)).
tt(Invalid CONTENT_LENGHT in POSTed form). This message is shown if
the content-length header has an incorrect value.
tt(Content-Type not found for file-field), followed by the file's
field name. This message is shown if no tt(Content-Type) specification
was found in an uploaded form.
tt(Can't open a file to write an uploaded file). This message
indicates that the CGI program was unable to open a file to write an
uploaded file to. This can be caused by an overfull disk or partition
or by incorrect write-permissions.
tt(multipart/form-data: no end-boundary found). This message is shown
if the end-boundary was missing in a tt(multipart/form-data) form.
itb(void setFileDestination(std::string const &path,
std::string const &prefix = "",
Create create = CREATE_PATH))
This member is used to specify the path and prefix of uploaded
files. Uploaded files will be stored at tt(path/prefixNr) where tt(Nr)
is an internally used number starting at one. When tt(CREATE_PATH) is
specified tt(path) must be available or the bf(CGI) object must be
able to create the path. If tt(DONT_CREATE_PATH) is specified the
specified path must be available. If not, an tt(FBB::Exception)
exception will be thrown.
itb(void setMaxUploadSize(size_t maxSize, int unit = 'M'))
This member can be used to change the maximum size of uploaded
files. Its default value is 100Mb. The tt(unit) can be one of tt(b)
(bytes, the default), tt(K) (Kbytes), tt(M) (Mbytes) or tt(G)
(Gbytes). Unit-specifiers are interpreted case insensitively. File
uploads will continue until the maximum upload size is exceeded,
followed by discarding any remainder.
itb(void swap(CGI &other))
The current and tt(other) object are swapped.
)
The first time one of the tt(param(), begin()) or tt(end()) members is
called these members may detect errors in the the received form data. If so,
an error message is written to the standard output stream and an
tt(FBB::Exception) exception will be thrown.
manpagesection(STATIC MEMBERS)
itemization(
itb(std::string dos2unix(std::string const &text))
This member converts all tt(\r\n) character combinations in tt(text)
into plain tt(\n) characters, returning the converted text.
itb(std::string unPercent(std::string const &text)) This member converts
all tt(%xx) encoded characters into their corresponding ASCII
values. Also, tt(+) characters are converted to single blank
spaces. The converted string is returned.
)
manpagesection(EXAMPLE)
verbinclude(../../cgi/driver/driver.cc)
To test the program's tt(get) form processing, call it as tt(driver get
'[:cgi:]'), with the file tt(get) containing:
verbinclude(../../cgi/driver/get)
To test the program's tt(post) form processing, call it as tt(driver post1
'[:cgi:]'), using tt(post1) and tt(post1.cin) found in Bobcat's source archive
under tt(../cgi/driver).
manpagefiles()
em(bobcat/cgi) - defines the class interface
manpageseealso()
bf(bobcat)(7)
manpagebugs()
None Reported.
includefile(include/trailer)
|
