cgiquery.txt

用C些的CGI函数库

CGIQuery函数子库文档
作者：		BetonArmEE
最新版本：	2007-04-04	v1.0

>>> 目录
1.关于
	1.1.功能概述
	1.2.兼容平台列表
	1.3.版本历史
2.知识手册
	2.1.query数据与query链表容器
3.使用指南
	3.1.创建、销毁query链表容器
	3.2.装载query数据到链表容器
	3.3.读取、遍历query数据
	3.4.系统限制选项
	3.5.调试选项
	3.6.示例1：读取浏览器端提交的地址栏数据
4.参考列表
	4.1.结构体列表
	4.2.函数列表

>>> 正文
1.关于

	1.1.功能概述
	
		CGIQuery是iCGI函数库中最重要的子函数库之一。
		CGIQuery主要处理浏览器访问网址的读取和分析，实现服务端应用获取用户访问网址数据处理完整解决方案。
		
	1.2.兼容平台列表
	
		Windows、UNIX、Linux
		
	1.3.版本历史
	
		2005-05-02	创建 第一版
		2007-04-02	创建 文档
		
2.知识手册

	2.1.query数据与query链表容器
	
		网络域名地址由域名、路径、文件名以及参数列表组成，最简单的网络域名地址比如“http://www.xxx.com/”，稍稍复杂一点的有“http://www.xxx.com/forum/showtopic.jsp?forumid=1&topicid=3”，“http:”是使用的协议，“www.xxx.com”是域名，“/forum/”是路径，“showtopic.jsp”是访问的动态语言程序，“forumid=1&topicid=3”是参数列表。当浏览器指向新网址后，query数据通过网络传输到服务器端，由web服务软件转交给cgi程序，cgi程序从环境变量中读出地址栏信息并做出相应业务逻辑处理。
		CGIQuery子函数库封装了cgi程序读取和分析地址栏过程，通过函数读取浏览器端发送过来的query数据到query链表容器数据结构，提供大量函数方便从query链表容器中读取地址栏数据。

3.使用指南

	3.1.创建、销毁query链表容器
	
		query链表容器其实是一个通用泛型链表（请参考iLibX函数库List子函数库相关文档），用于存放表单query数据，链表结点类型主要为key-value，key存放表单域名数据，value存放表单域值数据。
		
		·创建query链表容器
		
			以下代码片断声明了通用泛型链表结构plist并初始化为query链表容器空值：
				SList *plist = NULL ;
				plist = CGIQueryListInitial() ;
				
		·销毁query链表容器
		
			以下代码片断用于销毁query链表容器，如果query链表容器内有query数据，则销毁前先释放query数据：
				BOOL bret ;
				bret = CGIQueryListDestroy( &plist ) ;
			当销毁成功，CGIQueryListDestroy返回TRUE，否则返回FALSE
			
	3.2.装载query数据到链表容器
	
		query链表容器被初始化后需要装载浏览器端提交过来的query数据
		以下代码片断用于从web服务器软件处获取装载query数据到query链表容器里去：
			BOOL bret ;
			bret = CGIQueryReadData( &plist ) ;
			
	3.3.读取、遍历query数据
	
		由于query链表容器其实就是一个通用泛型链表，就可以用iLibX.List子函数库中的函数读取链表中结点数据即query数据，此外CGIQuery子函数库提供了一组函数能够更方便快捷的按表单域名为索引读取表单域值。
		注意：读取过程并没有把数据复制出来，而是把链表内表单域值数据的内存首地址赋值给应用程序指定的指针变量，应用程序可以通过引用该指针变量自行做复制等处理。
		
		·读取一般地址栏数据
			以下代码片断从query链表容器用于读取地址栏参数'forumid'的值：
				char *pvalue = NULL ;
				pvalue = CGIQueryGetValue( plist , "textfieldUserName" ) ;
			
		·遍历query数据
		
			请参考iLibX.List子函数库相关函数遍历链表即可。
			
	3.5.调试选项
	
		为方便调试query数据装载过程，设置调试选项能够使应用开发者方便观察query数据装载过程。
		函数SetQueryDebugFileName用于设置日志文件名，使装载query数据过程中有相关dump信息写入外部文件。如果日志文件名为空字符串（即""）则不写日志。可设置的日志文件名长度最长为255个字符。
		函数GetQueryDebugFileName用于复制当前已经设置的日志文件名到应用程序指定的缓冲区中。函数不检查缓冲大小，防溢出控制由应用开发者处理。
		
	3.6.示例1：读取浏览器端指向的地址栏数据
	
		浏览器端指向的本程序网址为：
			
			http://www.xxx.com/module/user/cgi-bin/sys_ServiceManage.fcsp?username=root&password=root
			
		服务器端cgi代码如下：
		
			SList *plistQuery = NULL ; /* query链表容器，其实就是iLibX.List链表 */
			char *username = NULL ; /* 为方便阅读代码，这里把变量名与地址栏参数名写成一样 */
			char *password = NULL ;
			BOOL bret ;
			
			/* 初始化query链表容器 */
			plistQuery = CGIQueryListInitial() ;
			if( plistQuery == NULL )
			{
				/* ...初始化query链表容器失败处理... */
			}
			
			/* 装载query数据到query链表容器 */
			bret = CGIQueryReadData( &plistQuery ) ;
			if( bret != TRUE )
			{
				/* ...装载query数据到query链表容器失败处理... */
			}
			
			/* 读取query数据，即由参数名获得地址栏参数值在query链表容器里的首地址 */
			username = CGIQueryGetValue( plistQuery , "username" ) ;
			password = CGIQueryGetValue( plistQuery , "password" ) ;
			
			/* ...这时已经得到了浏览器指向的地址参数，根据业务逻辑做相应的处理... */
			
			/* 销毁query链表容器 */
			bret = CGIQueryListDestroy( &plistQuery ) ;
			{
				/* ...销毁query链表容器失败处理... */
			}
			
4.参考列表

	4.1.函数列表
		
		SetQueryDebugFileName
		GetQueryDebugFileName
		
		CGIQueryListInitial
		CGIQueryListDestroy
		
		CGIQueryReadData
		
		CGIQueryGetValue
		
		SetQueryDebugFileName
		设置装载query链表容器时调试日志文件名
		
		函数原型：
			BOOL SetQueryDebugFileName( char *pcDebugPathFileName );
		输入参数：
			char *pcDebugPathFileName	调试日志文件名
		返回值：
			BOOL						设置成功，返回 TRUE
										设置失败，返回 FALSE
		
		详细描述与注意事项：
			（无）
		示例代码：
			SetQueryDebugFileName( "query.log" );
		相关函数：
			GetQueryDebugFileName
		
		GetQueryDebugFileName
		获得装载query链表容器时调试日志文件名
		
		函数原型：
			BOOL GetQueryDebugFileName( char *pcDebugPathFileName );
		输入参数：
			（无）
		输出参数：
			char *pcDebugPathFileName	调试日志文件名
		返回值：
			BOOL						总是返回 TRUE
		
		详细描述与注意事项：
			（无）
		示例代码：
			char buffer[256+1];
			GetQueryDebugFileName( buffer );
		相关函数：
			SetQueryDebugFileName

		·CGIQueryListInitial
		初始化query链表容器
		
		函数原型：
			SList *CGIQueryListInitial();
		输入参数：
			（无）
		返回值：
			SList *		总是返回iLibX.List链表初始化值
		
		详细描述与注意事项：
			（无）
		示例代码：
			SList *plist = NULL ;
			plist = CGIQueryListInitial() ;
		相关函数：
			CGIQueryListDestroy

		·CGIQueryListDestroy
		销毁query链表容器
		
		函数原型：
			BOOL CGIQueryListDestroy( SList **listQuery );
		输入参数：
			SList **listQuery		query链表容器的地址
		返回值：
			销毁成功，返回 TRUE
			销毁失败，返回 FALSE
		
		详细描述与注意事项：
			（无）
		示例代码：
			CGIQueryListDestroy( &plist );
		相关函数：
			CGIQueryListInitial , FreeCGIQueryData

		·CGIQueryReadData
		装载浏览器端指向的地址栏数据到链表容器
		
		函数原形：
			BOOL CGIQueryReadData( SList **listQuery )
		输入参数：
			SList **listQuery	query链表容器的地址
		返回值：
			读取成功，返回值 TRUE
			读取失败或者没有表单数据，返回 FALSE
		
		详细描述与注意事项：
			（无）
		示例代码：
			CGIQueryReadData( &plist );
		相关函数：
			（无）
		
		·CGIQueryGetValue
		由表单域名获取在query链表容器中表单域值的内存首地址
		
		函数原型：
			char *CGIQueryGetValue( SList *listQuery , char *name );
		输入参数：
			SList *listQuery		query链表容器
			char *name			表单域名
		返回值：
			char *				query链表容器中表单域值的内存首地址
		
		详细描述与注意事项：
			（无）
		示例代码：
			username = CGIQueryGetValue( plist , "username" ) ;
		相关函数：
			（无）