The cgixx Book

A CGI library for C++

Isaac W. Foraker

Abstract

This is for the cgixx C++ CGI library. For the most up to date documentation, go to http://tazthecat.net/~isaac/cgixx/.


Table of Contents

Introduction
What is cgixx?
Why cgixx?
What makes cgixx different?
1. Compilation and Installation
Supported Platforms/Compilers
Where to get cgixx
Building on Unix
2. Usage
Header
CGI
Cookies
A. Project Specifics
License
Credits
Reporting bugs

Introduction

What is cgixx?

cgixx is yet another C++ library for Common Gateway Interface (CGI).

Why cgixx?

Existing CGI libraries and classes seem bloated and complicated. I built cgixx to be small and simple, using modern C++ techniques.

What makes cgixx different?

Most CGI libraries include a full module for generating HTML. This assumes that all CGI programs generate HTML. There are many CGI programs which generate graphics, downloadable files, or simply redirect a client to another URL. cgixx focuses solely on providing the easiest possible CGI API for your C++ applications, including support for expiring URLs and Cookies, completely ignoring HTML.

Chapter 1. Compilation and Installation

Supported Platforms/Compilers

cgixx has been compiled and tested under the following platforms:

FreeBSD 4.5 GCC 2.95.4 and 3.2
MacOS X 10.3 with GCC 3.3 (Apple version)

cgixx unofficially builds under the following platforms:

Linux GCC 2.95.4 or 3.0+
Solaris 2.7+ GCC 3+
Windows Visual C++ 6 and 7 (a.k.a. .Net)

Building on Unix

At the time of the writing of this document, cgixx has been tested with GCC 2.95.4 and 3.2. Set the CXX environment variable to the path of your compiler. On many GCC systems, this can be simply $CXX=g++.

./configure [--help]
make
make install
			

Chapter 2. Usage

Table of Contents

Header
CGI
Cookies

This chapter is provided as a basic introduction to the use of the cgixx library. For more complete information, refer to the cgixx reference manual. The examples in this chapter are for demonstration only and may not be fully functional.

Header

CGI headers are generated through the cgixx::header class. The cgixx::header class allows you to control the expiration of content, cookies, and error codes. After the cgixx::header has been initialized, use the get() member method to retrieve the full header string.

#include <cgixx/cgixx.h>
#include <iostream>

int main(int argc, char* argv)
{
	cgixx::header header;

	// Set the header to expire immediately (or minus one day)
	header.setexpire("-1D");

	// Print the header
	std::cout << header.get();

	// Print the simple HTML output
	std::cout <<
		"<HTML><HEAD><TITLE>Test page</TITLE><HEAD>\n"
		"<BODY><H1>Test Page</H1><HR>\n"
		"</BODY></HTML>"
		<< std::endl;

	return 0;
}

CGI

CGI processing is handled by the cgixx::cgi class. This class processes client headers, including variables and cookies. The get() method is provided for retrieving variable values. Calling get() repeatedly on the same variable name will retrieve all values of that variable.

#include <cgixx/cgixx.h>
#include <iostream>
#include <string>

int main(int argc, char* argv)
{
	cgixx::header header;
	cgixx::cgi cgi;
	cgixx::methods method;
	std::string val;

	// Print the header
	std::cout << header.get();

	// Get the User Agent header
	cgi.getheader(cgixx::header_http_user_agent, val);

	// Print some HTML
	std::cout <<
		"<HTML><HEAD><TITLE>Test page</TITLE><HEAD>\n"
		"<BODY><H1>Test Page</H1><HR>\n"
		"User Agent: " << val << "<br>\n"
		"Method: ";
	
	// Get the CGI Method
	method = cgi.getmethod();
	switch (method) {
	case cgixx::method_get:
		std::cout << "Get";
		break;
	case cgixx::method_post:
		std::cout << "Post";
		break;
	default:
		std::cout << "unknown";
		break;
	}

	std::cout << "\n"
		"</BODY></HTML>"
		<< std::endl;
	return 0;
}

Cookies

Cookies can be generated using the cgixx::cookie class. When instantiating a cookie, you must specify either a name for the cookie, or another cgixx::cookie to copy. Specifying the cgixx::cgi environment in the cgixx::cookie constructor will automatically populate the domain and path cookie values.

#include <cgixx/cgixx.h>
#include <iostream>
#include <string>

int main(int argc, char* argv)
{
	cgixx::cgi cgi;
	cgixx::header header;
	std::string val;

	// Instantiate a couple of cookies
	cgixx::cookie a(cgi, "a", "1"), b(cgi, "b", "2");

	// Add the cookies to the header.
	header.addcookie(a);
	header.addcookie(b);

	// Print the header (including cookies)
	std::cout << header.get();

	// Print some HTML
	std::cout <<
		"<HTML><HEAD><TITLE>Test page</TITLE><HEAD>\n"
		"<BODY><H1>Test Page</H1><HR>\n";

	// Get cookies already assigned to the user agent
	cgixx::cgi::identifierlist idlist;
	cgi.getcookielist(idlist);

	// Print the current list of cookies returned by the user agent
	cgixx::cgi::identifierlist::iterator it(idlist.begin()),
		end(idlist.end());
	for (; it != end; ++it)
	{
		while (!cgi.getcookie(*it, val))
			std::cout << *it << ": " << val << "<br>\n";
	}

	std::cout << "\n"
		"</BODY></HTML>"
		<< std::endl;
	return 0;
}

Appendix A. Project Specifics

License

cgixx C++ CGI Library
Copyright (C) 2002-2004 Isaac W. Foraker (isaac(at)tazthecat(dot)net)
All Rights Reserved

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  3. Neither the name of the Author nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE AND DOCUMENTATION IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Credits

cgixx Programming and Documentation

  • Isaac W. Foraker (http://tazthecat.net/~isaac/)

cxxtools for build system

  • Peter J. Jones (http://pmade.org/~pjones/)

Reporting bugs

If you encounter a bug in cgixx, please e-mail a bug report to isaac(at)tazthecat(dot)net.