本文目錄
- 簡介
- api
- 簡介
- easy模組
- multi模組
簡介
api中文化系列是為了輔助Rust常用庫翻譯計劃而做的文章，用於簡單整理對應庫的api文件暴露的介面，方便整理後梳理成對應的簡潔的教程。
api
1.簡介
該api共提供了兩個模組easy和multi，六個struct和一個函式init。其中基本入口為easy模組。
2.easy模組
模組struct:
- Auth
- Easy
- Form
- Iter
- List
- Part
- SslOpt
- Transfer
1.Auth:
函式列表：
- new:返回一個空的Auth結構體例項，用於接下來的認證操作
- basic(bool):傳入一個人布林值，設定是否使用基礎http認證方式
- digest(bool):傳入一個布林值，設定是否使用Digest認證
- digest_ie(bool):傳入一個布林值，設定是否使用ie風格的Digest認證
- gssnegotiate(bool):傳入一個布林值，設定是否使用HTTP Negotiate認證
- ntlm(bool):傳入一個布林值，設定是否使用HTTP NTLM認證
- ntlm_wb(bool):傳入一個bool值，功能的話，Orz小生沒看懂
例項：
2.Easy：
函式列表：
- new:返回一個Easy例項，用於接下來的操作
- verbose(bool):設為true後,控制檯將輸出大量的資訊以供除錯
- show_header(bool):設為true後返回的資料將攜帶頭資訊
- progress(bool):是否顯示程式表（未找到設為true後的變化，Orz）
- signal(bool):Orz，看不懂
- wildcard_match(bool):是否根據檔名稱匹配傳輸多個檔案，檔案字尾使用fnmatch-like模式匹配
- write_function(F)：接受一個閉包函式作為引數傳入，閉包函式簽名為：F: FnMut(&[u8]) -> Result
+ Send + 'static, 在請求完成後會呼叫該閉包函式，返回的資料作為引數傳入，注意的是，返回的資料可能量非常大，也有可能小到0 - read_function(F):接受一個閉包函式作為引數，函式簽名等同上文write_function(F)，不同的是，該回撥是在請求上傳檔案完成後呼叫
- seek_function(F):待定
- progress_function(F):待定
- ssl_ctx_function(F):待定
- debug_function(F):待定
- header_function(F):待定
- fail_on_error(bool):接受一個布林值，指定是否在http返回的code>400直接fail
- url(&str):接受一個字串引用，指定要訪問的url
- port(u16): 傳入一個u16整型，指定埠號
- proxy(&str):接受一個字串引用，指定代理伺服器url
- proxy_port(u16):接受一個u16整型引數，設定代理伺服器埠號
- proxy_type(ProxyType):接受一個ProxyType的列舉，用於設定代理型別
- noproxy(&str):接受一個字串引用，定義一系列的主機列表，這些訪問這些主機時不使用代理，主機之間用逗號分割，可以用*萬用字元
- http_proxy_tunnel(bool):傳入一個布林值，定義是否通過代理隧道進行所有操作
- interface(&str):傳入一個字串引用，定義操作繫結哪一個網路介面，可以在這裡指定介面名稱、ip地址或者主機名
- set_local_port(u16):指示哪個埠應繫結到本地連線。預設是0，即任意埠
- local_port_range(u16):定義系統嘗試查詢可用埠的次數
- dns_cache_timeout(Duration):傳入標準庫結構體Duration,定義dns解析在記憶體中快取的時間
- buffer_size(size):傳入usize整型，定義接受緩衝區大小，位元組為單位
- tcp_nodelay(bool):配置是否定義TCP_NODELAY選項，否則Nagle's algorithm 將會是禁止狀態
- username(&str):定義認證時的使用的使用者
- password(&str):定義認證時使用的密碼
- http_auth(&Auth):傳入一個Auth例項引用，定義http認證方式
- proxy_username(&str):代理伺服器認證時的使用者名稱
- proxy_password(&str):代理伺服器認證時的密碼
- proxy_auth(&Auth):傳入Auth例項引用，定義http代理時的認證方式
- netrc(netRc):傳入一個列舉netRc,用於配置netrc解析
- autoreferer(bool):是否自動更新引用頭
- accept_encoding(&str):啟動http壓縮方式，設定Accept-Encoding頭內容，比如 identity, zlib, and gzip。傳入0長度的字串時會傳送所有可接受編碼
- transfer_encoding(bool):是否啟用http傳輸編碼
- follow_location(bool):是否跟隨返回頭中的3xx設定進行重定向
- unrestricted_auth(bool):配置後，憑證將不止傳送給第一個主機，重定向後的主機也會收到憑證
- max_redirections(u32):指定最大允許的重定向次數，如果設定為0則拒絕重定向
- put(bool):設定後將設定傳送PUT請求
- post(bool):設定後竟會傳送POST請求，並且自動新增Content-Type: application/x-www-form-urlencoded 頭部，攜帶的資料可以通過post_fields指定或者通過設定read function指定
- post_fields_copy(&[u8]):設定post時攜帶的資料，資料會被複制進該控制程式碼中，如果不需要，則可以選擇使用read callback。
- post_field_size(u64):配置post中傳輸的資料的大小，自動被呼叫作為post_fields的一部分，並且只有在為read callback提供資料資料時才會被呼叫。所以該選項也是可選的。
- httppost(Form):傳入一個Struct Form,設定使用multipart/formdata 格式傳輸資料，資料通過Form Struct例項傳入
- referer(&str):設定引用頭，refer欄位
- useragent(&str):設定頭部user-agent欄位
http_headers(List):傳入一個Struct List,批量設定http頭
cookie(&str):傳入字串如“key1=v1;key2=v2”，設定cookie，重複呼叫此函式會覆蓋上次的值
- cookie_file(AsRef
):傳入一個在標準庫trait AsRef處理後的路徑，通過該路徑傳入一個cookie檔案，格式可以時 Netscape / Mozilla的cookie格式，也可以是header裡set-Cookie的格式。同時如果多次呼叫該函式，會附加相應的值 - cookie_jar(AsRef
):傳入一個在標準庫trait AsRef處理後的路徑，通過該路徑傳入一個檔案，在刪除該控制程式碼時libcurl會把cookie寫入該檔案。注：libcurl並不會從該檔案中讀取任何cookie - cookie_session(bool):開啟後cookie將會只在每個會話中有效，每次開一個會話時，libcurl不會讀取之前儲存的cookie
- cookie_list(&str):新增到或操縱儲存在記憶體中的Cookie。這樣的cookie可以是Netscape / Mozilla格式的一行，也可以是常規的HTTP樣式頭（Set-Cookie：...）格式。這也將啟用Cookie引擎。這將單個Cookie新增到內部Cookie儲存。
- get(bool):啟用將傳送get請求
- ignore_content_length(bool):是否忽略標頭檔案中的content-length欄位
- http_content_decoding(bool):是否啟用http content解碼(注：這個選項預設是true)
- http_transfer_decoding(bool):是否啟用http傳輸解碼（注：這個選項預設是true）
- range(&str):表示此請求應檢索的範圍。提供的字串應為N-M形式，其中N或M可以被省略。 對於HTTP傳輸，也可以接受以逗號分隔的多個範圍。(這條沒看懂)
- resume_from(u64):設定一個點，值為一個偏移量，傳輸將從此處恢復繼續(文件是這個說的，具體效果有待考證)
- custom_request(&str):設定一個自定義的請求字串
- fetch_filetime(bool):是否獲取遠端資源的修改時間
- nobody(bool):設定為true後，請求將不會返回body體，這在有時候只是需要獲得頭資訊時蠻有用
- in_filesize(u64):如果要攜帶檔案上傳，該函式設定檔案尺寸
- upload(bool):是否允許上傳資料（禁止後將影響上傳相關函式）
- max_filesize(u64):下載的檔案的最大大小
- time_condition(TimeCondition):傳入一個列舉TimeCondition,設定一個請求的之間條件，與下一個函式搭配使用。
- time_value(i64):設定一個時間戳，對應的含義由上一個函式指定
- timeout(Duration):傳入一個標準庫Struct Duration,設定請求最大等待時間
- low_speed_limit(u32):設定請求時最最低速度，位元組/秒
- low_speed_time(Duration):傳入一個標準庫Struct Duration,設定低速限制時間段，在該時間段內速度低於low_speed_limit的視窗將會被關閉
- max_send_speed(u32):告訴限制，設定最高速度，位元組每秒
- max_recv_speed(u64):限制下載速度
- max_connects(u64):設定最大連線快取大小，預設是5，（注：修改此值並無使益處）
- fresh_connect(bool):是否強制重新建立一個新連線
- forbid_reuse(bool):設定是否在一個連線使用後立即關閉
- connect_timeout(Duration):傳入一個標準庫Struct Duration,設定連線階段最大等待時間
- ip_resolve(IpResolve):傳入列舉IpResolve,指定使用的ip協議版本。
- connect_only(bool):是否在成功連線主機後就停止。
- ssl_cert(AsRef
):傳入一個在標準庫trait AsRef處理後的路徑，通過該路徑傳入ssl 客戶端的證書 - ssl_cert_type(&str):設定ssl證書型別
- ssl_key(AsRef
):傳入一個在標準庫trait AsRef處理後的路徑，通過該路徑指定TLS和SSL客戶端證書的私鑰檔案。 - ssl_key_type(&str):設定ssl_key私鑰型別
- key_password(&str):設定私鑰密碼
- ssl_engine(&str):設定ssl引擎識別碼
- ssl_engine_default(bool):是否將該控制程式碼的ssl引擎設為預設值
- http_version(HttpVersion):傳入一個列舉HttpVersion,設定http版本
- ssl_version(SslVersion):傳入一個列舉SslVersion,設定ssl版本
- ssl_verify_host(bool):是否根據主機驗證ssl名稱，預設為true
- ssl_verify_host(bool):是否驗證對等主機的ssl證書，預設是true，若要禁止，需非常小心，禁止後幾乎就是禁止了ssl所有安全功能
- cainfo(AsRef
):傳入一個在標準庫trait AsRef處理後的路徑，通過該路徑指定CA包位置 - issuer_cert(AsRef
):傳入一個在標準庫trait AsRef處理後的路徑，通過該路徑指定issuer SSL。 - capath(AsRef
):傳入一個在標準庫trait AsRef處理後的路徑，通過該路徑指定CA證書的資料夾位置 - crlfile(AsRef
):傳入一個在標準庫trait AsRef處理後的路徑，通過該路徑指定證書撤銷列表檔案 - certinfo(bool):是否請求ssl證書資訊
- random_file(AsRef
):傳入一個在標準庫trait AsRef處理後的路徑，通過該路徑指定ssl用到的隨機數源 - egd_socket(AsRef
):傳入一個在標準庫trait AsRef處理後的路徑，通過該路徑指定EGD socket路徑 - ssl_cipher_list(&str):指定TLS用到的密碼
- ssl_sessionid_cache(bool):是否使用ssl的session-id快取
- ssl_options(&SslOpt):傳入結構體SslOpt,設定ssl相應選項
- effective_url():該函式返回值簽名為Result
- effective_url_bytes():該函式返回值簽名為Result
- response_code():該函式返回值簽名為 Result
,返回請求的返回狀態碼 - http_connectcode():該函式返回值簽名為 Result
,返回連線的狀態碼 - filetime():該函式返回值簽名為 Result
,返回檢索到文件的遠端伺服器時間 - total_time():該函式返回值簽名為 Result
,返回傳輸用的總時間 - namelookup_time():該函式返回值簽名為 Result
,返回域名解析所花時間 - connect_time():該函式返回值簽名為 Result
,返回連線伺服器所花時間 - appconnect_time():該函式返回值簽名為 Result
,返回直到SSL/SSH握手花費時間 - pretransfer_time():該函式返回值簽名為 Result
,返回直到開始傳輸時花費的時間 - starttransfer_time():該函式返回值簽名為 Result
,返回直到剛開始收到資料時花費的時間 - redirect_time():該函式返回值簽名為 Result
,返回所有重定向所花費的時間 - redirect_count():該函式返回值簽名為 Result
,返回重定向的次數。 - redirect_url():該函式返回值簽名為 Result
- redirect_url_bytes:該函式返回值簽名為 Result
- header_size():該函式返回值簽名為 Result
,返回頭部大小 - request_size():該函式返回值簽名為 Result
,返回請求包大小 - content_type():該函式返回值簽名為 Result
- content_type_bytes():該函式返回值簽名為 Result
- os_errno():該函式返回值簽名為 Result
,返回最後一次連線失敗時的錯誤號 - primary_ip():該函式返回值簽名為 Result
- primary_port():該函式返回值簽名為 Result
,返回最後一次連線的目的埠 - local_ip():該函式返回值簽名為 Result
- local_port():該函式返回值簽名為 Result
,返回最後一次連線的本地埠 - cookies():該函式返回值簽名為 Result
- ,返回Cookie列表
- perform():呼叫該函式後，請求正式發出！！！！！
- transfer():該函式返回值簽名為Transfer<'easy, 'data>,新建一個Transfer，用於設定回撥函式和資料.
- unpause_read():取消讀取的暫停狀態
- unpause_write():取消寫入的暫停狀態
- url_encode(&[u8]):傳入一個url，返回一個url encode後的String
- url_decode(&str):傳入一個url，返回一個url decode後的vector
- reset():重置該控制程式碼所有值為初始值
- recv(& mut [u8]):返回值簽名為Result
，從已經建立連線的socket里拉取資料 - send(&[u8]):向已經建立連線的socket裡寫入資料
- raw():返回一個 curl_sys::CURL指標
例項：
模組enums：
- HttpVersion
- InfoType
- IpResolve
- NetRc
- ProxyType
- ReadError
- SeekResult
- SslVersion
- TimeCondition
- WriteError
3.multi模組
詳情見：api中文化之Rust-curl（下）