A catch-all header is available which includes all of the headers you should need for CGI.

For the sake of clarity we alias the boost::cgi namespace rather than dumping all of the library names with a using namespace. This way, you can see what comes from the library.

The first thing to do is write a handler function which takes a request and a response and does all request-specific work. Later, we will look at writing the code that calls this function.

In our request handler, we will assume that the request has been fully-parsed and we can access all of the request data. The request data is available using public members of a cgi::request. These member variables are instances of the data_map_proxy, which has a std::map<>-like interface along with some additional helper functions to facilitate common CGI tasks, such as lexical conversion to different types. ^[1]

A CGI request has several types of variables available. These are listed in the table below, assuming that req is an instance of cgi::request:

Let's assume you now want to check if the user has a cookie, "user_name", set. We can check if a user has a cookie set like this:

First, we need to be able to clear the cookie we are setting. We will reset the cookie if the user navigates to "/path/to/script?reset=1".

The reset variable in the query string is a GET variable. The request data is accessed through a proxy class which works just like a std::map<> with some extra features.

One of them is pick, which looks up a key in the map and returns the value if it is found. Otherwise it returns a default value, which is the second argument.

The default value can be any type that supports Boost.Lexical_cast. If the key isn't found in the map, or the value cannot be cast to the type of the default value, the default is returned.

Set a cookie with no value to delete it.

The cgi::redirect free function returns a "Location" header that will redirect the user to the specified URL. This URL can be a relative or absolute but an absolute URL is always returned. To perform an internal redirect, use cgi::location instead.

Looking up a request cookie in req.cookies really returns a cgi::cookie. The line above works though because a cgi::cookie is implicitly convertible to a std::string.

The lookup is case-insensitive, so "USER_NAME" and "User_Name" would be equivalent lookup keys.

If the cookie is set, we'll be polite and say hello before quitting.

That's all we want to say for now, so we can return.

If you are familiar with CGI programming, you will notice the lack of any HTTP headers in the response. A cgi::response handles headers separately to the body. You can set headers at any point and when you send the response the headers will all be sent first.

If you don't explicitly set any response headers, a default header "Content-type: text/plain" is sent, followed by the usual HTTP end-of-line "\r\n" and a blank line which indicates the end of the headers and the start of response body.

If the cookie isn't set, we will check if the user has posted a GET / POST form with their name.

If they have told us their name, we should set a cookie so we remember it next time. Then we can say hello and exit.

There are two ways to set a cookie: either directly using req.set_cookie("user_name", user_name) or the method shown. You can also send an expiry date and a path for the cookie. ^[2] Note that if you set a cookie with no value, the cookie will be deleted.

Again, the request object isn't buffered, so we are going to keep using the response in case something breaks and we end up not wanting to set the cookie. The cookie we set below will expire when the client closes their browser.

This time, we shall send a Date header. If we do this (ie. send a header ourselves), we must also set the Content-type header, like below.

Now, if we have no idea who they are, we'll send a form asking them for their name. As the default "Content-type" header is "text/plain", we'll change this to "text/html" so the user's browser will display the HTML form. You can do this using set_header(req, "Content-type", "text/html") or resp<< header("Content-type", "text/html"). Since writing with raw strings is error-prone, the shortcut below is available.

A CGI program will handle one request each time it is invoked. Returning a non-zero status to the OS indicates an error handling the request. I don't know that HTTP servers treat non-zero exit codes specially. ^[3]

To send the response back to the request, use cgi::commit. The third status argument is optional and defaults to zero. The return value of cgi::commit is status.

We now have a request handler in all of it's contrived glory.

The program's main function needs to parse the request, call the request handler defined above, and finally send the response.

At this point, the environment variables are accessible. This includes cookie and form variables too, which are all parsed by default-constructing a cgi::request (this is optional).

The response class provides a streaming interface for writing replies. You can write to the request object directly, but for now we're going to just use the response, which works well for most situations.

Writing to a response is buffered. If an error occurs, you can simply clear() the response and send an error message instead. Buffered writing may not always suit your use-case (eg. returning large files), but when memory is not at a real premium, buffering the response is highly preferable.

Not only does buffering avoid network latency issues, but being able to cancel the response and send another is much cleaner than sending half a response, followed by "...Ooops". A cgi::response is not tied to a request, so the same response can be reused across multiple requests.

When sending a response that is large relative to the amount of memory available to the program, you may want to write unbuffered.