cgic2: the multipart handling extention to the cgic library

By Monika Orski

What is cgic2?

cgic2 is an extension to the cgic library by Thomas Boutell. It is an ANSI C-library to handle multipart/form-data input in web applications. For information on multipart/form-data, see RFC1867.
cgic2, like cgic, should be compatible with any CGI-compliant server environment.

Version Information

This is cgic2 version 1.0. It includes a distribution of cgic version 1.07.

Downloads

gzipped tar file
zip file

Credits and License Terms

cgic2 can be used free of charge, provided that a credit notice is provided online. Alternatively, a nonexclusive Commercial License can be purchased, which grants the right to use cgic2 without a public credit notice. Note that with cgic2, you are also using cgic. See http://www.boutell.com/cgic/ or the file cgic.txt in the download package for cgic details.
Please see the files license_cgic2.txt and license.txt in the dowload package for the details of the Basic License and Commercial License, including ordering information for the Commercial License.
Thanks are due to Robert Gustavsson at Abstractor, who commisioned the first cgic2 version, helped test it, and agreed to make it an open source library.

How to obtain cgic2

cgic2 is distributed via the web in two forms: as a Windows-compatible .ZIP file, and as a gzipped tar file. They are available in the Downloads section above.
The cgic2 distribution includes a cgic distribution.
Important: to use cgic and cgic2, you will need an ANSI-standard C compiler.

cgic2 Scope

The current version of cgic2 does not handle nestled multipart messages.

A Sample Application

The cgic2 distribution includes cgictest2, a simple sample application. Before you compile cgictest2, edit the line

#define FILEDIR "/tmp/vd/"

in cgictest2.c to point to a directory where you could store files for your test.
Edit the file testform2.html to point set the action to point to your cgictest2 binary. Then use it to test cgic2.

Important: To be able to use cgic2, first you have to make sure you can use cgic. Please see cgic.txt in the download package for detailed instructions on how to get things up and running.

cgic2 changes to cgic

The cgic code has mostly been left unchanged. cgic2 additions reside in their own files, cgic2.h and cgic2.c, for clarity. However, some changes to cgic.c where inevitable:

The definitions for cgiFormEntry and cgiFormEntryFirst have been moved from cgic.c to cgic.h
multipart detection and corresponding function calls have been added to main

Other changes:

The call to cgiMain now includes argv and argc
Now checking for a definition of __WIN32__ as well as WIN32

How to Write cgic2 Applications

When handling the parts of multipart input that are not file uploads, simply use the same cgic functions used for normal post data. The instructions in cgic.txt are fully applicable.
To get the files uploaded, the following funtions have been added:

cgiFileData - get the name, type and length of the file
cgiFileContents - get the file contents
cgiFileAll - get both file data and contents
cgiFileSave - write the file to a directory on your server

cgic2 Variables Reference

char *cgiMPBoundary
The multipart boundary in this multipart message.

cgic2 User Functions Reference

cgiFileResultType cgiFileData(char *name, char *resname, int maxnamelen, char *restype, int maxtypelen, int *length)
cgiFileData attempts to retrieve the name, type and length of the file specified in the upload field. It returns cgiFileNotFound if there is no such upload field, cgiFileSuccess otherwise.

cgiFileResultType cgiFileContent(char *name, void *content, int *length, int maxlength)
cgiFileContent attempts to retrieve the file contents of the file specified in the upload field and copy them to the buffer content, up to but not exceeding maxlength bytes. It returns cgiFileNotFound if there is no such upload field, cgiFileLengthExceedsBuffer if the file length exceeds maxlength, cgiFileMemory if the copy fails, cgiFileSuccess otherwise.

cgiFileResultType cgiFileAll(char *name, char *resname, int maxnamelen, char *restype, int maxtypelen, int *length, void *content, int maxlength)
cgiFileResultAll combines the funtionality of cgiFileData and cgiFileContent into one call.

cgiFileResultType cgiFileSave(char *name, char *dir)
cgiFileSave attempts to write the contents of file specified in the upload field to a file with the same name in the directory dir. It does not create and extra copy of the contents in memory. It returns cgiFileNotFound if there is no such upload field, cgiFileCouldNotCreate if it can not create a file in the directory specified, cgiFileMemory if the write fails, cgiFileEmpty if there are no contents to write, cgiFileSuccess otherwise.

cgic2 Support

The cgic2 library is delivered as is, with no regular support. However, bug reports, corrections and suggestions are very welcome. Please e-mail them to monika@orski.se.
If you would like customized help or extentions, please drop me an e-mail for price quotes.

Monika Orski
M Orski Konsult