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" ) ;
		相關函數：
			（無）