libcurl 响应头访问 API 深度解析curl_easy_header 与 curl_easy_nextheader 完整指南【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl本指南围绕 libcurl 提供的结构化 HTTP 响应头访问 API——curl_easy_header及其配套的curl_easy_nextheader展开介绍如何以类型安全、索引化、支持多请求与多来源origin的方式读取 HTTP 响应头。读完本文你将掌握这两个 API 的完整参数语义、curl_header结构体的每个字段含义、五种头来源位origin bits的使用场景、CURLHcode错误码的处理方式并理解它们在 libcurl 源码中的底层存储与生命周期机制。该 API 自 7.83.0 版本引入仅适用于 HTTP含 HTTPS、HTTP/2、HTTP/3协议族。一、为什么需要 curl_easy_header从回调到结构化查询在curl_easy_header出现之前应用获取 HTTP 响应头的常规途径是设置 CURLOPT_HEADERFUNCTION 回调逐行接收名称: 值的原始文本再由应用自行解析。这种方式的痛点在于头部来源混杂普通响应头、1xx 中间响应头、CONNECT 响应头、trailer正文之后的头、HTTP/2/3 伪头在同一个传输中可能交织出现回调里难以区分重定向与多阶段认证会产生一系列请求回调无法轻易判断当前头属于第几个请求同名头可能出现多次如多个Set-Cookie需要应用自己计数和索引回调收到的原始行需要自行剥离 CRLF、处理折叠folded行、注意大小写。curl_easy_header正是为解决这些问题而生的查询式APIlibcurl 在内部把接收到的所有 HTTP 头以结构化的curl_header形式保存应用可以随时按名称、索引、来源、请求序号进行查询无需再面对原始字节流。其声明位于 include/curl/header.h实现位于 lib/headers.c。二、函数签名与参数详解#include curl/curl.h CURLHcode curl_easy_header(CURL *easy, const char *name, size_t nameindex, unsigned int origin, int request, struct curl_header **hout);1. easy——easy 句柄执行传输所使用的CURL *句柄通常是curl_easy_init()的返回值并在curl_easy_perform()之后用于查询。该句柄同时决定了查询得到的头部数据的内存生命周期见下文内存与生命周期一节。2. name——头名称大小写不敏感不含冒号名称大小写不敏感传Content-Type、content-type或CONTENT-TYPE结果等价底层匹配使用curl_strequal进行不区分大小写的比较见 lib/headers.c。名称必须是null 结尾的字符串且不带冒号。返回结构体中name字段指向的是服务器实际发送的原始大小写形式可能与请求名不同详见下文结构体说明。3. nameindex——同名头的实例索引0 基0表示取第一个同名头实例。若返回结构体的amount字段大于 1说明该名称在当前作用域内存在多个实例可用更大的nameindex继续取下一个。索引超出实际数量nameindex amount时返回CURLHE_BADINDEX。典型场景是Set-Cookie或Warning这类允许重复出现的头。4. origin——头来源位掩码一次 HTTP 传输可能从多个地方产生头同名头在不同来源中语义可能不同因此origin是一个**按位或bitmask**参数用于限定只从指定的来源中查询。具体来源位见下文五种头来源ORIGINS一节。origin不能为 0也不能包含未定义的位否则返回CURLHE_BAD_ARGUMENT校验逻辑见 lib/headers.c。5. request——请求序号一次传输可能由一系列 HTTP 请求组成跟随重定向、多阶段认证如 Digest/NTLM 的 401 挑战-应答、Expect: 100-continue等都会产生额外的请求。request用于指定从第几个请求中取头0表示第一个请求每发生一次重定向等真实跟随内部计数data-state.requests递增一次见 lib/http.c-1是快捷方式表示该传输中的最后一个请求与请求总数无关传大于已发生请求数的值时返回CURLHE_NOREQUEST小于-1的值属于非法参数返回CURLHE_BAD_ARGUMENT。6. hout——输出指针函数将curl_header *指针写入hout指向的变量。成功时hout指向一个由 libcurl 管理的curl_header结构体。三、curl_header 结构体每个字段的含义struct curl_header { char *name; /* 头名称可能大小写与请求不同 */ char *value; /* 头值去除首尾空白null 结尾 */ size_t amount; /* 当前作用域内同名头的数量 */ size_t index; /* 本实例的 0 基编号恒小于 amount */ unsigned int origin; /* 来源位见 ORIGINS */ void *anchor; /* libcurl 内部私有句柄禁止修改 */ };该结构体定义于 include/curl/header.h。字段语义如下name指向内部存储区中的头名称不含冒号大小写为服务器实际发送的形式。查询时大小写不敏感但返回的名称可能与你请求的拼写不同。value头值按网络原样提供但首尾的空白字符与换行已被剥离且以\0结尾。对于 HTTP/1 遗留的折叠头folded header续行以空白开头的旧格式本 API 会将其展开为单一完整值行间以单个空格连接。amount在当前originrequest作用域内使用该名称的头总个数。index本实例在该作用域内的 0 基序号。同名头多次出现时index可以为 1、2……但恒小于amount。origin指示该头来源的位标志。文档定义 5 个位详见下节其余 27 个高位为保留位——不要假设它们有任何确定值。从源码看copy_header_external 在对外输出时会额外置入一个保留位1 27源码注释明确指出这是为了阻止应用用直接比较origin值从而强制应用使用按位与来测试来源位——这也解释了为何保留位不可假设为任何特定值。anchorlibcurl 内部使用的链表节点句柄指向Curl_llist_node供curl_easy_nextheader迭代定位使用。应用不得修改它。四、五种头来源ORIGINSorigin位定义于 include/curl/header.h。它们可以按位或组合使用例如CURLH_HEADER | CURLH_1XX | CURLH_TRAILER表示同时接受普通头、1xx 中间响应头和 trailer。位标志值含义CURLH_HEADER1 0服务器返回的普通响应头即状态行之后、正文之前的部分CURLH_TRAILER1 1trailer正文之后到达的头如 chunked 编码的尾部扩展头CURLH_CONNECT1 2CONNECT 响应中的头通过 HTTP(S) 代理建立隧道的 CONNECT 请求产生的响应头CURLH_1XX1 3HTTP 1xx 中间响应中的头如100 Continue、103 Early HintsCURLH_PSEUDO1 4HTTP/2 或 HTTP/3 的伪头pseudo header如:status、:method、:path从实现看hds_cw_collect_write 依据客户端写回调client writer收到的写入类型把原始头分类CLIENTWRITE_CONNECT→CURLH_CONNECTCLIENTWRITE_1XX→CURLH_1XXCLIENTWRITE_TRAILER→CURLH_TRAILER其余 →CURLH_HEADER而 HTTP/2 的伪头则在 lib/http2.c 中直接以CURLH_PSEUDO类型压入存储。这意味着即使服务器发送了同名但来源不同的头你也可以精确区分它们。五、返回的正确头重复与覆盖语义libcurl 存储并提供的是实际生效的头。文档明确承诺了以下行为若两个同名头到达且后者覆盖前者按 HTTP 语义后者生效则只提供后者若前者存活而后者无效则只提供前者使用本 API 的应用无需自行处理同名头的错误覆盖问题。需要澄清的是这里的覆盖指 HTTP 语义上后者覆盖前者的头例如后到的Content-Length而Set-Cookie这类允许多个实例并存的头会以amount 1的方式全部保留通过nameindex逐个访问。另外需注意HTTP 响应的第一行是状态行如HTTP/1.1 200 OK它不被本函数视为头。头是指状态行之后形如name: value的那些行。这一约定在存储侧同样成立——Curl_headers_push 会直接忽略纯 CR/LF 的body 分隔行而状态行由另外的路径处理不会进入头部存储链表。六、CURLHcode 返回值与错误码函数返回CURLHcode枚举值CURLHE_OK (0)表示成功非零表示出错。完整枚举定义于 include/curl/header.h错误码含义CURLHE_OK成功CURLHE_BADINDEX该名称存在但nameindex超出实际实例数CURLHE_MISSING当前作用域内不存在该名称的头CURLHE_NOHEADERS尚未有任何头例如尚未收到响应或查询过早CURLHE_NOREQUEST指定的request序号不存在该传输未发出这么多请求CURLHE_OUT_OF_MEMORY处理过程中内存不足CURLHE_BAD_ARGUMENT函数参数非法如origin为 0 或含未定义位、request -1、name或hout为 NULLCURLHE_NOT_BUILT_IN该 API 在编译时被禁用关于编译期禁用当构建时定义了CURL_DISABLE_HEADERS_API或CURL_DISABLE_HTTP时lib/headers.c 中的实现被替换为直接返回CURLHE_NOT_BUILT_IN的桩函数。因此生产代码应当对返回值做完整检查而不只假设成功。七、完整可运行示例示例 1查询单个头继承官方示例并完善错误处理官方示例 docs/libcurl/curl_easy_header.md 给出了最简用法这里补充完整的错误分支使其可复制到真实项目中#include stdio.h #include curl/curl.h int main(void) { struct curl_header *type NULL; CURL *curl curl_easy_init(); if(curl) { CURLHcode h; curl_easy_setopt(curl, CURLOPT_URL, https://example.com); curl_easy_perform(curl); /* 取最后一个请求的 Content-Type 普通响应头 */ h curl_easy_header(curl, Content-Type, 0, CURLH_HEADER, -1, type); if(h CURLHE_OK) printf(Content-Type: %s\n, type-value); else printf(header lookup failed: %d\n, (int)h); curl_easy_cleanup(curl); } return 0; }示例 2遍历同名头的全部实例利用amount与nameindex配合可枚举作用域内同名头的所有实例例如多个Set-Cookiestruct curl_header *h; size_t i; for(i 0; ; i) { CURLHcode rc curl_easy_header(curl, Set-Cookie, i, CURLH_HEADER, -1, h); if(rc CURLHE_BADINDEX) break; /* 没有更多实例了 */ if(rc ! CURLHE_OK) { /* 其他错误处理 */ break; } printf(cookie #%zu: %s\n, h-index, h-value); }示例 3与 curl_easy_nextheader 组合迭代全部头curl_easy_nextheader同样 7.83.0 引入声明见 include/curl/header.h实现见 lib/headers.c允许遍历作用域内的所有头。它返回下一个匹配的头指针没有更多匹配时返回 NULLprev传 NULL 表示从头开始之后每次传入上一次的返回值struct curl_header *prev NULL; struct curl_header *h; curl_easy_setopt(curl, CURLOPT_URL, https://example.com); curl_easy_perform(curl); /* 遍历第一个请求的普通响应头 */ while((h curl_easy_nextheader(curl, CURLH_HEADER, 0, prev))) { printf(%s: %s\n, h-name, h-value); prev h; } /* 遍历最后一个请求的普通头 1xx 中间响应头 trailer */ prev NULL; unsigned int origin CURLH_HEADER | CURLH_1XX | CURLH_TRAILER; while((h curl_easy_nextheader(curl, origin, -1, prev))) { printf(%s: %s\n, h-name, h-value); prev h; }使用curl_easy_nextheader时官方建议迭代过程中不要中途改变origin和request否则可能得到意外结果。另外prev指针在 easy 句柄开始下一次传输后即失效此时必须用 NULL 重新获取首个头。八、内存与生命周期何时拷贝、何时失效理解本 API 的内存模型对避免悬垂指针至关重要返回的curl_header结构体及其指向的name/value数据内存归 libcurl 所有与 easy 句柄关联最终在curl_easy_cleanup()时释放底层清理函数为 Curl_headers_cleanup。后续调用会覆盖先前的结果curl_easy_header每次都把结果写入同一个槽位data-state.headerout[0]见 lib/headers.ccurl_easy_nextheader则使用另一个槽位headerout[1]。因此如果要在多次调用之间保留数据必须自行拷贝。该 API可以在所有头到达之前调用也可以在 libcurl 回调如头回调内部调用它返回的是调用那一刻已接收头的状态。若此时一个头都没有返回CURLHE_NOHEADERS。结合 Curl_headers_push 的实现还可以看到存储侧的工程约束单次 HTTP 响应含 CONNECT 头与重定向允许的响应头总大小上限为 300 KiB、个数上限为 5000宏定义于 lib/http.h超过上限的头会被拒绝因此极端场景下查询可能取不到全部头。九、存储与分类的源码级原理头部数据从网络到达用户查询经历了完整的流水线全部位于 lib/headers.c初始化传输开始时 Curl_headers_init 检查连接协议族是否为 HTTP仅在 HTTP 协议下安装名为hds-collect的客户端写器cwriter避免重复安装。采集与分类hds_cw_collect_write拦截CLIENTWRITE_HEADER类写入依据写入标志把每行头归类为CURLH_CONNECT/CURLH_1XX/CURLH_TRAILER/CURLH_HEADER然后交给Curl_headers_push。存储Curl_headers_push剥离行尾 CR/LF、跳过 body 分隔空行把原始行连同类型、当前请求序号data-state.requests一起存入 easy 句柄的httphdrs链表内部元素为struct Curl_header_store定义见 lib/headers.hname/value通过 namevalue 在缓冲区内部就地切分——该函数对CURLH_PSEUDO类型的行会跳过开头的:再找名称结束符这正是 HTTP/2/3 伪头能被正确解析的原因。查询curl_easy_header先做参数校验再在链表中做两遍扫描第一遍统计作用域内同名头的amount第二遍定位到nameindex对应的节点最后把结果填入对外槽位并返回。这套设计的直接收益是查询时你拿到的是 libcurl 已经帮你分类、去空白、展开折叠行的干净数据并且request/origin/nameindex三个维度可以任意组合精确定位任意请求、任意来源、任意实例的头。十、注意事项与最佳实践大小写查询名称大小写不敏感但返回的name是线路上原始的大小写形式不要假设它与请求串一致。状态行不是头要用程序方式读取状态码应使用CURLINFO_RESPONSE_CODE等信息接口而非本 API。多实例判定优先检查返回结构体的amount字段再决定是否递增nameindex继续取用CURLHE_BADINDEX作为遍历终止条件同样可靠。回调内使用允许在头回调等 libcurl 回调中调用但记住它返回的是当前时刻已接收头集合的快照。内存拷贝需要长期保留头数据时务必在下次调用前自行strdup/拷贝。编译开关若库以CURL_DISABLE_HEADERS_API构建本 API 返回CURLHE_NOT_BUILT_IN代码应能容忍该返回值。迭代稳定性curl_easy_nextheader迭代过程中保持origin与request不变easy 句柄开始新传输后旧的prev指针失效。与curl_easy_header相关的其他 libcurl 接口还包括 CURLINFO_CONTENT_TYPE快速取Content-Type值、CURLOPT_HEADERFUNCTION逐行回调方式以及curl_easy_nextheader遍历方式开发者可根据场景在三者间取舍。本 API 的完整参考文档位于 docs/libcurl/curl_easy_header.md配套迭代接口文档位于 docs/libcurl/curl_easy_nextheader.md。【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
