CGIForm函數(shù)子庫(kù)文檔
作者：		BetonArmEE
最新版本：	2007-04-03	v1.0

>>> 目錄
1.關(guān)于
	1.1.功能概述
	1.2.兼容平臺(tái)列表
	1.3.版本歷史
2.知識(shí)手冊(cè)
	2.1.form數(shù)據(jù)與form鏈表容器
3.使用指南
	3.1.創(chuàng)建、銷毀form鏈表容器
	3.2.裝載form數(shù)據(jù)到鏈表容器
	3.3.讀取、遍歷form數(shù)據(jù)
	3.4.系統(tǒng)限制選項(xiàng)
	3.5.調(diào)試選項(xiàng)
	3.6.示例1：讀取瀏覽器端提交的表單數(shù)據(jù)
4.參考列表
	4.1.結(jié)構(gòu)體列表
	4.2.函數(shù)列表

>>> 正文
1.關(guān)于

	1.1.功能概述
	
		CGIForm是iCGI函數(shù)庫(kù)中最重要的子函數(shù)庫(kù)之一。
		CGIForm主要處理瀏覽器端表單數(shù)據(jù)（包含上傳文件數(shù)據(jù)）的讀取和分析，實(shí)現(xiàn)服務(wù)端應(yīng)用獲取瀏覽器端表單數(shù)據(jù)完整解決方案。
		
	1.2.兼容平臺(tái)列表
	
		Windows、UNIX、Linux
		
	1.3.版本歷史
	
		2005-05-02	創(chuàng)建 第一版
		2007-04-02	創(chuàng)建 文檔
		
2.知識(shí)手冊(cè)

	2.1.form數(shù)據(jù)與form鏈表容器
	
		瀏覽器端表單（form）擁有若干表單域（field），最簡(jiǎn)單的表單比如網(wǎng)站用戶注冊(cè)表單，要求用戶輸入用戶名、密碼等信息。當(dāng)表單提交后，form數(shù)據(jù)通過網(wǎng)絡(luò)傳輸?shù)椒?wù)器端，由web服務(wù)軟件轉(zhuǎn)交給cgi程序，cgi程序從環(huán)境變量中讀出form數(shù)據(jù)并做出相應(yīng)業(yè)務(wù)邏輯處理。
		CGIForm子函數(shù)庫(kù)封裝了cgi程序讀取和分析過程，通過函數(shù)讀取瀏覽器端發(fā)送過來的form數(shù)據(jù)到form鏈表容器數(shù)據(jù)結(jié)構(gòu)，提供大量函數(shù)方便從form鏈表容器中讀取表單域數(shù)據(jù)。

3.使用指南

	3.1.創(chuàng)建、銷毀form鏈表容器
	
		form鏈表容器其實(shí)是一個(gè)通用泛型鏈表（請(qǐng)參考iLibX函數(shù)庫(kù)List子函數(shù)庫(kù)相關(guān)文檔），用于存放表單form數(shù)據(jù)，鏈表結(jié)點(diǎn)類型主要為key-value，key存放表單域名數(shù)據(jù)，value存放表單域值數(shù)據(jù)。
		
		·創(chuàng)建form鏈表容器
		
			以下代碼片斷聲明了通用泛型鏈表結(jié)構(gòu)plist并初始化為form鏈表容器空值：
				SList *plist = NULL ;
				plist = CGIFormListInitial() ;
				
		·銷毀form鏈表容器
		
			以下代碼片斷用于銷毀form鏈表容器，如果form鏈表容器內(nèi)有form數(shù)據(jù)，則銷毀前先釋放form數(shù)據(jù)：
				BOOL bret ;
				bret = CGIFormListDestroy( &plist ) ;
			當(dāng)銷毀成功，CGIFormListDestroy返回TRUE，否則返回FALSE
			
	3.2.裝載form數(shù)據(jù)到鏈表容器
	
		form鏈表容器被初始化后需要裝載瀏覽器端提交過來的form數(shù)據(jù)
		以下代碼片斷用于從web服務(wù)器軟件處獲取裝載form數(shù)據(jù)到form鏈表容器里去：
			BOOL bret ;
			bret = CGIFormReadData( &plist ) ;
			
	3.3.讀取、遍歷form數(shù)據(jù)
	
		由于form鏈表容器其實(shí)就是一個(gè)通用泛型鏈表，就可以用iLibX.List子函數(shù)庫(kù)中的函數(shù)讀取鏈表中結(jié)點(diǎn)數(shù)據(jù)即form數(shù)據(jù)，此外CGIForm子函數(shù)庫(kù)提供了一組函數(shù)能夠更方便快捷的按表單域名為索引讀取表單域值。
		注意：讀取過程并沒有把數(shù)據(jù)復(fù)制出來，而是把鏈表內(nèi)表單域值數(shù)據(jù)的內(nèi)存首地址賦值給應(yīng)用程序指定的指針變量，應(yīng)用程序可以通過引用該指針變量自行做復(fù)制等處理。
		
		·讀取一般表單域數(shù)據(jù)
			以下代碼片斷從form鏈表容器用于讀取瀏覽器表單行編輯框'textfieldUserName'中用戶輸入的值：
				char *pvalue = NULL ;
				pvalue = CGIFormGetValue( plist , "textfieldUserName" ) ;
			以下代碼片斷從form鏈表容器用于獲得表單行編輯框'textfieldUserName'中用戶輸入的值的長(zhǎng)度：
				long size ;
				size = CGIFormGetValueSize( plist , "textfieldUserName" ) ;
			有時(shí)瀏覽器端傳送過來的表單數(shù)據(jù)并不符合c語言字符串規(guī)則，此函數(shù)可以確定表單域值的長(zhǎng)度。
			
		·讀取包含上傳文件表單域數(shù)據(jù)
		
			以下代碼片斷用于從form鏈表容器讀取表單上傳文件域'fileUpload'的文件名（完整的全文件名，包含路徑、主文件名和文件擴(kuò)展名）：
				char *pfilename = NULL ;
				pfilename = CGIFormGetFileName( plist , "fileUpload" ) ;
			以下代碼片斷用于從form鏈表容器獲得表單上傳文件域'fileUpload'的文件大?。▎挝粸樽止?jié)）：
				long size ;
				size = CGIFormGetFileSize( plist , "fileUpload" ) ;
			以下代碼片斷用于從form鏈表容器讀取表單上傳文件域'fileUpload'的文件實(shí)際內(nèi)容：
				char *pfilecontent = NULL ;
				pfilecontent = CGIFormGetFileContent( plist , "fileUpload" ) ;
				
		·遍歷form數(shù)據(jù)
		
			請(qǐng)參考iLibX.List子函數(shù)庫(kù)相關(guān)函數(shù)遍歷鏈表即可。
			
	3.4.系統(tǒng)限制選項(xiàng)
	
		為防止瀏覽器端發(fā)送惡意數(shù)據(jù)而造成CGIForm相關(guān)函數(shù)中緩沖溢出，設(shè)置系統(tǒng)限制選項(xiàng)保護(hù)之。
		函數(shù)CGIFormSetMaxFieldNameSize設(shè)置允許的最大表單域名長(zhǎng)度和上傳文件域全文件名長(zhǎng)度，超出該限制則截取有效長(zhǎng)度部分。
		函數(shù)CGIFormSetMaxFieldDataSize設(shè)置允許的最大表單域值大小，超出該限制則截取有效長(zhǎng)度部分。
		函數(shù)CGIFormSetMaxFieldFileDataSize設(shè)置允許的最大上傳文件內(nèi)容大小，超出該限制則截取有效長(zhǎng)度部分。
		注意：系統(tǒng)限制選項(xiàng)函數(shù)必須在form數(shù)據(jù)裝載到form鏈表容器中去之前設(shè)置，即函數(shù)CGIFormReadData調(diào)用前。
		
	3.5.調(diào)試選項(xiàng)
	
		為方便調(diào)試form數(shù)據(jù)裝載過程，設(shè)置調(diào)試選項(xiàng)能夠使應(yīng)用開發(fā)者方便觀察form數(shù)據(jù)裝載過程。
		函數(shù)SetFormDebugFileName用于設(shè)置日志文件名，使裝載form數(shù)據(jù)過程中有相關(guān)dump信息寫入外部文件。如果日志文件名為空字符串（即""）則不寫日志?？稍O(shè)置的日志文件名長(zhǎng)度最長(zhǎng)為255個(gè)字符。
		函數(shù)GetFormDebugFileName用于復(fù)制當(dāng)前已經(jīng)設(shè)置的日志文件名到應(yīng)用程序指定的緩沖區(qū)中。函數(shù)不檢查緩沖大小，防溢出控制由應(yīng)用開發(fā)者處理。
		
	3.6.示例1：讀取瀏覽器端提交的表單數(shù)據(jù)
	
		瀏覽器端html代碼如下：
		
			<form name="formUserLogin" method="post" action="/cgi-bin/UserLogin.fcsp">
				用戶名：<input type="text" name="textfieldUserName">
				密碼：<input type="password" name="textfieldPassword">
				<input type="submit" name="submitUserLogin" value="提交">
			</form>
			
		服務(wù)器端cgi代碼如下：
		
			SList *plistForm = NULL ; /* form鏈表容器，其實(shí)就是iLibX.List鏈表 */
			char *textfieldUserName = NULL ; /* 為方便閱讀代碼，這里把變量名與表單域名寫成一樣 */
			char *textfieldPassword = NULL ;
			BOOL bret ;
			
			/* 初始化form鏈表容器 */
			plistForm = CGIFormListInitial() ;
			if( plistForm == NULL )
			{
				/* ...初始化form鏈表容器失敗處理... */
			}
			
			/* 裝載form數(shù)據(jù)到form鏈表容器 */
			bret = CGIFormReadData( &plistForm ) ;
			if( bret != TRUE )
			{
				/* ...裝載form數(shù)據(jù)到form鏈表容器失敗處理... */
			}
			
			/* 讀取form數(shù)據(jù)，即由表單域名獲得表單域值在form鏈表容器里的首地址 */
			textfieldUserName = CGIFormGetValue( plistForm , "textfieldUserName" ) ;
			textfieldPassword = CGIFormGetValue( plistForm , "textfieldPassword" ) ;
			
			/* ...這時(shí)已經(jīng)得到了瀏覽器端表單用戶名與密碼，根據(jù)業(yè)務(wù)邏輯做相應(yīng)的處理... */
			
			/* 銷毀form鏈表容器 */
			bret = CGIFormListDestroy( &plistForm ) ;
			{
				/* ...銷毀form鏈表容器失敗處理... */
			}
			
4.參考列表

	4.1.結(jié)構(gòu)體列表
	
		typedef struct tagCGIFormData
		{
			char *name; /* 表單域名 */
			char *data; /* 表單域值 或者 上傳文件域文件內(nèi)容 */
			long datasize; /* 表單域值大小 或者 上傳文件域文件大小 */
			
			char *filename; /* 上傳文件域全文件名 */
		}
		SCGIFormData; /* form數(shù)據(jù)，表單域信息包，form鏈表容器結(jié)點(diǎn)值 */
		
	4.2.函數(shù)列表
	
		SetFormDebugFileName
		GetFormDebugFileName
		
		CGIFormSetMaxFieldNameSize
		CGIFormSetMaxFieldDataSize
		CGIFormSetMaxFieldFileDataSize
		
		CGIFormListInitial
		CGIFormListDestroy
		FreeCGIFormData
		
		CGIFormReadData
		
		CGIFormGetValue
		CGIFormGetValueSize
		CGIFormGetFileName
		CGIFormGetFileSize
		CGIFormGetFileContent
		
		·SetFormDebugFileName
		設(shè)置裝載form鏈表容器時(shí)調(diào)試日志文件名
		
		函數(shù)原型：
			BOOL SetFormDebugFileName( char *pcDebugPathFileName );
		輸入?yún)?shù)：
			char *pcDebugPathFileName	調(diào)試日志文件名
		返回值：
			BOOL						設(shè)置成功，返回 TRUE
										設(shè)置失敗，返回 FALSE
		
		詳細(xì)描述與注意事項(xiàng)：
			（無）
		示例代碼：
			SetFormDebugFileName( "form.log" );
		相關(guān)函數(shù)：
			GetFormDebugFileName
		
		·GetFormDebugFileName
		獲得裝載form鏈表容器時(shí)調(diào)試日志文件名
		
		函數(shù)原型：
			BOOL GetFormDebugFileName( char *pcDebugPathFileName );
		輸入?yún)?shù)：
			（無）
		輸出參數(shù)：
			char *pcDebugPathFileName	調(diào)試日志文件名
		返回值：
			BOOL						總是返回 TRUE
		
		詳細(xì)描述與注意事項(xiàng)：
			（無）
		示例代碼：
			char buffer[256+1];
			SetFormDebugFileName( buffer );
		相關(guān)函數(shù)：
			SetFormDebugFileName

		·CGIFormSetMaxFieldNameSize
		設(shè)置最大表單域名長(zhǎng)度
		
		函數(shù)原型：
			void CGIFormSetMaxFieldNameSize( long maxsize );
		輸入?yún)?shù)：
			long maxsize	最大表單域名長(zhǎng)度
		返回值：
			（無）
		
		詳細(xì)描述與注意事項(xiàng)：
			（無）
		示例代碼：
			CGIFormSetMaxFieldNameSize( 1024 );
		相關(guān)函數(shù)：
			CGIFormSetMaxFieldDataSize , CGIFormSetMaxFieldFileDataSize

		·CGIFormSetMaxFieldDataSize
		設(shè)置最大表單域值大小
		
		函數(shù)原型：
			void CGIFormSetMaxFieldDataSize( long maxsize );
		輸入?yún)?shù)：
			long maxsize	最大表單域值大小
		返回值：
			（無）
		
		詳細(xì)描述與注意事項(xiàng)：
			（無）
		示例代碼：
			CGIFormSetMaxFieldDataSize( 1024 );
		相關(guān)函數(shù)：
			CGIFormSetMaxFieldNameSize , CGIFormSetMaxFieldFileDataSize

		·CGIFormSetMaxFieldFileDataSize
		設(shè)置最大上傳文件域文件大小
		
		函數(shù)原型：
			void CGIFormSetMaxFieldFileDataSize( long maxsize );
		輸入?yún)?shù)：
			long maxsize		最大上傳文件域文件大小
		返回值：
			（無）
		
		詳細(xì)描述與注意事項(xiàng)：
			（無）
		示例代碼：
			CGIFormSetMaxFieldFileDataSize( 1024 );
		相關(guān)函數(shù)：
			CGIFormSetMaxFieldNameSize , CGIFormSetMaxFieldDataSize

		·CGIFormListInitial
		初始化form鏈表容器
		
		函數(shù)原型：
			SList *CGIFormListInitial();
		輸入?yún)?shù)：
			（無）
		返回值：
			SList *		總是返回iLibX.List鏈表初始化值
		
		詳細(xì)描述與注意事項(xiàng)：
			（無）
		示例代碼：
			SList *plist = NULL ;
			plist = CGIFormListInitial() ;
		相關(guān)函數(shù)：
			CGIFormListDestroy

		·CGIFormListDestroy
		銷毀form鏈表容器
		
		函數(shù)原型：
			BOOL CGIFormListDestroy( SList **listForm );
		輸入?yún)?shù)：
			SList **listForm		form鏈表容器的地址
		返回值：
			銷毀成功，返回 TRUE
			銷毀失敗，返回 FALSE
		
		詳細(xì)描述與注意事項(xiàng)：
			（無）
		示例代碼：
			CGIFormListDestroy( &plist );
		相關(guān)函數(shù)：
			CGIFormListInitial , FreeCGIFormData

		·CGIFormReadData
		裝載瀏覽器端提交的表單數(shù)據(jù)到鏈表容器
		
		函數(shù)原形：
			BOOL CGIFormReadData( SList **listForm )
		輸入?yún)?shù)：
			SList **listForm	form鏈表容器的地址
		返回值：
			讀取成功，返回值 TRUE
			讀取失敗或者沒有表單數(shù)據(jù)，返回 FALSE
		
		詳細(xì)描述與注意事項(xiàng)：
			（無）
		示例代碼：
			CGIFormReadData( &plist );
		相關(guān)函數(shù)：
			（無）
		
		·CGIFormGetValue
		由表單域名獲取在form鏈表容器中表單域值的內(nèi)存首地址
		
		函數(shù)原型：
			char *CGIFormGetValue( SList *listForm , char *name );
		輸入?yún)?shù)：
			SList *listForm		form鏈表容器
			char *name			表單域名
		返回值：
			char *				form鏈表容器中表單域值的內(nèi)存首地址
		
		詳細(xì)描述與注意事項(xiàng)：
			（無）
		示例代碼：
			textfieldUserName = CGIFormGetValue( plist , "textfieldUserName" ) ;
		相關(guān)函數(shù)：
			CGIFormGetValueSize

		·CGIFormGetValueSize
		獲得表單域值大小
		
		函數(shù)原型：
			long CGIFormGetValueSize( SList *listForm , char *name );
		輸入?yún)?shù)：
			SList *listForm		form鏈表容器
			char *name			表單域名
		返回值：
			long				表單域值大小
		
		詳細(xì)描述與注意事項(xiàng)：
			（無）
		示例代碼：
			long size ;
			size = CGIFormGetValueSize( plist , "textfieldUserName" ) ;
		相關(guān)函數(shù)：
			CGIFormGetValue

		·CGIFormGetFileName
		由上傳文件域名獲取在form鏈表容器中上傳文件域全文件名的內(nèi)存首地址
		
		函數(shù)原型：
			char *CGIFormGetFileName( SList *listForm , char *name );
		輸入?yún)?shù)：
			SList *listForm		form鏈表容器
			char *name			上傳文件域名
		返回值：
			char *				form鏈表容器中上傳文件域文件名的內(nèi)存首地址
		
		詳細(xì)描述與注意事項(xiàng)：
			（無）
		示例代碼：
			char *pfilename = NULL ;
			pfilename = CGIFormGetFileName( plist , "fileUpload" ) ;
		相關(guān)函數(shù)：
			CGIFormGetFileSize , CGIFormGetFileContent

		·CGIFormGetFileSize
		由上傳文件域名獲取在form鏈表容器中上傳文件域文件大小
		獲取上傳文件域文件大小
		
		函數(shù)原型：
			long CGIFormGetFileSize( SList *listForm , char *name );
		輸入?yún)?shù)：
			SList *listForm		form鏈表容器
			char *name			上傳文件域名
		返回值：
			long				form鏈表容器中上傳文件域文件大小
		
		詳細(xì)描述與注意事項(xiàng)：
			（無）
		示例代碼：
			long size ;
			size = ·CGIFormGetFileSize( plist , "fileUpload" ) ;
		相關(guān)函數(shù)：
			CGIFormGetFileName , CGIFormGetFileContent

		·CGIFormGetFileContent
		由上傳文件域名獲取在form鏈表容器中上傳文件域文件內(nèi)容的內(nèi)存首地址
		
		函數(shù)原型：
			char *CGIFormGetFileContent( SList *listForm , char *name );
		輸入?yún)?shù)：
			SList *listForm		form鏈表容器
			char *name			上傳文件域名
		返回值：
			char *				form鏈表容器中上傳文件域文件內(nèi)容的內(nèi)存首地址
		
		詳細(xì)描述與注意事項(xiàng)：
			（無）
		示例代碼：
			char *pfilecontent = NULL ;
			pfilecontent = CGIFormGetFileContent( plist , "fileUpload" ) ;
		相關(guān)函數(shù)：
			CGIFormGetFileName , CGIFormGetFileSize