curl 中 CURLINFO_PROTOCOL 选项详解：查询传输所用 URL 方案的已弃用 libcurl 接口与 CURLINFO

curl 中 CURLINFO_PROTOCOL 选项详解：查询传输所用 URL 方案的已弃用 libcurl 接口与 CURLINFO_SCHEME 迁移指南

【免费下载链接】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

CURLINFO_PROTOCOL是 libcurl 通过curl_easy_getinfo()提供的一个查询选项，用于在传输完成后获取本次传输所使用的 URL 方案（scheme），返回一个long类型的CURLPROTO_*位标志。该选项自 7.52.0 引入，自 7.85.0 起被官方标记为弃用，并推荐改用返回字符串的CURLINFO_SCHEME。本文以 CURLINFO_PROTOCOL 官方文档为核心，结合 curl 仓库源码，完整讲解其用法、全部可返回值、底层赋值链路以及弃用原因和迁移方法。

基本用法

CURLINFO_PROTOCOL的使用方式是通过curl_easy_getinfo()传入一个long *指针，接收最后一次传输所用的方案标志值：

#include <curl/curl.h> CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PROTOCOL, long *p);

注意几点关键约束：

传入参数必须是long *类型指针，与其他CURLINFO_LONG类型选项（如CURLINFO_RESPONSE_CODE）使用同一取值通道；
返回的是“最后一次传输”（the last transfer）所使用的方案，在curl_easy_perform()之后调用才有意义；
该选项适用于所有协议（文档 front matter 中Protocol: All）。

在include/curl/curl.h中，该枚举定义为CURLINFO_LONG + 48，且带有弃用属性：

CURLINFO_PROTOCOL CURL_DEPRECATED(7.85.0, "Use CURLINFO_SCHEME") = CURLINFO_LONG + 48,

见 include/curl/curl.h。紧随其后的CURLINFO_SCHEME = CURLINFO_STRING + 49就是官方推荐的替代选项。

返回值：CURLPROTO_* 位标志全集

文档列出的全部可能返回值如下，每个值都是一个独立的 bit（1L << N）。结合 include/curl/curl.h 中的定义，可整理成完整的取值表：

常量	位值	含义
`CURLPROTO_HTTP`	`1L << 0`	http
`CURLPROTO_HTTPS`	`1L << 1`	https
`CURLPROTO_FTP`	`1L << 2`	ftp
`CURLPROTO_FTPS`	`1L << 3`	ftps
`CURLPROTO_SCP`	`1L << 4`	scp
`CURLPROTO_SFTP`	`1L << 5`	sftp
`CURLPROTO_TELNET`	`1L << 6`	telnet
`CURLPROTO_LDAP`	`1L << 7`	ldap
`CURLPROTO_LDAPS`	`1L << 8`	ldaps
`CURLPROTO_DICT`	`1L << 9`	dict
`CURLPROTO_FILE`	`1L << 10`	file
`CURLPROTO_TFTP`	`1L << 11`	tftp
`CURLPROTO_IMAP`	`1L << 12`	imap
`CURLPROTO_IMAPS`	`1L << 13`	imaps
`CURLPROTO_POP3`	`1L << 14`	pop3
`CURLPROTO_POP3S`	`1L << 15`	pop3s
`CURLPROTO_SMTP`	`1L << 16`	smtp
`CURLPROTO_SMTPS`	`1L << 17`	smtps
`CURLPROTO_RTSP`	`1L << 18`	rtsp
`CURLPROTO_RTMP`	`1L << 19`	rtmp
`CURLPROTO_RTMPT`	`1L << 20`	rtmpt
`CURLPROTO_RTMPE`	`1L << 21`	rtmpe
`CURLPROTO_RTMPTE`	`1L << 22`	rtmpete
`CURLPROTO_RTMPS`	`1L << 23`	rtmps
`CURLPROTO_RTMPTS`	`1L << 24`	rtMPTS
`CURLPROTO_GOPHER`	`1L << 25`	gopher
`CURLPROTO_SMB`	`1L << 26`	smb
`CURLPROTO_SMBS`	`1L << 27`	smbs
`CURLPROTO_MQTT`	`1L << 28`	mqtt
`CURLPROTO_GOPHERS`	`1L << 29`	gophers

头文件中还额外定义了CURLPROTO_ALL ((unsigned long)0xffffffff)，表示“旧式”的“全部启用”掩码。需要说明：

头文件明确注释这些CURLPROTO_定义“是供已弃用的CURLOPT_*PROTOCOLS选项使用的，请勿使用”（见 include/curl/curl.h）。CURLINFO_PROTOCOL只是复用了这套位定义作为“查询结果枚举”；
文档所列的 RTMP 系列（RTMP/RTMPE/RTMPS/RTMPT/RTMPTE/RTMPTS）在头文件中仍保留位定义，但 RTMP 支持在较新的 curl 中已被移除，这些值实际上不会再被返回——这也是位枚举难以反映现状的一个例子；
头文件注释特别指出long可能是 32 位或 64 位，但“永远不应依赖 32 位以外的任何假设”，因此这套位空间事实上只覆盖 30 个已知方案，无法表达后来新增的 scheme。

底层实现：conn_protocol 从哪来

从源码结构看，CURLINFO_PROTOCOL的取值链路非常短：

存储：struct Curl_easy中的data->info结构保存conn_protocol（uint32_t类型，见 lib/urldata.h）。curl_easy_getinfo处理前会在 lib/getinfo.c 将其清零（info->conn_protocol = 0;）。
赋值：真正写入发生在建连阶段。lib/url.c有两处赋值点：
- file://这类无需网络连接的协议在 lib/url.c：
```
data->info.conn_scheme = needle->scheme->name; /* conn_protocol can only provide "old" protocols */>data->info.conn_scheme =>case CURLINFO_PROTOCOL: *param_longp = (long)data->info.conn_protocol; break;
```
- 掩码：赋值时与CURLPROTO_MASK（0x3fffffff，定义于 lib/protocol.h）按位与，确保结果只落在 30 位已定义的枚举空间内。

对比之下，替代选项CURLINFO_SCHEME的读取实现是返回字符串指针data->info.conn_scheme（见 lib/getinfo.c 中case CURLINFO_SCHEME:分支），两者写入时机完全相同、来源相同（scheme->name），差异只在表达形式：一个是受限的位枚举，一个是任意 scheme 名称字符串。

弃用原因与 CURLINFO_SCHEME 迁移

文档明确声明：

This option is deprecated. We strongly recommend using CURLINFO_SCHEME(3) instead, because this option cannot return all possible schemes. The scheme might also sometimes be referred to as the protocol.

弃用时间点为7.85.0（DEPRECATED 章节），与curl.h中的CURL_DEPRECATED(7.85.0, "Use CURLINFO_SCHEME")一致。弃用的根本原因在于能力边界：

位标志空间被固定为 30 个历史方案，任何新增 scheme（例如 curl 目前支持的ws、wss等 WebSocket 方案，以及未来新增的 scheme）都没有对应位，CURLINFO_PROTOCOL对它们无能为力；
CURLINFO_SCHEME返回char *（内部常量字符串，指向 scheme 名称，如"https"），可以表达任意方案，且与CURLINFO_PROTOCOL使用同一个内部字段conn_scheme，行为语义一致。

CURLINFO_SCHEME同样自 7.52.0 引入（见 CURLINFO_SCHEME 文档），因此迁移无需担心版本门槛——只要你的 libcurl >= 7.52.0，两个选项都可用；升级到 7.85.0 之后的版本时，继续编译使用CURLINFO_PROTOCOL的代码可能会触发编译器弃用告警（取决于CURL_DEPRECATED的宏实现）。

迁移前后代码对照

文档原始示例（使用已弃用选项）：

int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode result; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); result = curl_easy_perform(curl); if(result == CURLE_OK) { long scheme; curl_easy_getinfo(curl, CURLINFO_PROTOCOL, &scheme); } curl_easy_cleanup(curl); } }

等价的推荐写法：

int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode result; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); result = curl_easy_perform(curl); if(result == CURLE_OK) { char *scheme = NULL; curl_easy_getinfo(curl, CURLINFO_SCHEME, &scheme); /* scheme 为内部常量字符串（如 "https"），无需释放； 仅当本次传输未能建立连接时可能为 NULL，使用前建议判空 */ } curl_easy_cleanup(curl); } }

迁移检查清单：

将long scheme改为char *scheme = NULL；
将CURLINFO_PROTOCOL改为CURLINFO_SCHEME；
下游逻辑从“按位比较CURLPROTO_*”改为“字符串比较（如strcmp(scheme, "https") == 0）”，并处理scheme == NULL的边界情况。

如果确实需要保留旧式位标志（例如与既有CURLOPT_PROTOCOLS时代的判断逻辑对接），旧写法仍然可以编译运行，弃用是“推荐替换”而非“立即移除”，但新代码不应再引入该用法。

返回值与错误码

按文档 RETURN VALUE 章节：curl_easy_getinfo()返回CURLcode表示成功或错误。CURLE_OK（0）表示一切正常，非零表示发生错误（错误码含义参见 libcurl-errors 文档）。与CURLINFO_PROTOCOL相关的典型错误：

CURLE_BAD_FUNCTION_ARGUMENT：未先执行curl_easy_perform()或参数指针类型不匹配（例如误用curl_easy_setopt通道）；
从 lib/getinfo.c 的默认分支可见，未知选项类型会返回CURLE_UNKNOWN_OPTION，因此选项必须走CURLINFO_LONG通道，不能与其他类型选项混用指针类型。

注意：调用curl_easy_getinfo本身成功（返回CURLE_OK）不代表值一定有效——如果传输尚未进行或未建立连接，conn_protocol保持初始化的 0，读到 0 时应理解为“无对应老方案”，而非某个真实协议。

测试用例佐证

仓库自带的回归测试对两个选项成对覆盖，可直接作为行为参照：

tests/libtest/lib1535.c：专门测试CURLINFO_PROTOCOL。其流程为：curl_easy_init()→ 未执行传输时查询（验证返回 0/CURLE_OK）→ 用curl_easy_dupehandle()复制句柄后查询（验证 dupe 句柄行为）→curl_easy_setopt设置 URL 并执行curl_easy_perform()后再次查询（验证得到正确协议位），最终统一curl_easy_cleanup()收尾；
tests/libtest/lib1536.c：对CURLINFO_SCHEME做了完全对称的测试（注释即为“Test CURLINFO_SCHEME”），两者测试骨架一一对应，说明官方在实现层面把两个选项视为同一信息的两种表达方式。

阅读这两个文件可以快速确认：无论新旧选项，查询时机（perform 前后）、dupehandle 场景的语义都一致。

适用版本与小结

事项	版本	依据
`CURLINFO_PROTOCOL`引入	7.52.0	文档 front matter`Added-in: 7.52.0`
`CURLINFO_PROTOCOL`弃用	7.85.0	文档 DEPRECATED 章节 + include/curl/curl.h
`CURLINFO_SCHEME`引入	7.52.0	CURLINFO_SCHEME 文档

小结：

CURLINFO_PROTOCOL通过curl_easy_getinfo(handle, CURLINFO_PROTOCOL, &long)返回最后一次传输所用方案的CURLPROTO_*位标志，内部取自data->info.conn_protocol，在lib/url.c建连时以scheme->protocol & CURLPROTO_MASK写入；
它自 7.85.0 起弃用，原因是 30 位枚举空间无法覆盖所有 scheme，源码注释“can only provide 'old' protocols”是其直接证据；
新代码与后续迁移应统一使用CURLINFO_SCHEME获取 scheme 字符串，两者共享同一内部数据源，语义等价、表达更完整；
配套查询接口总览可参考 curl_easy_getinfo 文档与 CURLINFO_RESPONSE_CODE 文档（文档 See-also 中列出的相邻选项）。