libcurl使用介绍

目录

1. 参考
2. curl介绍
3. libcurl-easy的API介绍
4. 注意事项

1. 参考

• [1] curl官网/curl_easy_setopt

2. curl介绍

curl是用C语言写的，提供使用URL进行文件传输的功能。目前已经支持非常多的流行的互联网协议，如：FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, LDAP, LDAPS 和 FILE等。curl支持SSL认证，HTTP POST/PUT，FTP上传，HTTP上传、代理、cookies、用户+密码认证、文件续传、代理管道等一系列强大的功能。

curl可以分成命令行工具和libcurl两个部分，命令行工具可以直接输入指令完成相应功能，libcurl则是一个URL传输库，线程安全且兼容IPv6，并且使用方便。

libcurl支持3种不同的模式，分别是"easy"、"multi"和"share"模式。

1. libcurl-easy是一组同步接口，函数都是curl_easy_*形式，这种模式调用curl_easy_perform()函数进行URL数据传输，直到传输完成函数才返回。
2. libcurl-multi是一组异步接口，函数都是curl_multi_*形式，调用curl_multi_perform()函数进行传输，但是每次调用只传一片数据，我们可以用select()函数控制多个下载任务进行同步下载，来实现在一个线程中同时下载多个文件。
3. libcurl-share允许在多线程中操作共享数据。

下面主要讲libcurl-easy的使用方式。

3. libcurl-easy的API介绍

分以下两部分进行介绍：

1. 基础使用流程
2. 其他常用功能

3.1 基础使用流程

基础的一些方法如下：

curl_global_init()
curl_easy_init()
curl_easy_reset(CURL * handle)
curl_easy_setopt(CURL * handle, CURLOPT_URL,)
curl_easy_setopt(CURL *handle, CURLOPT_WRITEFUNCTION, write_callback)
curl_easy_setopt(CURL *handle, CURLOPT_WRITEDATA, void *pointer)
curl_easy_setopt(CURL * handle, CURLOPT_POSTFIELDS,)
curl_easy_setopt(CURL *handle, CURLOPT_HTTPHEADER, struct curl_slist *headers)
curl_easy_setopt(CURL *handle, CURLOPT_CONNECTTIMEOUT, timeout_seconds)
curl_easy_setopt(CURL *handle,   CURLOPT_USERAGENT, "libcurl-agent/1.0"）
curl_easy_perform(CURL * handle)
curl_easy_cleanup(CURL * handle)
curl_global_cleanup()

• curl_global_init()、curl_global_cleanup()：
  curl_global_init()函数是初始化一系列全局变量，并分配一些全局资源，在调用libcurl函数之前，先调用curl_global_init(CURL_GLOBAL_ALL)做初始化；在调用完毕后，用curl_global_cleanup()则释放这些资源。

• CURL *curl_easy_init()：
  此函数需要最先被调用，返回CRUL easy句柄；后续其他函数调用都要用到这个句柄。如果没有调用curl_global_init()，该函数自动调用，但是考虑到线程安全的问题，最好自己调用curl_global_init()。

• void curl_easy_reset(CURL *handle )：
  重新初始化CURL句柄的选项设置。

• CURLcode curl_easy_setopt(CURL * handle, CURLOPT_URL,)：
  字符串类型，设置要处理的URL。

• CURLcode curl_easy_setopt(CURL * handle, CURLOPT_POSTFIELDS,)：
  字符串类型，提交http的post操作字符串数据。

• CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPHEADER, struct curl_slist *headers):
  自定义请求头信息。

• CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEFUNCTION, write_callback)：
  注册写回调函数

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEDATA, void *pointer);
size_t write_callback(char *ptr, size_t size, size_t nmemb, void *userdata);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEFUNCTION, write_callback)

• CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECTTIMEOUT,timeout_seconds)：
  设置连接耗时。

• CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEOUT, timerout_seconds)：
  设置传输耗时。

• CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERAGENT, "libcurl-agent/1.0"）

• CURLcode curl_easy_perform(CURL * handle)：
  执行数据传输。

• void curl_easy_cleanup(CURL * handle)：
  该函数与curl_easy_init函数成对出现，handle即为调用curl_easy_init返回的句柄。该函数在CURL会话结束退出时调用，之后handle无效。

3.2 其他常用功能

• CURLcode curl_easy_setopt(CURL *handle, CURLOPT_VERBOSE, long onoff)：
  获取verbose信息。

• CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADERFUNCTION, header_callback)：
  接收header数据。

• CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FOLLOWLOCATION, long enable):
  布尔值类型，该参数设置为非零值表示follow服务器返回的重定向信息。

size_t header_callback(char *buffer, size_t size, size_t nitems, void *userdata);
//其中，ptr指向接收到的header头数据，数据大小为size*nmemb，
//stream指向调用CURLOPT_WRITEHEADER选项设置的参数。
//该回调函数应返回实际处理的数据量大小，或者出错返回-1。

• curl_easy_setopt(CURL *handle, CURLOPT_NOPROGRESS, false)：
  设为false 下面才能设置进度响应函数。

• CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROGRESSFUNCTION, progress_callback)：

int progress_callback(void *clientp,   double dltotal,   double dlnow,   double ultotal,   double ulnow);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROGRESSDATA, void *pointer);

• CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... ):
  查询CRUL会话的内部信息，具体说明请参考参考文档

4. 注意事项

• curl_global_init()初始化的全局变量和资源并不是线程安全的，因此，在多线程应用的环境中，不要多次调用curl_global_init()和curl_global_cleanup()。
• 调用curl_easy_init()的时候，如果没有调用curl_global_init()，该函数自动调用，但是考虑到线程安全的问题，最好自己调用curl_global_init()。