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

xrtCookieJarConfigInit

初始化安全、适合通用 HTTP 客户端的配置；输出可位于合法的未对齐存储。

void xrtCookieJarConfigInit(xcookiejarconfig* pConfig);

参数	说明
xcookiejarconfig* pConfig	配置结构

返回：初始化安全、适合通用 HTTP 客户端的配置；输出可位于合法的未对齐存储。

示例已编译验证

cookiejarconfiginit obj;
xrtCookieJarConfigInit(&obj);

xrtCookieJarCreate

创建线程安全 CookieJar；配置为空时使用默认值，非空配置会立即复制。

xcookiejar* xrtCookieJarCreate(const xcookiejarconfig* pConfig);

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

返回：创建线程安全 CookieJar；配置为空时使用默认值，非空配置会立即复制。

示例已编译验证

/* 创建线程安全 CookieJar；配置为空时使用默认值，非空配置会立即复制。 */
xhandle* h = xrtCookieJarCreate();

xrtCookieJarRetain

增加 CookieJar 引用；失效对象返回空指针。

xcookiejar* xrtCookieJarRetain(const xcookiejar* pJar);

参数	说明
const xcookiejar* pJar	Jar 参数

返回：增加 CookieJar 引用；失效对象返回空指针。

示例已编译验证

/* 增加 CookieJar 引用；失效对象返回空指针。 */
result = xrtCookieJarRetain(pJar);

xrtCookieJarRelease

释放 CookieJar 引用；空指针是安全的空操作。

void xrtCookieJarRelease(xcookiejar* pJar);

参数	说明
xcookiejar* pJar	Jar 参数

返回：释放 CookieJar 引用；空指针是安全的空操作。

示例已编译验证

xrtCookieJarRelease(pJar);

xrtCookieJarClear

删除全部 Cookie，但保留已经分配的数组容量。

void xrtCookieJarClear(xcookiejar* pJar);

参数	说明
xcookiejar* pJar	Jar 参数

返回：删除全部 Cookie，但保留已经分配的数组容量。

示例已编译验证

/* 删除全部 Cookie，但保留已经分配的数组容量。 */
result = xrtCookieJarClear(pJar);

xrtCookieJarCount

返回当前条目数；不会隐式清理过期条目。

size_t xrtCookieJarCount(const xcookiejar* pJar);

参数	说明
const xcookiejar* pJar	Jar 参数

返回：返回当前条目数；不会隐式清理过期条目。

示例已编译验证

/* 返回当前条目数；不会隐式清理过期条目。 */
result = xrtCookieJarCount(pJar);

xrtCookieJarPurge

删除在指定时间已经过期的 Cookie，并返回删除数量。

size_t xrtCookieJarPurge(xcookiejar* pJar, xtime iNow);

参数	说明
xcookiejar* pJar	Jar 参数
xtime iNow	当前时间值

返回：删除在指定时间已经过期的 Cookie，并返回删除数量。

示例已编译验证

/* 删除在指定时间已经过期的 Cookie，并返回删除数量。 */
result = xrtCookieJarPurge(pJar, iNow);

xrtCookieJarSet

使用已解析 Set-Cookie 更新存储；策略拒绝通过 Reject 返回。

xcookiestorestatus xrtCookieJarSet( xcookiejar* pJar, const xcookiestorecontext* pContext, const xsetcookie* pCookie, xcookiereject* pReject );

参数	说明
xcookiejar* pJar	Jar 参数
const xcookiestorecontext* pContext	上下文
const xsetcookie* pCookie	Cookie
xcookiereject* pReject	Reject 参数

返回：使用已解析 Set-Cookie 更新存储；策略拒绝通过 Reject 返回。

示例已编译验证

/* 使用已解析 Set-Cookie 更新存储；策略拒绝通过 Reject 返回。 */
result = xrtCookieJarSet(pJar, pContext, pCookie, pReject);

xrtCookieJarStore

宽松解析 Set-Cookie 字段值后更新存储。

xcookiestorestatus xrtCookieJarStore( xcookiejar* pJar, const xcookiestorecontext* pContext, xstrview SetCookie, xcookiereject* pReject );

参数	说明
xcookiejar* pJar	Jar 参数
const xcookiestorecontext* pContext	上下文
xstrview SetCookie	SetCooke 参数
xcookiereject* pReject	Reject 参数

返回：宽松解析 Set-Cookie 字段值后更新存储。

示例已编译验证

/* 宽松解析 Set-Cookie 字段值后更新存储。 */
result = xrtCookieJarStore(pJar, pContext, SetCookie, pReject);

xrtCookieJarStoreUrl

使用当前时间和 HTTP API 语义接收一个普通、非分区 Cookie。

xcookiestorestatus xrtCookieJarStoreUrl( xcookiejar* pJar, xstrview URL, xstrview SetCookie, xcookiereject* pReject );

参数	说明
xcookiejar* pJar	Jar 参数
xstrview URL	URL 参数
xstrview SetCookie	SetCooke 参数
xcookiereject* pReject	Reject 参数

返回：使用当前时间和 HTTP API 语义接收一个普通、非分区 Cookie。

示例已编译验证

/* 使用当前时间和 HTTP API 语义接收一个普通、非分区 Cookie。 */
result = xrtCookieJarStoreUrl(pJar, URL, SetCookie, pReject);

xrtCookieJarWrite

按请求上下文写出不含字段名和零结尾的 Cookie 字段值。

bool xrtCookieJarWrite( xcookiejar* pJar, const xcookierequestcontext* pContext, void* pOutput, size_t iCapacity, size_t* pSize );

参数	说明
xcookiejar* pJar	Jar 参数
const xcookierequestcontext* pContext	上下文
void* pOutput	出：输出缓冲
size_t iCapacity	容量
size_t* pSize	出：大小

返回：按请求上下文写出不含字段名和零结尾的 Cookie 字段值。

示例已编译验证

/* 按请求上下文写出不含字段名和零结尾的 Cookie 字段值。 */
result = xrtCookieJarWrite(pJar, pContext, pOutput, iCapacity, pSize);

xrtCookieJarBuild

按请求上下文分配并构建零结尾 Cookie 字段值。

str xrtCookieJarBuild( xcookiejar* pJar, const xcookierequestcontext* pContext, size_t* pSize );

参数	说明
xcookiejar* pJar	Jar 参数
const xcookierequestcontext* pContext	上下文
size_t* pSize	出：大小

返回：按请求上下文分配并构建零结尾 Cookie 字段值。

示例已编译验证

/* 按请求上下文分配并构建零结尾 Cookie 字段值。 */
result = xrtCookieJarBuild(pJar, pContext, pSize);

xrtCookieJarWriteUrl

使用当前时间、同站和 HTTP API 语义写出普通请求 Cookie。

bool xrtCookieJarWriteUrl( xcookiejar* pJar, xstrview URL, void* pOutput, size_t iCapacity, size_t* pSize );

参数	说明
xcookiejar* pJar	Jar 参数
xstrview URL	URL 参数
void* pOutput	出：输出缓冲
size_t iCapacity	容量
size_t* pSize	出：大小

返回：使用当前时间、同站和 HTTP API 语义写出普通请求 Cookie。

示例已编译验证

/* 使用当前时间、同站和 HTTP API 语义写出普通请求 Cookie。 */
result = xrtCookieJarWriteUrl(pJar, URL, pOutput, iCapacity, pSize);

xrtCookieJarBuildUrl

使用当前时间、同站和 HTTP API 语义构建普通请求 Cookie。

str xrtCookieJarBuildUrl( xcookiejar* pJar, xstrview URL, size_t* pSize );

参数	说明
xcookiejar* pJar	Jar 参数
xstrview URL	URL 参数
size_t* pSize	出：大小

返回：使用当前时间、同站和 HTTP API 语义构建普通请求 Cookie。

示例已编译验证

/* 使用当前时间、同站和 HTTP API 语义构建普通请求 Cookie。 */
result = xrtCookieJarBuildUrl(pJar, URL, pSize);

xrtCookieJarSnapshot

在锁内复制全部未过期条目，返回并发稳定的不可变快照。

xcookiesnapshot* xrtCookieJarSnapshot( xcookiejar* pJar, xtime iNow );

参数	说明
xcookiejar* pJar	Jar 参数
xtime iNow	当前时间值

返回：在锁内复制全部未过期条目，返回并发稳定的不可变快照。

示例已编译验证

/* 在锁内复制全部未过期条目，返回并发稳定的不可变快照。 */
result = xrtCookieJarSnapshot(pJar, iNow);

xrtCookieSnapshotDestroy

销毁快照；空指针是安全的空操作。

void xrtCookieSnapshotDestroy(xcookiesnapshot* pSnapshot);

参数	说明
xcookiesnapshot* pSnapshot	Snashot 参数

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

示例已编译验证

xrtCookieSnapshotDestroy(pSnapshot);

xrtCookieSnapshotCount

返回快照中的 Cookie 数量。

size_t xrtCookieSnapshotCount(const xcookiesnapshot* pSnapshot);

参数	说明
const xcookiesnapshot* pSnapshot	Snashot 参数

返回：返回快照中的 Cookie 数量。

示例已编译验证

/* 返回快照中的 Cookie 数量。 */
result = xrtCookieSnapshotCount(pSnapshot);

xrtCookieSnapshotAt

返回稳定借用条目，越界返回空指针且不设置错误。

const xcookieinfo* xrtCookieSnapshotAt( const xcookiesnapshot* pSnapshot, size_t iIndex );

参数	说明
const xcookiesnapshot* pSnapshot	Snashot 参数
size_t iIndex	下标

返回：返回稳定借用条目，越界返回空指针且不设置错误。

示例已编译验证

/* 返回稳定借用条目，越界返回空指针且不设置错误。 */
result = xrtCookieSnapshotAt(pSnapshot, iIndex);

xrtCookieJarStoreHeaders

分别处理每个 Set-Cookie 字段，绝不把同名字段合并。

bool xrtCookieJarStoreHeaders( xcookiejar* pJar, const xcookiestorecontext* pContext, const xhttpheaders* pHeaders, xcookiestorereport* pReport );

参数	说明
xcookiejar* pJar	Jar 参数
const xcookiestorecontext* pContext	上下文
const xhttpheaders* pHeaders	头部对象
xcookiestorereport* pReport	Reort 参数

返回：分别处理每个 Set-Cookie 字段，绝不把同名字段合并。

示例已编译验证

/* 分别处理每个 Set-Cookie 字段，绝不把同名字段合并。 */
result = xrtCookieJarStoreHeaders(pJar, pContext, pHeaders, pReport);

xrtCookieJarApply

构建并设置单个 Cookie 字段；没有可发送条目时删除已有字段。

bool xrtCookieJarApply( xcookiejar* pJar, const xcookierequestcontext* pContext, xhttpheaders* pHeaders );

参数	说明
xcookiejar* pJar	Jar 参数
const xcookierequestcontext* pContext	上下文
xhttpheaders* pHeaders	头部对象

返回：构建并设置单个 Cookie 字段；没有可发送条目时删除已有字段。

示例已编译验证

/* 构建并设置单个 Cookie 字段；没有可发送条目时删除已有字段。 */
result = xrtCookieJarApply(pJar, pContext, pHeaders);