libcurl 接口調用方式

http://hi.baidu.com/tracyu1026/item/bb6d5def4292b10b570f1d48

 

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的函數。
   
    一、CURL *curl_easy_init()
    此函數須要最早被調用，返回CRUL easy句柄；後續其餘函數調用都要用到這個句柄。若是沒有調用curl_global_init()，該函數自動調用，可是考慮到線程安全的問題，最好本身調用curl_global_init()。

 

    二、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傳輸顯示的進度條。
   

     CURLOPT_INFILESIZE

     當你上傳一個文件到遠程站點，這個選項告訴PHP你上傳文件的大小。

 

    CURLOPT_VERBOSE

    若是你想CURL報告每一件意外的事情，設置這個選項爲一個非零值。

 

    CURLOPT_HEADER

     若是你想把一個頭包含在輸出中，設置這個選項爲一個非零值。

 

    CURLOPT_NOBODY

    若是你不想在輸出中包含body部分，設置這個選項爲一個非零值。

 

    CURLOPT_FAILONERROR

    若是你想讓PHP在發生錯誤(HTTP代碼返回大於等於300)時，不顯示，設置這個選項爲一人非零值。默認行爲是返回一個正常頁，忽略代碼。

 

    CURLOPT_UPLOAD:若是你想讓PHP爲上傳作準備，設置這個選項爲一個非零值。

 

*CURLOPT_POST: 若是你想PHP去作一個正規的HTTPPOST，設置這個選項爲一個非零值。這個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_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_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或其它操做是有益的，更 Passa string to be used instead of GET or HEAD when doing an HTTPrequest. This is useful for doing or another, more obscure, HTTPrequest. 注 意:在確認你的服務器支持命令先不要去這樣作。下列的選項要求一個文件描述(經過使用fopen()函數得到)：　

 

*CURLOPT_FILE:這個文件將是你放置傳送的輸出文件，默認是STDOUT.

*CURLOPT_INFILE: 這個文件是你傳送過來的輸入文件。

*CURLOPT_STDERR:這個文件寫有錯誤而不是stderr。用來獲取須要登陸的頁面的例子,當前作法是每次或許都登陸一次,有須要的人再作改進了:)

    三、void curl_easy_reset(CURL *handle )
    從新初始化CURL句柄的選項設置。

 四、CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... )
    查詢CRUL會話的內部信息，具體說明請參考curl自帶文檔。
   
    五、void curl_easy_cleanup(CURL * handle )
    該函數與curl_easy_init函數成對出現，handle即爲調用curl_easy_init返回的句柄。該函數在CURL會話結束退出時調用，以後handle無效。