GNU Cgicc
This document describes the GNU Cgicc library, a C++ class library that
facilitates the development of Common Gateway Inteface (CGI)
applications for the World Wide Web (WWW).
This is edition 3.1.3 of the Cgicc documentation, 3 July 2000.
Node:Overview of CGI, Next:A tutorial example, Previous:Top, Up:Top
Overview of the Common Gateway Interface
What is the Common Gateway Interface?
The Common Gateway Interface (CGI) is a standard for external gateway
programs to interface with information servers, such as HTTP
servers1.
CGI scripts or CGI applications?
Historically, many CGI applications were written in scripting languages
such as Perl. Not surprisingly, CGI code called by the HTTP server was
referred to as a CGI script. As the popularity of the web grew
and the need for dynamic content increased, CGI applications written in
languages other than Perl became more and more popular. These
applications were referred to simply as scripts. Although the term
script does not make intuitive sense for a compiled program, the
term has stuck. In this manual, the terms script and
application are used interchangeably.
CGI processing
When an HTTP server receives a request for a CGI script, the
server communicates to the script the details of the request. The
HTTP server and a CGI script communicate in four major ways:
- Environment variables
The HTTP server uses environment variables to pass information
about the request to the CGI script. Depending on the type of
request, the environment variables may or may not contain all the
information required by the script to function properly.
- The command line
The command line is only used for ISINDEX queries. Generally,
ISINDEX queries should not be used; since the command line is used
directly, they present many potential security risks.
- Standard input
For HTTP POST or PUT queries, the HTTP server communicates
information to the CGI script via standard input. The amount of
information written to standard input is stored in the
CONTENT_LENGTH environment variable.
- Standard output
A script returns its output on standard output. The output can be a
document generated by the script, or instructions to the server for
retrieving the desired output.
Node:A tutorial example, Next:Library overview, Previous:Overview of CGI, Up:Top
A tutorial example
Introduction
It is easiest to understand how Cgicc might be used by first looking at
an example. Suppose you have an HTML form on your web site asking a
user to enter their name, age, and sex, perhaps as part of a
user-registration procedure. You wish to write a CGI script using Cgicc
to process the form in some meaningful way.
Applications written using Cgicc, like all other applications, begin
with a main function:
int main(int argc, char **argv)
{
// CGI processing goes here
}
Initialization
The three main classes of Cgicc you will use to process the submitted
data are Cgicc, CgiEnvironment, and FormEntry.
These classes will be explained in detail later; for now, it is
sufficient to know that:
- The class
Cgicc is used for retrieving information on the
submitted form elements.
- The class
CgiEnvironment is used to retrieve information on
environment variables passed from the HTTP server.
- The class
FormEntry is used to extract various types of data from
the submitted form elements.
All of Cgicc's functionality is accessed through class Cgicc.
Thus, the first step in CGI processing is to instantiate an object of
type Cgicc:
Cgicc cgi;
Upon instantiation, the class Cgicc parses all data passed to the
CGI script by the HTTP server.
Since errors are handled using exceptions, you may wish to wrap your CGI
code in a try block to better handle unexpected conditions:
try {
Cgicc cgi;
}
catch(exception& e) {
// Caught a standard library exception
}
Extracting Form Information
Each element of data entered by the user is parsed into a
FormEntry. A FormEntry contains methods for accessing
data as strings, integers, and doubles. In the hypothetical form
mentioned above, a user would enter their name, age, and sex.
Regardless of the type of value, the data is accessed via
FormEntry2. You obtain
FormEntry objects via Cgicc's getElement methods,
all of which return typedefs of standard-library iterators:
form_iterator name = cgi.getElement("name");
If the item is not found, the iterator will refer to an invalid element,
and should not be dereferenced using operator* or
operator->. Cgicc provides methods for determining
whether an iterator refers to a valid element:
if(name != cgi.getElements().end()) {
// iterator refers to a valid element
}
Output of Form Data
Once you have a valid element, you will more than likely want to do
something with the data The simplest thing to do is just echo it back to
the user. You can extract a string from a FormEntry by
calling the getValue method. Since ostream has an
overload for writing basic_string objects, it is trivial to
output objects of this type:
cout << "Your name is " << name->getValue() << endl;
Since both iterator and FormEntry overload
operator*, the code given above may also be written as:
cout << "Your name is " << **name << endl;
The first * returns an object of type FormEntry, and the second *
returns an object of type string.
The HTTP Response
A CGI response will generally consist of an HTML document. The HTTP
protocol requires that a certain set of headers precede all documents,
to inform the client of the size and type of data being received, among
other things. In a normal CGI response, the HTTP server will take care
of sending many of these headers for you. However, it is necessary for
the CGI script to supply the type of content it is returning to the HTTP
server and the client. This is done by emitting a Content-Type
header3.
Cgicc provides several classes for outputting HTTP headers, all of which
begin with HTTP. A standard HTML document need only output a
single header:
cout << HTTPHTMLHeader() << endl;
Simple HTML Output
Cgicc provides one class for every HTML tag defined in the HTML 4.0
standard in the header file "cgicc/HTMLClasses.h". These classes
have the same name as the HTML tags. For example, in HTML, to indicate
the start of a document you write <HTML>; this can be accomplished
using Cgicc by writing
cout << html() << endl;
The class html keeps state internally, so the code above will
produce as output <HTML>; conversely, the code
cout << html() << "html text!" << html() << endl;
will produce as output <HTML>html text!</HTML>.
All of Cgicc's HTML output classes are subclasses of the abstract class
HTMLElement. You can embed the text for the element directly in
the constructor:
cout << html("html text!") << endl;
Furthermore, it is possible to embed one HTMLElement in another:
cout << head(title("Title")) << endl;
This produces as output <HEAD><TITLE>Title</TITLE></HEAD>.
More Complex HTML Output
In real HTML, most tags possess a set of attributes. For example, the
HTML <IMG> tag requires certain attributes specifying the source
image file, the image width, height, and so on. There are a bewildering
number of possible attributes in HTML 4.04. A typical <IMG> tag
might look like
<IMG SRC="file.jpg" WIDTH="100" HEIGHT="100" ALT="description">
This tag has four attributes: SRC, WIDTH, HEIGHT,
and ALT, with the values file.jpg, 100, 100,
and description, respectively. Attributes in HTML tags are
represented by the class HTMLAttribute, which essentially is a
name/value pair. To build an HTMLElement containing
HTMLAttribute objects, use the set method on
HTMLElement. To generate the <IMG> tag given above:
cout << img().set("SRC", "file.jpg")
.set("WIDTH", "100").set("HEIGHT", "100")
.set("ALT", "description") << endl;
In a similar way, multiple HTMLElement objects may be embedded at
the same level inside another HTMLElement. To build an
HTMLElement containing multiple embedded HTMLElement
objects, use the add method on HTMLElement:
cout << tr().add(td("0")).add(td("1")).add(td("2")) << endl;
This produces as output <TR><TD>0</TD><TD>1</TD><TD>2</TD></TR>.
Notes on Output
All of Cgicc's output is written to the C++ standard output stream,
cout. It is not necessary to use Cgicc's HTML output classes;
they are provided as a convenience. If you prefer, you may output the
HTML code directly to cout.
The Complete Example
The code below is a complete CGI program that synthesizes all the sample
code given in this chapter.
#include <iostream>
#include <vector>
#include <string>
#include "cgicc/Cgicc.h"
using namespace std;
using namespace cgicc;
int
main(int argc,
char **argv)
{
try {
Cgicc cgi;
// Send HTTP header
cout << HTTPHTMLHeader() << endl;
// Set up the HTML document
cout << html() << << head(title("Cgicc example")) << endl;
cout << body() << endl;
// Print out the submitted element
form_iterator name = cgi.getElement("name");
if(name != cgi.getElements().end()) {
cout << "Your name: " << **name << endl;
}
// Close the HTML document
cout << body() << html();
}
catch(exception& e) {
// handle any errors - omitted for brevity
}
}
Node:Library overview, Next:CGI classes, Previous:A tutorial example, Up:Top
Library overview
The GNU Cgicc library contains classes divided into two broad groups:
Node:CGI classes, Next:HTTP header classes, Previous:Library overview, Up:Top
CGI classes
CGI classes are used to query and manipulate CGI data passed from the
HTTP server.
Cgicc is the main class of the Cgicc library. It is used to
retrieve information on specific HTML form elements (such as checkboxes,
radio buttons, and text fields), on uploaded files, and to save,
restore, and retrieve information on the CGI environment.
See class Cgicc, for API details.
|
CgiEnvironment encapsulates the data passed from the HTTP server
to the CGI application. This includes all environment variables set by
the HTTP server specified in the CGI standard.
See class CgiEnvironment, for API details.
|
FormEntry is an immutable class representing a single user entry
in an HTML form element such as a text field, a radio button, or a
checkbox. A FormEntry is essentially a name/value pair, where
the name is the name of the form element as specified in the HTML form
itself, and the value is user-entered or user-selected
value. FormEntry provides methods allowing access to the value as
a string, integer, or double.
See class FormEntry, for API details.
|
FormFile is an immutable class representing a file uploaded via
the HTTP file upload mechanism. A FormFile is very similar to a
FormEntry, but does not provide the numerous methods for
accessing the value as different types.
See class FormFile, for API details.
|
Node:HTTP header classes, Next:HTML generation classes, Previous:CGI classes, Up:Top
HTTP header classes
HTTP headers are used to indicate to the client information on the data
being returned as a result of the CGI request. For example, standard
HTTP headers indicate the type, size, and modification date of the
transmitted data.
An HTTPCookie is a name/value pair used to store a piece of
information about the caller using the caller's own machine. Cookies
are often used as a means to identify users.
|
HTTPHeader is the base class for all HTTP headers. It is rarely
used directly; instead, use one of the provided subclasses.
|
HTTPContentHeader is a subclass of HTTPHeader used to
indicate the type of data returned to the client by the CGI application.
|
HTTPRedirectHeader is a subclass of HTTPHeader used to
redirect the client to a different URL.
|
HTTPStatusHeader is a subclass of HTTPHeader used to
return a 3-digit HTTP status code and the associated message.
|
HTTPNPHeader is a subclass of HTTPHeader used to indicate
to the HTTP server that it should not parse the data returned by the CGI
application. Normally, the HTTP server parses the data returned by the
CGI application and fills in certain headers, such as the data size.
|
HTTPHTMLHeader is a subclass of HTTPContentHeader used for
data of MIME type text/html.
|
HTTPPlainHeader is a subclass of HTTPContentHeader used
for data of MIME type text/plain.
|
HTTPGIFHeader is a subclass of HTTPContentHeader used for
data of MIME type image/gif.
|
HTTPJPEGHeader is a subclass of HTTPContentHeader used for
data of MIME type image/jpeg.
|
HTTPXBMHeader is a subclass of HTTPContentHeader used for
data of MIME type image/x-xbitmap.
|
HTTPAudioHeader is a subclass of HTTPContentHeader used
for data of MIME type audio/basic.
|
Node:HTML generation classes, Next:class Cgicc, Previous:HTTP header classes, Up:Top
HTML generation classes
The Cgicc library provides one class for each HTML element defined in
the HTML 4.0 specification. In all cases, the name of the class
corresponds to the name of the HTML element.
|
This class is used to specify the HTML version information as required
by the HTML 4.0 standard.
|
Node:class Cgicc, Next:class CgiEnvironment, Previous:HTML generation classes, Up:Top
class Cgicc
Cgicc is the main class of the Cgicc library. It is used to
retrieve information on specific HTML form elements (such as checkboxes,
radio buttons, and text fields), on uploaded files, and to save,
restore, and retrieve information on the CGI environment.
Constructors
| void Cgicc ()
|
Method on Cgicc |
Constructor. Upon creation, Cgicc performs all necessary CGI
initialization.
|
Library Information
| const char* getCompileDate () const
|
Method on Cgicc |
Get the date at which the library was compiled. The string returned is
of the format mmm dd yyyy.
|
| const char* getCompileTime () const
|
Method on Cgicc |
Get the time at which the library was compiled. The string returned is
of the format hh:mm:ss in 24-hour time.
|
| const char* getVersion () const
|
Method on Cgicc |
Get the version number of Cgicc. The string returned is of the format
#.#.
|
| const char* getHost () const
|
Method on Cgicc |
Get the host for which Cgicc was configured. The string returned is a
canonical host triplet of the form processor-manufacturer-os.
|
Form Element Access
| form_iterator vector::iterator
|
Data Type |
|
A standard template library iterator referring to a FormEntry object.
|
| const_form_iterator vector::const_iterator
|
Data Type |
|
A standard template library iterator referring to a constant FormEntry object.
|
| file_iterator vector::iterator
|
Data Type |
|
A standard template library iterator referring to a FormFile object.
|
| const_file_iterator vector::const_iterator
|
Data Type |
|
A standard template library iterator referring to a constant FormFile object.
|
| bool queryCheckbox (const string& elementName) const
|
Method on Cgicc |
Returns true if a checkbox with name elementName is
checked, false otherwise.
|
| form_iterator operator[] (const string& name)
|
Method on Cgicc |
Find a radio button in a radio group, or a selected list item with
element name name. If an element with name name is not
found, the returned iterator will be set to the value returned by
getElements().end().
|
| const_form_iterator operator[] (const string& name) const
|
Method on Cgicc |
Find a radio button in a radio group, or a selected list item with
element name name. If an element with name name is not
found, the returned iterator will be set to the value returned by
getElements().end().
|
| form_iterator getElement (const string& name)
|
Method on Cgicc |
Find a radio button in a radio group, or a selected list item with
element name name. If an element with name name is not
found, the returned iterator will be set to the value returned by
getElements().end().
|
| const_form_iterator getElement (const string& name) const
|
Method on Cgicc |
Find a radio button in a radio group, or a selected list item with
element name name. If an element with name name is not
found, the returned iterator will be set to the value returned by
getElements().end().
|
| bool getElement (const string& name, vector& result) const
|
Method on Cgicc |
Find multiple checkboxes in a group, or selected items in a list with
element name name. Returns true if any items with name
name were found, false otherwise.
|
| form_iterator getElementByValue (const string& value)
|
Method on Cgicc |
Find a radio button in a radio group, or a selected list item with
element value value. If an element with value value is not
found, the returned iterator will be set to the value returned by
getElements().end().
|
| const_form_iterator getElementByValue (const string& name) const
|
Method on Cgicc |
Find a radio button in a radio group, or a selected list item with
element value value. If an element with value value is not
found, the returned iterator will be set to the value returned by
getElements().end().
|
| bool getElementByValue (const string& name, vector& result) const
|
Method on Cgicc |
Find multiple checkboxes in a group, or selected items in a list with
element value value. Returns true if any items with value
value were found, false otherwise.
|
| const vector& operator* () const
|
Method on Cgicc |
|
Get all the submitted form elements, excluding files.
|
| const vector& getElements () const
|
Method on Cgicc |
|
Get all the submitted form elements, excluding files.
|
Uploaded File Access
| file_iterator getFile (const string& name)
|
Method on Cgicc |
Find an uploaded file with element name name. If a file belonging
to element name name is not found, the returned iterator will be
set to the value returned by getFiles().end().
|
| const_file_iterator getFile (const string& name) const
|
Method on Cgicc |
Find an uploaded file with element name name. If a file belonging
to element name name is not found, the returned iterator will be
set to the value returned by getFiles().end().
|
| const vector& getFiles () const
|
Method on Cgicc |
Environment Access
| const CgiEnvironment& getEnvironment () const
|
Method on Cgicc |
|
Returns the current CGI environment.
|
Save and Restore
| void save (const string& filename) const
|
Method on Cgicc |
|
Save the current CGI environment to a file with name filename.
|
| void restore (const string& filename)
|
Method on Cgicc |
|
Restore the CGI environment from a previously-saved environment
contained in file filename.
|
Node:class CgiEnvironment, Next:class FormEntry, Previous:class Cgicc, Up:Top
class CgiEnvironment
CgiEnvironment encapsulates the data passed from the HTTP server
to the CGI application. This includes all environment variables set by
the HTTP server specified in the CGI standard.
Constructor
| void CgiEnvironment ()
|
Method on CgiEnvironment |
Constructor - not usually called directly. Instead, an object of type
CgiEnvironment is retrieved by calling the
getEnvironment() method on Cgicc.
|
Server Information
| string getServerSoftware () const
|
Method on CgiEnvironment |
Get the name and version of the HTTP server software, for example
Apache/1.3.4.
|
| string getServerName () const
|
Method on CgiEnvironment |
Get the hostname, DNS name, or IP address of the HTTP server. This is
not a URL; for example, www.gnu.org.
|
| string getGatewayInterface () const
|
Method on CgiEnvironment |
Get the name and version of the gateway interface. This is usually
CGI/1.1.
|
| string getServerProtocol () const
|
Method on CgiEnvironment |
Get the name and revision of the protocol used for this request. This is
usually HTTP/1.0.
|
| unsigned long getServerPort () const
|
Method on CgiEnvironment |
|
Get the port number on the server to which this request was sent. This
will usually be 80.
|
| bool usingHTTPS () const
|
Method on CgiEnvironment |
Returns true if this is a secure request using the HTTPS
protocol, false otherwise.
|
CGI Query Information
| string getCookies () const
|
Method on CgiEnvironment |
Get the HTTP cookies associated with this query, if any. The string
returned by this method may contain multiple cookies; it is recommended
to use the method getCookieList() instead, which returns a
vector<HTTPCookie>.
|
| const vector& getCookieList () const
|
Method on CgiEnvironment |
Get a vector containing the HTTP cookies associated with this
query, if any.
|
| string getRequestMethod () const
|
Method on CgiEnvironment |
Get the request method used for this query. It is usually one of
GET or POST.
|
| string getPathInfo () const
|
Method on CgiEnvironment |
|
Get the extra path information for this request, given by the client.
|
| string getPathTranslated () const
|
Method on CgiEnvironment |
Get the translated path information for this request (the virtual to
physical mapping; for example, www.gnu.org to
/htdocs/index.html.
|
| string getScriptName () const
|
Method on CgiEnvironment |
|
Get the full path of this CGI application, for self-referential URIs.
|
| string getQueryString () const
|
Method on CgiEnvironment |
Get the string following the ? in the URI which called this CGI
application. The query string is only valid for applications called via
the GET method. For example, in the URI
foo.cgi?cgicc=yes, the query string is cgicc=yes.
|
| unsigned long getContentLength () const
|
Method on CgiEnvironment |
Get the length of the data read from stdin, in chars. This is
only valid for applications called via the POST method.
|
| string getContentType () const
|
Method on CgiEnvironment |
Get the content type of the submitted information. For applications
called via the GET method, this information is irrelevant. For
applications called via the POST method, this is usually
application/x-www-form-urlencoded.
|
| string getPostData () const
|
Method on CgiEnvironment |
Get the data passed via stdin. This data is of MIME type
getContentType().
|
Server Specific Information
| string getReferrer () const
|
Method on CgiEnvironment |
|
Get the URI which called this CGI application. Depending on the HTTP
server software, this value may not be set.
|
Remote User Information
| string getRemoteHost () const
|
Method on CgiEnvironment |
|
Get the hostname of the remote machine making the request.
|
| string getRemoteAddr () const
|
Method on CgiEnvironment |
|
Get the IP address of the remote machine making the request.
|
| string getAuthType () const
|
Method on CgiEnvironment |
|
Get the protocol-specific user authentication method used. This is only
applicable if the server supports user authentication, and the user has
authenticated.
|
| string getRemoteUser () const
|
Method on CgiEnvironment |
|
Get the authenticated remote user name. This is only applicable if the
server supports user authentication, and the user has authenticated.
|
| string getRemoteIdent () const
|
Method on CgiEnvironment |
|
Get the remote user name retrieved from the server. This is only
applicable if the server supports RFC 931 (obsoleted by RFC 1431)
identification 15.
This should only be used for logging purposes.
|
| string getAccept () const
|
Method on CgiEnvironment |
Get the MIME data types accepted by the client's browser. This format
of this string is a comma (,) separated list.
|
| string getUserAgent () const
|
Method on CgiEnvironment |
Get the name of the browser used for this CGI request. For example,
Mozilla/4.1 [en] (WinNT; U).
|
ErrorDocument Handling
(For a tutorial on ErrorDocument handling, see
<http://hoohoo.ncsa.uiuc.edu/cgi/ErrorCGI.html>)
| string getRedirectRequest () const
|
Method on CgiEnvironment |
|
Get the redirect request. This will only be valid if you are using this
CGI application in place of the default server messages during
ErrorDocument handling.
|
| string getRedirectURL () const
|
Method on CgiEnvironment |
|
Get the redirect URL. This will only be valid if you are using this CGI
application in place of the default server messages during ErrorDocument
handling.
|
| string getRedirectStatus () const
|
Method on CgiEnvironment |
|
Get the redirect status. This will only be valid if you are using this
CGI application in place of the default server messages during
ErrorDocument handling.
|
Node:class FormEntry, Next:class FormFile, Previous:class CgiEnvironment, Up:Top
class FormEntry
FormEntry is an immutable class representing a single user entry
in an HTML form element such as a text field, a radio button, or a
checkbox. A FormEntry is essentially a name/value pair, where
the name is the name of the form element as specified in the HTML form
itself, and the value is the user-entered or user-selected value.
Constructors
| void FormEntry ()
|
Method on FormEntry |
|
Default constructor - should not generally be used.
|
| void FormEntry (const string& name, const string& value)
|
Method on FormEntry |
|
Constructor. name is the name of the form element, and
value is the value of the form element.
|
| void FormEntry (const FormEntry& entry)
|
Method on FormEntry |
Copy constructor. entry is the FormEntry to copy.
|
Overloaded Operators
| bool operator== (const FormEntry& entry) const
|
Method on FormEntry |
Equality operator. Returns true if entry has the same name
and value as this FormEntry, false otherwise.
|
| bool operator!= (const FormEntry& entry) const
|
Method on FormEntry |
Inequality operator. Returns false if entry has the same name
and value as this FormEntry, true otherwise.
|
| FormEntry& operator= (const FormEntry& entry)
|
Method on FormEntry |
Assignment operator. Sets the name and value of this FormEntry to
those of entry.
|
| string operator* () const
|
Method on FormEntry |
|
Get the value of the form element. The value may contain line breaks.
|
Accessor Methods
| string getName () const
|
Method on FormEntry |
|
Get the name of the form element.
|
| string getValue () const
|
Method on FormEntry |
|
Get the value of the form element. The value may contain line breaks.
|
| string getValue (string::size_type maxChars) const
|
Method on FormEntry |
|
Get the value of the form element, truncated to at most maxChars
characters.
|
| string getStrippedValue () const
|
Method on FormEntry |
|
Get the value of the form element, stripped of any line breaks.
|
| string getStrippedValue (string::size_type maxChars) const
|
Method on FormEntry |
|
Get the value of the form element, stripped of any line breaks and
truncatd to maxChars characters.
|
| long getIntegerValue (long min = LONG_MIN, long max = LONG_MAX) const
|
Method on FormEntry |
|
Get the value of the form element as an integer. The optional
parameters min and max specify the legal range of return
values.
|
| double getDoubleValue (double min = DBL_MIN, double max = DBL_MAX) const
|
Method on FormEntry |
|
Get the value of the form element as a double. The optional
parameters min and max specify the legal range of return
values.
|
| string::size_type length () const
|
Method on FormEntry |
|
Get the number of characters in the value of this form element.
|
| bool isEmpty () const
|
Method on FormEntry |
Returns true if the form element is empty, that is, if
length() == 0.
|
Node:class FormFile, Next:classes for HTTP headers, Previous:class FormEntry, Up:Top
class FormFile
FormFile is an immutable class representing a file uploaded via
the HTTP file upload mechanism. If you are going to use file upload in
your CGI application, remember to set the ENCTYPE of the form to
multipart/form-data.
Constructors
| void FormFile ()
|
Method on FormFile |
|
Default constructor - should not generally be used.
|
| void FormFile (const string& name, const string& filename, const string& dataType, const string& data)
|
Method on FormFile |
|
Constructor. name is the name of the form element, filename
is the basename of the file on the remote machine, dataType is the
MIME type of the data, and data is the actual file contents.
|
| void FormFile (const FormFile& file)
|
Method on FormFile |
Copy constructor.
file is the FormFile to copy.
|
Overloaded Operators
| bool operator== (const FormFile& file) const
|
Method on FormFile |
Equality operator. Returns true if file has the same
filename as this FormFile, false otherwise.
|
| bool operator!= (const FormFile& file) const
|
Method on FormFile |
Inequality operator. Returns false if file has the same
filename as this FormFile, true otherwise.
|
| FormFile& operator= (const FormFile& file)
|
Method on FormFile |
Assignment operator. Sets the name, filename, dataType, and data of this
FormFile to those of file.
|
Accessor Methods
| void writeToStream (ostream& out)
|
Method on FormFile |
Writes the data contained in this FormFile to the stream
out.
|
| string getName () const
|
Method on FormFile |
|
Get the name of the form element.
|
| string getFilename () const
|
Method on FormFile |
|
Get the basename of file on the remote machine.
|
| string getDataType () const
|
Method on FormFile |
|
Get the MIME type of the file data.
|
| string getData () const
|
Method on FormFile |
| string::size_type getDataLength () const
|
Method on FormFile |
|
Get the length of the file data, in bytes.
|
Node:classes for HTTP headers, Next:classes for HTML output, Previous:class FormFile, Up:Top
classes for HTTP headers
HTTPCookie
An HTTPCookie is a name/value pair used to store a piece of
information about the caller using the caller's own machine. Cookies
are often used as a means to identify users16.
Constructors
| void HTTPCookie ()
|
Method on HTTPCookie |
Creates an empty HTTPCookie.
|
| void HTTPCookie (const string& name, const string& value)
|
Method on HTTPCookie |
Creates an HTTPCookie with name name and value value,
expiring at the end of the current HTTP session.
|
| void HTTPCookie (const string& name, const string& value, const string& comment, const string& domain, unsigned long maxAge, const string& path, bool secure)
|
Method on HTTPCookie |
Creates an HTTPCookie with name name and value
value. comment is any textual comment to be associated with
the cookie. domain is the hostname for which this cookie is
valid. If domain is empty, the hostname of the HTTP server which
generates the response will be used. The cookie will expire in
maxAge seconds. path is the subset of URIs in a domain for
which the cookie is valid. Generally, path will be /.
secure indicates if this a secure cookie.
|
| void HTTPCookie (const HTTPCookie& cookie)
|
Method on HTTPCookie |
Copy constructor. cookie is the HTTPCookie to copy.
|
Accessor Methods
| string getName () const
|
Method on HTTPCookie |
|
Get the name of this cookie.
|
| string getValue () const
|
Method on HTTPCookie |
|
Get the value of this cookie.
|
| string getComment () const
|
Method on HTTPCookie |
|
Get the comment associated with the cookie, if any.
|
| string getDomain () const
|
Method on HTTPCookie |
|
Get the hostname for which this cookie is valid. If empty, the cookie
is valid for the hostname generating the HTTP response.
|
| unsigned long getMaxAge () const
|
Method on HTTPCookie |
|
Get the lifetime of the cookie, in seconds.
|
| string getPath () const
|
Method on HTTPCookie |
|
Get the subset of URIs in a domain for which this cookie is valid. If
empty, the cookie is valid for all URIs in a domain.
|
| bool getSecure () const
|
Method on HTTPCookie |
Returns true if this cookie is secure, false otherwise.
|
Mutator Methods
| void setName (const string& name)
|
Method on HTTPCookie |
|
Set the name of this cookie to name.
|
| void setValue (const string& value)
|
Method on HTTPCookie |
|
Set the value of this cookie to value.
|
| void setComment (const string& comment)
|
Method on HTTPCookie |
|
Set the comment associated with this cookie.
|
| void setDomain (const string& domain)
|
Method on HTTPCookie |
|
Set the hostname for which this cookie is valid.
|
| void setMaxAge (unsigned long maxAge)
|
Method on HTTPCookie |
|
Set the lifetime of this cookie, in seconds.
|
| void setPath (const string& path)
|
Method on HTTPCookie |
|
Set the subset of URIs in a domain for which this cookie is valid to
path.
|
| void setSecure (bool secure)
|
Method on HTTPCookie |
|
Mark this cookie as secure or unsecure.
|
HTTPHeader
HTTPHeader is the base class for all HTTP headers. It is rarely
used directly; instead, use one of the provided subclasses.
| void HTTPHeader (const string& data)
|
Method on HTTPHeader |
|
Creates an HTTP header containing data data.
|
| void HTTPHeader (const HTTPHeader& header)
|
Method on HTTPHeader |
Creates a copy of the HTTPHeader header.
|
| string getData ()
|
Method on HTTPHeader |
|
Get the data contained in this HTTP header.
|
HTTPContentHeader
HTTPContentHeader is a subclass of HTTPHeader used to
indicate the type of data returned to the client by the CGI application.
| void HTTPContentHeader (const string& mimeType)
|
Method on HTTPContentHeader |
|
Creates an HTTP header for data of MIME type mimeType.
|
HTTPRedirectHeader
HTTPRedirectHeader is a subclass of HTTPHeader used to
redirect the client to a different URL.
| void HTTPRedirectHeader (const string& url)
|
Method on HTTPRedirectHeader |
|
Creates an HTTP header used to redirect the client to URL url.
|
HTTPStatusHeader
HTTPStatusHeader is a subclass of HTTPHeader used to
return a 3-digit HTTP status code and the associated message.
| void HTTPStatusHeader (int status, const string& message)
|
Method on HTTPStatusHeader |
Creates an HTTP status header. status is the 3 digit status code,
for example 404. message is the message associated with
the status code, for example not found.
|
HTTPNPHeader
HTTPNPHeader is a subclass of HTTPHeader used to indicate
to the HTTP server that it should not parse the data returned by the CGI
application. Normally, the HTTP server parses the data returned by the
CGI application and fills in certain headers, such as the data size.
| void HTTPNPHeader ()
|
Method on HTTPNPHeader |
|
Creates a non-parsed HTTP header. This tells the HTTP server that it
should not parse the output of the CGI application.
|
HTTPHTMLHeader
| void HTTPHTMLHeader ()
|
Method on HTTPHTMLHeader |
Creates an HTTP header for data of MIME type text/html.
|
HTTPPlainHeader
| void HTTPPlainHeader ()
|
Method on HTTPPlainHeader |
Creates an HTTP header for data of MIME type text/plain.
|
HTTPGIFHeader
| void HTTPGIFHeader ()
|
Method on HTTPGIFHeader |
Creates an HTTP header for data of MIME type image/gif.
|
HTTPJPEGHeader
| void HTTPJPEGHeader ()
|
Method on HTTPJPEGHeader |
Creates an HTTP header for data of MIME type image/jpeg.
|
HTTPXBMHeader
| void HTTPXBMHeader ()
|
Method on HTTPXBMHeader |
Creates an HTTP header for data of MIME type image/x-xbitmap.
|
HTTPAudioHeader
| void HTTPAudioHeader ()
|
Method on HTTPAudioHeader |
Creates an HTTP header for data of MIME type audio/basic.
|
Node:classes for HTML output, Next:Reporting Bugs, Previous:classes for HTTP headers, Up:Top
classes for HTML output
For an introduction to Cgicc's HTML output, please see See A tutorial example, for more information.
Cgicc provides one concrete class for each HTML element defined in the
HTML 4.0 standard (see HTML generation classes). Every class
defining an HTML element is a subclass of the abstract base class
HTMLElement.
There are a number of methods defined on HTMLElement which are,
by definition, defined for all subclasses. In most instances, these
functions will not be used directly, but rather are invoked implicitly
by the subclasses.
HTMLElement
| const char* getName () const
|
Method on HTMLElement |
Returns the name of the HTML element. For example HTML or
BODY.
|
| const HTMLAttributeList* getAttributes () const
|
Method on HTMLElement |
Returns the HTMLAttributeList containing all the attributes
associated with this HTML element, if any.
|
| void setAttributes (const HTMLAttributeList& attributes)
|
Method on HTMLElement |
|
Set the attributes associated with this HTML element.
|
| const HTMLElementList* getEmbedded () const
|
Method on HTMLElement |
Returns the HTMLElementList containing all the HTML elements
embedded in this one, if any.
|
| void setEmbedded (const HTMLElementList& embedded)
|
Method on HTMLElement |
|
Set the HTML elements embedded in this HTML element.
|
Setting HTML Attributes
For most real-world HTML, an HTMLElement will contain one or more
embedded HTML attributes. HTML attributes are added to
HTMLElement objects via the set methods on
HTMLElement.
| HTMLElement& set(const string& name)
|
Method on HTMLElement |
Set an HTMLAttribute with name name on this HTML element.
|
| HTMLElement& set(const string& name, const string& value)
|
Method on HTMLElement |
Set an HTMLAttribute with name name and value value
on this HTML element.
|
Embedding HTML Elements
It is often desirable to embed multiple HTML elements in another at the
same level. HTML elements are embedded in an HTMLElement via the
add methods on HTMLElement.
| HTMLElement& add(const HTMLElement& element)
|
Method on HTMLElement |
|
Add element to the list of HTML elements embedded in this one.
|
| HTMLElement& add(HTMLElement *element)
|
Method on HTMLElement |
Add element to the list of HTML elements embedded in this one.
The HTMLElement takes ownership of element, which should
not subsequently be deleted.
|
HTMLElement Construction
All subclasses of HTMLElement possess the same set of
constructors. They are presented here once for all subclasses; in the
documentation below, the arbitrary element H1, represented by the
class h1, was chosen.
|
Default constructor. Creates an empty HTML element.
|
| void h1 (const string& text)
|
Method on h1 |
|
Creates a new HTML element containing the text text.
|
| void h1 (const HTMLElement& embed)
|
Method on h1 |
|
Creates a new HTML element containing the embedded HTML element
embed.
|
Node:Reporting Bugs, Next:Copying, Previous:classes for HTML output, Up:Top
Reporting Bugs
There is a mailing list for reporting bugs, bug-cgicc@gnu.org,
to enable the developers to track submitted bug reports.
If you think you have found a bug in Cgicc, then you should send as
complete a report as possible to this list. Ideally, you should include
the text you get by running config.guess, the text you see when
you run configure, and if you can, a patch made with diff
-u5 which fixes the problem.
If you wish to subscribe to this list, send empty mail with a
Subject: line of subscribe to
bug-cgicc-request@gnu.org.
Node:Copying, Next:Concept Index, Previous:Reporting Bugs, Up:Top
GNU General Public License
Version 2, June 1991
Copyright © 1989, 1991 Free Software Foundation, Inc. 59
Temple Place, Suite 330, Boston, MA 02111-1307 USA
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
Preamble
The licenses for most software are designed to take away your freedom to
share and change it. By contrast, the GNU General Public License is
intended to guarantee your freedom to share and change free software-to
make sure the software is free for all its users. This General Public
License applies to most of the Free Software Foundation's software and
to any other program whose authors commit to using it. (Some other Free
Software Foundation software is covered by the GNU Library General
Public License instead.) You can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not price.
Our General Public Licenses are designed to make sure that you have the
freedom to distribute copies of free software (and charge for this
service if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid anyone
to deny you these rights or to ask you to surrender the rights. These
restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether gratis
or for a fee, you must give the recipients all the rights that you have.
You must make sure that they, too, receive or can get the source code.
And you must show them these terms so they know their rights.
We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software. If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.
Finally, any free program is threatened constantly by software patents.
We wish to avoid the danger that redistributors of a free program will
individually obtain patent licenses, in effect making the program
proprietary. To prevent this, we have made it clear that any patent
must be licensed for everyone's free use or not licensed at all.
The precise terms and conditions for copying, distribution and
modification follow.
GNU General Public License
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
- This License applies to any program or other work which contains a
notice placed by the copyright holder saying it may be distributed under
the terms of this General Public License. The "Program", below, refers
to any such program or work, and a "work based on the Program" means
either the Program or any derivative work under copyright law: that is
to say, a work containing the Program or a portion of it, either
verbatim or with modifications and/or translated into another language.
(Hereinafter, translation is included without limitation in the term
"modification".) Each licensee is addressed as "you".
Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of running
the Program is not restricted, and the output from the Program is
covered only if its contents constitute a work based on the Program
(independent of having been made by running the Program). Whether that
is true depends on what the Program does.
- You may copy and distribute verbatim copies of the Program's source code
as you receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice and
disclaimer of warranty; keep intact all the notices that refer to this
License and to the absence of any warranty; and give any other
recipients of the Program a copy of this License along with the Program.
You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.
- You may modify your copy or copies of the Program or any portion of it,
thus forming a work based on the Program, and copy and distribute such
modifications or work under the terms of Section 1 above, provided that
you also meet all of these conditions:
- You must cause the modified files to carry prominent notices stating
that you changed the files and the date of any change.
- You must cause any work that you distribute or publish, that in whole or
in part contains or is derived from the Program or any part thereof, to
be licensed as a whole at no charge to all third parties under the terms
of this License.
- If the modified program normally reads commands interactively when run,
you must cause it, when started running for such interactive use in the
most ordinary way, to print or display an announcement including an
appropriate copyright notice and a notice that there is no warranty (or
else, saying that you provide a warranty) and that users may
redistribute the program under these conditions, and telling the user
how to view a copy of this License. (Exception: if the Program itself
is interactive but does not normally print such an announcement, your
work based on the Program is not required to print an announcement.)
These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works. But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.
In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.
- You may copy and distribute the Program (or a work based on it, under
Section 2) in object code or executable form under the terms of Sections
1 and 2 above provided that you also do one of the following:
- Accompany it with the complete corresponding machine-readable source
code, which must be distributed under the terms of Sections 1 and 2
above on a medium customarily used for software interchange; or,
- Accompany it with a written offer, valid for at least three years, to
give any third party, for a charge no more than your cost of physically
performing source distribution, a complete machine-readable copy of the
corresponding source code, to be distributed under the terms of Sections
1 and 2 above on a medium customarily used for software interchange; or,
- Accompany it with the information you received as to the offer to
distribute corresponding source code. (This alternative is allowed only
for noncommercial distribution and only if you received the program in
object code or executable form with such an offer, in accord with
Subsection b above.)
The source code for a work means the preferred form of the work for
making modifications to it. For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to control
compilation and installation of the executable. However, as a special
exception, the source code distributed need not include anything that is
normally distributed (in either source or binary form) with the major
components (compiler, kernel, and so on) of the operating system on
which the executable runs, unless that component itself accompanies the
executable.
If distribution of executable or object code is made by offering access
to copy from a designated place, then offering equivalent access to copy
the source code from the same place counts as distribution of the source
code, even though third parties are not compelled to copy the source
along with the object code.
- You may not copy, modify, sublicense, or distribute the Program except
as expressly provided under this License. Any attempt otherwise to
copy, modify, sublicense or distribute the Program is void, and will
automatically terminate your rights under this License. However,
parties who have received copies, or rights, from you under this License
will not have their licenses terminated so long as such parties remain
in full compliance.
- You are not required to accept this License, since you have not signed
it. However, nothing else grants you permission to modify or distribute
the Program or its derivative works. These actions are prohibited by
law if you do not accept this License. Therefore, by modifying or
distributing the Program (or any work based on the Program), you
indicate your acceptance of this License to do so, and all its terms and
conditions for copying, distributing or modifying the Program or works
based on it.
- Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions. You may not impose any further restrictions
on the recipients' exercise of the rights granted herein. You are not
responsible for enforcing compliance by third parties to this License.
- If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all. For example, if a patent license
would not permit royalty-free redistribution of the Program by all those
who receive copies directly or indirectly through you, then the only way
you could satisfy both it and this License would be to refrain entirely
from distribution of the Program.
If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is implemented
by public license practices. Many people have made generous
contributions to the wide range of software distributed through that
system in reliance on consistent application of that system; it is up to
the author/donor to decide if he or she is willing to distribute
software through any other system and a licensee cannot impose that
choice.
This section is intended to make thoroughly clear what is believed to be
a consequence of the rest of this License.
- If the distribution and/or use of the Program is restricted in certain
countries either by patents or by copyrighted interfaces, the original
copyright holder who places the Program under this License may add an
explicit geographical distribution limitation excluding those countries,
so that distribution is permitted only in or among countries not thus
excluded. In such case, this License incorporates the limitation as if
written in the body of this License.
- The Free Software Foundation may publish revised and/or new versions of
the General Public License from time to time. Such new versions will be
similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the Program
specifies a version number of this License which applies to it and "any
later version", you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation. If the Program does not specify a version
number of this License, you may choose any version ever published by the
Free Software Foundation.
- If you wish to incorporate parts of the Program into other free programs
whose distribution conditions are different, write to the author to ask
for permission. For software which is copyrighted by the Free Software
Foundation, write to the Free Software Foundation; we sometimes make
exceptions for this. Our decision will be guided by the two goals of
preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.
NO WARRANTY
- BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.
- IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.
To do so, attach the following notices to the program. It is safest to
attach them to the start of each source file to most effectively convey
the exclusion of warranty; and each file should have at least the
"copyright" line and a pointer to where the full notice is found.
one line to give the program's name and a brief idea of what it does.
Copyright (C) <year> name of author
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Also add information on how to contact you by electronic and paper mail.
If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) year name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type
show w. This is free software, and you are welcome to
redistribute it under certain conditions; type show c for
details.
The hypothetical commands show w and show c should show
the appropriate parts of the General Public License. Of course, the
commands you use may be called something other than show w and
show c; they could even be mouse-clicks or menu items-whatever
suits your program.
You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the program, if
necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the program
Gnomovision (which makes passes at compilers) written by James
Hacker.
signature of Ty Coon, 1 April 1989
Ty Coon, President of Vice
This General Public License does not permit incorporating your program
into proprietary programs. If your program is a subroutine library, you
may consider it more useful to permit linking proprietary applications
with the library. If this is what you want to do, use the GNU Library
General Public License instead of this License.
Node:Concept Index, Next:Function Index, Previous:Copying, Up:Top
Concept Index
Menu
Node:Function Index, Next:Data Type Index, Previous:Concept Index, Up:Top
Function Index
Menu
Node:Data Type Index, Previous:Function Index, Up:Top
Data Type Index
Menu
Table of Contents
Footnotes
-
The official specification for the Common Gateway
Interface may be found at
<http://hoohoo.ncsa.uiuc.edu/cgi/interface.html>.
-
This is not entirely true. For uploaded
files, the data is accessed via the class FormFile.
-
The full HTTP 1.1 specification may be found in RFC 2068
at
<http://www.w3.org/Protocols/rfc2068/rfc2068>
-
For a definitive
list, see the HTML 4.0 specification at
<http://www.w3.org/TR/REC-html40/>
-
For a complete
description see the HTML 4.0 specification at
<http://www.w3.org/TR/REC-html40/>
-
It is preferable to use stylesheets instead of
this element
-
It is preferable to use stylesheets instead of
this element
-
This element is not part of the strict DTD
-
This element is not part of the strict DTD
-
It is preferable to use stylesheets instead of
this element
-
This element is not part of the strict DTD
-
This element is not part of the strict
DTD
-
It is preferable to use stylesheets instead
of this element
-
It is preferable to use stylesheets instead of
this element
-
RFC 1431 may be found at
<http://info.internet.isi.edu:80/in-notes/rfc/files/rfc1413.txt>
-
The technical
specification for cookies may be found at
<http://www.cis.ohio-state.edu/htbin/rfc/rfc2109.html>.