Chapter 1. CGI 0.01

Darren Garvey

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

	Important
This manual does not document a library that is a part of _Boost_. The major part of it has been developed this summer as part of the Google Summer of Code, 'GSoC07'. Everything from here on in is alpha-grade, some bits more than others; comments and bug reports are welcome. These documents are either hosted at sourceforge, or at svn.boost.org. For free!

Important

This manual does not document a library that is a part of _Boost_. The major part of it has been developed this summer as part of the Google Summer of Code, 'GSoC07'. Everything from here on in is alpha-grade, some bits more than others; comments and bug reports are welcome.

These documents are either hosted at sourceforge, or at svn.boost.org. For free!

Preface

How to use this manual

All science is either Physics, or stamp collecting.

-- Ernest Rutherford.

Overview

THIS LIBRARY IS NOT A PART OF BOOST.

Boost.CGI is an open-source library for writing CGI programs in Standard C++. The library supports vanilla CGI, SCGI and FastCGI (SCGI doesn't really work yet) so it can be used to write anything from simple 'CGI scripts' to full-fledged, scalable applications. This library rests on top of and should appear familiar to users of Boost.Asio, a cross-platform asynchronous (and fast) networking library. One of the main aims of the library is to allow programs to be written for any of the supported protocols without any real modification.

Motivation

C++ may not be the most common language used for CGI programming, but it is a powerful one that can be used to produce scalable, maintainable and uncompromisingly efficient applications.

A discussion about the benefits of CGI programming in C++ is beyond the scope of this document and I've assumed you're here because you want to try C++ CGI programming, but here is a short list anyway:

Having a binary application is inherently more secure than scripting languages in the situation where an error causes the application, rather than the output to be returned to the client. See http://www.w3.org/Security/Faq/wwwsf4.html for more.
C++ has a very large and professional user base, providing a wealth of expertise and experience.
Millions of lines of C++ code can be reused to reduce development/testing times.
In places where RAD (rapid application development) is of the utmost importance, scripting languages can still be used, for instance by using Boost.Python.
C++ is fast. You can rest assured that the language will never be a bottleneck for your applications.
C++ rarely misses out on access to new technologies: for instance, if a new RDBMS came out tomorrow, it would almost certainly ship with a C/C++ API. The same would not be true for many other languages.
Web applications can benefit from an enforced modular design. ^[1] C++'s flexibility with regard to object-oriented design patterns is highly-regarded and well documented.

With web applications becoming increasingly complex and responsive (ie. asynchronous, vis-à-vis AJAX) all the while being required to scale boundlessly - the benefits of C++ begin to show.

The generally poor support for CGI programming for C++ - most libraries are either unmaintained, or don't take advantage of modern C++ capabilities - has driven the development of this library. moremoremore

How to use this manual

	Note
	At the moment, the Boost style guidelines aren't honoured properly or consistently. Please ignore this for now, as the ambiguity is half-intentional (since this is not* a Boost library*). It's simple enough to rectify.

Naming Conventions

Headers

Table 1.1. What Headers to Include

Protocol	`#include` line
All	`#include <boost/cgi.hpp>`
CGI	`#include <boost/cgi/cgi.hpp>`
aCGI	`#include <boost/cgi/acgi.hpp>`
FastCGI	`#include <boost/cgi/fcgi.hpp>`

Namespaces

The classes/functions that are shared between protocols are in the cgi::common namespace. Using the above headers dumps these into the relevant namespace.

Protocol	`namespace`
CGI	`namespace boost::cgi` OR `namespace cgi::cgi`
aCGI	`namespace boost::acgi` OR `namespace cgi::acgi`
FastCGI	`namespace boost::fcgi` OR `namespace cgi::fcgi`

Protocol

namespace

CGI

namespace boost::cgi

namespace cgi::cgi

aCGI

namespace boost::acgi

namespace cgi::acgi

FastCGI

namespace boost::fcgi

namespace cgi::fcgi

Macros

Macros are prefixed with BOOST_CGI_* .

The only public macros so far are:

Valid macros

BOOST_CGI_DEFAULT_CONTENT_TYPE: This defaults to "text/plain" and causes a default "content-type" header to be output, but only when you don't output any other headers.
BOOST_CGI_NO_DEFAULT_CONTENT_TYPE: #define this when you don't want a default "content-type" header to be output. CGI scripts always need one of these, so you will be responsible for sending one!

Code snippets

As you are probably used to, it is assumed that code snippets in this manual have the correct #includes and "using namespace boost::<protocol>;" prepended to them.

Comments and Support

Use cases, example requests, puzzles and problems should be sent to the mailing list:

cgi-talk @ lists.sf \.\ net

or thereabouts.

^[1] For an example design choice, see Model-View-Controller.