cgicookie.txt

用C些的CGI函数库

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链表容器时调试日志文件名