#ifndef _INCLUDE_CGIFORM_H_
#define _INCLUDE_CGIFORM_H_

/*
** 庫名			:	CGIForm
** 庫描述		:	用于處理表單信息的CGI函數庫
** 作者			:	calvin
** E-mail		:	CalvinWilliams@yeah.net
** QQ			:	21021078
** 創建日期時間	:	
** 更新日期時間	:	2005/5/2
*/

/* TEXTBLOCK 文檔標題 *
CGIForm函數庫文檔
BetonArmEE
v1.0.0.20070403
/TEXTBLOCK */

/* TEXTBLOCK 關于 功能概述
	CGIForm是iCGI函數庫中最重要的子函數庫之一。
	CGIForm主要處理瀏覽器端表單數據（包含上傳文件數據）的讀取和分析，實現服務端應用獲取瀏覽器端表單數據完整解決方案。
/TEXTBLOCK */

/* TEXTBLOCK 關于 兼容平臺列表
		Windows	UNIX	Linux
-------------------------------------
CGIForm	Y		Y		Y
TEXTBLOCK */

/* TEXTBLOCK 關于 版本歷史
2005-05-02	創建 第一版
2007-04-02	創建 文檔
/TEXTBLOCK */

/* TEXTBLOCK 知識手冊 form數據與form鏈表容器
	瀏覽器端表單（form）擁有若干表單域（field），最簡單的表單比如網站用戶注冊表單，要求用戶輸入用戶名、密碼等信息。當表單提交后，form數據通過網絡傳輸到服務器端，由web服務軟件轉交給cgi程序，cgi程序從環境變量中讀出form數據并做出相應業務邏輯處理。
	CGIForm子函數庫封裝了cgi程序讀取和分析過程，通過函數讀取瀏覽器端發送過來的form數據到form鏈表容器數據結構，提供大量函數方便從form鏈表容器中讀取表單域數據。
/TEXTBLOCK */

/* TEXTBLOCK 使用指南 創建、銷毀form鏈表容器
	form鏈表容器其實是一個通用泛型鏈表（請參考iLibX函數庫List子函數庫相關文檔），用于存放表單form數據，鏈表結點類型主要為key-value，key存放表單域名數據，value存放表單域值數據。
	
	·創建form鏈表容器
	
		以下代碼片斷聲明了通用泛型鏈表結構plist并初始化為form鏈表容器空值：
			SList *plist = NULL ;
			plist = CGIFormListInitial() ;
			
	·銷毀form鏈表容器
	
		以下代碼片斷用于銷毀form鏈表容器，如果form鏈表容器內有form數據，則銷毀前先釋放form數據：
			BOOL bret ;
			bret = CGIFormListDestroy( &plist ) ;
		當銷毀成功，CGIFormListDestroy返回TRUE，否則返回FALSE
/TEXTBLOCK */

/* TEXTBLOCK 使用指南 裝載form數據到鏈表容器
	form鏈表容器被初始化后需要裝載瀏覽器端提交過來的form數據
	以下代碼片斷用于從web服務器軟件處獲取裝載form數據到form鏈表容器里去：
		BOOL bret ;
		bret = CGIFormReadData( &plist ) ;
/TEXTBLOCK */

/* TEXTBLOCK 使用指南 讀取、遍歷form數據
	由于form鏈表容器其實就是一個通用泛型鏈表，就可以用iLibX.List子函數庫中的函數讀取鏈表中結點數據即form數據，此外CGIForm子函數庫提供了一組函數能夠更方便快捷的按表單域名為索引讀取表單域值。
	注意：讀取過程并沒有把數據復制出來，而是把鏈表內表單域值數據的內存首地址賦值給應用程序指定的指針變量，應用程序可以通過引用該指針變量自行做復制等處理。
	
	·讀取一般表單域數據
		以下代碼片斷從form鏈表容器用于讀取瀏覽器表單行編輯框'textfieldUserName'中用戶輸入的值：
			char *pvalue = NULL ;
			pvalue = CGIFormGetValue( plist , "textfieldUserName" ) ;
		以下代碼片斷從form鏈表容器用于獲得表單行編輯框'textfieldUserName'中用戶輸入的值的長度：
			long size ;
			size = CGIFormGetValueSize( plist , "textfieldUserName" ) ;
		有時瀏覽器端傳送過來的表單數據并不符合c語言字符串規則，此函數可以確定表單域值的長度。
		
	·讀取包含上傳文件表單域數據
	
		以下代碼片斷用于從form鏈表容器讀取表單上傳文件域'fileUpload'的文件名（完整的全文件名，包含路徑、主文件名和文件擴展名）：
			char *pfilename = NULL ;
			pfilename = CGIFormGetFileName( plist , "fileUpload" ) ;
		以下代碼片斷用于從form鏈表容器獲得表單上傳文件域'fileUpload'的文件大小（單位為字節）：
			long size ;
			size = CGIFormGetFileSize( plist , "fileUpload" ) ;
		以下代碼片斷用于從form鏈表容器讀取表單上傳文件域'fileUpload'的文件實際內容：
			char *pfilecontent = NULL ;
			pfilecontent = CGIFormGetFileContent( plist , "fileUpload" ) ;
			
	·遍歷form數據
	
		請參考iLibX.List子函數庫相關函數遍歷鏈表即可。
/TEXTBLOCK */

/* TEXTBLOCK 使用指南 系統限制選項
	為防止瀏覽器端發送惡意數據而造成CGIForm相關函數中緩沖溢出，設置系統限制選項保護之。
	函數CGIFormSetMaxFieldNameSize設置允許的最大表單域名長度和上傳文件域全文件名長度，超出該限制則截取有效長度部分。
	函數CGIFormSetMaxFieldDataSize設置允許的最大表單域值大小，超出該限制則截取有效長度部分。
	函數CGIFormSetMaxFieldFileDataSize設置允許的最大上傳文件內容大小，超出該限制則截取有效長度部分。
	注意：系統限制選項函數必須在form數據裝載到form鏈表容器中去之前設置，即函數CGIFormReadData調用前。
/TEXTBLOCK */

/* TEXTBLOCK 使用指南 調試選項
	為方便調試form數據裝載過程，設置調試選項能夠使應用開發者方便觀察form數據裝載過程。
	函數SetFormDebugFileName用于設置日志文件名，使裝載form數據過程中有相關dump信息寫入外部文件。如果日志文件名為空字符串（即""）則不寫日志。可設置的日志文件名長度最長為255個字符。
	函數GetFormDebugFileName用于復制當前已經設置的日志文件名到應用程序指定的緩沖區中。函數不檢查緩沖大小，防溢出控制由應用開發者處理。
/TEXTBLOCK */

#ifdef _TYPE_OS_WINDOWS_
#include <io.h>
#endif

#include "LibX.h"
#include "TypeX.h"
#include "ListX.h"

#if ( defined _TYPE_OS_AIX_ ) | ( defined _TYPE_OS_SCO_ ) | ( defined _TYPE_OS_LINUX_ )
#endif

#ifdef __cplusplus
extern "C" {
#endif

/*
** 函數集說明	:	調試函數集
*/

/* FUNCTIONLIST 參考列表 函數列表 */
_WINDLL_EXPORT BOOL SetFormDebugFileName( char *pcDebugPathFileName );
_WINDLL_EXPORT BOOL GetFormDebugFileName( char *pcDebugPathFileName );
/* /FUNCTIONLIST */

/*
** 結構名	:	SCGIFormData
** 結構說明	:	包含form結點項的內容信息
*/

/* STRUCTDES 參考列表 結構列表 */
typedef struct tagCGIFormData
{
	char *name; /* 表單域名 */
	char *data; /* 表單域值 或者 上傳文件域文件內容 */
	long datasize; /* 表單域值大小 或者 上傳文件域文件大小 */
	
	char *filename; /* 上傳文件域全文件名 */
}
SCGIFormData; /* form數據，表單域信息包，form鏈表容器結點值 */
/* /STRUCTDES */

/*
** 函數集說明	:	設置域特性最大值
*/

/* FUNCTIONLIST 參考列表 函數列表 */
_WINDLL_EXPORT void CGIFormSetMaxFieldNameSize( long maxsize );
_WINDLL_EXPORT void CGIFormSetMaxFieldDataSize( long maxsize );
_WINDLL_EXPORT void CGIFormSetMaxFieldFileDataSize( long maxsize );
/* /FUNCTIONLIST */

/*
** 函數集說明	:	form數據鏈表初始化、銷毀函數
*/

/* FUNCTIONLIST 參考列表 函數列表 */
_WINDLL_EXPORT SList *CGIFormListInitial();
_WINDLL_EXPORT BOOL CGIFormListDestroy( SList **listForm );
/* /FUNCTIONLIST */

/*
** 函數集說明	:	form數據鏈表填充函數
*/

/* FUNCTIONLIST 參考列表 函數列表 */
_WINDLL_EXPORT BOOL FreeCGIFormData( void *pv );
_WINDLL_EXPORT BOOL CGIFormReadData( SList **listForm );
/* /FUNCTIONLIST */

/*
** 函數集說明	:	form數據鏈表取值函數
*/

/* FUNCTIONLIST 參考列表 函數列表 */
_WINDLL_EXPORT char *CGIFormGetValue( SList *listForm , char *name );
_WINDLL_EXPORT long CGIFormGetValueSize( SList *listForm , char *name );
_WINDLL_EXPORT char *CGIFormGetFileName( SList *listForm , char *name );
_WINDLL_EXPORT long CGIFormGetFileSize( SList *listForm , char *name );
_WINDLL_EXPORT char *CGIFormGetFileContent( SList *listForm , char *name );
/* /FUNCTIONLIST */

#ifdef __cplusplus
}
#endif

#endif