api中文化之Rust-curl（上）

時間 2019-11-16

標籤 api 文化 rust curl 欄目 Linux 简体版

原文原文鏈接

本文目錄

簡介
api
1. 簡介
2. easy模塊
3. multi模塊

簡介

api中文化系列是爲了輔助Rust經常使用庫翻譯計劃而作的文章，用於簡單整理對應庫的api文檔暴露的接口，方便整理後梳理成對應的簡潔的教程。html

Rust經常使用庫翻譯之curl傳送門
 Rust翻譯計劃總傳送門
node

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小生沒看懂

實例：

實現了Clone實例
實現了Debug實例

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頭api
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<&str>
effective_url_bytes():該函數返回值簽名爲Result<&[u8]>
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<&str>
redirect_url_bytes:該函數返回值簽名爲 Result<&[u8]>
header_size():該函數返回值簽名爲 Result ,返回頭部大小
request_size():該函數返回值簽名爲 Result ,返回請求包大小
content_type():該函數返回值簽名爲 Result<&str>
content_type_bytes():該函數返回值簽名爲 Result<&[u8]>
os_errno():該函數返回值簽名爲 Result ,返回最後一次鏈接失敗時的錯誤號
primary_ip():該函數返回值簽名爲 Result<&str>
primary_port():該函數返回值簽名爲 Result ,返回最後一次鏈接的目的端口
local_ip():該函數返回值簽名爲 Result<&str>
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指針