CGICookie函數子庫文檔
作者：		BetonArmEE
最新版本：	2007-04-03	v1.0

>>> 目錄
1.關于
	1.1.功能概述
	1.2.兼容平臺列表
	1.3.版本歷史
2.知識手冊
	2.1.cookie數據與cookie鏈表容器
	2.2.cookie屬性容器
3.使用指南
	3.1.創建、銷毀cookie鏈表容器
	3.2.裝載cookie數據到鏈表容器
	3.3.傳送cookie數據給瀏覽器
	3.4.讀寫、遍歷cookie數據
	3.5.設置cookie屬性
	3.6.調試選項
	3.7.示例1：讀取瀏覽器端傳送過來的cookie數據
	3.8.示例2：寫入cookie數據到瀏覽器端
4.參考列表
	4.1.結構體列表
	4.2.函數列表

>>> 正文
1.關于

	1.1.功能概述
	
		CGICookie是iCGI函數庫中最重要的子函數庫之一。
		CGICookie主要處理瀏覽器與服務器交互會話時使用的cookie數據的讀寫，實現服務端應用讀寫cookie數據完整解決方案。
		
	1.2.兼容平臺列表
	
		Windows、UNIX、Linux
		
	1.3.版本歷史
	
		2005-05-02	創建 第一版
		2007-04-02	創建 文檔
		
2.知識手冊

	2.1.cookie數據與cookie鏈表容器
		
		瀏覽器端和服務器端交互經常使用cookie來保存一次會話所需要的認證信息，比如某些論壇的用戶登錄狀態。cookie可由服務器端或瀏覽器端創建，當瀏覽器端訪問一個網址時會自動把從屬于該域名的cookie信息發往服務器端
		
		瀏覽器端表單（cookie）擁有若干表單域（field），最簡單的表單比如網站用戶注冊表單，要求用戶輸入用戶名、密碼等信息。當表單提交后，cookie數據通過網絡傳輸到服務器端，由web服務軟件轉交給cgi程序，cgi程序從環境變量中讀出cookie數據并做出相應業務邏輯處理。
		CGICookie子函數庫封裝了cgi程序讀取和分析過程，通過函數讀取瀏覽器端發送過來的cookie數據到cookie鏈表容器數據結構，提供大量函數方便從cookie鏈表容器中讀取表單域數據。
	
	2.2.cookie屬性容器
	
		瀏覽器端和服務器端交互的cookie信息不僅包含cookie鍵-值數據，還包含cookie屬性數據。cookie屬性數據描述了cookie所屬的域名及路徑、cookie過期時間、cookie安全屬性。
	
3.使用指南

	3.1.創建、銷毀cookie鏈表容器
	
		cookie鏈表容器其實是一個通用泛型鏈表（請參考iLibX函數庫List子函數庫相關文檔），用于存放表單cookie數據，鏈表結點類型主要為key-value，key存放表單域名數據，value存放表單域值數據。
		
		·創建cookie鏈表容器
		
			以下代碼片斷聲明了通用泛型鏈表結構plist并初始化為cookie鏈表容器空值：
				SList *plist = NULL ;
				plist = CGICookieListInitial() ;
		·銷毀cookie鏈表容器
		
			以下代碼片斷用于銷毀cookie鏈表容器，如果cookie鏈表容器內有cookie數據，則銷毀前先釋放cookie數據：
				BOOL bret ;
				bret = CGICookieListDestroy( &plist ) ;
			當銷毀成功，CGICookieListDestroy返回TRUE，否則返回FALSE
			
	3.2.裝載cookie數據到鏈表容器
	
		cookie鏈表容器被初始化后需要裝載瀏覽器端發送過來的cookie數據
		以下代碼片斷用于從web服務器軟件處獲取裝載cookie數據到cookie鏈表容器里去：
			BOOL bret ;
			bret = CGICookieReadData( &plist ) ;
			
	3.3.發送cookie數據到瀏覽器端
			
		以下代碼發送cookie數據到瀏覽器端，瀏覽器接收到以后自動寫入cookie保存目錄
			BOOL bret ;
			SCookieInfo cookieinfo ;
			...
			bret = CGICookieWriteData( &plist , &cookieinfo ) ;
			
	3.4.讀寫、遍歷cookie數據
	
		由于cookie鏈表容器其實就是一個通用泛型鏈表，就可以用iLibX.List子函數庫中的函數讀取鏈表中結點數據即cookie數據，此外CGICookie子函數庫提供了一組函數能夠更方便快捷的按表單域名為索引讀取表單域值。
		注意：讀取過程并沒有把數據復制出來，而是把鏈表內表單域值數據的內存首地址賦值給應用程序指定的指針變量，應用程序可以通過引用該指針變量自行做復制等處理。
		
		·讀取cookie鏈表容器里面的cookie數據
		
			以下代碼片斷從cookie鏈表容器用于讀取cookie鍵'cookieUserName'的cookie值：
				char *cookieUserName = NULL ;
				cookieUserName = CGICookieGetValue( plist , "cookieUserName" ) ;
		
		·向cookie鏈表容器里添加一個新的cookie鍵-值項

			以下代碼片斷添加一個新的cookie鍵-值項到cookie鏈表容器里
				BOOL bret ;
				bret = CGICookieAddItem( &plist , "cookieUserName" , "root" ) ;
			
		·修改cookie鏈表容器里的一個cookie鍵-值項
			
			以下代碼片斷修改一個cookie鍵-值項
				BOOL bret ;
				bret = CGICookieEditItem( &plist , "cookiePassword" , "root" ) ;
		
		·刪除cookie鏈表容器里的一個cookie鍵-值項
			
			以下代碼片斷從cookie鏈表容器里刪除一個cookie鍵-值項
				BOOL bret ;
				bret = CGICookieDeleteItem( &plist , "cookieUserName" ) ;
		
		·設置cookie鏈表容器里的一個cookie鍵-值項
			
			以下代碼片斷設置一個cookie鍵-值項到cookie鏈表容器里，如果該cookie鍵沒有則添加，如果有則修改
				BOOL bret ;
				bret = CGICookieSetItem( &plist , "cookieNickName" , "系統管理員" ) ;
		
		·遍歷cookie數據
		
			請參考iLibX.List子函數庫相關函數遍歷鏈表即可。
		
	3.5.設置cookie屬性
	
		·設置cookie所屬域名
		
			以下代碼設置cookie所屬域名屬性為"www.xxx.com"
				BOOL bret ;
				SCookieInfo cookieinfo ;
				bret = CGICookieSetDomain( &cookieinfo , "www.xxx.com" ) ;
		
		·設置cookie所屬網址目錄
		
			以下代碼設置cookie所屬網址目錄為"/"
				BOOL bret ;
				SCookieInfo cookieinfo ;
				bret = CGICookieSetPath( &cookieinfo , "/" ) ;
		
		·設置cookie過期時間
		
			以下代碼設置cookie過期時間為"2008-01-01 00:00:00 GMT"
				BOOL bret ;
				SCookieInfo cookieinfo ;
				bret = CGICookieSetExprires( &cookieinfo , "2008-01-01 00:00:00 GMT" ) ;
		
		·設置cookie安全屬性
		
			以下代碼設置cookie安全屬性為空
				BOOL bret ;
				SCookieInfo cookieinfo ;
				bret = CGICookieSetSecure( &cookieinfo , "" ) ;
		
	3.6.調試選項
	
		為方便調試cookie數據裝載過程，設置調試選項能夠使應用開發者方便觀察cookie數據裝載過程。
		函數SetCookieDebugFileName用于設置日志文件名，使裝載cookie數據過程中有相關dump信息寫入外部文件。如果日志文件名為空字符串（即""）則不寫日志。可設置的日志文件名長度最長為255個字符。
		函數GetCookieDebugFileName用于復制當前已經設置的日志文件名到應用程序指定的緩沖區中。函數不檢查緩沖大小，防溢出控制由應用開發者處理。
		
	3.7.示例1：讀取瀏覽器端傳送過來的cookie數據
	
		瀏覽器端傳送過來的cookie數據如下：
		
			cookieUserName=root; cookiePassword=root;
			
		服務器端cgi代碼如下：
		
			SList *plistCookie = CGICookieListInitial() ; /* cookie鏈表容器，其實就是iLibX.List鏈表 */
			char *cookieUserName; /* 為方便閱讀代碼，這里把變量名與cookie鍵寫成一樣 */
			char *cookieRealName;
			char *cookiePassword;
			
			BOOL bret ;
			
			/* 初始化cookie鏈表容器 */
			plistCookie = CGICookieListInitial() ;
			if( plistCookie == NULL )
			{
				/* ...初始化cookie鏈表容器失敗處理... */
			}
			
			/* 裝載cookie數據到cookie鏈表容器 */
			bret = CGICookieReadData( &plistCookie ) ;
			if( bret != TRUE )
			{
				/* ...裝載cookie數據到cookie鏈表容器失敗處理... */
			}
			
			/* 讀取cookie數據，即由表單域名獲得表單域值在cookie鏈表容器里的首地址 */
			cookieUserName = CGICookieGetValue( plistCookie , "cookieUserName" ) ;
			cookieRealName = CGICookieGetValue( plistCookie , "cookieRealName" ) ;
			
			/* ...這時已經得到了瀏覽器端表單用戶名與密碼，根據業務邏輯做相應的處理... */
			
			/* 銷毀cookie鏈表容器 */
			bret = CGICookieListDestroy( &plistCookie ) ;
			{
				/* ...銷毀cookie鏈表容器失敗處理... */
			}
			
	3.8.示例2：寫入cookie數據到瀏覽器端
			
			SList *plistCookie = CGICookieListInitial() ; /* cookie鏈表容器，其實就是iLibX.List鏈表 */
			SCookieInfo *pinfoCookie = CGICookieInfoInitial() ; /* cookie屬性容器 */
			struct tm *time_tm = NULL ;

			char *cookieUserName; /* 為方便閱讀代碼，這里把變量名與cookie鍵寫成一樣 */
			char *cookiePassword;
			
			BOOL bret ;
			
			/* 初始化cookie鏈表容器 */
			plistCookie = CGICookieListInitial() ;
			if( plistCookie == NULL )
			{
				/* ...初始化cookie鏈表容器失敗處理... */
			}
			
			/* 添加cookie數據 */
			CGICookieAddItem( &listCookie , "cookieUserName" , "root" );
			CGICookieAddItem( &listCookie , "cookiePassword" , "root" );
			
			/* 設置cookie屬性 */
			CGICookieSetPath( infoCookie , "/" );
			
			time_tm = GetLocalTimeStruct() ;
			OffsetHours( time_tm , +12 );
			CGICookieSetExprires( infoCookie , time_tm );
			
			/* 寫cookie數據 */
			CGICookieWriteData( listCookie , infoCookie );
			
			/* 銷毀cookie鏈表容器 */
			bret = CGICookieListDestroy( &plistCookie ) ;
			{
				/* ...銷毀cookie鏈表容器失敗處理... */
			}

4.參考列表

	4.1.結構體列表
	
		typedef struct tagCookieInfo
		{
			char *exprires; /* 過期時間 */
			char *path; /* 路徑 */
			char *domain; /* 域名 */
			char *secure; /* 安全權限 */
		}
		SCookieInfo; /* cookie屬性結構 */
		
	4.2.函數列表
	
		SetCookieDebugFileName
		GetCookieDebugFileName
		
		CGICookieListInitial
		CGICookieListDestroy
		CGICookieInfoInitial
		CGICookieInfoDestroy
		
		CGICookieReadData
		CGICookieWriteData
		
		CGICookieGetValue
		
		CGICookieAddItem
		CGICookieEditItem
		CGICookieDeleteItem
		CGICookieSetItem
		
		CGICookieSetExprires
		CGICookieSetPath
		CGICookieSetDomain
		CGICookieSetSecure
		
		·SetCookieDebugFileName
		設置讀寫cookie鏈表容器時調試日志文件名
		
		函數原型：
			BOOL SetCookieDebugFileName( char *pcDebugPathFileName );
		輸入參數：
			char *pcDebugPathFileName	調試日志文件名
		返回值：
			BOOL						設置成功，返回 TRUE
										設置失敗，返回 FALSE
		
		詳細描述與注意事項：
			（無）
		示例代碼：
			SetCookieDebugFileName( "cookie.log" );
		相關函數：
			GetCookieDebugFileName
		
		·GetCookieDebugFileName
		獲得讀寫cookie鏈表容器時調試日志文件名