libcurl库（C++）快速使用

简介

libcurl作为是一个多协议的便于客户端使用的URL传输库，基于C语言，提供C语言的API接口，支持DICT, FILE, FTP, FTPS, Gopher, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMTP, SMTPS, Telnet and TFTP这些协议，同时支持使用SSL证书的安全文件传输：HTTP POST, HTTP PUT, FTP 上传, 基于HTTP形式的上传、代理、Cookies、用户加密码的认证等多种应用场景。另外，libcurl是一个高移植性的库，能在绝大多数系统上运行，包括Solaris, NetBSD, FreeBSD, OpenBSD, Darwin, HPUX, IRIX, AIX, Tru64, Linux, UnixWare, HURD, Windows, Amiga, OS/2, BeOs, Mac OS X, Ultrix, QNX, OpenVMS, RISC OS, Novell NetWare, DOS等。

前段时间需要使用C++发起http请求，这里对这些使用做一个总结以备忘。libcurl封装了协议的底层实现，非常方便用户开发应用层逻辑。

使用步骤

具体使用主要遵循如下步骤：
1. 全局初始化
2. 创建当次请求句柄
3. 设置属性
4. 执行
5. 销毁当次请求句柄
6. 全局析构

下面详细说明：

1.全局初始化

CURLcode curl_global_init(long flags);
flags:
    CURL_GLOBAL_ALL //初始化所有内部的模块
    CURL_GLOBAL_SSL //初始化支持安全套接字
    CURL_GLOBAL_WIN32 //初始化win32套接字库
    CURL_GLOBAL_NOTHING //不初始化任何额外模块
    CURL_GLOBAL_DEFAULT //与CURL_GLOBAL_ALL相同

该函数必须再所有其他libcurl函数调用前被调用，从而构建整个libcurl函数运行所需的环境，多次调用是幂等的。flags参数能够使用”或”操作符进行多个选项的拼接。一般情况使用CURL_GLOBAL_ALL是最好的选择。
该函数不是线程安全的，不能在程序的其他线程中调用，只能应用程序开始时，进行全局初始化调用。虽然不调用这个函数，使用curl_easy_init也会自行调用该函数，但在多线程处理时，可能出现多次调用的情况，应避免。

2.创建当次请求句柄

每次请求都需要创建一个句柄，所有操作围绕以此句柄进行：

CURL *curl_handler = curl_easy_init();

3.设置属性

libcurl针对所有协议，统一使用一个简单的函数curl_easy_setopt进行设置，这大大简化了使用，不过需要参考不同协议设置不同的属性https://curl.haxx.se/libcurl/c/curl_easy_perform.html。这里以http发送GET请求为例设置如下：

//设置请求的url
curl_easy_setopt(curl_handler, CURLOPT_URL, url);

//设置是否返回请求头
curl_easy_setopt(curl_handler, CURLOPT_HEADER, 1L);

//设置屏蔽其他信号
curl_easy_setopt(curl_handler, CURLOPT_NOSIGNAL, 1L);

//设置下载数据回调函数
curl_easy_setopt(curl_handler, CURLOPT_WRITEFUNCTION, write_func);
curl_easy_setopt(curl_handler, CURLOPT_WRITEDATA, write_data);
回调函数原型：
    size_t function( void *ptr, size_t size, size_t nmemb, void *userp);
        函数将在libcurl接收到数据后被调用。
        void *ptr是下载回来的数据.
        void *userp是用户指针, 用户通过这个指针传输自己的数据.
CURLOPT_WRITEDATA：设置回调函数中的void *userp指针的来源。

//设置是否使用下载进度控制函数
curl_easy_setopt(curl_handler, CURLOPT_NOPROGRESS, 0L);
curl_easy_setopt(curl_handler, CURLOPT_PROGRESSFUNCTION, prog_func);
curl_easy_setopt(curl_handler, CURLOPT_PROGRESSDATA, pdata);
下载进度回调函数与下载数据的回调函数原型相同，data也相同。

//设置请求头
struct curl_list *header_list = NULL;
for (int i = 0; i < headers.size(); ++i) {
    header_list = curl_slist_append(header_list, headers[i].c_str());
}
curl_easy_setopt(curl_handler, CURLOPT_HTTPHEADER, header_list);
curl_slist_free_all(header_list);

//其他选项
     CURLOPT_HEADERFUNCTION
     CURLOPT_HEADERDATA
       只取HTTP头部数据, 处理与下载数据回调的处理相同. 
     CURLOPT_TIMEOUT
       超时时间.
     CURLOPT_CONNECTIONTIMEOUT
       连接等待时间.
     CURLOPT_FOLLOWLOCATION
　　   设置支持302重定向
　　 CURLOPT_RANGE
    　 断点续传, 指定传输分片, 格式:"0-200"

其中，针对http协议，不同请求有特定的属性需要设置，下面依次列举：
- HEAD：需要设置CURLOPT_NOBODY为true
- DELETE：需要设置CURLOPT_CUSTOMREQUEST为”DELETE”
- PUT：需要设置CURLOPT_UPLOAD为true，同时设置CURLOPT_READFUNCTION、CURLOPT_READDATA、CURLOPT_INFILESIZE_LARGE
- POST：需要设置CURLOPT_POST为true，设置CURLOPT_POSTFIELDS、CURLOPT_POSTFIELDSIZE

4.执行

CURLcode curl_easy_perform(CURL *handler);

该函数执行当次请求创建的句柄，返回值有非常详细的定义libcurl库返回状态码解释与速查。

5.销毁当次请求句柄

void curl_easy_cleanup(CURL *handler);

该函数销毁当次请求创建的句柄。

6.全局析构

void curl_global_cleanup();

该函数销毁全局执行环境。

其他接口

libcurl除了上述常用接口外，提供了其他接口可以进行更为方便和精确的控制。

CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... );
//支持的CURLINFO类型见此：https://curl.haxx.se/libcurl/c/curl_easy_getinfo.html

curl_version()  returns a pointer to the libcurl version string
curl_getdate()  converts a date string to time_t
curl_formadd()  build multipart form-data posts
curl_formfree() free a previously built form POST
curl_slist_append() builds a linked list
curl_slist_free_all()   frees a whole curl_slist as made with curl_slist_append()
curl_easy_escape()  URL encodes a string
curl_easy_unescape()    URL decodes a string

后续将实现的例程进行更新。