curl学习篇3：curl API简介

说明：
  本文章旨在总结备份、方便以后查询，由于是个人总结，如有不对，欢迎指正；另外，内容大部分来自网络、书籍、和各类手册，如若侵权请告知，马上删帖致歉。
  QQ 群 号：513683159 【相互学习】
内容来源：
官方API手册、(转)libcurl库使用方法，好长，好详细。、libcurl库具体使用方法、curl_easy_setopt的基本选项解析、curl中curl_easy_setopt的CURLoption参数详解、libcurl 函数之 curl_easy_setopt 详细、Libcurl API概述

函数介绍：

curl_global_init()

  函数原型：CURLcode curl_global_init(long flags)
  函数功能：全局初始化curl，给定要初始化的不同特性的位集。
  函数位置：easy.c
  参数：flags：

#define CURL_GLOBAL_SSL (1<<0)  							 //初始化支持 安全套接字层。
#define CURL_GLOBAL_WIN32 (1<<1)							 //初始化win32套接字库。
#define CURL_GLOBAL_ALL (CURL_GLOBAL_SSL|CURL_GLOBAL_WIN32)	 //初始化所有的可能的调用。
#define CURL_GLOBAL_NOTHING 0								 //没有额外的初始化。
#define CURL_GLOBAL_DEFAULT CURL_GLOBAL_ALL					 //默认初始化
#define CURL_GLOBAL_ACK_EINTR (1<<2)

  返回值：CURLcode变量：curl的状态
  NOTE：
    虽然libcurl是线程安全的，但curl_global_init是不能保证线程安全的，所以不要在每个线程中都调用curl_global_init，应该将该函数的调用放在主线程中。

curl_easy_init()

  函数原型：struct Curl_easy *curl_easy_init(void)
  函数功能：用于分配、设置和初始化返回的简单句柄的外部接口。如果出现任何错误，则返回NULL。(表示一个会话的开始)
  函数位置：easy.c
  返回值：CURL的指针(easy_handle：句柄)
  NOTE：
     在调用结束时要用curl_easy_cleanup()函数清理。

curl_easy_setopt()

  函数原型curl_easy_setopt(handle, option, value)
  函数功能：告诉curl库.程序将有如何的行为。
  参数：
    参数1：CURL *handle ：句柄。
    参数2：CURL option：选项。.(都在curl.h库里有定义,man 也可以查看到)
    参数3：value，函数指针，对象指针或curl_off_t。
  NOTE：
  使用此函数调用设置的选项对使用此句柄执行的所有即将到来的传输有效。传输之间不会以任何方式重置选项，因此如果您希望使用不同选项进行后续传输，则必须在传输之间进行更改。您可以选择使用curl_easy_reset将所有选项重置为内部默认值。
  函数位置：typecheck-gcc.h

选项-http相关

  libcurl 函数之 curl_easy_setopt 详细
  官方API手册
  1.CURLOPT_URL:设置访问URL(获取/放置的完整URL).
  2.CURLOPT_WRITEFUNCTION、CURLOPT_WRITEDATA
    CURLOPT_WRITEFUNCTION:设定一个回调函数，执行libcurl在接受到数据后用户想进行的操作，通常函数多做数据保存的功能，如处理下载文件。
    CURLOPT_WRITEDATA:用于表明CURLOPT_WRITEFUNCTION中的stream指针的来源，即：设定回调函数的第四个参数的数据类型。【若不写该函数则标准输出到屏幕上，若单使用该函数则使用默认回调函数将接受到数据简单标准输出】
    回调函数原型为：size_t function( void *ptr, size_t size, size_t nmemb, void *stream)【以fwrite()函数语法为准】
  3.CURLOPT_HEADERFUNCTION
    CURLOPT_HEADERFUNCTION:设定一个回调函数，执行libcurl在接受到http头数据后用户想进行的操作。
    CURLOPT_WRITEDATA:用于表明CURLOPT_WRITEFUNCTION中的stream指针的来源，即：设定回调函数的第四个参数的数据类型。【若不写该函数则标准输出到屏幕上，若单使用该函数则使用默认回调函数将接受到数据简单标准输出】
    回调函数原型为：size_t function( void *ptr, size_t size, size_t nmemb, void *stream)【以fwrite()函数语法为准】
  4.CURLOPT_HEADERDATA
    发送FILE *或void *存储头，如果你使用回调，它只是简单地传递回调未修改。
    会直接输出到屏幕上。
  5.CURLOPT_READFUNCTION、 CURLOPT_READDATA
    CURLOPT_READFUNCTION设定一个回调函数，读取数据传递给远程主机时将调用CURLOPT_READFUNCTION指定的函数，函数原型是：size_t function(void *ptr, size_t size, size_t nmemb,void *stream) 【以fread()函数语法为准】
     CURLOPT_READDATA表明CURLOPT_READFUNCTION函数原型中的stream指针来源，即：设定回调函数的第四个参数的数据类型。
  6.CURLOPT_NOPROGRESS、CURLOPT_PROGRESSFUNCTION、CURLOPT_PROGRESSDATA
    跟数据传输进度相关的参数。CURLOPT_PROGRESSFUNCTION指定的函数正常情况下每秒被libcurl调用一次，为了使CURLOPT_PROGRESSFUNCTION被调用，CURLOPT_NOPROGRESS必须被设置为false，CURLOPT_PROGRESSDATA指定的参数将作为 CURLOPT_PROGRESSFUNCTION指定函数的第一个参数
  7.CURLOPT_TIMEOUT、CURLOPT_CONNECTIONTIMEOUT
    CURLOPT_TIMEOUT用于设置传输时间.
    CURLOPT_CONNECTIONTIMEOUT设置连接等待时间
  8.CURLOPT_FOLLOWLOCATION:设置重定位URL
     CURLOPT_RESUME_FROM:断点续传相关设置。
    CURLOPT_RANGE指定char *参数传递给libcurl，用于指明http域的RANGE头域，例如：
        表示头500个字节：bytes=0-499
        表示第二个500字节：bytes=500-999
        表示最后500个字节：bytes=-500
        表示500字节以后的范围：bytes=500-
        第一个和最后一个字节：bytes=0-0,-1
        同时指定几个范围：bytes=500-600,601-999
    CURLOPT_RESUME_FROM传递一个long参数给libcurl，指定你希望开始传递的偏移量。
  9.CURLOPT_UPLOAD：
    如果第三个参数被设置为1的话，就是让libcurl做好上传的准备。如果传输协议是http的话，uoload就是发送put。
  10. CURLOPT_SSL_VERIFYPEER:
    第三个参数的缺省值为1.该函数多用于设定curl忽略对网站证书的检查（不管忽略不忽略，curl都是检查的）。
  11.CURLOPT_VERBOSE
    相当厉害的一个参数，可以向控制台（默认）输出curl接受和发送的数据，输出流可以重定向。
  12.CURLOPT_HTTPGET
    将curl向服务器交互数据的方式改变为get

选项-http消息头

  使用libcurl发送http请求时，会自动添加一些http头
  可通过CURLOPT_HTTPHEADER属性手动替换、添加或删除相应的HTTP消息头。
   HTTP支持GET, HEAD或者POST提交请求。可以设置CURLOPT_CUSTOMREQUEST来设置自定义的请求方式，libcurl默认以GET方式提交请求。

选项-http应答头

   发出http请求后，服务器会返回应答头信息和应答数据，如果仅仅是打印应答头的所有内容，则直接可以通过curl_easy_setopt(curl, CURLOPT_HEADERFUNCTION, 打印函数)的方式来完成，这里需要获取的是应答头中特定的信息，如：应答码、cookies列表等，则需使用函数：
    CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... );
     info参数就是我们需要获取的内容，如:
      1.CURLINFO_RESPONSE_CODE：获取应答码
      2.CURLINFO_HEADER_SIZE：头大小
      3.CURLINFO_COOKIELIST：cookies列表
  除了获取应答信息外，这个函数还能获取curl的一些内部信息，如请求时间、连接时间等等。

选项-http验证

  在使用HTTP协议时，客户端有很多种方式向服务器提供验证信息。默认的 HTTP验证方法是"Basic”，它将用户名与密码以明文的方式、经Base64编码后保存在HTTP请求头中，发往服务器。当然这不太安全。
  当前版本的libcurl支持的验证方法有：basic, Digest, NTLM, Negotiate, GSS-Negotiate and SPNEGO。
    可通过CURLOPT_HTTPAUTH属性来设置具体的验证方式：
  curl_easy_setopt(easy_handle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST);
   向代理服务器发送验证信息时，可以通过CURLOPT_PROXYAUTH设置验证方式：   curl_easy_setopt(easy_handle, CURLOPT_PROXYAUTH, CURLAUTH_NTLM);
  也可同时设置多种验证方式（通过按位与）,使用‘CURLAUTH_ANY‘将允许libcurl可以选择任何它所支持的验证方式。通过CURLOPT_HTTPAUTH或 CURLOPT_PROXYAUTH属性设置的多种验证方式，libcurl会在运行时选择一种它认为是最好的方式与服务器通信：
   curl_easy_setopt(easy_handle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST|CURLAUTH_BASIC);
  // curl_easy_setopt(easy_handle, CURLOPT_HTTPAUTH, CURLAUTH_ANY);

curl_easy_perform()

  函数原型：CURLcode curl_easy_perform(struct Curl_easy *data)
  函数功能：执行前面设置的阻塞传输的外部接口。
  函数位置：easy.c
  参数：CURL的指针(句柄)
  返回值：CURLcode变量：curl的状态

1.CURLE_OK								//任务完成一切都好
2.CURLE_UNSUPPORTED_PROTOCOL			//不支持的协议，由URL的头部指定
3.CURLE_COULDNT_CONNECT					//不能连接到remote 主机或者代理
4.CURLE_REMOTE_ACCESS_DENIED			//访问被拒绝
5.CURLE_HTTP_RETURNED_ERROR				//Http返回错误
6.CURLE_READ_ERROR						//读本地文件错误

  NOTE：
    在初始化CURL类型的指针 以及curl_easy_setop()t完成后调用. 即：完成curl_easy_setopt指定的所有选项（执行curl的各种操作），并且通过分析其返回值，可以判断curl执行的情况。

curl_easy_cleanup()

  函数原型：void curl_easy_cleanup(struct Curl_easy *data)
  函数功能：清除/释放给定简单句柄的外部接口。(结束一个会话)
  函数位置：easy.c
  参数：CURL的指针(句柄)
  返回值：无
  NOTE：
    与curl_easy_init配合着用.

curl_global_cleanup()

  函数原型：void curl_global_cleanup(void)
  函数功能：全局清理curl，使用“init_flags”的值来确定哪些需要清理，哪些不需要。【init_flags为easy.c中的全局变量】
  函数位置：easy.c
  参数：无
  返回值：无

---

curl_version()

  函数原型：char *curl_version(void)
  函数功能： 返回libcurl库的版本的字符串。
  函数位置：version.c
  参数：无
  返回值：版本字符串

curl_easy_getinfo()

  函数原型：CURLcode curl_easy_getinfo(struct Curl_easy *data, CURLINFO info, ...)
  函数功能：外部接口，允许应用程序从执行的传输和类似操作中检索信息。
  函数位置：easy.c
  参数：
    1.struct Curl_easy:CURL的指针(句柄)
    2.选项：URLINFO_RESPONSE_CODE：获得http返回的状态码，如400，200。
    
  返回值：CURLcode变量：curl的状态
  NOTE：

curl_getate()

  函数原型：
  函数功能：将日期字符串转换为Time_t
  函数位置：
  参数：
  返回值：
  NOTE：

curl_easegetinfo()

  函数原型：
  函数功能：获取有关已执行的传输的信息
  函数位置：
  参数：
  返回值：
  NOTE：

curl_formadd()

  函数原型：
  函数功能：帮助构建HTTP表单POST
  函数位置：
  参数：
  返回值：
  NOTE：

curl_formfree()

  函数原型：
  函数功能：释放一个用卷曲形
  函数位置：
  参数：
  返回值：
  NOTE：

curl_slist_append()

  函数原型：
  函数功能：构建链接列表
  函数位置：
  参数：
  返回值：
  NOTE：

curl_slist_free_all()

  函数原型：
  函数功能：释放整个卷曲列表
  函数位置：
  参数：
  返回值：
  NOTE：

curl_url_set()

  函数原型：
  函数功能：解析URL
  函数位置：
  参数：
  返回值：
  NOTE：

  
  
  
    
  
  函数原型：
  函数功能：
  函数位置：
  参数：
  返回值：
  NOTE：