libcurl教程

Just4life發表於2013-08-26

原文地址：http://curl.haxx.se/libcurl/c/libcurl-tutorial.html

譯者注：這是一篇介紹如何使用libcurl的入門教程。文件不是逐字逐句按原文翻譯，而是根據筆者對libcurl的理解，參考原文寫成。文中用到的一些例子，可能不是出自原文，而是筆者在學習過程中，寫的一些示例程式（筆者使用的libcurl版本是：7.19.6）。出現在這裡主要是為了更好的說明libcurl的某些api函式的使用。許多例子都參考libcurl提供的example程式碼。原文example中的提供的示例程式完全使用C語言，而這裡筆者提供的例子使用C++語言。因為能力有限，對於libcurl的某些理解和使用可能有誤，歡迎批評指正。

目標

本文件介紹了在應用程式開發過程中，如何正確使用libcurl的基本方式和指導原則。文件使用C語言來呼叫libcurl的介面，當然也適用於其他與C語言接近的語言。

文件主要針對使用libcurl來進行開發的人員。文件所摜的應用程式泛指你寫的原始碼，這些程式碼使用了libcurl進行資料傳輸。

更多關於libcurl的功能和介面資訊，可以在相關的主頁上查閱。

編譯原始碼

有很多種不同的方式來編譯C語言程式碼。這裡使用UNIX平臺下的編譯方式。即使你使用的是其他的作業系統，你仍然可以通過閱讀本文件來獲取許多有用的資訊。

編譯

你的編譯器必須知道libcurl標頭檔案的位置。所以在編譯的時候，你要設定標頭檔案的包含路徑。可以使用curl-config工具來獲取這方面的資訊：

$ curl-config –cflags

連結

編譯完原始碼（這時的原始碼不是指libcurl的原始碼，你是你自己寫的程式程式碼）之後，你還必須把目標檔案連結成單個可執行檔案。你要連結libcurl庫，以及libcurl所依賴的其他庫，例如OpenSLL庫。當然可能還需要一些其他的作業系統庫。最後你還要設定一些編譯選項，當然可以使用curl-config工具簡化操作：

$curl-config –libs

是否使用SSL

定製編譯libcurl。與其他庫不同的是，libcurl可以定製編譯，根據實際需要是否支援某些特性，如是否支援SSL傳輸，像HTTPS和FTPS。如果決定需要支援SSL，必須在編譯時正確的設定。可以使用’curl-config’來判斷libcurl庫是否支援SSL：

$ curl-config –feature

autoconf巨集

當你編寫配置指令碼來檢測libcurl及其相應設定時，你可以使用預定義巨集。文件docs/libcurl/libcurl.m4告訴你如何使用這些巨集。

跨平臺的可移植的程式碼

libcurl的開發人員花費很大的努力，使libcurl儘可能在大多數平臺上正常執行。

全域性初始化

應用程式在使用libcurl之前，必須先初始化libcurl。libcurl只需初始化一次。可以使用以下語句進行初始化：

curl_global_init();

curl_global_init()接收一個引數，告訴libcurl如何初始化。引數CURL_GLOBAL_ALL 會使libcurl初始化所有的子模組和一些預設的選項，通常這是一個比較好的預設引數值。還有兩個可選值：

CURL_GLOBAL_WIN32

只能應用於Windows平臺。它告訴libcurl初始化winsock庫。如果winsock庫沒有正確地初始化，應用程式就不能使用socket。在應用程式中，只要初始化一次即可。

CURL_GLOBAL_SSL

如果libcurl在編譯時被設定支援SSL，那麼該引數用於初始化相應的SSL庫。同樣，在應用程式中，只要初始化一次即可。

libcurl有預設的保護機制，如果在呼叫curl_easy_perform時它檢測到還沒有通過curl_global_init進行初始化，libcurl會根據當前的執行時環境，自動呼叫全域性初始化函式。但必須清楚的是，讓系統自已初始化不是一個好的選擇。

當應用程式不再使用libcurl的時候，應該呼叫curl_global_cleanup來釋放相關的資源。

在程式中，應當避免多次呼叫curl_global_init和curl_global_cleanup。它們只能被呼叫一次。

libcurl提供的功能

在執行時根據libcurl支援的特性來進行開發，通常比編譯時更好。可以通過呼叫curl_version_info函式返回的結構體來獲取執行時的具體資訊，從而確定當前環境下libcurl支援的一些特性。下面是筆者在visual studio2008中呼叫相關函式獲取libcurl版本資訊的截圖：

使用easy interface

首先介紹libcurl中被稱為easy interface的api函式，所有這些函式都是有相同的字首：curl_easy 。

當前版本的libcurl也提供了multi interface，關於這些介面的詳細使用，在下面的章節中會有介紹。在使用multi interface之前，你首先應該理解如何使用easy interface。

要使用easy interface，首先必須建立一個easy handle，easy handle用於執行每次操作。基本上，每個執行緒都應該有自己的easy handle用於資料通訊（如果需要的話）。千萬不要在多執行緒之間共享同一個easy handle。下面的函式用於獲取一個easy handle ：

CURL *easy_handle = curl_easy_init();

在easy handle上可以設定屬性和操作(action)。easy handle就像一個邏輯連線，用於接下來要進行的資料傳輸。

使用curl_easy_setopt函式可以設定easy handle的屬性和操作，這些屬性和操作控制libcurl如何與遠端主機進行資料通訊。一旦在easy handle中設定了相應的屬性和操作，它們將一直作用該easy handle。也就是說，重複使用easy hanle向遠端主機發出請求，先前設定的屬性仍然生效。

easy handle的許多屬性使用字串(以/0結尾的位元組陣列)來設定。通過curl_easy_setopt函式設定字串屬性時，libcurl內部會自動拷貝這些字串，所以在設定完相關屬性之後，字串可以直接被釋放掉（如果需要的話）。

easy handle最基本、最常用的屬性是URL。你應當通過CURLOPT_URL屬性提供適當的URL：

curl_easy_setopt(easy_handle, CURLOPT_URL, "http://blog.csdn.net/JGood ");

假設你要獲取URL所表示的遠端主機上的資源。你需要寫一段程式用來完成資料傳輸，你可能希望直接儲存接收到的資料而不是簡單的在輸出視窗中列印它們。所以，你必須首先寫一個回撥函式用來儲存接收到的資料。回撥函式的原型如下：

size_t write_data(void *buffer, size_t size, size_t nmemb, void *userp);

可以使用下面的語句來註冊回撥函式，回撥函式將會在接收到資料的時候被呼叫：

curl_easy_setopt(easy_handle, CURLOPT_WRITEFUNCTION, write_data);

可以給回撥函式提供一個自定義引數，libcurl不處理該引數，只是簡單的傳遞：

curl_easy_setopt(easy_handle, CURLOPT_WRITEDATA, &internal_struct);

如果你沒有通過CURLOPT_WRITEFUNCTION屬性給easy handle設定回撥函式，libcurl會提供一個預設的回撥函式，它只是簡單的將接收到的資料列印到標準輸出。你也可以通過CURLOPT_WRITEDATA屬性給預設回撥函式傳遞一個已經開啟的檔案指標，用於將資料輸出到檔案裡。

下面是一些平臺相關的注意點。在一些平臺上，libcurl不能直接操作由應用程式開啟的檔案。所以，如果使用預設的回撥函式，同時通過CURLOPT_WRITEDATA屬性給easy handle傳遞一個檔案指標，應用程式可能會執行失敗。如果你希望自己的程式能跑在任何系統上，你必須避免出現這種情況。

如果以win32動態連線庫的形式來使用libcurl，在設定CURLOPT_WRITEDATA屬性時，你必須同時使用CURLOPT_WRITEFUNCTION來註冊回撥函式。否則程式會執行失敗（筆者嘗試只傳遞一個開啟的檔案指標而不顯式設定回撥函式，程式並沒有崩潰。可能是我使用的方式不正確。）。

當然，libcurl還支援許多其他的屬性，在接下來的篇幅裡，你將會逐步地接觸到它們。呼叫下面的函式，將執行真正的資料通訊：

success = curl_easy_perform(easy_handle);

curl_easy_perfrom將連線到遠端主機，執行必要的命令，並接收資料。當接收到資料時，先前設定的回撥函式將被呼叫。libcurl可能一次只接收到1位元組的資料，也可能接收到好幾K的資料，libcurl會盡可能多、及時的將資料傳遞給回撥函式。回撥函式返回接收的資料長度。如果回撥函式返回的資料長度與傳遞給它的長度不一致（即返回長度 != size * nmemb），libcurl將會終止操作，並返回一個錯誤程式碼。

當資料傳遞結束的時候，curl_easy_perform將返回一個程式碼表示操作成功或失敗。如果需要獲取更多有關通訊細節的資訊，你可以設定CURLOPT_ERRORBUFFER屬性，讓libcurl快取許多可讀的錯誤資訊。

easy handle在完成一次資料通訊之後可以被重用。這裡非常建議你重用一個已經存在的easy handle。如果在完成資料傳輸之後，你建立另一個easy handle來執行其他的資料通訊，libcurl在內部會嘗試著重用上一次建立的連線。

對於有些協議，下載檔案可能包括許多複雜的子過程：日誌記錄、設定傳輸模式、選擇當前資料夾，最後下載檔案資料。使用libcurl，你不需要關心這一切，你只需簡單地提供一個URL，libcurl會給你做剩餘所有的工作。

下面的這個例子演示瞭如何獲取網頁原始碼，將其儲存到本地檔案，並同時將獲取的原始碼輸出到控制檯上。

/**
 *	@brief libcurl接收到資料時的回撥函式
 *
 *	將接收到的資料儲存到本地檔案中，同時顯示在控制檯上。
 *
 *	@param [in] buffer 接收到的資料所在緩衝區
 *	@param [in] size 資料長度
 *	@param [in] nmemb 資料片數量
 *	@param [in/out] 使用者自定義指標
 *	@return 獲取的資料長度
 */

size_t process_data(void *buffer, size_t size, size_t nmemb, void *user_p)
{
	FILE *fp = (FILE *)user_p;
	size_t return_size = fwrite(buffer, size, nmemb, fp);
	cout << (char *)buffer << endl;

	return return_size;
}



int main(int argc, char **argv)
{
	// 初始化libcurl
	CURLcode return_code;
	return_code = curl_global_init(CURL_GLOBAL_WIN32);
	if (CURLE_OK != return_code)
	{
		cerr << "init libcurl failed." << endl;
		return -1;
	}


	// 獲取easy handle
	CURL *easy_handle = curl_easy_init();
	if (NULL == easy_handle)
	{
		cerr << "get a easy handle failed." << endl;
                  curl_global_cleanup();

		return -1;
	}

	FILE *fp = fopen("data.html", "ab+");	// 
	// 設定easy handle屬性
	curl_easy_setopt(easy_handle, CURLOPT_URL, http://blog.csdn.net/JGood);
	curl_easy_setopt(easy_handle, CURLOPT_WRITEFUNCTION, &process_data);
	curl_easy_setopt(easy_handle, CURLOPT_WRITEDATA, fp);


	// 執行資料請求
	curl_easy_perform(easy_handle);	

	// 釋放資源

	fclose(fp);
	curl_easy_cleanup(easy_handle);
	curl_global_cleanup();


	return 0;
}

多執行緒問題

首先一個基本原則就是：絕對不應該線上程之間共享同一個libcurl handle，不管是easy handle還是multi handle（將在下文中介紹）。一個執行緒每次只能使用一個handle。

libcurl是執行緒安全的，但有兩點例外：訊號(signals)和SSL/TLS handler。訊號用於超時失效名字解析(timing out name resolves)。libcurl依賴其他的庫來支援SSL/STL，所以用多執行緒的方式訪問HTTPS或FTPS的URL時，應該滿足這些庫對多執行緒操作的一些要求。詳細可以參考：

OpenSSL: http://www.openssl.org/docs/crypto/threads.html#DESCRIPTION

GnuTLS: http://www.gnu.org/software/gnutls/manual/html_node/Multi_002dthreaded-applications.html

NSS: 宣稱是多執行緒安全的。

什麼時候libcurl無法正常工作

傳輸失敗總是有原因的。你可能錯誤的設定了一些libcurl的屬性或者沒有正確的理解某些屬性的含義，或者是遠端主機返回一些無法被正確解析的內容。

這裡有一個黃金法則來處理這些問題：將CURLOPT_VERBOSE屬性設定為1，libcurl會輸出通訊過程中的一些細節。如果使用的是http協議，請求頭/響應頭也會被輸出。將CURLOPT_HEADER設為1，這些頭資訊將出現在訊息的內容中。

當然不可否認的是，libcurl還存在bug。當你在使用libcurl的過程中發現bug時，希望能夠提交給我們，好讓我們能夠修復這些bug。你在提交bug時，請同時提供詳細的資訊：通過CURLOPT_VERBOSE屬性跟蹤到的協議資訊、libcurl版本、libcurl的客戶程式碼、作業系統名稱、版本、編譯器名稱、版本等等。

如果你對相關的協議瞭解越多，在使用libcurl時，就越不容易犯錯。

上傳資料到遠端站點

libcurl提供協議無關的方式進行資料傳輸。所以上傳一個檔案到FTP伺服器，跟向HTTP伺服器提交一個PUT請求的操作方式是類似的：

1. 建立easy handle或者重用先前建立的easy handle。

2. 設定CURLOPT_URL屬性。

3. 編寫回撥函式。在執行上傳的時候，libcurl通過回撥函式讀取要上傳的資料。（如果要從遠端伺服器下載資料，可以通過回撥來儲存接收到的資料。）回撥函式的原型如下：

size_t function(char *bufptr, size_t size, size_t nitems, void *userp);

bufptr指標表示緩衝區，用於儲存要上傳的資料，size * nitems是緩衝區資料的長度，userp是一個使用者自定義指標，libcurl不對該指標作任何操作，它只是簡單的傳遞該指標。可以使用該指標在應用程式與libcurl之間傳遞資訊。

4. 註冊回撥函式，設定自定義指標。語法如下：

// 註冊回撥函式
curl_easy_setopt(easy_handle, CURLOPT_READFUNCTION, read_function); 
// 設定自定義指標
curl_easy_setopt(easy_handle, CURLOPT_READDATA, &filedata);

5. 告訴libcurl，執行的是上傳操作。

curl_easy_setopt(easy_handle, CURLOPT_UPLOAD, 1L);

有些協議在沒有預先知道上傳檔案大小的情況下，可能無法正確判斷上傳是否結束，所以最好預先使用CURLOPT_INFILESIZE_LARGE屬性：告訴它要上傳檔案的大小：

/* in this example, file_size must be an curl_off_t variable */
curl_easy_setopt(easy_handle, CURLOPT_INFILESIZE_LARGE, file_size);

6. 呼叫curl_easy_perform。

接下來，libcurl將會完成剩下的所有工作。在上傳檔案過程中，libcurl會不斷呼叫先前設定的回撥函式，用於將要上傳的資料讀入到緩衝區，並執行上傳。

下面的例子演示如何將檔案上傳到FTP伺服器。筆者使用的是IIS自帶的FTP服務，同時在FTP上設定了可寫許可權。

/**
 *	@brief 讀取資料的回撥。
 */
size_t read_data(void *buffer, size_t size, size_t nmemb, void *user_p)
{
	return fread(buffer, size, nmemb, (FILE *)user_p);
}


int main(int argc, char **argv)
{
	// 初始化libcurl
	CURLcode code;
	code = curl_global_init(CURL_GLOBAL_WIN32);
	if (code != CURLE_OK)
	{
		cerr << "init libcurl failed." << endl;
		return -1;
	}


	FILE *fp = fopen("a.html", "rb");
	if (NULL == fp)
	{
		cout << "can't open file." << endl;
		curl_global_cleanup();
		return -1;
	}


	// 獲取檔案大小
	fseek(fp, 0, 2);
	int file_size = ftell(fp);
	rewind(fp);


	// 獲取easy handle

	CURL *easy_handle = NULL;
	easy_handle = curl_easy_init();
	if (NULL == easy_handle)
	{
		cerr << "get a easy handle failed." << endl;
		fclose(fp);
		curl_global_cleanup();
		return -1;
	}


	// 設定eash handle屬性
	curl_easy_setopt(easy_handle, CURLOPT_URL, ftp://127.0.0.1/upload.html);
	curl_easy_setopt(easy_handle, CURLOPT_UPLOAD, 1L);
	curl_easy_setopt(easy_handle, CURLOPT_READFUNCTION, &read_data);
	curl_easy_setopt(easy_handle, CURLOPT_READDATA, fp);
	curl_easy_setopt(easy_handle, CURLOPT_INFILESIZE_LARGE, file_size);


	// 執行上傳操作
	code = curl_easy_perform(easy_handle);
	if (code == CURLE_OK)
	{
		cout << "upload successfully." << endl;
	}


	// 釋放資源
	fclose(fp);
	curl_easy_cleanup(easy_handle);
	curl_global_cleanup();


	return 0;
}

關於密碼

客戶端向伺服器傳送請求時，許多協議都要求提供使用者名稱與密碼。libcurl提供了多種方式來設定它們。

一些協議支援在URL中直接指定使用者名稱和密碼，類似於： protocol://user:password@example.com/path/。libcurl能正確的識別這種URL中的使用者名稱與密碼並執行相應的操作。如果你提供的使用者名稱和密碼中有特殊字元，首先應該對其進行URL編碼。

也可以通過CURLOPT_USERPWD屬性來設定使用者名稱與密碼。引數是格式如 “user:password ”的字串：

curl_easy_setopt(easy_handle, CURLOPT_USERPWD, "user_name:password");

（下面這幾段文字我理解地模模糊糊）有時候在訪問代理伺服器的時候，可能時時要求提供使用者名稱和密碼進行使用者身份驗證。這種情況下，libcurl提供了另一個屬性CURLOPT_PROXYUSERPWD：

curl_easy_setopt(easy_handle, CURLOPT_PROXYUSERPWD, "user_name:password");

在UNIX平臺下，訪問FTP的使用者名稱和密碼可能會被儲存在$HOME/.netrc檔案中。libcurl支援直接從這個檔案中獲取使用者名稱與密碼：

curl_easy_setopt(easy_handle, CURLOPT_NETRC, 1L);

在使用SSL時，可能需要提供一個私鑰用於資料安全傳輸，通過CURLOPT_KEYPASSWD來設定私鑰：

curl_easy_setopt(easy_handle, CURLOPT_KEYPASSWD, "keypassword");

HTTP驗證

上一章介紹瞭如何在libcurl中，對需要身份驗證的URL設定使用者名稱與密碼。在使用HTTP協議時，客戶端有很多種方式向伺服器提供驗證資訊。預設的HTTP驗證方法是"Basic”，它將使用者名稱與密碼以明文的方式、經Base64編碼後儲存在HTTP請求頭中，發往伺服器。當然這不太安全。

當前版本的libcurl支援的驗證方法有：basic, Digest, NTLM, Negotiate, GSS-Negotiate and SPNEGO。（譯者感嘆：搞Web這麼多年，盡然不知道這些Http的驗證方式，實在慚愧。）可以通過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);

HTTP Post

這一章介紹如何使用libcurl以Post方式向HTTP伺服器提交資料。

方法一，也是最簡單的方式，就像html中使用<form>標籤提交資料一樣，只需向libcurl提供一個包含資料的字串即可。下面是筆者學習過程中的一個demo程式：

int main(int argc, char **argv)
{
	code = curl_global_init(CURL_GLOBAL_WIN32);
	CURL *easy_handle = curl_easy_init();


	curl_easy_setopt(easy_handle, CURLOPT_URL, http://localhost:2210/Default.aspx);
	// 單個域post
	curl_easy_setopt(easy_handle, CURLOPT_POSTFIELDS, "name=jgood&address=hangzhou");
	code = curl_easy_perform(easy_handle);

	curl_easy_cleanup(easy_handle);
	curl_global_cleanup();


	return 0;
}

在asp.net Web伺服器上跟蹤除錯，得到客戶程式提交上來的資料，下面是截圖：

上面的程式碼夠簡單吧~_~ 有時候，我們需要提交一些二進位制資料到HTTP伺服器，使用方法一就不行了，因為方法一中實際提交的是一個字串，字串遇到/0就表示結束了。所以在上傳二進位制資料的時候，必須明確的告訴libcurl要提交的資料的長度。在上傳二進位制資料的時候，還應該設定提交的Content-Type頭資訊。下面的示例程式碼：

int main(int argc, char **argv)
{
	curl_global_init(CURL_GLOBAL_WIN32);
	CURL *easy_handle = curl_easy_init();


	// 上傳二進位制資料
	char data[] = { 1, 0, 1, 0, 1, 1, 1, 1, 0, 1, 1, 1, 0 };
	curl_slist *http_headers = NULL;
	http_headers = curl_slist_append(http_headers, "Content-Type: text/xml");

	curl_easy_setopt(easy_handle, CURLOPT_HTTPHEADER, http_headers);
	curl_easy_setopt(easy_handle, CURLOPT_URL, http://localhost:2210/Default.aspx);
	curl_easy_setopt(easy_handle, CURLOPT_POSTFIELDS, data);
	curl_easy_setopt(easy_handle, CURLOPT_POSTFIELDSIZE, sizeof(data));


	curl_easy_perform(easy_handle);


	curl_slist_free_all(http_headers);
	curl_easy_cleanup(easy_handle);
	curl_global_cleanup();


	return 0;
}

在asp.net Web伺服器上跟蹤除錯，得到客戶程式提交上來的二進位制資料，下面是截圖：

上面介紹的兩種方式，可以完成大部分的HTTP POST操作。但上面的兩種方式都不支援multi-part formposts。Multi-part formposts被認為是提交二進位制資料(或大量資料)的更好方法，可以在RFC1867, RFC2388中找到他們的定義。何為Multi-part？其實，就我理解，就是在Post提交的時候，有不同的資料單元，每個單元有自己的名稱與內容，內容可以是文字的，也可以是二進位制的。同時，每個資料單元都可以有自己的訊息頭，MIME型別，這些資料單元組成一個連結串列，提交到HTTP伺服器。libcurl提供了方便的api用於支援multi-part formposts。使用curl_formadd函式，可以新增不同的資料資料單元，然後提交到伺服器。下面是一個multi-part formposts的例子（更詳細的使用，請參考：http://curl.haxx.se/libcurl/c/curl_formadd.html ）：

int main()
{

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:2210/Default.aspx);
	curl_httppost *post = NULL;
	curl_httppost *last = NULL;	

	// 文字資料
	curl_formadd(&post, &last, CURLFORM_COPYNAME, "name", CURLFORM_COPYCONTENTS, "JGood", CURLFORM_END);
	curl_formadd(&post, &last, CURLFORM_COPYNAME, "address", CURLFORM_COPYCONTENTS, "HangZhou", 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();


	return 0;
}

最後要說明的是，所有在easy handle上設定的屬性都是”sticky”的，什麼意思？就是說在easy handle上設定的屬性都將被儲存，即使執行完curl_easy_perform之後，這些屬性值仍然存在。通過將CURLOPT_HTTPGET設為1可以使easy handle回到最原始的狀態：

curl_easy_setopt(easy_handle, CURLOPT_HTTPGET, 1L);

顯示進度

libcurl支援通訊過程中的進度控制。通過將CURLOPT_NOPROCESS設定為0開啟進度支援。該選項預設值為1。對大多數應用程式，我們需要提供一個進度顯示回撥。libcurl會不定期的將當前傳輸的進度通過回撥函式告訴你的程式。回撥函式的原型如下：

int progress_callback(void *clientp, double dltotal, double dlnow, double ultotal, double ulnow);

通過CURLOPT_PROGRESSFUNCTION註冊該回撥函式。引數clientp是一個使用者自定義指標，應用程式通過CURLOPT_PROCESSDATA屬性將該自定義指定傳遞給libcurl。libcurl對該引數不作任何處理，只是簡單將其傳遞給回撥函式。

在C++中使用libcurl

在C++中使用libcurl跟在C語言中沒有任何區別，只有一個地方要注意：回撥函式不能是類的非靜態成員函式。例如：

class AClass { 
     static size_t write_data(void *ptr, size_t size, size_t nmemb, void *ourpointer) 
     { 
       /* do what you want with the data */
     } 
}

代理

什麼是代理？Merrian-Webster的解釋是：一個通過驗證的使用者扮演另一個使用者。今天，代理已經被廣泛的使用。許多公司提供網路代理伺服器，允許員工的網路客戶端訪問、下載檔案。代理伺服器處理這些使用者的請求。

libcurl支援SOCKS和HTTP代理。使用代理，libcurl會把使用者輸入的URL提交給代理伺服器，而不是直接根據URL去訪問遠端資源。

當前版本的libcurl並不支援SOCKS代理的所有功能。

對於HTTP代理來說，即使請求的URL不是一個合法的HTTP URL（比方你提供了一個ftp的url），它仍然會先被提交到HTTP代理。

代理選項

CURLOPT_PROXY屬性用於設定libcurl使用的代理伺服器地址：

curl_easy_setopt(easy_handle, CURLOPT_PROXY, "proxy-host.com:8080");

可以把主機名與埠號分開設定：

curl_easy_setopt(easy_handle, CURLOPT_PROXY, "proxy-host.com"); 
curl_easy_setopt(easy_handle, CURLOPT_PROXYPORT, "8080");  // 埠號是用字串還是整數？？

有些代理伺服器要求使用者通過驗證之後才允許接受其請求，此時應該先提供驗證資訊：

curl_easy_setopt(easy_handle, CURLOPT_PROXYUSERPWD, "user:password");

還要告訴libcurl使用的代理型別（如果沒有提供，libcurl會認為是HTTP代理）：

curl_easy_setopt(easy_handle, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS4);

環境變數

對於有些協議，libcurl會自動檢測並使用一些環境變數，並根據這些環境變數來確定要使用的代理伺服器。這些環境變數的名稱格式一般是"[protocol]_proxy"（注意小寫）。例如輸入一個HTTP的URL，那麼名稱為"http_proxy"的環境變數就會被檢測是否存在，如果存在，libcurl會使用該環境變數指定的代理。相同的規則也適用於FTP。

這些環境變數的值的格式必須是這樣的："[protocol://][user:password@]machine[:port]"。libcurl會忽略掉[protocol://]，如果沒有提供埠號，libcurl使用該協議的預設埠。

有兩個比較特殊的環境變數：'all_proxy'與'no_proxy'。如果一個URL所對應的協議，它的環境變數沒有設定，那麼'all_proxy'指定的代理將被使用。'no_proxy'則指定了一個不應被使用的代理主機的列表。例如：no_proxy的值是'192.168.1.10'，即使存在http_proxy，它的值也是'192.168.1.10'，'192.168.1.10'也不會被作為代理。no_proxy=”*”表示不允許使用任何代理。

顯式地將CURLOPT_PROXY屬性設定為空，可以禁止libcurl檢查並使用環境變數來使用代理。

SSL和代理

SSL為點到點通訊提供安全保障。它包含一些強壯的加密措施和其他安全檢測，這使得上面講到的代理方式不適用於SSL。除非代理伺服器提供專用通道，對進出該代理伺服器的資料不作任何檢測或禁止。通過HTTP代理伺服器開啟SSL連線，意味著代理伺服器要直接連線到目標主機的指定埠。因為代理伺服器對在專用通道上傳輸的資料的型別毫無所知，所以它往往會使某些機制失效，如快取機制。許多組織只允許在443埠上建立這種型別的資料通道。

代理通道(Tunneling Through Proxy)

正如上面講到的，要使SSL工作必須在代理伺服器建立專用資料通道，通常專用通道只被限制應用於HTTPS。通過HTTP代理在應用程式與目標之間建立一個專用資料通道，應該預防在該專有通道上執行非HTTP的操作，如進行FTP上傳或執行FTP命令。代理伺服器管理員應該禁止非法的操作。

通過CURLOPT_HTTPPROXYTUNNEL屬性來告訴libcurl使用代理通道：

curl_easy_setopt(easy_handle, CURLOPT_HTTPPROXYTUNNEL, 1L);

有時候你想通過代理通道執行平常的HTTP操作，而實際上卻可能使你不經過代理伺服器而直接與遠端主機進行互動。libcurl不會代替這種新引入的行為。

自動配置代理

許多瀏覽器支援自動配置代理，例如NetScape。libcurl並不支援這些。

持久化的好處(Persistence Is The Way to Happiness)

當需要傳送多次請求時，應該重複使用easy handle。

每次執行完curl_easy_perform，licurl會繼續保持與伺服器的連線。接下來的請求可以使用這個連線而不必建立新的連線（如果目標主機是同一個的話）。這樣可以減少網路開銷。
即使連線被釋放了，libcurl也會快取這些連線的會話資訊，這樣下次再連線到目標主機上時，就可以使用這些資訊，從而減少重新連線所需的時間。

FTP連線可能會被儲存較長的時間。因為客戶端要與FTP伺服器進行頻繁的命令互動。對於有訪問人數上限的FTP伺服器，保持一個長連線，可以使你不需要排除等待，就直接可以與FTP伺服器通訊。

libcurl會快取DNS的解析結果。

在今後的libcurl版本中，還會新增一些特性來提高資料通訊的效率。
每個easy handle都會儲存最近使用的幾個連線，以備重用。預設是5個。可以通過CURLOPT_MAXCONNECTS屬性來設定儲存連線的數量。

如果你不想重用連線，將CURLOPT_FRESH_CONNECT屬性設定為1。這樣每次提交請求時，libcurl都會先關閉以前建立的連線，然後重新建立一個新的連線。也可以將CURLOPT_FORBID_REUSE設定為1，這樣每次執行完請求，連線就會馬上關閉。

libcurl使用的HTTP訊息頭

當使用libcurl傳送http請求時，它會自動新增一些http頭。我們可以通過CURLOPT_HTTPHEADER屬性手動替換、新增或刪除相應的HTTP訊息頭。

Host

http1.1（大部分http1.0)版本都要求客戶端請求提供這個資訊頭。

Pragma

"no-cache"。表示不要緩衝資料。

Accept

"*/*"。表示允許接收任何型別的資料。

Expect

以POST的方式向HTTP伺服器提交請求時，libcurl會設定該訊息頭為"100-continue"，它要求伺服器在正式處理該請求之前，返回一個"OK"訊息。如果POST的資料很小，libcurl可能不會設定該訊息頭。

自定義選項

當前越來越多的協議都構建在HTTP協議之上（如：soap），這主要歸功於HTTP的可靠性，以及被廣泛使用的代理支援（可以穿透大部分防火牆）。這些協議的使用方式與傳統HTTP可能有很大的不同。對此，libcurl作了很好的支援。

自定義請求方式(CustomRequest)

HTTP支援GET, HEAD或者POST提交請求。可以設定CURLOPT_CUSTOMREQUEST來設定自定義的請求方式，libcurl預設以GET方式提交請求：

curl_easy_setopt(easy_handle, CURLOPT_CUSTOMREQUEST, "MYOWNREQUEST");

修改訊息頭

HTTP協議提供了訊息頭，請求訊息頭用於告訴伺服器如何處理請求；響應訊息頭則告訴瀏覽器如何處理接收到的資料。在libcurl中，你可以自由的新增這些訊息頭：

struct curl_slist *headers=NULL; /* init to NULL is important */
headers = curl_slist_append(headers, "Hey-server-hey: how are you?");
headers = curl_slist_append(headers, "X-silly-content: yes");
/* pass our list of custom made headers */
curl_easy_setopt(easyhandle, CURLOPT_HTTPHEADER, headers);
curl_easy_perform(easyhandle); /* transfer http */
curl_slist_free_all(headers); /* free the header list */

對於已經存在的訊息頭，可以重新設定它的值：

headers = curl_slist_append(headers, "Accept: Agent-007");  
headers = curl_slist_append(headers, "Host: munged.host.line");

刪除訊息頭

對於一個已經存在的訊息頭，設定它的內容為空，libcurl在傳送請求時就不會同時提交該訊息頭：

headers = curl_slist_append(headers, "Accept:");

強制分塊傳輸(Enforcing chunked transfer-encoding)

（這段文字理解可能有誤碼）以非GET的方式提交HTTP請求時，如果設定了自定義的訊息頭”Transfer-Encoding:chunked”，libcurl會分塊提交資料，即使要上傳的資料量已經知道。在上傳資料大小未知的情況下，libcurl自動採用分塊上傳資料。（譯者注：非GET方式提交請求，提交的資料量往往比較大。）

HTTP版本

每一次http請求，都包含一個表示當前使用http版本的訊息頭。libcurl預設使用HTTP 1.1。可以通過CURLOPT_HTTP_VERSION屬性來設定具體的版本號：

curl_easy_setopt(easy_handle, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0);

FTP自定義命令

並不是所以的協議都像HTTP那樣，通過訊息頭來告訴伺服器如何處理請求。對於FTP，你就要使用另外的方式來處理。

傳送自定義的命令到ftp伺服器，意味著你傳送的命令必須是能被ftp伺服器理解的命令（FTP協議中定義的命令，參考rfc959）。

下面是一個簡單的例子，在檔案傳輸操作操作之前刪除指定檔案：

headers = curl_slist_append(headers, "DELE file-to-remove");
/* pass the list of custom commands to the handle */

curl_easy_setopt(easyhandle, CURLOPT_QUOTE, headers);
// curl_easy_setopt(easyhandle, CURLOPT_POSTQUOTE, headers); // 在資料傳輸之後操行刪除操作

curl_easy_perform(easyhandle); /* transfer ftp data! */
curl_slist_free_all(headers); /* free the header list */

FTP伺服器執行命令的順序，同這些命令被新增到列表中順序是一致的。發往伺服器的命令列表中，只要有一個命令執行失敗，ftp伺服器就會返回一個錯誤程式碼，此時libcurl將直接返回CURLE_QUOTE_ERROR，不再執行剩餘的FTP命令。

將CURLOPT_HEADER設定為1，libcurl獲取目標檔案的資訊，並以HTTP訊息頭的樣式來輸出訊息頭。

FTP自定義CUSTOMREQUEST

使用CURLOPT_CUSTOMREQUEST屬性，可以向FTP伺服器傳送命令。"NLST"是ftp預設的列出檔案列表的命令。下面的程式碼用於列出FTP伺服器上的檔案列表：

int main(int argc, char **argv)
{
	curl_global_init(CURL_GLOBAL_WIN32);
	CURL *easy_handle = curl_easy_init();
	curl_easy_setopt(easy_handle, CURLOPT_URL, "ftp://127.0.0.1/");
	curl_easy_setopt(easy_handle, CURLOPT_CUSTOMREQUEST, "NLST");

	curl_easy_perform(easy_handle);

	curl_easy_cleanup(easy_handle);
	curl_global_cleanup();


	return 0;
}

Cookies Without Chocolate Chips

cookie是一個鍵值對的集合，HTTP伺服器發給客戶端的cookie，客戶端提交請求的時候，也會將cookie傳送到伺服器。伺服器可以根據cookie來跟蹤使用者的會話資訊。cookie有過期時間，超時後cookie就會失效。cookie有域名和路徑限制，cookie只能發給指定域名和路徑的HTTP伺服器。

cookie以訊息頭”Set-Cookie”的形式從HTTP伺服器傳送到客戶端；客戶端發以訊息頭”Cookie”的形式將Cookie提交到HTTP伺服器。為了對這些東西有個直觀的概念，下圖是FireFox中，使用Firebug跟蹤到的cookie訊息頭：

在libcurl中，可以通過CURLOPT_COOKIE屬性來設定發往伺服器的cookie：

curl_easy_setopt(easy_handle, CURLOPT_COOKIE, "name1=var1; name2=var2;");

下面的例子演示瞭如何使用libcurl傳送cookie資訊給HTTP伺服器，程式碼非常的簡單：

int main(int argc, char **argv)
{
	curl_global_init(CURL_GLOBAL_WIN32);
	CURL *easy_handle = curl_easy_init();


	curl_easy_setopt(easy_handle, CURLOPT_URL, http://localhost:2210/Default.aspx);
	curl_easy_setopt(easy_handle, CURLOPT_COOKIE, "name=JGood; address=HangZhou");


	curl_easy_perform(easy_handle);


	curl_easy_cleanup(easy_handle);
	curl_global_cleanup();


	return 0;
}

下圖是在ASP.NET Web伺服器上除錯時跟蹤到的Cookie資料：

     在實在的應用場景中，你可能需要儲存伺服器傳送給你的cookie，並在接下來的請求中，把這些cookie一併發往伺服器。所以，可以把上次從伺服器收到的所有響應頭資訊儲存到文字檔案中，當下次需要向伺服器傳送請求時，通過CURLOPT_COOKIEFILE屬性告訴libcurl從該檔案中讀取cookie資訊。
    設定CURLOPT_COOKIEFILE屬性意味著啟用libcurl的cookie parser。在cookie parser被啟用之前，libcurl忽略所以之前接收到的cookie資訊。cookie parser被啟用之後，cookie資訊將被儲存記憶體中，在接下來的請求中，libcurl會自動將這些cookie資訊新增到訊息頭裡，你的應用程式不需要做任何事件。大多數情況下，這已經足夠了。需要注意的是，通過CURLOPT_COOKIEFILE屬性來啟用cookie parser，給CURLOPT_COOKIEFILE屬性設定的一個儲存cookie資訊的文字檔案路徑，可能並不需要在磁碟上物理存在。
    如果你需要使用NetScape或者FireFox瀏覽器的cookie檔案，你只要用這些瀏覽器的cookie檔案的路徑來初始化CURLOPT_COOKIEFILE屬性，libcurl會自動分析cookie檔案，並在接下來的請求過程中使用這些cookie資訊。
    libcurl甚至能夠把接收到的cookie資訊儲存成能被Netscape/Mozilla的瀏覽器所識別的cookie檔案。通過把這些稱為cookie-jar。通過設定CURLOPT_COOKIEJAR選項，在呼叫curl_easy_cleanup釋放easy handle的時候，所有的這些cookie資訊都會儲存到cookie-jar檔案中。這就使得cookie資訊能在不同的easy handle甚至在瀏覽器之間實現共享。

FTP Peculiarities We Need

在使用FTP協議進行資料傳輸的時候，需要建立兩個連線。第一個連線用於傳輸控制命令，另一個連線用於傳輸資料。（關於FTP的通訊過程，請參考這篇文章：http://www.wangjia.net/bo-blog/post/698/）。 FTP通訊需要建立兩個連線這個事實往往被很多人忽略。根據第二個連線的發起方是誰，可以分為主動模式與被動模式。libcurl對此都提供了支援。libcurl預設使用被動模式，因為被動模式可以方便的穿透防火牆，NAT等問題。在被動模式下，libcurl要求ftp伺服器開啟一個新的埠監聽，然後libcurl連線該埠用於資料傳輸。如果使用主動模式，程式必須告訴FTP伺服器你監聽的IP與埠，通過設定CURLOPT_FTPPORT屬性來完成。

Headers Equal Fun

（這段文字我理解的很模糊，請讀者參考原文）有些協議提供獨立於正常資料的訊息頭、meta-data。正常的資料流裡通常不包括資訊頭和後設資料。可以將CURLOPT_HEADER設定為1，使資訊頭、後設資料也能出現在資料流中。libcurl的強大之處在於，它能夠從資料流中解析出訊息頭，….

Post Transfer Information

[ curl_easy_getinfo ]

安全考慮

請參考原文，此處略。

使用multi interface同時進行多項傳輸

     上面介紹的easy interface以同步的方式進行資料傳輸，curl_easy_perform會一直阻塞到資料傳輸完畢後返回，且一次操作只能傳送一次請求，如果要同時傳送多個請求，必須使用多執行緒。
    而multi interface以一種簡單的、非阻塞的方式進行傳輸，它允許在一個執行緒中，同時提交多個相同型別的請求。在使用multi interface之前，你應該掌握easy interface的基本使用。因為multi interface是建立在easy interface基礎之上的，它只是簡單的將多個easy handler新增到一個multi stack，而後同時傳輸而已。
    使用multi interface很簡單，首先使用curl_multi_init()函式建立一個multi handler，然後使用curl_easy_init()建立一個或多個easy handler，並按照上面幾章介紹的介面正常的設定相關的屬性，然後通過curl_multi_add_handler將這些easy handler新增到multi handler，最後呼叫curl_multi_perform進行資料傳輸。
    curl_multi_perform是非同步的、非阻塞的函式。如果它返回CURLM_CALL_MULTI_PERFORM，表示資料通訊正在進行。

通過select()來操作multi interface將會使工作變得簡單（譯者注：其實每個easy handler在低層就是一個socket，通過select()來管理這些socket，在有資料可讀/可寫/異常的時候，通知應用程式）。在呼叫select()函式之前，應該使用curl_multi_fdset來初始化fd_set變數。

select()函式返回時，說明受管理的低層socket可以操作相應的操作（接收資料或傳送資料，或者連線已經斷開），此時應該馬上呼叫curl_multi_perform，libcurl將會執行相應操作。使用select()時，應該設定一個較短的超時時間。在呼叫select()之前，造成不要忘記通過curl_multi_fdset來初始化fd_set，因為每次操作，fd_set中的檔案描述符可能都不一樣。

如果你想中止multi stack中某一個easy handle的資料通訊，可以呼叫curl_multi_remove_handle函式將其從multi stack中取出。千萬另忘記釋放掉easy handle（通過curl_easy_cleanup()函式）。

當multi stack中的一個eash handle完成資料傳輸的時候，同時執行的傳輸任務數量就會減少一個。當數量降到0的時候，說明所有的資料傳輸已經完成。

curl_multi_info_read用於獲取當前已經完成的傳輸任務資訊，它返回每一個easy handle的CURLcode狀態碼。可以根據這個狀態碼來判斷每個easy handle傳輸是否成功。

下面的例子，演示瞭如何使用multi interface進行網頁抓取：

int main(int argc, char **argv)
{
	// 初始化
	curl_global_init(CURL_GLOBAL_WIN32);
	CURLM *multi_handle = NULL;
	CURL *easy_handle1 = NULL;
	CURL *easy_handle2 = NULL;
	
	extern size_t save_sina_page(void *buffer, size_t size, size_t count, void *user_p);
	extern size_t save_sohu_page(void *buffer, size_t size, size_t count, void *user_p);
	FILE *fp_sina = fopen("sina.html", "ab+");
	FILE *fp_sohu = fopen("sohu.html", "ab+");

	multi_handle = curl_multi_init();

	// 設定easy handle
	easy_handle1 = curl_easy_init();
	curl_easy_setopt(easy_handle1, CURLOPT_URL, "http://www.sina.com.cn");
	curl_easy_setopt(easy_handle1, CURLOPT_WRITEFUNCTION, &save_sina_page);
	curl_easy_setopt(easy_handle1, CURLOPT_WRITEDATA, fp_sina);

	easy_handle2 = curl_easy_init();
	curl_easy_setopt(easy_handle2, CURLOPT_URL, "http://www.sohu.com");
	curl_easy_setopt(easy_handle2, CURLOPT_WRITEFUNCTION, &save_sohu_page);
	curl_easy_setopt(easy_handle2, CURLOPT_WRITEDATA, fp_sohu);

	// 新增到multi stack
	curl_multi_add_handle(multi_handle, easy_handle1);
	curl_multi_add_handle(multi_handle, easy_handle2);

	// 
	int running_handle_count;
	while (CURLM_CALL_MULTI_PERFORM == curl_multi_perform(multi_handle, &running_handle_count))
	{
		cout << running_handle_count << endl;
	}

	while (running_handle_count)
	{
		timeval tv;
		tv.tv_sec = 1;
		tv.tv_usec = 0;

		int max_fd;
		fd_set fd_read;
		fd_set fd_write;
		fd_set fd_except;

		FD_ZERO(&fd_read);
		FD_ZERO(&fd_write);
		FD_ZERO(&fd_except);

		curl_multi_fdset(multi_handle, &fd_read, &fd_write, &fd_except, &max_fd);
		int return_code = select(max_fd + 1, &fd_read, &fd_write, &fd_except, &tv);
		if (SOCKET_ERROR == return_code)
		{
			cerr << "select error." << endl;
			break;
		}
		else
		{
			while (CURLM_CALL_MULTI_PERFORM == curl_multi_perform(multi_handle, &running_handle_count))
			{
				cout << running_handle_count << endl;
			}
		}
	}

	// 釋放資源
	fclose(fp_sina);
	fclose(fp_sohu);
	curl_easy_cleanup(easy_handle1);
	curl_easy_cleanup(easy_handle2);
	curl_multi_cleanup(multi_handle);
	curl_global_cleanup();

	return 0;
}

size_t save_sina_page(void *buffer, size_t size, size_t count, void *user_p)
{
	return fwrite(buffer, size, count, (FILE *)user_p);
}

size_t save_sohu_page(void *buffer, size_t size, size_t count, void *user_p)
{
	return fwrite(buffer, size, count, (FILE *)user_p);
}

SSL, 證書，其他技巧

[ seeding, passwords, keys, certificates, ENGINE, ca certs ]

在easy handler之間共享資料

[fill in]

[Libcurl]Build&Use Manual
2017-11-24
UI
Libcurl簡明使用指南
2014-04-08
多執行緒的libcurl的使用
2022-01-17
執行緒
C++使用libcurl進行http通訊
2021-02-22
C++HTTP
開源的網路協議庫LibCurl
2013-08-23
協議
C++ LibCurl實現Web指紋識別
2023-11-21
C++Web
【Curl(libcurl)開發之二】Cocos2dx之深入(libcurl)的curl_easy_setopt引數詳細介紹！
2017-11-08
libcurl多執行緒超時設定不安全
2014-12-01
執行緒
windows下curl報錯:curl : (1) Protocol https not supported or disabled in libcurl
2017-06-07
WindowsProtocolHTTP
configure: error: libcurl >= 7.28.0 library and headers are required with support for https
2024-04-05
ErrorHeaderUIHTTP
基於libcurl實現REST風格http/https的get和post
2018-10-16
RESTHTTP
C++ 用libcurl庫進行http通訊網路程式設計
2018-03-09
C++HTTP程式設計
編譯支援iOS的libcurl+OpenSSL庫(支援https IPv6)
2018-01-03
編譯iOSHTTP
iOS 使用libcurl 獲取網路請求各階段的時間
2018-01-03
iOS
C++用libcurl庫進行http網路通訊程式設計
2014-12-12
C++HTTP程式設計
iOS用libcurl發起一個get請求，並儲存返回資料到沙盒
2018-01-03
iOS
Win10系統執行程式提示計算機中丟失libcurl.dll怎麼辦
2016-10-16
Win10行程計算機
【Cocos2d-X】iOS6 中 libcurl.a及iOS6中無法橫屏的解決方法薦
2012-09-28
iOS
winscp教程，winscp教程，使用教程
2020-10-23
appium教程教程（一）
2020-12-09
APP
git 入門教程之github 教程
2019-03-29
Github
Kafka教程(一)Kafka入門教程
2016-04-21
Kafka
保姆級mysql安裝教程+下載教程-附視訊教程
2020-05-18
MySql
開盒查人教程開盒查人教程開盒查人教程開盒查人教程
2024-05-09
python基礎教程|菜鳥教程
2020-11-03
Python
leapftp教程，掌握leapftp教程只需6步
2020-09-03
FTP
Memcache教程 Memcache零基礎教程
2014-11-05
rbac 教程
2019-12-20
God教程
2019-03-24
Go
使用教程
2021-09-09
Vuex教程
2021-09-09
Vue
flutter教程
2021-07-15
Flutter
SQL教程
2020-11-14
SQL
MySQL 教程
2020-10-24
MySql
Swoole 教程
2022-06-13
flyway教程
2018-06-22
Canvas 教程
2018-01-24
Canvas
Mockito 教程
2018-03-15
Mockito