Using libcurl in VC++

curl是瑞典curl组织开发的，Official Website：

Introduction

curl是一个基于命令行的应用工具，提供利用URL标准进行文件传输的功能。

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

curl是用C语言写的，但是绑定了很多开发语言。大体上可以把curl分成命令行工具和libcurl库两个部分，命令行工具可以直接输入指令完成相应功能，libcurl则是一个客户端URL传输库，是线程安全且兼容IPv6，可以非常方便地用来做相关开发。

How to Using Curl Lib：

Compile curl without openssl and zlib.

Step1：下载CURL 最近的几个版本，我是curl-7.21.5。然后解压到curl-7.21.5文件夹。

Step2：打开curl-7.21.5文件夹，找到vc6curl.dsw。就是VC6工程的文件。

Step3：用2008打开，选择 生成（B）-》生成解决方案（F7） ，不要点三角形那个启动调试

Step4：打开curl-7.21.5\lib\DLL-Debug 找到libcurld.dll和libcurld_imp.lib。

Step5：打开curl-7.21.5\include\找到curl文件和第四步找到的libcurld.dll和libcurld_imp.lib一起放到你新建的工程目录你。比如你新建了个名为：DDDDDD的工程，那么久把他们放到\Visual Studio 2008\Projects\DDDDDD\DDDDDD就是有很多.h 和。CPP的地方

Step6：在你工程MAIN函数前面 include"curl/curl.h" 不行的话就用include<curl/curl.h>

Step7：VS2008编代码的左边，在工程DDDDDD就是头文件上方右击属性-》配置属性-》链接器-》命令行有个附加选项那打入libcurld_imp.lib就OK了

如果运行提示缺少libsasl.dll，就下个SVN，在安装目录下的bin目录下找到libsasl.dll，复制到工程目录下即可

静态和动态的libcurl库都有debug和release版本，分别位于cURL源代码lib子文件夹中的DLL-Debug、DLL-Release、LIB-Debug和LIB-Release文件夹
curl的可执行文件也是按照相同的方式生成，分别使用对应的libcurl库。curl可执行文件分别位于cURL源代码src子文件夹中的DLL-Debug、DLL-Release、LIB-Debug和LIB-Release文件夹
代码生成的时候使用的是动态的CRT（C Runtime Library）

基于libcurl库的开发（Windows平台，MSVC2010开发环境）。

libcurl是一个简单易用的基于URL传输的客户端开发库，支持多种平台以及三十多种开发语言绑定。libcurl是线程安全的，兼容IPv6，功能强大且运行效率高。

在10环境中做libcurl开发，需要将静态库文件加到编译链接环境中，并且要dll动态运行库支持。

libcurl提供了一组C语言API函数直接调用。首先需要提到的两个函数就是curl_global_init()和curl_global_cleanup()。libcurl要用到一系列的全局常量，curl_global_init()函数就是初始化这些变量，并分配一些全局资源；curl_global_cleanup()则负责释放这些资源。因此一般情况下，在调用libcurl函数之前，先用curl_global_init(CURL_GLOBAL_ALL)做初始化，在调用完毕后，用curl_global_cleanup()

退出。需要注意的是，这些全局变量和资源并不是线程安全的，因此，在多线程应用的环境中，最好不要多次调用curl_global_init()和curl_global_cleanup()，调用其他函数并不会改变这些全局变量和资源。

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

1、CURL *curl_easy_init()

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

2、CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter)

所有参数和选项设置都是通过这个函数完成的，它告诉libcurl怎样去进行传输。参数handle即为curl_easy_init()返回的句柄，后面根据option的类型，设置相应的parameter值，该函数每次调用只能设置一个选项。具体的option讲解在这两篇博文中有较全面的介绍：
http://blog.163.com/wangsen_315/blog/static/9461414200882384555217/ http://blog.sina.com.cn/s/blog_4f9fc6e10100einf.html
这里只总结一下与下载有关的常用选项设置。

CURLOPT_URL

字符串类型，该选项设置要处理的URL地址，该选项是进行curl_easy_perform之前唯一必须要设置的选项。

CURLOPT_COOKIE

字符串类型，设置http头中的cookie信息。

CURLOPT_COOKIEFILE

字符串类型，同CURLOPT_COOKIE，不过cookie信息从文件中读取。

CURLOPT_FOLLOWLOCATION

布尔值类型，该参数设置为非零值表示follow服务器返回的重定向信息。

CURLOPT_POSTFIELDS

字符串类型，提交http的post操作字符串数据。

CURLOPT_TIMEOUT

long数值类型，设置函数执行的最长时间，时间单位为s。

CURLOPT_CONNECTTIMEOUT

long数值类型，设置连接服务器最长时间，时间单位为s；当置为0时表示无限长。

CURLOPT_MAX_RECV_SPEED_LARGE

curl_off_t类型数据，指定下载过程中最大速度，单位bytes/s。

CURLOPT_HEADERFUNCTION

函数指针类型，该选项设置一个处理接收到的header数据的回调函数，函数原型为：

size_t function( void *ptr, size_t size, size_t nmemb, void *stream)；

其中，ptr指向接收到的header头数据，数据大小为size*nmemb，stream指向调用CURLOPT_WRITEHEADER选项设置的参数。该回调函数应返回实际处理的数据量大小，或者出错返回-1。

CURLOPT_WRITEFUNCTION

函数指针类型，该选项设置一个处理接收到的下载数据的回调函数，函数原型为：

size_t function( void *ptr, size_t size, size_t nmemb, void *stream);

其中，ptr指向接收到的数据，数据大小为size*nmemb，stream指向调用CURLOPT_WRITEDATA选项设置的参数。

如果函数指针置为NULL，则会调用默认的函数，将数据写入到由CURLOPT_WRITEDATA指定的FILE*中。

CURLOPT_HTTPHEADER

curl_slist结构体类型，该选项自定义请求头信息。

CURLOPT_NOPROGRESS

布尔值类型，设置该值为非零值关闭PHP为CRUL传输显示的进度条。

3、void curl_easy_reset(CURL *handle )

重新初始化CURL句柄的选项设置。

4、CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... )

查询CRUL会话的内部信息，具体说明请参考curl自带文档。

5、void curl_easy_cleanup(CURL * handle )

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

The Basic Processes of Using Curl lib.

curl_easy_init()
curl_easy_setopt()
curl_easy_perform()
curl_easy_cleanup()

Upload File by Http Post

curl_global_init(CURL_GLOBAL_WIN32);
CURL*easy_handle = curl_easy_init();
// 使用multi-parts form post
curl_easy_setopt(easy_handle, CURLOPT_URL,http://localhost:8080/uploadServlet);
curl_httppost*post = NULL;
curl_httppost *last =NULL;
// 文本数据
curl_formadd(&post,&last, CURLFORM_COPYNAME, "filePath",CURLFORM_COPYCONTENTS, "tempfile", CURLFORM_END);
// 文本文件中的数据
curl_formadd(&post,&last, CURLFORM_COPYNAME, "file",CURLFORM_FILECONTENT, "ReadMe.txt", CURLFORM_END);
curl_easy_setopt(easy_handle, CURLOPT_HTTPPOST,post);
curl_easy_perform(easy_handle);
curl_formfree(post);
curl_easy_cleanup(easy_handle);
curl_global_cleanup();

Or

CURL *curl;
CURLcode res;
curl = curl_easy_init();
if(curl)
{
curl_formadd(&post, &last,
CURLFORM_COPYNAME, "file",
CURLFORM_FILE, "C:\\rect.jpg",
CURLFORM_END);

curl_formadd(&post, &last,
CURLFORM_COPYNAME, "name",
CURLFORM_COPYCONTENTS, "rect",
CURLFORM_END);

curl_easy_setopt(curl, CURLOPT_URL, "http://blah.com/upload.php");
curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);

res = curl_easy_perform(curl);
if(res)
{
return 0;
}

curl_formfree(post);
}
else
{
return 0;
}

curl_easy_cleanup(curl);

Upload File with Callback：

#include <stdio.h>
#include <string.h>

#include <curl/curl.h>
#include <curl/types.h>
#include <curl/easy.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <errno.h>
#ifdef WIN32
#include <io.h>
#else
#include <unistd.h>
#endif

/*
* This example shows an FTP upload, with a rename of the file just after
* a successful upload.
*
* Example based on source code provided by Erick Nuwendam. Thanks!
*/

#define LOCAL_FILE      "feed.txt"
#define RENAME_FILE_TO  "feed.zip"

/* NOTE: if you want this example to work on Windows with libcurl as a
DLL, you MUST also provide a read callback with CURLOPT_READFUNCTION.
Failing to do so will give you a crash since a DLL may not use the
variable's memory when passed in to it from an app like this. */
static size_t read_callback(void *ptr, size_t size, size_t nmemb, void *stream)
{
/* in real-world cases, this would probably get this data differently
as this fread() stuff is exactly what the library already would do
by default internally */
size_t retcode = fread(ptr, size, nmemb, stream);

printf("*** We read %d bytes from file\n", retcode);
return retcode;
}

int main(void)
{
CURL *curl;
CURLcode res;
FILE *hd_src;
struct stat file_info;
curl_off_t fsize;

char *REMOTE_URL = "http://iss.netii.net/projects/message/";

struct curl_slist *headerlist=NULL;
static const char buf_2 [] = "RNTO " RENAME_FILE_TO;

/* get the file size of the local file */
if(stat(LOCAL_FILE, &file_info)) {
printf("Couldnt open '%s': %s\n", LOCAL_FILE, strerror(errno));
return 1;
}
fsize = (curl_off_t)file_info.st_size;

printf("Local file size: %" CURL_FORMAT_CURL_OFF_T " bytes.\n", fsize);

/* get a FILE * of the same file */
hd_src = fopen(LOCAL_FILE, "rb");

/* In windows, this will init the winsock stuff */
curl_global_init(CURL_GLOBAL_ALL);

/* get a curl handle */
curl = curl_easy_init();
if(curl) {
/* build a list of commands to pass to libcurl */
headerlist = curl_slist_append(headerlist, buf_2);

/* we want to use our own read function */
curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback);

/* enable uploading */
curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L);

/* specify target */
curl_easy_setopt(curl,CURLOPT_URL, REMOTE_URL);

/* pass in that last of FTP commands to run after the transfer */
curl_easy_setopt(curl, CURLOPT_POSTQUOTE, headerlist);

/* now specify which file to upload */
curl_easy_setopt(curl, CURLOPT_READDATA, hd_src);

/* Set the size of the file to upload (optional).  If you give a *_LARGE
option you MUST make sure that the type of the passed-in argument is a
curl_off_t. If you use CURLOPT_INFILESIZE (without _LARGE) you must
make sure that to pass in a type 'long' argument. */
curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE,
(curl_off_t)fsize);

/* Now run off and do what you've been told! */
res = curl_easy_perform(curl);

/* clean up the FTP commands list */
curl_slist_free_all (headerlist);

/* always cleanup */
curl_easy_cleanup(curl);
}
fclose(hd_src); /* close the local file */
getchar();
curl_global_cleanup();
return 0;
}

Download File from Http

#define CURL_STATICLIB
#include <stdio.h>
#include <curl/curl.h>
#include <curl/types.h>
#include <curl/easy.h>
#include <string>

size_t write_data(void *ptr, size_t size, size_t nmemb, FILE *stream) {
size_t written;
written = fwrite(ptr, size, nmemb, stream);
return written;
}

int main(void) {
CURL *curl;
FILE *fp;
CURLcode res;
char *url = "http://localhost/aaa.txt";
char outfilename[FILENAME_MAX] = "C:\\bbb.txt";
curl = curl_easy_init();
if (curl) {
fp = fopen(outfilename,"wb");
curl_easy_setopt(curl, CURLOPT_URL, url);
curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_data);
curl_easy_setopt(curl, CURLOPT_WRITEDATA, fp);
res = curl_easy_perform(curl);
curl_easy_cleanup(curl);
fclose(fp);
}
return 0;
}

How to Using Curl Command Line：

curl的用法为：curl [options] [URL...]

其中options是下载需要的参数，大约有80多个，curl的各个功能完全是依靠这些参数完成的。具体参数的使用，用户可以参考curl的man帮助。

-a/--append 上传文件时，附加到目标文件
-A/--user-agent <string>  设置用户代理发送给服务器
- anyauth   可以使用“任何”身份验证方法
-b/--cookie <name=string/file> cookie字符串或文件读取位置
- basic 使用HTTP基本验证
-B/--use-ascii 使用ASCII /文本传输
-c/--cookie-jar <file> 操作结束后把cookie写入到这个文件中
-C/--continue-at <offset>  断点续转
-d/--data <data>   HTTP POST方式传送数据
--data-ascii <data>  以ascii的方式post数据
--data-binary <data> 以二进制的方式post数据
--negotiate     使用HTTP身份验证
--digest        使用数字身份验证
--disable-eprt  禁止使用EPRT或LPRT
--disable-epsv  禁止使用EPSV
-D/--dump-header <file> 把header信息写入到该文件中
--egd-file <file> 为随机数据(SSL)设置EGD socket路径
--tcp-nodelay   使用TCP_NODELAY选项
-e/--referer 来源网址
-E/--cert <cert[:passwd]> 客户端证书文件和密码 (SSL)
--cert-type <type> 证书文件类型 (DER/PEM/ENG) (SSL)
--key <key>     私钥文件名 (SSL)
--key-type <type> 私钥文件类型 (DER/PEM/ENG) (SSL)
--pass  <pass>  私钥密码 (SSL)
--engine <eng>  加密引擎使用 (SSL). "--engine list" for list
--cacert <file> CA证书 (SSL)
--capath <directory> CA目录 (made using c_rehash) to verify peer against (SSL)
--ciphers <list>  SSL密码
--compressed    要求返回是压缩的形势 (using deflate or gzip)
--connect-timeout <seconds> 设置最大请求时间
--create-dirs   建立本地目录的目录层次结构
--crlf          上传是把LF转变成CRLF
-f/--fail          连接失败时不显示http错误
--ftp-create-dirs 如果远程目录不存在，创建远程目录
--ftp-method [multicwd/nocwd/singlecwd] 控制CWD的使用
--ftp-pasv      使用 PASV/EPSV 代替端口
--ftp-skip-pasv-ip 使用PASV的时候,忽略该IP地址
--ftp-ssl       尝试用 SSL/TLS 来进行ftp数据传输
--ftp-ssl-reqd  要求用 SSL/TLS 来进行ftp数据传输
-F/--form <name=content> 模拟http表单提交数据
-form-string <name=string> 模拟http表单提交数据
-g/--globoff 禁用网址序列和范围使用{}和[]
-G/--get 以get的方式来发送数据
-h/--help 帮助
-H/--header <line>自定义头信息传递给服务器
--ignore-content-length  忽略的HTTP头信息的长度
-i/--include 输出时包括protocol头信息
-I/--head  只显示文档信息
从文件中读取-j/--junk-session-cookies忽略会话Cookie
- 界面<interface>指定网络接口/地址使用
- krb4 <级别>启用与指定的安全级别krb4
-j/--junk-session-cookies 读取文件进忽略session cookie
--interface <interface> 使用指定网络接口/地址
--krb4 <level>  使用指定安全级别的krb4
-k/--insecure 允许不使用证书到SSL站点
-K/--config  指定的配置文件读取
-l/--list-only 列出ftp目录下的文件名称
--limit-rate <rate> 设置传输速度
--local-port<NUM> 强制使用本地端口号
-m/--max-time <seconds> 设置最大传输时间
--max-redirs <num> 设置最大读取的目录数
--max-filesize <bytes> 设置最大下载的文件总量
-M/--manual  显示全手动
-n/--netrc 从netrc文件中读取用户名和密码
--netrc-optional 使用 .netrc 或者 URL来覆盖-n
--ntlm          使用 HTTP NTLM 身份验证
-N/--no-buffer 禁用缓冲输出
-o/--output 把输出写到该文件中
-O/--remote-name 把输出写到该文件中，保留远程文件的文件名
-p/--proxytunnel   使用HTTP代理
--proxy-anyauth 选择任一代理身份验证方法
--proxy-basic   在代理上使用基本身份验证
--proxy-digest  在代理上使用数字身份验证
--proxy-ntlm    在代理上使用ntlm身份验证
-P/--ftp-port <address> 使用端口地址，而不是使用PASV
-Q/--quote <cmd>文件传输前，发送命令到服务器
-r/--range <range>检索来自HTTP/1.1或FTP服务器字节范围
--range-file 读取（SSL）的随机文件
-R/--remote-time   在本地生成文件时，保留远程文件时间
--retry <num>   传输出现问题时，重试的次数
--retry-delay <seconds>  传输出现问题时，设置重试间隔时间
--retry-max-time <seconds> 传输出现问题时，设置最大重试时间
-s/--silent静音模式。不输出任何东西
-S/--show-error   显示错误
--socks4 <host[:port]> 用socks4代理给定主机和端口
--socks5 <host[:port]> 用socks5代理给定主机和端口
--stderr <file>
-t/--telnet-option <OPT=val> Telnet选项设置
--trace <file>  对指定文件进行debug
--trace-ascii <file> Like --跟踪但没有hex输出
--trace-time    跟踪/详细输出时，添加时间戳
-T/--upload-file <file> 上传文件
--url <URL>     Spet URL to work with
-u/--user <user[:password]>设置服务器的用户和密码
-U/--proxy-user <user[:password]>设置代理用户名和密码
-v/--verbose
-V/--version 显示版本信息
-w/--write-out [format]什么输出完成后
-x/--proxy <host[:port]>在给定的端口上使用HTTP代理
-X/--request <command>指定什么命令
-y/--speed-time 放弃限速所要的时间。默认为30
-Y/--speed-limit 停止传输速度的限制，速度时间'秒
-z/--time-cond  传送时间设置
-0/--http1.0  使用HTTP 1.0
-1/--tlsv1  使用TLSv1（SSL）
-2/--sslv2 使用SSLv2的（SSL）
-3/--sslv3         使用的SSLv3（SSL）
--3p-quote      like -Q for the source URL for 3rd party transfer
--3p-url        使用url，进行第三方传送
--3p-user       使用用户名和密码，进行第三方传送
-4/--ipv4   使用IP4
-6/--ipv6   使用IP6
-#/--progress-bar 用进度条显示当前的传送状态

Summary：

curl非常博大，要想用好这个工具，除了详细学习参数之外，还需要深刻理解http的各种协议与URL的各个语法。推荐读物：

RFC 2616 HTTP协议语法的定义。

RFC 2396 URL语法的定义。

RFC 2109 Cookie是怎样工作的。

RFC 1867 HTTP如何POST，以及POST的格式。