cgiform.h

用C些的CGI函数库

#ifndef _INCLUDE_CGIFORM_H_
#define _INCLUDE_CGIFORM_H_

/*
** 库名			:	CGIForm
** 库描述		:	用于处理表单信息的CGI函数库
** 作者			:	calvin
** E-mail		:	[e-mail]
** QQ			:	21021078
** 创建日期时间	:	
** 更新日期时间	:	2005/5/2
*/

/* TEXTBLOCK 文档标题 *
CGIForm函数库文档
BetonArmEE
v1.0.0.20070403
/TEXTBLOCK */

/* TEXTBLOCK 关于 功能概述
	CGIForm是iCGI函数库中最重要的子函数库之一。
	CGIForm主要处理浏览器端表单数据（包含上传文件数据）的读取和分析，实现服务端应用获取浏览器端表单数据完整解决方案。
/TEXTBLOCK */

/* TEXTBLOCK 关于 兼容平台列表
		Windows	UNIX	Linux
-------------------------------------
CGIForm	Y		Y		Y
TEXTBLOCK */

/* TEXTBLOCK 关于 版本历史
2005-05-02	创建 第一版
2007-04-02	创建 文档
/TEXTBLOCK */

/* TEXTBLOCK 知识手册 form数据与form链表容器
	浏览器端表单（form）拥有若干表单域（field），最简单的表单比如网站用户注册表单，要求用户输入用户名、密码等信息。当表单提交后，form数据通过网络传输到服务器端，由web服务软件转交给cgi程序，cgi程序从环境变量中读出form数据并做出相应业务逻辑处理。
	CGIForm子函数库封装了cgi程序读取和分析过程，通过函数读取浏览器端发送过来的form数据到form链表容器数据结构，提供大量函数方便从form链表容器中读取表单域数据。
/TEXTBLOCK */

/* TEXTBLOCK 使用指南 创建、销毁form链表容器
	form链表容器其实是一个通用泛型链表（请参考iLibX函数库List子函数库相关文档），用于存放表单form数据，链表结点类型主要为key-value，key存放表单域名数据，value存放表单域值数据。
	
	·创建form链表容器
	
		以下代码片断声明了通用泛型链表结构plist并初始化为form链表容器空值：
			SList *plist = NULL ;
			plist = CGIFormListInitial() ;
			
	·销毁form链表容器
	
		以下代码片断用于销毁form链表容器，如果form链表容器内有form数据，则销毁前先释放form数据：
			BOOL bret ;
			bret = CGIFormListDestroy( &plist ) ;
		当销毁成功，CGIFormListDestroy返回TRUE，否则返回FALSE
/TEXTBLOCK */

/* TEXTBLOCK 使用指南 装载form数据到链表容器
	form链表容器被初始化后需要装载浏览器端提交过来的form数据
	以下代码片断用于从web服务器软件处获取装载form数据到form链表容器里去：
		BOOL bret ;
		bret = CGIFormReadData( &plist ) ;
/TEXTBLOCK */

/* TEXTBLOCK 使用指南 读取、遍历form数据
	由于form链表容器其实就是一个通用泛型链表，就可以用iLibX.List子函数库中的函数读取链表中结点数据即form数据，此外CGIForm子函数库提供了一组函数能够更方便快捷的按表单域名为索引读取表单域值。
	注意：读取过程并没有把数据复制出来，而是把链表内表单域值数据的内存首地址赋值给应用程序指定的指针变量，应用程序可以通过引用该指针变量自行做复制等处理。
	
	·读取一般表单域数据
		以下代码片断从form链表容器用于读取浏览器表单行编辑框'textfieldUserName'中用户输入的值：
			char *pvalue = NULL ;
			pvalue = CGIFormGetValue( plist , "textfieldUserName" ) ;
		以下代码片断从form链表容器用于获得表单行编辑框'textfieldUserName'中用户输入的值的长度：
			long size ;
			size = CGIFormGetValueSize( plist , "textfieldUserName" ) ;
		有时浏览器端传送过来的表单数据并不符合c语言字符串规则，此函数可以确定表单域值的长度。
		
	·读取包含上传文件表单域数据
	
		以下代码片断用于从form链表容器读取表单上传文件域'fileUpload'的文件名（完整的全文件名，包含路径、主文件名和文件扩展名）：
			char *pfilename = NULL ;
			pfilename = CGIFormGetFileName( plist , "fileUpload" ) ;
		以下代码片断用于从form链表容器获得表单上传文件域'fileUpload'的文件大小（单位为字节）：
			long size ;
			size = CGIFormGetFileSize( plist , "fileUpload" ) ;
		以下代码片断用于从form链表容器读取表单上传文件域'fileUpload'的文件实际内容：
			char *pfilecontent = NULL ;
			pfilecontent = CGIFormGetFileContent( plist , "fileUpload" ) ;
			
	·遍历form数据
	
		请参考iLibX.List子函数库相关函数遍历链表即可。
/TEXTBLOCK */

/* TEXTBLOCK 使用指南 系统限制选项
	为防止浏览器端发送恶意数据而造成CGIForm相关函数中缓冲溢出，设置系统限制选项保护之。
	函数CGIFormSetMaxFieldNameSize设置允许的最大表单域名长度和上传文件域全文件名长度，超出该限制则截取有效长度部分。
	函数CGIFormSetMaxFieldDataSize设置允许的最大表单域值大小，超出该限制则截取有效长度部分。
	函数CGIFormSetMaxFieldFileDataSize设置允许的最大上传文件内容大小，超出该限制则截取有效长度部分。
	注意：系统限制选项函数必须在form数据装载到form链表容器中去之前设置，即函数CGIFormReadData调用前。
/TEXTBLOCK */

/* TEXTBLOCK 使用指南 调试选项
	为方便调试form数据装载过程，设置调试选项能够使应用开发者方便观察form数据装载过程。
	函数SetFormDebugFileName用于设置日志文件名，使装载form数据过程中有相关dump信息写入外部文件。如果日志文件名为空字符串（即""）则不写日志。可设置的日志文件名长度最长为255个字符。
	函数GetFormDebugFileName用于复制当前已经设置的日志文件名到应用程序指定的缓冲区中。函数不检查缓冲大小，防溢出控制由应用开发者处理。
/TEXTBLOCK */

#ifdef _TYPE_OS_WINDOWS_
#include <io.h>
#endif

#include "LibX.h"
#include "TypeX.h"
#include "ListX.h"

#if ( defined _TYPE_OS_AIX_ ) | ( defined _TYPE_OS_SCO_ ) | ( defined _TYPE_OS_LINUX_ )
#endif

#ifdef __cplusplus
extern "C" {
#endif

/*
** 函数集说明	:	调试函数集
*/

/* FUNCTIONLIST 参考列表 函数列表 */
_WINDLL_EXPORT BOOL SetFormDebugFileName( char *pcDebugPathFileName );
_WINDLL_EXPORT BOOL GetFormDebugFileName( char *pcDebugPathFileName );
/* /FUNCTIONLIST */

/*
** 结构名	:	SCGIFormData
** 结构说明	:	包含form结点项的内容信息
*/

/* STRUCTDES 参考列表 结构列表 */
typedef struct tagCGIFormData
{
	char *name; /* 表单域名 */
	char *data; /* 表单域值 或者 上传文件域文件内容 */
	long datasize; /* 表单域值大小 或者 上传文件域文件大小 */
	
	char *filename; /* 上传文件域全文件名 */
}
SCGIFormData; /* form数据，表单域信息包，form链表容器结点值 */
/* /STRUCTDES */

/*
** 函数集说明	:	设置域特性最大值
*/

/* FUNCTIONLIST 参考列表 函数列表 */
_WINDLL_EXPORT void CGIFormSetMaxFieldNameSize( long maxsize );
_WINDLL_EXPORT void CGIFormSetMaxFieldDataSize( long maxsize );
_WINDLL_EXPORT void CGIFormSetMaxFieldFileDataSize( long maxsize );
/* /FUNCTIONLIST */

/*
** 函数集说明	:	form数据链表初始化、销毁函数
*/

/* FUNCTIONLIST 参考列表 函数列表 */
_WINDLL_EXPORT SList *CGIFormListInitial();
_WINDLL_EXPORT BOOL CGIFormListDestroy( SList **listForm );
/* /FUNCTIONLIST */

/*
** 函数集说明	:	form数据链表填充函数
*/

/* FUNCTIONLIST 参考列表 函数列表 */
_WINDLL_EXPORT BOOL FreeCGIFormData( void *pv );
_WINDLL_EXPORT BOOL CGIFormReadData( SList **listForm );
/* /FUNCTIONLIST */

/*
** 函数集说明	:	form数据链表取值函数
*/

/* FUNCTIONLIST 参考列表 函数列表 */
_WINDLL_EXPORT char *CGIFormGetValue( SList *listForm , char *name );
_WINDLL_EXPORT long CGIFormGetValueSize( SList *listForm , char *name );
_WINDLL_EXPORT char *CGIFormGetFileName( SList *listForm , char *name );
_WINDLL_EXPORT long CGIFormGetFileSize( SList *listForm , char *name );
_WINDLL_EXPORT char *CGIFormGetFileContent( SList *listForm , char *name );
/* /FUNCTIONLIST */

#ifdef __cplusplus
}
#endif

#endif