FBB::CGI - handles GET and POST submitted form data
SYNOPSIS
#include <bobcat/cgi>
Linking option: -lbobcat
DESCRIPTION
The class CGI offers an interface to data submitted by web-forms. The
data is sent to a script handling the data using a <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 CGI allows C++ programmers to process the form by an executable
which usually results in faster processing and at construction time benefits
from the type safety offered by C++. The class CGI handles data
submitted using the GET method as well as data submitted using the
POST method automatically.
By default the class's constructor writes the customary 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:
// 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 FBB::Errno exception is
thrown.
NAMESPACE
FBB
All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace FBB.
INHERITS FROM
-
TYPEDEF
CGI::MapStringVector:
A shorthand for std::map<std::string, std::vector<std::string> >,
which is the data type in which form-variables are stored.
ENUMERATIONS
The CGI::Method enumeration specifies values indicating the way the
form's data were submitted:
CGI::UNDETERMINED:
Used internally indicating that the form's method was neither GET
nor POST.
CGI::GET:
Indicates that the GET method was used when submitting the form's
data;
CGI::POST:
Indicates that the POST method was used when submitting the form's
data.
The CGI::Create enumeration is used to request or suppress creation of
the directory to contain any file uploaded by a form:
CGI::DONT_CREATE_PATH:
When uploading files, the destination directory must exist;
CGI::CREATE_PATH:
When uploading files, the destination directory will be created.
CONSTRUCTORS
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 std::cout for output. Specifying 0
as header suppresses outputting the Content-type line. Otherwise the
content type line is also followed by two \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 which will be escaped. The backslash is the escape character. It
will be used unescaped only if the defaultEscape value is specified as
false and no insertions were performed.
The copy constructor is available.
OERLOADED OPERATORS
Note: the following three insertion operators defining sets of
characters that should be escaped can only be used until the first time one of
the param(), begin() or end() members is called. Once one of these
latter three members has been called the set of characters to be escaped is
fixed and attempts to modify them will fail silently.
CGI &operator<<(std::string const &accept):
This member's actions are suppressed once param(), begin() or
end() (see below) has been called.
The insertion operator can be used to fine-tune the set of characters
that will be shown escaped in strings returned by param() (see
below). Depending on the value of the constructor's defaultEscape
parameter characters inserted into the CGI object will or will not
be escaped by a backslash. If the constructor's defaultEscape
parameter was specified as true then the insertion operator will
define a set of characters that will not be escaped. If
defaultEscape was specified as false then the insertion
operator will define a set of characters that will be
escaped. Once an insertion operator has been used the backlash itself
will always be escaped and a request to use it unescaped is silently
ignored. The accept string can be specified as a regular
expression character set without specifying the surrounding square
brackets. E.g., an insertion like cgi << "-a-z0-9" will accept the
dash, lower case letters and the digits. Individual characters,
character ranges using the dash and all standard character classes
([:alnum:], [:alpha:], [:cntrl:], [:digit:], [:graph:], [:lower:],
[:print:], [:punct:], [:space:], [:upper:], and [:xdigit:]) can be
used to specify a set of characters. In addition to these standard
character classes the class [:cgi:] is available representing the
set " ' ` ; and \. Note that standard character classes
do require you to specify square brackets. When a series of
insertions are performed then the union of the sets defined by these
insertions are used. Note: using unescaped single quotes, the
double quotes, backtick characters and semicolons in CGI-programs
might be risky and is not advised.
CGI &operator<<(int c):
This member's actions are suppressed once param(), begin() or
end() (see below) has been called.
This insertion operator is used to change the default escape handling
of a single character c. The int parameter is cast internally
to a char.
CGI &operator<<(std::pair<char, char> range):
This member's actions are suppressed once param(), begin() or
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.
std::ostream &std::operator<<(std::ostream &out, CGI const &cgi): CGI objects can be inserted into ostreams to display the
characters that will appear escaped in strings returned by the
param() member function. Each character for which isprint()
returns 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.
char const *operator[](std::string const &key) const:
The index operator returns the value of the environment variable
specified as the index. An empty string is returned if the variable
specified at key is not defined.
The assignment operator is available.
MEMBER FUNCTIONS
CGI::MapStringVector::const_iterator begin() const:
Returns the begin iterator of the form's parameter map. Iterator values
unequal 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 param() member below.
CGI::MapStringVector::const_iterator end() const:
Returns the end iterator of the form's parameter map.
unsigned long long maxUploadSize() const:
Returns the current maximum file upload size in bytes.
CGI::Method method() const:
Returns the method used when submitting the form as either CGI::GET
or CGI::POST.
std::string const &query() const:
Returns the query-string submitted with CGI::GET or CGI::POST
forms (if the POSTed form specified
ENCTYPE="multipart/form-data" the query string is empty).
std::vector<std::string> const ¶m(std::string const &variable)
const:
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
multipart/form-data) then the vector will contain multiple
strings. With GET and POST methods not using
multipart/form-data input fields extending over multiple lines are
stored in one string, using \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.,
application/octet-stream), the fourth string contains OK if
the file was successfully uploaded and 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.
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 path/prefixNr where Nr
is an internally used number starting at one. When CREATE_PATH is
specified path must be available or the CGI object must be
able to create the path. If DONT_CREATE_PATH is specified the
specified path must be available. If not, an FBB::Errno exception
will be thrown.
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 unit can be one of b
(bytes, the default), K (Kbytes), M (Mbytes) or G
(Gbytes). Unit-specifiers are interpreted case insensitively. File
uploads will continue until the maximum upload size is exceeded,
followed by discarding any remainder.
The first time one of the param(), begin() or 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
FBB::Errno exception will be thrown.
To test the program provide it, e.g., with the following file at its standard
input:
INFO=This is an abbreviated set of environment variables
SERVER_ADMIN=f.b.brokken@rug.nl
GATEWAY_INTERFACE=CGI/1.1
SERVER_PROTOCOL=HTTP/1.1
REQUEST_METHOD=GET
QUERY_STRING=hidden=hidval&submit=Submit+%20Query
FILES
bobcat/cgi - defines the class interface
SEE ALSO
bobcat(7)
BUGS
None Reported.
DISTRIBUTION FILES
bobcat_2.02.03-x.dsc: detached signature;
bobcat_2.02.03-x.tar.gz: source archive;
bobcat_2.02.03-x_i386.changes: change log;
libbobcat1_2.02.03-x_*.deb: debian package holding the
libraries;
libbobcat1-dev_2.02.03-x_*.deb: debian package holding the
libraries, headers and manual pages;
http://sourceforge.net/projects/bobcat: public archive location;
BOBCAT
Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.
COPYRIGHT
This is free software, distributed under the terms of the
GNU General Public License (GPL).