📄 cgiform.txt
字号:
CGIForm函数子库文档
作者： BetonArmEE
最新版本： 2007-04-03 v1.0
>>> 目录
1.关于
1.1.功能概述
1.2.兼容平台列表
1.3.版本历史
2.知识手册
2.1.form数据与form链表容器
3.使用指南
3.1.创建、销毁form链表容器
3.2.装载form数据到链表容器
3.3.读取、遍历form数据
3.4.系统限制选项
3.5.调试选项
3.6.示例1：读取浏览器端提交的表单数据
4.参考列表
4.1.结构体列表
4.2.函数列表
>>> 正文
1.关于
1.1.功能概述
CGIForm是iCGI函数库中最重要的子函数库之一。
CGIForm主要处理浏览器端表单数据（包含上传文件数据）的读取和分析，实现服务端应用获取浏览器端表单数据完整解决方案。
1.2.兼容平台列表
Windows、UNIX、Linux
1.3.版本历史
2005-05-02 创建 第一版
2007-04-02 创建 文档
2.知识手册
2.1.form数据与form链表容器
浏览器端表单（form）拥有若干表单域（field），最简单的表单比如网站用户注册表单，要求用户输入用户名、密码等信息。当表单提交后，form数据通过网络传输到服务器端，由web服务软件转交给cgi程序，cgi程序从环境变量中读出form数据并做出相应业务逻辑处理。
CGIForm子函数库封装了cgi程序读取和分析过程，通过函数读取浏览器端发送过来的form数据到form链表容器数据结构，提供大量函数方便从form链表容器中读取表单域数据。
3.使用指南
3.1.创建、销毁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
3.2.装载form数据到链表容器
form链表容器被初始化后需要装载浏览器端提交过来的form数据
以下代码片断用于从web服务器软件处获取装载form数据到form链表容器里去：
BOOL bret ;
bret = CGIFormReadData( &plist ) ;
3.3.读取、遍历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子函数库相关函数遍历链表即可。
3.4.系统限制选项
为防止浏览器端发送恶意数据而造成CGIForm相关函数中缓冲溢出，设置系统限制选项保护之。
函数CGIFormSetMaxFieldNameSize设置允许的最大表单域名长度和上传文件域全文件名长度，超出该限制则截取有效长度部分。
函数CGIFormSetMaxFieldDataSize设置允许的最大表单域值大小，超出该限制则截取有效长度部分。
函数CGIFormSetMaxFieldFileDataSize设置允许的最大上传文件内容大小，超出该限制则截取有效长度部分。
注意：系统限制选项函数必须在form数据装载到form链表容器中去之前设置，即函数CGIFormReadData调用前。
3.5.调试选项
为方便调试form数据装载过程，设置调试选项能够使应用开发者方便观察form数据装载过程。
函数SetFormDebugFileName用于设置日志文件名，使装载form数据过程中有相关dump信息写入外部文件。如果日志文件名为空字符串（即""）则不写日志。可设置的日志文件名长度最长为255个字符。
函数GetFormDebugFileName用于复制当前已经设置的日志文件名到应用程序指定的缓冲区中。函数不检查缓冲大小，防溢出控制由应用开发者处理。
3.6.示例1：读取浏览器端提交的表单数据
浏览器端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>
服务器端cgi代码如下：
SList *plistForm = NULL ; /* form链表容器，其实就是iLibX.List链表 */
char *textfieldUserName = NULL ; /* 为方便阅读代码，这里把变量名与表单域名写成一样 */
char *textfieldPassword = NULL ;
BOOL bret ;
/* 初始化form链表容器 */
plistForm = CGIFormListInitial() ;
if( plistForm == NULL )
{
/* ...初始化form链表容器失败处理... */
}
/* 装载form数据到form链表容器 */
bret = CGIFormReadData( &plistForm ) ;
if( bret != TRUE )
{
/* ...装载form数据到form链表容器失败处理... */
}
/* 读取form数据，即由表单域名获得表单域值在form链表容器里的首地址 */
textfieldUserName = CGIFormGetValue( plistForm , "textfieldUserName" ) ;
textfieldPassword = CGIFormGetValue( plistForm , "textfieldPassword" ) ;
/* ...这时已经得到了浏览器端表单用户名与密码，根据业务逻辑做相应的处理... */
/* 销毁form链表容器 */
bret = CGIFormListDestroy( &plistForm ) ;
{
/* ...销毁form链表容器失败处理... */
}
4.参考列表
4.1.结构体列表
typedef struct tagCGIFormData
{
char *name; /* 表单域名 */
char *data; /* 表单域值 或者 上传文件域文件内容 */
long datasize; /* 表单域值大小 或者 上传文件域文件大小 */
char *filename; /* 上传文件域全文件名 */
}
SCGIFormData; /* form数据，表单域信息包，form链表容器结点值 */
4.2.函数列表
SetFormDebugFileName
GetFormDebugFileName
CGIFormSetMaxFieldNameSize
CGIFormSetMaxFieldDataSize
CGIFormSetMaxFieldFileDataSize
CGIFormListInitial
CGIFormListDestroy
FreeCGIFormData
CGIFormReadData
CGIFormGetValue
CGIFormGetValueSize
CGIFormGetFileName
CGIFormGetFileSize
CGIFormGetFileContent
·SetFormDebugFileName
设置装载form链表容器时调试日志文件名
函数原型：
BOOL SetFormDebugFileName( char *pcDebugPathFileName );
输入参数：
char *pcDebugPathFileName 调试日志文件名
返回值：
BOOL 设置成功，返回 TRUE
设置失败，返回 FALSE
详细描述与注意事项：
（无）
示例代码：
SetFormDebugFileName( "form.log" );
相关函数：
GetFormDebugFileName
·GetFormDebugFileName
获得装载form链表容器时调试日志文件名
函数原型：
BOOL GetFormDebugFileName( char *pcDebugPathFileName );
输入参数：
（无）
输出参数：
char *pcDebugPathFileName 调试日志文件名
返回值：
BOOL 总是返回 TRUE
详细描述与注意事项：
（无）
示例代码：
char buffer[256+1];
SetFormDebugFileName( buffer );
相关函数：
SetFormDebugFileName
·CGIFormSetMaxFieldNameSize
设置最大表单域名长度
函数原型：
void CGIFormSetMaxFieldNameSize( long maxsize );
输入参数：
long maxsize 最大表单域名长度
返回值：
（无）
详细描述与注意事项：
（无）
示例代码：
CGIFormSetMaxFieldNameSize( 1024 );
相关函数：
CGIFormSetMaxFieldDataSize , CGIFormSetMaxFieldFileDataSize
·CGIFormSetMaxFieldDataSize
设置最大表单域值大小
函数原型：
void CGIFormSetMaxFieldDataSize( long maxsize );
输入参数：
long maxsize 最大表单域值大小
返回值：
（无）
详细描述与注意事项：
（无）
示例代码：
CGIFormSetMaxFieldDataSize( 1024 );
相关函数：
CGIFormSetMaxFieldNameSize , CGIFormSetMaxFieldFileDataSize
·CGIFormSetMaxFieldFileDataSize
设置最大上传文件域文件大小
函数原型：
void CGIFormSetMaxFieldFileDataSize( long maxsize );
输入参数：
long maxsize 最大上传文件域文件大小
返回值：
（无）
详细描述与注意事项：
（无）
示例代码：
CGIFormSetMaxFieldFileDataSize( 1024 );
相关函数：
CGIFormSetMaxFieldNameSize , CGIFormSetMaxFieldDataSize
·CGIFormListInitial
初始化form链表容器
函数原型：
SList *CGIFormListInitial();
输入参数：
（无）
返回值：
SList * 总是返回iLibX.List链表初始化值
详细描述与注意事项：
（无）
示例代码：
SList *plist = NULL ;
plist = CGIFormListInitial() ;
相关函数：
CGIFormListDestroy
·CGIFormListDestroy
销毁form链表容器
函数原型：
BOOL CGIFormListDestroy( SList **listForm );
输入参数：
SList **listForm form链表容器的地址
返回值：
销毁成功，返回 TRUE
销毁失败，返回 FALSE
详细描述与注意事项：
（无）
示例代码：
CGIFormListDestroy( &plist );
相关函数：
CGIFormListInitial , FreeCGIFormData
·CGIFormReadData
装载浏览器端提交的表单数据到链表容器
函数原形：
BOOL CGIFormReadData( SList **listForm )
输入参数：
SList **listForm form链表容器的地址
返回值：
读取成功，返回值 TRUE
读取失败或者没有表单数据，返回 FALSE
详细描述与注意事项：
（无）
示例代码：
CGIFormReadData( &plist );
相关函数：
（无）
·CGIFormGetValue
由表单域名获取在form链表容器中表单域值的内存首地址
函数原型：
char *CGIFormGetValue( SList *listForm , char *name );
输入参数：
SList *listForm form链表容器
char *name 表单域名
返回值：
char * form链表容器中表单域值的内存首地址
详细描述与注意事项：
（无）
示例代码：
textfieldUserName = CGIFormGetValue( plist , "textfieldUserName" ) ;
相关函数：
CGIFormGetValueSize
·CGIFormGetValueSize
获得表单域值大小
函数原型：
long CGIFormGetValueSize( SList *listForm , char *name );
输入参数：
SList *listForm form链表容器
char *name 表单域名
返回值：
long 表单域值大小
详细描述与注意事项：
（无）
示例代码：
long size ;
size = CGIFormGetValueSize( plist , "textfieldUserName" ) ;
相关函数：
CGIFormGetValue
·CGIFormGetFileName
由上传文件域名获取在form链表容器中上传文件域全文件名的内存首地址
函数原型：
char *CGIFormGetFileName( SList *listForm , char *name );
输入参数：
SList *listForm form链表容器
char *name 上传文件域名
返回值：
char * form链表容器中上传文件域文件名的内存首地址
详细描述与注意事项：
（无）
示例代码：
char *pfilename = NULL ;
pfilename = CGIFormGetFileName( plist , "fileUpload" ) ;
相关函数：
CGIFormGetFileSize , CGIFormGetFileContent
·CGIFormGetFileSize
由上传文件域名获取在form链表容器中上传文件域文件大小
获取上传文件域文件大小
函数原型：
long CGIFormGetFileSize( SList *listForm , char *name );
输入参数：
SList *listForm form链表容器
char *name 上传文件域名
返回值：
long form链表容器中上传文件域文件大小
详细描述与注意事项：
（无）
示例代码：
long size ;
size = ·CGIFormGetFileSize( plist , "fileUpload" ) ;
相关函数：
CGIFormGetFileName , CGIFormGetFileContent
·CGIFormGetFileContent
由上传文件域名获取在form链表容器中上传文件域文件内容的内存首地址
函数原型：
char *CGIFormGetFileContent( SList *listForm , char *name );
输入参数：
SList *listForm form链表容器
char *name 上传文件域名
返回值：
char * form链表容器中上传文件域文件内容的内存首地址
详细描述与注意事项：
（无）
示例代码：
char *pfilecontent = NULL ;
pfilecontent = CGIFormGetFileContent( plist , "fileUpload" ) ;
相关函数：
CGIFormGetFileName , CGIFormGetFileSize
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -