xhttp/form_data API 参考 - XRT 程序设计

xrtFormDataConfigInit

初始化适合 HTTP 表单的限制；输出可位于合法的未对齐存储。

void xrtFormDataConfigInit(xformdataconfig* pConfig);

参数	说明
xformdataconfig* pConfig	配置结构

返回：初始化适合 HTTP 表单的限制；输出可位于合法的未对齐存储。

示例已编译验证

formdataconfiginit obj;
xrtFormDataConfigInit(&obj);

xrtFormDataCreate

创建拥有型空容器；配置为空时采用默认值，非空配置会立即复制。

xformdata* xrtFormDataCreate( const xformdataconfig* pConfig );

参数	说明
const xformdataconfig* pConfig	配置结构

返回：创建拥有型空容器；配置为空时采用默认值，非空配置会立即复制。

示例已编译验证

/* 创建拥有型空容器；配置为空时采用默认值，非空配置会立即复制。 */
xhandle* h = xrtFormDataCreate();

xrtFormDataClone

深复制元数据并为每个正文取得独立引用。

xformdata* xrtFormDataClone(const xformdata* pForm);

参数	说明
const xformdata* pForm	表单对象

返回：深复制元数据并为每个正文取得独立引用。

示例已编译验证

/* 深复制元数据并为每个正文取得独立引用。 */
result = xrtFormDataClone(pForm);

xrtFormDataDestroy

销毁容器；空指针是安全的空操作。

void xrtFormDataDestroy(xformdata* pForm);

参数	说明
xformdata* pForm	表单对象

返回：销毁容器；空指针是安全的空操作。

示例已编译验证

xrtFormDataDestroy(pForm);

xrtFormDataClear

清空全部 Part，但保留条目数组容量供后续复用。

void xrtFormDataClear(xformdata* pForm);

参数	说明
xformdata* pForm	表单对象

返回：清空全部 Part，但保留条目数组容量供后续复用。

示例已编译验证

/* 清空全部 Part，但保留条目数组容量供后续复用。 */
result = xrtFormDataClear(pForm);

xrtFormDataReserve

预留至少指定数量的 Part 槽位。

bool xrtFormDataReserve(xformdata* pForm, size_t iParts);

参数	说明
xformdata* pForm	表单对象
size_t iParts	Parts 参数

返回：预留至少指定数量的 Part 槽位。

示例已编译验证

/* 预留至少指定数量的 Part 槽位。 */
result = xrtFormDataReserve(pForm, iParts);

xrtFormDataCount

返回当前 Part 数量；空容器返回零。

size_t xrtFormDataCount(const xformdata* pForm);

参数	说明
const xformdata* pForm	表单对象

返回：返回当前 Part 数量；空容器返回零。

示例已编译验证

/* 返回当前 Part 数量；空容器返回零。 */
result = xrtFormDataCount(pForm);

xrtFormDataMetadata

返回名称、文件名和媒体类型的有效元数据字节总数。

size_t xrtFormDataMetadata(const xformdata* pForm);

参数	说明
const xformdata* pForm	表单对象

返回：返回名称、文件名和媒体类型的有效元数据字节总数。

示例已编译验证

/* 返回名称、文件名和媒体类型的有效元数据字节总数。 */
result = xrtFormDataMetadata(pForm);

xrtFormDataAppendBody

追加一个正文 Part；Filename 为空指针时参数缺席。

bool xrtFormDataAppendBody( xformdata* pForm, xstrview Name, xhttpbody* pBody, const xstrview* pFilename, xstrview ContentType );

参数	说明
xformdata* pForm	表单对象
xstrview Name	名称（xstrview）
xhttpbody* pBody	消息体
const xstrview* pFilename	文件名
xstrview ContentType	内容类型

返回：追加一个正文 Part；Filename 为空指针时参数缺席。

示例已编译验证

/* 追加一个正文 Part；Filename 为空指针时参数缺席。 */
result = xrtFormDataAppendBody(pForm, Name, pBody, pFilename, ContentType);

xrtFormDataAppendText

复制文本值并追加普通字段。

bool xrtFormDataAppendText( xformdata* pForm, xstrview Name, xstrview Value );

参数	说明
xformdata* pForm	表单对象
xstrview Name	名称（xstrview）
xstrview Value	值

返回：复制文本值并追加普通字段。

示例已编译验证

/* 复制文本值并追加普通字段。 */
result = xrtFormDataAppendText(pForm, Name, Value);

xrtFormDataAppendBytes

复制二进制值并追加普通字段或文件字段。

bool xrtFormDataAppendBytes( xformdata* pForm, xstrview Name, xbytesview Data, const xstrview* pFilename, xstrview ContentType );

参数	说明
xformdata* pForm	表单对象
xstrview Name	名称（xstrview）
xbytesview Data	数据内容
const xstrview* pFilename	文件名
xstrview ContentType	内容类型

返回：复制二进制值并追加普通字段或文件字段。

示例已编译验证

/* 复制二进制值并追加普通字段或文件字段。 */
result = xrtFormDataAppendBytes(pForm, Name, Data, pFilename, ContentType);

xrtFormDataSetBody

在首个同名位置替换全部同名项；不存在时追加。

bool xrtFormDataSetBody( xformdata* pForm, xstrview Name, xhttpbody* pBody, const xstrview* pFilename, xstrview ContentType );

参数	说明
xformdata* pForm	表单对象
xstrview Name	名称（xstrview）
xhttpbody* pBody	消息体
const xstrview* pFilename	文件名
xstrview ContentType	内容类型

返回：在首个同名位置替换全部同名项；不存在时追加。

示例已编译验证

/* 在首个同名位置替换全部同名项；不存在时追加。 */
result = xrtFormDataSetBody(pForm, Name, pBody, pFilename, ContentType);

xrtFormDataSetText

复制文本值并原子替换全部同名项。

bool xrtFormDataSetText( xformdata* pForm, xstrview Name, xstrview Value );

参数	说明
xformdata* pForm	表单对象
xstrview Name	名称（xstrview）
xstrview Value	值

返回：复制文本值并原子替换全部同名项。

示例已编译验证

/* 复制文本值并原子替换全部同名项。 */
result = xrtFormDataSetText(pForm, Name, Value);

xrtFormDataSetBytes

复制二进制值并原子替换全部同名项。

bool xrtFormDataSetBytes( xformdata* pForm, xstrview Name, xbytesview Data, const xstrview* pFilename, xstrview ContentType );

参数	说明
xformdata* pForm	表单对象
xstrview Name	名称（xstrview）
xbytesview Data	数据内容
const xstrview* pFilename	文件名
xstrview ContentType	内容类型

返回：复制二进制值并原子替换全部同名项。

示例已编译验证

/* 复制二进制值并原子替换全部同名项。 */
result = xrtFormDataSetBytes(pForm, Name, Data, pFilename, ContentType);

xrtFormDataRemove

删除全部同名 Part 并返回删除数量。

size_t xrtFormDataRemove( xformdata* pForm, xstrview Name );

参数	说明
xformdata* pForm	表单对象
xstrview Name	名称（xstrview）

返回：删除全部同名 Part 并返回删除数量。

示例已编译验证

/* 删除全部同名 Part 并返回删除数量。 */
result = xrtFormDataRemove(pForm, Name);

xrtFormDataCountName

返回同名 Part 数量。

size_t xrtFormDataCountName( const xformdata* pForm, xstrview Name );

参数	说明
const xformdata* pForm	表单对象
xstrview Name	名称（xstrview）

返回：返回同名 Part 数量。

示例已编译验证

/* 返回同名 Part 数量。 */
result = xrtFormDataCountName(pForm, Name);

xrtFormDataHas

判断是否存在同名 Part；未匹配不是错误。

bool xrtFormDataHas( const xformdata* pForm, xstrview Name );

参数	说明
const xformdata* pForm	表单对象
xstrview Name	名称（xstrview）

返回：判断是否存在同名 Part；未匹配不是错误。

示例已编译验证

/* 判断是否存在同名 Part；未匹配不是错误。 */
result = xrtFormDataHas(pForm, Name);

xrtFormDataAt

复制指定位置的借用 Part 视图。

bool xrtFormDataAt( const xformdata* pForm, size_t iIndex, xformdatapart* pPart );

参数	说明
const xformdata* pForm	表单对象
size_t iIndex	下标
xformdatapart* pPart	出：片段

返回：复制指定位置的借用 Part 视图。

示例已编译验证

/* 复制指定位置的借用 Part 视图。 */
result = xrtFormDataAt(pForm, iIndex, pPart);

xrtFormDataGet

复制首个同名 Part；无匹配返回 false 且不是错误。

bool xrtFormDataGet( const xformdata* pForm, xstrview Name, xformdatapart* pPart );

参数	说明
const xformdata* pForm	表单对象
xstrview Name	名称（xstrview）
xformdatapart* pPart	出：片段

返回：复制首个同名 Part；无匹配返回 false 且不是错误。

示例已编译验证

/* 复制首个同名 Part；无匹配返回 false 且不是错误。 */
result = xrtFormDataGet(pForm, Name, pPart);

xrtFormDataFind

从 Index 开始查找下一个同名项，ITEM 时 Index 指向下一位置。

xhttpnext xrtFormDataFind( const xformdata* pForm, xstrview Name, size_t* pIndex, xformdatapart* pPart );

参数	说明
const xformdata* pForm	表单对象
xstrview Name	名称（xstrview）
size_t* pIndex	出：下标
xformdatapart* pPart	出：片段

返回：从 Index 开始查找下一个同名项，ITEM 时 Index 指向下一位置。

示例已编译验证

/* 从 Index 开始查找下一个同名项，ITEM 时 Index 指向下一位置。 */
result = xrtFormDataFind(pForm, Name, pIndex, pPart);

xrtFormDataBody

按给定 boundary 创建零合并复制的 multipart/form-data 正文。

xhttpbody* xrtFormDataBody( const xformdata* pForm, const xmultipartboundary* pBoundary );

参数	说明
const xformdata* pForm	表单对象
const xmultipartboundary* pBoundary	边界

返回：按给定 boundary 创建零合并复制的 multipart/form-data 正文。

示例已编译验证

/* 按给定 boundary 创建零合并复制的 multipart/form-data 正文。 */
result = xrtFormDataBody(pForm, pBoundary);

xrtFormDataBodyRandom

生成安全随机 boundary，并创建对应 multipart/form-data 正文。

xhttpbody* xrtFormDataBodyRandom( const xformdata* pForm, xmultipartboundary* pBoundary );

参数	说明
const xformdata* pForm	表单对象
xmultipartboundary* pBoundary	边界

返回：生成安全随机 boundary，并创建对应 multipart/form-data 正文。

示例已编译验证

/* 生成安全随机 boundary，并创建对应 multipart/form-data 正文。 */
result = xrtFormDataBodyRandom(pForm, pBoundary);

xrtFormDataParse

把完整 multipart/form-data 正文复制为拥有型容器；输入描述符会立即快照。

xformdata* xrtFormDataParse( xbytesview Body, const xmultipartboundary* pBoundary, const xformdataconfig* pConfig, const xmultipartlimits* pLimits, xmultiparterrorinfo* pError );

参数	说明
xbytesview Body	消息体内容
const xmultipartboundary* pBoundary	边界
const xformdataconfig* pConfig	配置结构
const xmultipartlimits* pLimits	Lmts 参数
xmultiparterrorinfo* pError	错误对象

返回：把完整 multipart/form-data 正文复制为拥有型容器；输入描述符会立即快照。

示例已编译验证

/* 把完整 multipart/form-data 正文复制为拥有型容器；输入描述符会立即快照。 */
result = xrtFormDataParse(Body, pBoundary, pConfig, pLimits, pError);

xrtFormDataParseContentType

从 Content-Type 读取 boundary，再解析完整正文；错误输出支持未对齐存储。

xformdata* xrtFormDataParseContentType( xstrview ContentType, xbytesview Body, const xformdataconfig* pConfig, const xmultipartlimits* pLimits, xmultiparterrorinfo* pError );

参数	说明
xstrview ContentType	内容类型
xbytesview Body	消息体内容
const xformdataconfig* pConfig	配置结构
const xmultipartlimits* pLimits	Lmts 参数
xmultiparterrorinfo* pError	错误对象

返回：从 Content-Type 读取 boundary，再解析完整正文；错误输出支持未对齐存储。

示例已编译验证

/* 从 Content-Type 读取 boundary，再解析完整正文；错误输出支持未对齐存储。 */
result = xrtFormDataParseContentType(ContentType, Body, pConfig, pLimits, pError);