cgic2: the multipart handling extention to the cgic library
By Monika Orski
What is cgic2?
cgic2 is an extension to the cgic
Thomas Boutell. It is an ANSI C-library to
handle multipart/form-data input in web applications. For information on
cgic2, like cgic, should be compatible with any CGI-compliant server environment.
Version InformationThis is cgic2 version 1.0. It includes a distribution of cgic version 1.07.
Downloadsgzipped tar file
Credits and License Termscgic2 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 cgic2cgic2 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 ScopeThe current version of cgic2 does not handle nestled multipart messages.
A Sample ApplicationThe 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 cgicThe 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
- The call to cgiMain now includes argv and argc
- Now checking for a definition of __WIN32__ as well as WIN32
How to Write cgic2 ApplicationsWhen 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 Referencechar *cgiMPBoundary
The multipart boundary in this multipart message.
cgic2 User Functions ReferencecgiFileResultType 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 SupportThe cgic2 library is delivered as is, with no regular support. However, bug reports, corrections and suggestions are very welcome. Please e-mail them to email@example.com.
If you would like customized help or extentions, please drop me an e-mail for price quotes.
M Orski Konsult