curl教程 - 台部落

原文地址：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:[email protected]/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]

站內首發文章

紅衣落桂花

發佈了24 篇原創文章 · 獲贊 3 · 訪問量 2萬+

私信關注