C++中LibCurl库使用流程及配置详解

		
CURLcode curl_global_init(long flags); //这个函数只能用一次。(调用curl_global_cleanup清理后可再次使用初始化)
//参数：flags
 	//CURL_GLOBAL_ALL: 初始化所有的 libcurl 功能。
 	//CURL_GLOBAL_SSL: 初始化 SSL 相关的功能，如支持 HTTPS 议。
 	//CURL_GLOBAL_WIN32: 在 Windows 平台上初始化一些特定的功能。
 	//CURL_GLOBAL_NOTHING: 不做任何初始化，这种情况下需要手动初始化特定的功能。
//返回值： CURLcode 类型的错误码，如果初始化成功则返回 CURLE_OK，否则返回其他错误码表示初始化失败

curl_easy_setopt(curl, CURLOPT_URL, url.data());   // 设置要下载的URL地址
curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteCallback);   // 设置回调函数以将数据写入文件
curl_easy_setopt(curl, CURLOPT_WRITEDATA, &downloadData);   // 传递包含输出文件指针、进度等的结构体给回调函数

CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter);
	//参数：
	//	- handle: 指向 CURL 句柄的指针，表示要设置选项的 CURL 句柄。
	//	- option: 枚举类型 CURLoption，表示要设置的选项类型。
	//	- parameter: 选项对应的参数值，类型根据不同选项而定，既可以是个函数的指针,也可以是某个对象的指针,也可以是个long型的变量
	常见CURLoption类型(更多CURLoption类型的选项都在curl.h库里有定义,man 也可以查看到)：
		CURLOPT_URL: 设置请求的 URL。
		CURLOPT_HTTPHEADER: 设置请求头信息。
		CURLOPT_POSTFIELDS: 设置请求体数据。
		CURLOPT_TIMEOUT: 设置请求超时时间。
		CURLOPT_WRITEFUNCTION: 设置写数据回调函数。
		CURLOPT_WRITEDATA: 设置写数据回调函数的用户数据。
		CURLOPT_PROXY: 设置代理服务器地址。
		CURLOPT_SSL_VERIFYPEER: 设置是否验证对等证书。
		CURLOPT_SSL_VERIFYHOST: 设置是否验证主机名。
		CURLOPT_CUSTOMREQUEST: 设置自定义请求方法。
		CURLOPT_USERAGENT: 设置用户代理信息。
		CURLOPT_VERBOSE: 设置是否输出详细的调试信息。
		CURLOPT_FOLLOWLOCATION: 设置是否跟随重定向。
		CURLOPT_COOKIE: 设置请求中的 Cookie。
		CURLOPT_COOKIEFILE: 设置从文件中读取 Cookie。
		CURLOPT_COOKIEJAR: 设置保存 Cookie 到文件。
		CURLOPT_RESUME_FROM: 设置断点续传的起始位置。
		CURLOPT_LOW_SPEED_LIMIT: 设置低速下载速度限制。
		CURLOPT_LOW_SPEED_TIME: 设置低速下载持续时间。
		CURLOPT_CONNECTTIMEOUT: 设置连接超时时间
	
	例如：
	struct curl_slist *headers = NULL;
	headers = curl_slist_append(headers, "Content-Type: application/json");
	curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);	//设置请求头
	curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");	//设置 URL
	curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "key1=value1&key2=value2");	//设置请求体
	curl_easy_setopt(curl, CURLOPT_TIMEOUT, 10L); // 设置请求超时时间,超时时间为10秒
	curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_callback);//设置写数据回调函数
	curl_easy_setopt(curl, CURLOPT_WRITEDATA, &response);//设置回调函数用户数据
	curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy.example.com:8080");	//设置代理
	curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L); //设置 SSL 选项, 禁止验证对等证书

size_t write_callback(char *ptr, size_t size, size_t nmemb, void *userdata);
//参数：
	- ptr 是接收到的数据缓冲区指针，
	- size 是单个数据块的大小，
	- nmemb 是数据块的数量，
	- userdata 是传递给 CURLOPT_WRITEDATA 的用户数据指针。
//返回值：回调函数返回接收到的数据大小。

int progress_callback(void *clientp, double dltotal, double dlnow, double ultotal, double ulnow);
//参数：
	- clientp 是传递给 `CURLOPT_PROGRESSDATA` 的用户数据指针，
	- dltotal 是预期下载总字节数，
	- dlnow 是当前已下载字节数，
	- ultotal 是预期上传总字节数，
	- ulnow 是当前已上传字节数。
//返回值：回调函数应该返回 0 以继续下载操作，返回非零值表示终止下载操作。

if (res != CURLE_OK) {
    fprintf(stderr, "curl_easy_perform() failed: %s\n", curl_easy_strerror(res));
} else {    // 请求成功，处理响应数据  }

//以下是一些常用的 CURLcode 枚举值,详细的错误描述字符串，可以通过const char *curl_easy_strerror(CURLcode errornum ) 这个函数取得
CURLE_OK (0): 操作成功完成。
CURLE_UNSUPPORTED_PROTOCOL (1): 不支持的协议。
CURLE_URL_MALFORMAT (3): URL 格式错误。
CURLE_COULDNT_RESOLVE_HOST (6): 无法解析主机名。
CURLE_COULDNT_CONNECT (7): 无法连接到主机或代理。
CURLE_OPERATION_TIMEDOUT (28): 操作超时。
CURLE_SSL_CONNECT_ERROR (35): SSL/TLS 连接错误。
CURLE_PEER_FAILED_VERIFICATION (51): 对等证书验证失败。
CURLE_GOT_NOTHING (52): 未收到任何数据。
CURLE_SEND_ERROR (55): 发送数据时出错。
CURLE_RECV_ERROR (56): 接收数据时出错。
CURLE_SSL_CERTPROBLEM (58): 证书问题。
CURLE_SSL_CIPHER (59): SSL/TLS 密码错误。
CURLE_SSL_CACERT (60): 未找到合适的 CA 证书。
CURLE_USE_SSL_FAILED (64): 使用 SSL/TLS 失败。

#include <stdio.h>
#include <curl/curl.h>


struct DownloadData {
	FILE *file = nullptr; // 声明为 null ;
	s32 fileSize;
	s32 downloaded;
	std::string hash;
	bool isInitialized = false;
};

// 定义写数据回调函数
size_t HttpDownloadService::WriteCallback(void *contents, size_t size, size_t nmemb, void *userp) {
	// size_t data_size = size * nmemb; // 计算本次写入的数据总大小(size是单个数据块大小,nmemb是块的数量)
   	// 获取传递进来的DownloadData结构体指针
   	struct DownloadData *downloadData = (struct DownloadData *) userp;
   // 将数据块写入文件,返回实际写入的大小
    size_t write_size = fwrite(contents, size, nmemb, downloadData->file);
  	downloadData->downloaded += write_size;  // 更新已下载的总字节数
   	if (downloadData->fileSize > 0) {
     	downloaded = downloadData->downloaded;
        double progress = (double) downloadData->downloaded / downloadData->fileSize * 100; 
        std::cout << " Download fileSize: " << downloadData->fileSize << "  Download Progress: " << progress << "%" << std::endl;
      }
   	return write_size;
}
        
int main() {
      curl_global_init(CURL_GLOBAL_ALL);// 初始化CURL库
      CURL *curl = curl_easy_init();  // 获取一个CURL句柄用于本次传输    
      if (curl) {      
     	const char *outputFileName = "aaa.txt";
        struct DownloadData downloadData;
        // 以二进制写模式打开输出文件
        downloadData.file = fopen(outputFileName, "wb"); // Open the file and get FILE* pointer
        downloadData.fileSize = 7022;  // 预期的总文件大小,字节数
        downloadData.downloaded = 0;    // 已下载的字节数
        downloadData.hash = "8b32dbbdfcffc01ae7ff4cd29c9e4bfa973e9df29a629c80605d374d4237e2ba"; // 预期的下载文件SHA256哈希值
        
        curl_easy_setopt(curl, CURLOPT_URL, “http://example.com”);   // 设置要下载的URL地址
        curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteCallback);   // 设置回调函数以将数据写入文件
        curl_easy_setopt(curl, CURLOPT_WRITEDATA, &downloadData);   // 传递包含输出文件指针、进度等的结构体给回调函数
        curl_easy_setopt(curl, CURLOPT_NOPROGRESS, 0);   // 启用进度回调
        curl_easy_setopt(curl, CURLOPT_PROGRESSFUNCTION, nullptr);  // 进度回调函数可选,这里不使用
        curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT, 3);

      		CURLcode res = curl_easy_perform(curl);  // 执行请求
        if (res != CURLE_OK) {
        	// 请求失败，处理错误
             std::cout << "Download failed: {}: " << curl_easy_strerror(res)<< std::endl;
        } else {
         	// 请求成功，处理响应数据
            logger->Info(SRC_LOC, "Download completed successfully.");
            std::cout << "Download completed successfully. " << std::endl;
            //……eg：对比文件大小和hash检查下载文件是否正常
        }

        curl_easy_cleanup(curl);    // 清理CURL句柄资源
        fclose(downloadData.file); // Close the file
      }
       
    curl_global_cleanup();  // 清理CURL库资源
    return 0;
}