curl库中curl_easy_setopt函数详解

#include
CURLcodecurl_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 个参数中的回调函数必须是下面的函数原型：

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 中：

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 传输请求发送完后发送。比如像下面的执行顺序是无法达到目的的：

1 . ... ...

2 curl_easy_perform(curl);

3 curl_easy_setopt(curl, CURLOPT_QUOTE, headerlist);

4 curl_easy_perform(curl);

5 ... ...

 

上面假设第 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 的方法进行上传，除非另有指定。

CURLOPT_HEADER：设为1，则在返回的内容里包含http header；

CURLOPT_FOLLOWLOCATION：设为0，则不会自动301，302跳转；

*CURLOPT_INFILESIZE: 当你上传一个文件到远程站点，这个选项告诉PHP你上传文件的大小。
*CURLOPT_VERBOSE: 如果你想CURL报告每一件意外的事情，设置这个选项为一个非零值。
*CURLOPT_HEADER: 如果你想把一个头包含在输出中，设置这个选项为一个非零值。
*CURLOPT_NOPROGRESS: 如果你不会PHP为CURL传输显示一个进程条，设置这个选项为一个非零值。

 

注意：PHP自动设置这个选项为非零值，你应该仅仅为了调试的目的来改变这个选项。

*CURLOPT_NOBODY: 如果你不想在输出中包含body部分，设置这个选项为一个非零值。
*CURLOPT_FAILONERROR: 如果你想让PHP在发生错误(HTTP代码返回大于等于300)时，不显示，设置这个选项为一人非零值。默认行为是返回一个正常页，忽略代码。
*CURLOPT_UPLOAD: 如果你想让PHP为上传做准备，设置这个选项为一个非零值。
*CURLOPT_POST: 如果你想PHP去做一个正规的HTTP POST，设置这个选项为一个非零值。这个POST是普通的 application/x-www-from-urlencoded 类型，多数被HTML表单使用。
*CURLOPT_FTPLISTONLY: 设置这个选项为非零值，PHP将列出FTP的目录名列表。
*CURLOPT_FTPAPPEND: 设置这个选项为一个非零值，PHP将应用远程文件代替覆盖它。
*CURLOPT_NETRC: 设置这个选项为一个非零值，PHP将在你的 ~./netrc 文件中查找你要建立连接的远程站点的用户名及密码。
*CURLOPT_FOLLOWLOCATION: 设置这个选项为一个非零值(象 “Location: “)的头，服务器会把它当做HTTP头的一部分发送(注意这是递归的，PHP将发送形如 “Location: “的头)。
*CURLOPT_PUT: 设置这个选项为一个非零值去用HTTP上传一个文件。要上传这个文件必须设置CURLOPT_INFILE和CURLOPT_INFILESIZE选项.
*CURLOPT_MUTE: 设置这个选项为一个非零值，PHP对于CURL函数将完全沉默。
*CURLOPT_TIMEOUT: 设置一个长整形数，作为最大延续多少秒。
*CURLOPT_LOW_SPEED_LIMIT: 设置一个长整形数，控制传送多少字节。
*CURLOPT_LOW_SPEED_TIME: 设置一个长整形数，控制多少秒传送CURLOPT_LOW_SPEED_LIMIT规定的字节数。
*CURLOPT_RESUME_FROM: 传递一个包含字节偏移地址的长整形参数，(你想转移到的开始表单)。
*CURLOPT_SSLVERSION: 传递一个包含SSL版本的长参数。默认PHP将被它自己努力的确定，在更多的安全中你必须手工设置。
*CURLOPT_TIMECONDITION: 传递一个长参数，指定怎么处理CURLOPT_TIMEVALUE参数。你可以设置这个参数为TIMECOND_IFMODSINCE 或 TIMECOND_ISUNMODSINCE。这仅用于HTTP。
*CURLOPT_TIMEVALUE: 传递一个从1970-1-1开始到现在的秒数。这个时间将被CURLOPT_TIMEVALUE选项作为指定值使用，或被默认TIMECOND_IFMODSINCE使用。

下列选项的值将被作为字符串：

*CURLOPT_URL: 这是你想用PHP取回的URL地址。你也可以在用curl_init()函数初始化时设置这个选项。
*CURLOPT_USERPWD: 传递一个形如[username]:[password]风格的字符串,作用PHP去连接。
*CURLOPT_PROXYUSERPWD: 传递一个形如[username]:[password] 格式的字符串去连接HTTP代理。
*CURLOPT_RANGE: 传递一个你想指定的范围。它应该是”X-Y”格式，X或Y是被除外的。HTTP传送同样支持几个间隔，用逗句来分隔(X-Y,N-M)。
*CURLOPT_POSTFIELDS: 传递一个作为HTTP “POST”操作的所有数据的字符串。
*CURLOPT_REFERER: 在HTTP请求中包含一个”referer”头的字符串。
*CURLOPT_USERAGENT: 在HTTP请求中包含一个”user-agent”头的字符串。
*CURLOPT_FTPPORT: 传递一个包含被ftp “POST”指令使用的IP地址。这个POST指令告诉远程服务器去连接我们指定的IP地址。这个字符串可以是一个IP地址，一个主机名，一个网络界面名(在UNIX下)，或是‘-’(使用系统默认IP地址)。
*CURLOPT_COOKIE: 传递一个包含HTTP cookie的头连接。
*CURLOPT_SSLCERT: 传递一个包含PEM格式证书的字符串。
*CURLOPT_SSLCERTPASSWD: 传递一个包含使用CURLOPT_SSLCERT证书必需的密码。
*CURLOPT_COOKIEFILE: 传递一个包含cookie数据的文件的名字的字符串。这个cookie文件可以是Netscape格式，或是堆存在文件中的HTTP风格的头。
*CURLOPT_CUSTOMREQUEST: 当进行HTTP请求时，传递一个字符被GET或HEAD使用。为进行DELETE或其它操作是有益的，更Pass a string to be used instead of GET or HEAD when doing an HTTP request. This is useful for doing or another, more obscure, HTTP request.

注意: 在确认你的服务器支持命令先不要去这样做。

下列的选项要求一个文件描述(通过使用fopen()函数获得)：

*CURLOPT_FILE: 这个文件将是你放置传送的输出文件，默认是STDOUT.
*CURLOPT_INFILE: 这个文件是你传送过来的输入文件。
*CURLOPT_WRITEHEADER: 这个文件写有你输出的头部分。
*CURLOPT_STDERR: 这个文件写有错误而不是stderr。

 

 

 

几种选项测试函数:

 

#include 
#include 

#include 

#include 

#include      

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;

}