curl_easy_setopt() -- 为一个简易的 curl 句柄设置选项

beyes

函数原型：

#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter);

说明：
此函数用来告诉 libcurl 执行什么样的动作。该函数有 3 个参数(该函数的可设置选项非常之多)：
第 1 个参数 handle 是由 curl_easy_init() 返回的句柄；第 2 个参数是可以设置的选项(CURLoption)；第 3 个参数是与第 2 个选项相关联的参数，这个参数可以是 long 型，也可以是一个函数指针(function pointer)，还可以是一个对象的指针 (object pointer)，或者是一个 curl_off_t 类型，这些参数类型必须由选项值(CURLoption)来确定。

具体选项说明(分大类和小类，本说明为个人理解以及对说明手册的翻译，根据应用不断更新说明内容，分类顺序不按照说明手册)：

网络选项(NETWORK OPTIONS)：

1. CURLOPT_URL
这个选项后面接实际要处理的 URL ，这个 URL 是一个以 '\0' 结尾的字符串或参数指针(关于这个参数的简单示例见：http://www.groad.net/bbs/read.php?tid-1641.html)。如果 URL 参数不写上协议头(如 "http://" 或者 "ftp:// 等等 )，那么函数会自己进行猜解所给的主机上用的是哪一种服务协议。假如你给的这个地址是一个不被 支持的协议，那么在其后执行 curl_easy_perform() 函数或 curl_multi_perform() 函数时， libcurl 将返回错误(CURLE_UNSUPPORTED_PROTOCOL)。这个选项是唯一一个必须在 curl_easy_perform() 调用之前就要设置的选项。

2. CURLOPT_POSTFIELDSIZE
该选项要求第 3 个参数 parameter 是一个 void * 指针，它指向一个向 HTTP 服务器 POST 出去的一段数据，这段数据要根据服务器的具体要求填写。该选项用法参考示例：http://www.groad.net/bbs/read.php?tid-3909.html

3. CURLOPT_WRITEFUNCTION
使用该选项时，要求第 3 个参数中的回调函数必须是下面的函数原型：

[C++] 纯文本查看 复制代码

size_t function( char *ptr, size_t size, size_t nmemb, void *userdata);

在启动会话时，一旦检测到有需要接收的数据时，回调函数被调用。ptr 所指向的数据大小由 size 和 nmemb 的乘积获得。函数最后需要返回接收数据的大小。如果不使用该函数，那么接收到的数据会直接打印到终端；使用该函数，那么接收到的数据保存在 ptr 所执向的区域，可以利用此来保存接收下来的数据。

4. CURLOPT_USERAGENT
该选项要求传递一个以 '\0' 结尾的字符串指针，这个字符串用来在向服务器请求时发送 HTTP 头部中的 User-Agent 信息，有些服务器是需要检测这个信息的，如果没有设置 User-Agent，那么服务器拒绝请求。设置后，可以骗过服务器对此的检查。

5.  CURLOPT_WRITEDATA

使用该选项时，第 3 个参数作为用户数据的指针而传递到使用  CURLOPT_WRITEFUNCTION 选项时指定的回调函数中(第 4 个参数)。如果不想用回调函数而保存数据，那么可以使用 CURLOPT_WRITEDATA 选项，使用该选项时，函数的第 3 个参数必须是个 FILE 指针，函数会将接收到的数据自动的写到这个 FILE 指针所指向的文件流中。

6. CURLOPT_VERBOSE
在使用该选项且第 3 个参数为 1 时，curl 库会显示详细的操作信息。这对程序的调试具有极大的帮助。

7. CURLOPT_NOBODY
使用该选项时，若第 3 个参数设为 1，这样在输出中就不会包含主体内容部分。这仅是对在传输的所有内容中，含有“头部”和“主题内容”两部分的协议而言。如 HTTP(S) 服务器，在这种情况下将会使 libcurl 库仅发出一个头部请求。

8. CURLOPT_HEADER
使用该选项时，第 3 个参数设置为 1，那么会通知 curl 库在输出时要同时包含 "头部“ 和 "主题内容" 两个部分。该选项仅是对那些同时包含了”头部“和”主题内容“这两部分的协议而言(如 HTTP)。

9. CURLOPT_HEADERFUNCTION
该选项与上面第 3 个选项 CURLOPT_WRITEFUNCTION 类似，只要它一接收到头部信息时，它就会执行回调函数。需要注意的是，回调函数里处理的头部包含了所有收到的响应的头部信息，而不只是最后一次的响应。如果需要处理其中的一个头部，那么自己需要在所收集的头部信息中进行区分。

10. CURLOPT_WRITEHEADER 和  CURLOPT_HEADERDATA
这两个选项是同一种意思。它们和第 5 条中的 CURLOPT_WRITEDATA 选项功能一样，表示在接收到头部信息并调用回调函数时，给回调函数传递第 4 个参数。

11. CURLOPT_INFILESIZE
当向服务器上传文件时，该选项用来告诉 curl 库期望上传的文件的大小。使用该选项时，应该给函数第 3 个参数的应该是个 long 型变量。如果用的是 SCP 传输，那么该选项强制使用 CURLOPT_INFILESIZE_LARGE 。

12. CURLOPT_INFILESIZE_LARGE
该选项和 CURLOPT_INFILESIZE 功能一样，但是它要求函数的第 3 个参数必须是个 curl_off_t 类型。curl_off_t 为 int64_t 类型，而 int64_t 定义在 stdint.h 中：

[C++] 纯文本查看 复制代码

# if __WORDSIZE == 64
typedef long int                int64_t;
# else
__extension__
typedef long long int           int64_t;

由上面定义知，一般的，如果是 32 位平台，它就是 long long 型，表示 64 位的；如果是 64 位平台，它就是 long 型，也为 64 位。总之，就是个 64 位的。

13. CURLOPT_QUOTE 和 CURLOPT_POSTQUOTE
这两个选项的功能类似，它们的共同点都是给 FTP 或 SFTP 传递命令。这些命令应该放在 struct slist 链表中存储，使用时需要用 curl_slist_append() 函数将这些命令打包起来，然后一起发送出去。
它们的不同点是：CURLOPT_QUOTE 选项要求命令要在 FTP 传输请求之前就要发送到库，而 CURLOPT_POSTQUOTE 则可以在 FTP 传输请求发送完后发送。比如像下面的执行顺序是无法达到目的的：

[Plain Text] 纯文本查看 复制代码

... ...
curl_easy_perform(curl);
curl_easy_setopt(curl, CURLOPT_QUOTE, headerlist);
curl_easy_perform(curl);
... ...

上面假设第 1 条 curl_easy_perform(curl); 语句已经发送了 FTP 传输请求，然后再用 CURLOPT_QUOTE 发送命令是错误的，这里应该使用 CURLOPT_POSTQUOTE 选项。使用 CURLOPT_QUOTE 选项需要先用 curl_easy_perform() 函数将其发送，然后再用一次 curl_easy_perform() 发送 FTP 传输请求。也就是说需要执行两次  curl_easy_perform() 函数。而用  CURLOPT_POSTQUOTE 选项则不需要这样，它只要将选项设置好后，然后只执行一次 curl_easy_perform() 函数即可。

14. CURLOPT_READFUNCTION 和 CURLOPT_READDATA
这两个选项和上面的  CURLOPT_WRITEFUNCTION 和 CURLOPT_WRITEDATA 类似。在 CURLOPT_READFUNCTION 的回调函数里，第 1 个参数 ptr 指针用来接收从第 4 个参数传递过来的数据(这个参数往往是个文件流指针)，而这个参数是使用 CURLOPT_READDATA 选项时传递过来的。

15. CURLOPT_UPLOAD
在使用该选项时，第 3 个参数设置为 1，表示要准备上传文件。这个参数往往会配合 CURLOPT_READDATA，CURLOPT_INFILESIZE_LARGE，以及 CURLOPT_INFILESIZE 这几个选项一起用。如果是使用 HTTP 协议，那么使用 PUT 的方法进行上传，除非另有指定。

beyes

测试代码：

[C++] 纯文本查看 复制代码

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <curl/curl.h>
#include <curl/easy.h>


static size_t save_header(void *ptr, size_t size, size_t nmemb, void *data)
{

        fwrite(ptr, size, nmemb, data);
        return (size * nmemb);
}

int main(void)
{
        char url[] = "http://www.sina.com.cn/";
        CURL *curl;
        CURLcode res;
   
        FILE *fp;
        if (!(fp = fopen("htmheader.html", "w"))) {
                printf ("fopen error\\n");
                return -1;
        }

        curl_global_init(CURL_GLOBAL_ALL);

        curl = curl_easy_init();
        if (curl) {
                curl_easy_setopt(curl, CURLOPT_URL, url);
                curl_easy_setopt(curl, CURLOPT_NOBODY, 1L);
                curl_easy_setopt(curl, CURLOPT_HEADER, 0L);
                curl_easy_setopt(curl, CURLOPT_HEADERFUNCTION, save_header);
                curl_easy_setopt(curl, CURLOPT_WRITEHEADER, fp);
                curl_easy_perform(curl);
        }
       curl_easy_cleanup(curl);
        curl_global_cleanup();

        fclose (fp);
        return 0;
}

收到来自新浪服务器的头部信息：

$ cat htmheader.html
HTTP/1.0 200 OK
Last-Modified: Mon, 04 Jul 2011 04:01:58 GMT
Accept-Ranges: bytes
X-Powered-By: mod_xlayout_jh/0.0.1vhs.markIII.remix
Vary: Accept-Encoding
X-UA-Compatible: IE=EmulateIE7
Content-Type: text/html
Date: Mon, 04 Jul 2011 04:03:23 GMT
Server: Apache/2.0.61 (Unix)
Expires: Mon, 04 Jul 2011 04:04:23 GMT
Cache-Control: max-age=60
Age: 51
Content-Length: 535318
X-Cache: HIT from 236-37.D07071950.sina.com.cn
Connection: close