cgihtml.txt

用C些的CGI函数库

CGIHtml函数子库文档
作者：		BetonArmEE
最新版本：	2007-05-01	v1.0

>>> 目录
1.关于
	1.1.功能概述
	1.2.兼容平台列表
	1.3.版本历史
2.知识手册
	2.1.HTML头、Url重定向、错误状态
	2.2.HTML模板技术
3.使用指南
	3.1.HTML头、Url重定向、错误状态
	3.2.HTML模板使用例子
	3.3.HTML模板使用中防缓冲区溢出
	3.4.其它HTML处理函数
4.参考列表
	4.1.函数列表

>>> 正文
1.关于

	1.1.功能概述
	
		CGIHtml主要发送HTML头、Url重定向、错误状态等功能，同时还包含了一个HTML模板库。
		
	1.2.兼容平台列表
	
		Windows、UNIX、Linux
		
	1.3.版本历史
	
		2005-05-02	创建 第一版
		2007-05-01	创建 文档
		
2.知识手册

	2.1.HTML头、Url重定向、错误状态
		
		HTML头包含在HTTP协议里面，它总是在发送HTML代码前被发送，当然，HTML头还包含许多其它的内容，这里仅支持HTTP数据类型，比如HTML类型、图片类型、下载二进制数据类型。HTML头一般和HTML之间有两个"\r\n"。一旦发送了HTML头，后面就应该紧跟HTML代码。
		Url重定向用于在不改变客户端网址显示而把当前链接重定向到另一个网址上去，一般用于隐藏真实网址的重定向。一旦url重定向了，后面不应该再输出任何东西。
		错误状态用于应用程序主动置返回代码给web服务器软件，web服务器软件选择合适的返回页面给浏览器。返回代码包括“200”（正确得到服务端响应处理）等，请参考HTTP规范。
		应用代码中，HTML头与Url重定向、错误状态只能放在所有输出最前面且只能选择其一。
		
	2.2.HTML模板技术
		
		HTML模板技术通过在模板字符串中进行字符串替换，用于获得最终HTML代码流。
		HTML模板代码一般放置在字符数组缓冲区里，其中不仅包含符合规范的HTML代码，还包含数据替换宏。数据替换宏也是一串以'\0'结束的字符数组变量值，其取名没有固定要求，但一般推荐以'$'包裹宏名组成以区别HTML代码。
		
3.使用指南

	3.1.HTML头、Url重定向、错误状态
		
		·HTML头
			
			在发送HTML代码前需要发送HTTP响应类型，以下代码为发送HTTP响应类型为HTML代码
			CGIHtmlSendContent( CONTENT_TYPE_TEXTHTML );
			
			如果HTTP响应类型为图片二进制数据
			CGIHtmlSendContent( CONTENT_TYPE_IMAGEJPEG );
			
		·Url重定向
			
			以下代码重定向当前url为“http://www.xxx.com/”（浏览器里的url不变）
			CGIHtmlLocationURL( "http://www.xxx.com/" );
		
		·错误状态
			
			以下代码置HTTP响应代码为“404”
			CGIHtmlSendStatus( 404 );
			
	3.2.HTML模板使用例子
		
		char	acTemplateBuffer[ 1024 + 1 ] ; /* 声明模板缓冲区 */
		char	acHtmlBuffer[ 1024 + 1 ] ; /* HTML缓冲区 */
		SList	*plistTemplateTag = NULL ; /* 模板替换宏链表 */
		
		memset( acTemplateBuffer , 0x00 , sizeof(acTemplateBuffer) );
		memset( acHtmlBuffer , 0x00 , sizeof(acHtmlBuffer) );
		
		/* 装载模板文件 */
		iret = CGIHtmlLoadTemplate( "template.html" , acTemplateBuffer ) ;
		
		/* 初始化模板替换宏链表 */
		plistTemplateTag = CGIHtmlTemplateTagListInitial() ;
		
		/* 向模板替换宏里添加替换项 */
		CGIHtmlAddTemplateStringTag( &plistTemplateTag , "$用户名$" , "root" );
		CGIHtmlAddTemplateLongTag( &plistTemplateTag , "$CREDIT$" , 1000 );
		
		/* 模板替换宏链表处理模板 */
		iret = CGIHtmlProcessTemplate( plistTemplateTag , acTemplateBuffer , acHtmlBuffer ) ;
		
		/* 输出HTML给浏览器 */
		CGIHtmlSendContent( CONTENT_TYPE_TEXTHTML );
		printf( "%s" , acHtmlBuffer );
		
		/* 销毁模板替换宏链表 */
		CGIHtmlTemplateTagListDestroy( &plistTemplateTag );
	
	3.3.HTML模板使用中防缓冲区溢出
		
		在上例中变量acTemplateBuffer、acHtmlBuffer在使用中有可能溢出，比如使用CGIHtmlLoadTemplate装载的文件太大或者CGIHtmlProcessTemplate处理后的HTML代码过长，CGIHtml函数库提供了这两个函数的安全版本（安全的装载模板文件函数CGIHtmlLoadTemplateSafely和安全的模板处理函数CGIHtmlProcessTemplateSafely）建议在关键代码部位代替非安全函数。
		
	3.4.其它HTML处理函数
		
		函数CGIHtmlProcessHtmlByUBB可以处理目标缓冲区中的UBB代码转换成HTML代码，它的安全版本函数是CGIHtmlProcessHtmlByUBBSafely。
		函数CGIHtmlProcessTextToHtml可以处理目标缓冲区中的文本代码转换成HTML代码（比如'\t'转换为"&nbsp&nbsp&nbsp&nbsp"，'\n'转换为"<p>"，'<'转换为"&lt;"），它的安全版本函数是CGIHtmlProcessTextToHtmlSafely。
		
4.参考列表
	
	4.1.宏列表
		
		CONTENT_TYPE_TEXTHTML	HTTP响应类型为HTML代码
		CONTENT_TYPE_IMAGEJPEG	HTTP响应类型为二进制图片数据
		CONTENT_TYPE_DOWNLOAD	HTTP响应类型为二进制下载数据
		
	4.2.函数列表
	
		void CGIHtmlSendContent( int ContentType );
		void CGIHtmlLocationURL( char *url );
		void CGIHtmlSendStatus( int status );
		
		SList *CGIHtmlTemplateTagListInitial();
		BOOL CGIHtmlTemplateTagListDestroy( SList **listHtmlTemplateTag );
		
		int CGIHtmlLoadTemplate( char *filename , char *template_buf );
		int CGIHtmlLoadTemplateSafely( char *filename , char **template_buf , long *template_buf_size );
		
		BOOL CGIHtmlAddTemplateLongTag( SList **listHtmlTemplateTag , char *tag , long l );
		BOOL CGIHtmlAddTemplateDoubleTag( SList **listHtmlTemplateTag , char *tag , double d );
		BOOL CGIHtmlAddTemplateStringTag( SList **listHtmlTemplateTag , char *tag , char *str );
		
		int CGIHtmlProcessTemplate( SList *listHtmlTemplateTag , char *template_buf , char *html_buf );
		int CGIHtmlProcessTemplateSafely( SList *listHtmlTemplateTag , char *template_buf , long *template_buf_size , char **html_buf , long *html_buf_size );
		
		int CGIHtmlProcessHtmlByUBB( char *html_buf );
		int CGIHtmlProcessHtmlByUBBSafely( char **html_buf , long *html_buf_size );
		
		int CGIHtmlProcessTextToHtml( char *html_buf );
		int CGIHtmlProcessTextToHtmlSafely( char **html_buf , long *html_buf_size );
		
		·CGIHtmlSendContent
		设置HTTP响应类型
		
		函数原型：
			void CGIHtmlSendContent( int ContentType );
		输入参数：
			int ContentType			HTTP响应类型
		返回值：
			（无）
		
		详细描述与注意事项：
			（无）
		示例代码：
			CGIHtmlSendContent( CONTENT_TYPE_TEXTHTML );
		相关函数：
			CGIHtmlLocationURL , CGIHtmlSendStatus
		
		·CGIHtmlLocationURL
		重定向当前url
		
		函数原型：
			void CGIHtmlLocationURL( char *url );
		输入参数：
			char *url			新的url
		返回值：
			（无）
		
		详细描述与注意事项：
			浏览器里的url不变
		示例代码：
			CGIHtmlLocationURL( "http://www.xxx.com" );
		相关函数：
			CGIHtmlSendContent , CGIHtmlSendStatus
		
		·CGIHtmlSendStatus
		发送HTTP错误代码给浏览器
		
		函数原型：
			void CGIHtmlSendStatus( int status );
		输入参数：
			int status		HTTP错误代码
		返回值：
			（无）
		
		详细描述与注意事项：
			浏览器里的url不变
		示例代码：
			CGIHtmlSendStatus( 404 );
		相关函数：
			CGIHtmlSendContent , CGIHtmlLocationURL
		
		·CGIHtmlTemplateTagListInitial
		初始化HTML模板替换宏链表
		
		函数原型：
			SList *CGIHtmlTemplateTagListInitial();
		输入参数：
			（无）
		返回值：
			NULL
		
		详细描述与注意事项：
			（无）
		示例代码：
			SList	*plistTemplateTag = NULL ;
			plistTemplateTag = CGIHtmlTemplateTagListInitial() ;
		相关函数：
			CGIHtmlTemplateTagListDestroy
		
		·CGIHtmlTemplateTagListDestroy
		销毁HTML模板替换宏链表
		
		函数原型：
			BOOL CGIHtmlTemplateTagListDestroy( SList **listHtmlTemplateTag );
		输入参数：
			SList **listHtmlTemplateTag		HTML模板替换宏链表首结点地址的地址
		返回值：
			成功，返回 TRUE
			失败，返回 FALSE
		
		详细描述与注意事项：
			（无）
		示例代码：
			SList	*plistTemplateTag = NULL ;
			BOOL	bret ;
			bret = CGIHtmlTemplateTagListDestroy( &plistTemplateTag ) ;
		相关函数：
			CGIHtmlTemplateTagListInitial
		
		·CGIHtmlLoadTemplate
		装载HTML模板
		
		函数原型：
			int CGIHtmlLoadTemplate( char *filename , char *template_buf );
		输入参数：
			char *filename			外部HTML模板文件名
			char *template_buf		装载缓冲区
		返回值：
			成功，返回 0
			失败，返回 -1
		
		详细描述与注意事项：
			（无）
		示例代码：
			char	acTemplateBuffer[ 1024 + 1 ] ;
			int		iret ;
			iret = CGIHtmlLoadTemplate( "template.html" , acTemplateBuffer ) ;
		相关函数：
			CGIHtmlLoadTemplateSafely
		
		·CGIHtmlLoadTemplateSafely
		安全的装载HTML模板