本文目錄
- 簡(jiǎn)介
- api
- 簡(jiǎn)介
- easy模塊
- multi模塊
簡(jiǎn)介
api中文化系列是為了輔助Rust常用庫翻譯計(jì)劃而做的文章捌朴,用于簡(jiǎn)單整理對(duì)應(yīng)庫的api文檔暴露的接口捣鲸,方便整理后梳理成對(duì)應(yīng)的簡(jiǎn)潔的教程。
Rust常用庫翻譯之curl傳送門
Rust翻譯計(jì)劃總傳送門
api
1.簡(jiǎn)介
該api共提供了兩個(gè)模塊easy和multi糯而,六個(gè)struct和一個(gè)函數(shù)init。其中基本入口為easy模塊克滴。
2.easy模塊
模塊struct:
- Auth
- Easy
- Form
- Iter
- List
- Part
- SslOpt
- Transfer
1.Auth:
函數(shù)列表:
- new:返回一個(gè)空的Auth結(jié)構(gòu)體實(shí)例逼争,用于接下來的認(rèn)證操作
- basic(bool):傳入一個(gè)人布爾值,設(shè)置是否使用基礎(chǔ)http認(rèn)證方式
- digest(bool):傳入一個(gè)布爾值劝赔,設(shè)置是否使用Digest認(rèn)證
- digest_ie(bool):傳入一個(gè)布爾值誓焦,設(shè)置是否使用ie風(fēng)格的Digest認(rèn)證
- gssnegotiate(bool):傳入一個(gè)布爾值,設(shè)置是否使用HTTP Negotiate認(rèn)證
- ntlm(bool):傳入一個(gè)布爾值着帽,設(shè)置是否使用HTTP NTLM認(rèn)證
- ntlm_wb(bool):傳入一個(gè)bool值杂伟,功能的話,Orz小生沒看懂
實(shí)例:
2.Easy:
函數(shù)列表:
new:返回一個(gè)Easy實(shí)例仍翰,用于接下來的操作
verbose(bool):設(shè)為true后,控制臺(tái)將輸出大量的信息以供調(diào)試
show_header(bool):設(shè)為true后返回的數(shù)據(jù)將攜帶頭信息
progress(bool):是否顯示進(jìn)程表(未找到設(shè)為true后的變化赫粥,Orz)
signal(bool):Orz,看不懂
wildcard_match(bool):是否根據(jù)文件名稱匹配傳輸多個(gè)文件予借,文件后綴使用fnmatch-like模式匹配
write_function(F):接受一個(gè)閉包函數(shù)作為參數(shù)傳入越平,閉包函數(shù)簽名為:F: FnMut(&[u8]) -> Result<usize, WriteError> + Send + 'static, 在請(qǐng)求完成后會(huì)調(diào)用該閉包函數(shù),返回的數(shù)據(jù)作為參數(shù)傳入灵迫,注意的是秦叛,返回的數(shù)據(jù)可能量非常大,也有可能小到0
read_function(F):接受一個(gè)閉包函數(shù)作為參數(shù)瀑粥,函數(shù)簽名等同上文write_function(F)挣跋,不同的是,該回調(diào)是在請(qǐng)求上傳文件完成后調(diào)用
seek_function(F):待定
progress_function(F):待定
ssl_ctx_function(F):待定
debug_function(F):待定
header_function(F):待定
fail_on_error(bool):接受一個(gè)布爾值狞换,指定是否在http返回的code>400直接fail
url(&str):接受一個(gè)字符串引用避咆,指定要訪問的url
port(u16): 傳入一個(gè)u16整型,指定端口號(hào)
proxy(&str):接受一個(gè)字符串引用哀澈,指定代理服務(wù)器url
proxy_port(u16):接受一個(gè)u16整型參數(shù)牌借,設(shè)置代理服務(wù)器端口號(hào)
proxy_type(ProxyType):接受一個(gè)ProxyType的枚舉,用于設(shè)置代理類型
noproxy(&str):接受一個(gè)字符串引用割按,定義一系列的主機(jī)列表膨报,這些訪問這些主機(jī)時(shí)不使用代理,主機(jī)之間用逗號(hào)分割适荣,可以用*通配符
http_proxy_tunnel(bool):傳入一個(gè)布爾值现柠,定義是否通過代理隧道進(jìn)行所有操作
interface(&str):傳入一個(gè)字符串引用,定義操作綁定哪一個(gè)網(wǎng)絡(luò)接口弛矛,可以在這里指定接口名稱够吩、ip地址或者主機(jī)名
set_local_port(u16):指示哪個(gè)端口應(yīng)綁定到本地連接。默認(rèn)是0丈氓,即任意端口
local_port_range(u16):定義系統(tǒng)嘗試查找可用端口的次數(shù)
dns_cache_timeout(Duration):傳入標(biāo)準(zhǔn)庫結(jié)構(gòu)體Duration,定義dns解析在內(nèi)存中緩存的時(shí)間
buffer_size(size):傳入usize整型周循,定義接受緩沖區(qū)大小强法,字節(jié)為單位
tcp_nodelay(bool):配置是否定義TCP_NODELAY選項(xiàng),否則Nagle's algorithm 將會(huì)是禁止?fàn)顟B(tài)
username(&str):定義認(rèn)證時(shí)的使用的用戶
password(&str):定義認(rèn)證時(shí)使用的密碼
http_auth(&Auth):傳入一個(gè)Auth實(shí)例引用湾笛,定義http認(rèn)證方式
proxy_username(&str):代理服務(wù)器認(rèn)證時(shí)的用戶名
proxy_password(&str):代理服務(wù)器認(rèn)證時(shí)的密碼
proxy_auth(&Auth):傳入Auth實(shí)例引用饮怯,定義http代理時(shí)的認(rèn)證方式
netrc(netRc):傳入一個(gè)枚舉netRc,用于配置netrc解析
autoreferer(bool):是否自動(dòng)更新引用頭
accept_encoding(&str):啟動(dòng)http壓縮方式,設(shè)置Accept-Encoding頭內(nèi)容嚎研,比如 identity, zlib, and gzip蓖墅。傳入0長(zhǎng)度的字符串時(shí)會(huì)發(fā)送所有可接受編碼
transfer_encoding(bool):是否啟用http傳輸編碼
follow_location(bool):是否跟隨返回頭中的3xx設(shè)置進(jìn)行重定向
unrestricted_auth(bool):配置后,憑證將不止發(fā)送給第一個(gè)主機(jī)临扮,重定向后的主機(jī)也會(huì)收到憑證
max_redirections(u32):指定最大允許的重定向次數(shù)论矾,如果設(shè)置為0則拒絕重定向
put(bool):設(shè)置后將設(shè)置發(fā)送PUT請(qǐng)求
post(bool):設(shè)置后竟會(huì)發(fā)送POST請(qǐng)求,并且自動(dòng)添加Content-Type: application/x-www-form-urlencoded 頭部杆勇,攜帶的數(shù)據(jù)可以通過post_fields指定或者通過設(shè)置read function指定
post_fields_copy(&[u8]):設(shè)置post時(shí)攜帶的數(shù)據(jù)贪壳,數(shù)據(jù)會(huì)被復(fù)制進(jìn)該句柄中,如果不需要靶橱,則可以選擇使用read callback寥袭。
post_field_size(u64):配置post中傳輸?shù)臄?shù)據(jù)的大小路捧,自動(dòng)被調(diào)用作為post_fields的一部分关霸,并且只有在為read callback提供數(shù)據(jù)數(shù)據(jù)時(shí)才會(huì)被調(diào)用。所以該選項(xiàng)也是可選的杰扫。
httppost(Form):傳入一個(gè)Struct Form,設(shè)置使用multipart/formdata 格式傳輸數(shù)據(jù)队寇,數(shù)據(jù)通過Form Struct實(shí)例傳入
referer(&str):設(shè)置引用頭,refer字段
useragent(&str):設(shè)置頭部user-agent字段
http_headers(List):傳入一個(gè)Struct List,批量設(shè)置http頭
cookie(&str):傳入字符串如“key1=v1;key2=v2”章姓,設(shè)置cookie佳遣,重復(fù)調(diào)用此函數(shù)會(huì)覆蓋上次的值
cookie_file(AsRef<Path>):傳入一個(gè)在標(biāo)準(zhǔn)庫trait AsRef處理后的路徑,通過該路徑傳入一個(gè)cookie文件凡伊,格式可以時(shí) Netscape / Mozilla的cookie格式零渐,也可以是header里set-Cookie的格式。同時(shí)如果多次調(diào)用該函數(shù)系忙,會(huì)附加相應(yīng)的值
cookie_jar(AsRef<Path>):傳入一個(gè)在標(biāo)準(zhǔn)庫trait AsRef處理后的路徑诵盼,通過該路徑傳入一個(gè)文件,在刪除該句柄時(shí)libcurl會(huì)把cookie寫入該文件银还。注:libcurl并不會(huì)從該文件中讀取任何cookie
cookie_session(bool):開啟后cookie將會(huì)只在每個(gè)會(huì)話中有效风宁,每次開一個(gè)會(huì)話時(shí),libcurl不會(huì)讀取之前存儲(chǔ)的cookie
cookie_list(&str):添加到或操縱保存在內(nèi)存中的Cookie蛹疯。這樣的cookie可以是Netscape / Mozilla格式的一行戒财,也可以是常規(guī)的HTTP樣式頭(Set-Cookie:...)格式。這也將啟用Cookie引擎捺弦。這將單個(gè)Cookie添加到內(nèi)部Cookie存儲(chǔ)饮寞。
get(bool):啟用將發(fā)送get請(qǐng)求
ignore_content_length(bool):是否忽略頭文件中的content-length字段
http_content_decoding(bool):是否啟用http content解碼(注:這個(gè)選項(xiàng)默認(rèn)是true)
http_transfer_decoding(bool):是否啟用http傳輸解碼(注:這個(gè)選項(xiàng)默認(rèn)是true)
range(&str):表示此請(qǐng)求應(yīng)檢索的范圍孝扛。提供的字符串應(yīng)為N-M形式,其中N或M可以被省略幽崩。 對(duì)于HTTP傳輸疗琉,也可以接受以逗號(hào)分隔的多個(gè)范圍。(這條沒看懂)
resume_from(u64):設(shè)置一個(gè)點(diǎn)歉铝,值為一個(gè)偏移量盈简,傳輸將從此處恢復(fù)繼續(xù)(文檔是這個(gè)說的,具體效果有待考證)
custom_request(&str):設(shè)置一個(gè)自定義的請(qǐng)求字符串
fetch_filetime(bool):是否獲取遠(yuǎn)程資源的修改時(shí)間
nobody(bool):設(shè)置為true后太示,請(qǐng)求將不會(huì)返回body體柠贤,這在有時(shí)候只是需要獲得頭信息時(shí)蠻有用
in_filesize(u64):如果要攜帶文件上傳,該函數(shù)設(shè)置文件尺寸
upload(bool):是否允許上傳數(shù)據(jù)(禁止后將影響上傳相關(guān)函數(shù))
max_filesize(u64):下載的文件的最大大小
time_condition(TimeCondition):傳入一個(gè)枚舉TimeCondition,設(shè)置一個(gè)請(qǐng)求的之間條件类缤,與下一個(gè)函數(shù)搭配使用臼勉。
time_value(i64):設(shè)置一個(gè)時(shí)間戳,對(duì)應(yīng)的含義由上一個(gè)函數(shù)指定
timeout(Duration):傳入一個(gè)標(biāo)準(zhǔn)庫Struct Duration,設(shè)置請(qǐng)求最大等待時(shí)間
low_speed_limit(u32):設(shè)置請(qǐng)求時(shí)最最低速度餐弱,字節(jié)/秒
low_speed_time(Duration):傳入一個(gè)標(biāo)準(zhǔn)庫Struct Duration,設(shè)置低速限制時(shí)間段宴霸,在該時(shí)間段內(nèi)速度低于low_speed_limit的窗口將會(huì)被關(guān)閉
max_send_speed(u32):告訴限制,設(shè)置最高速度膏蚓,字節(jié)每秒
max_recv_speed(u64):限制下載速度
max_connects(u64):設(shè)置最大連接緩存大小瓢谢,默認(rèn)是5,(注:修改此值并無使益處)
fresh_connect(bool):是否強(qiáng)制重新建立一個(gè)新連接
forbid_reuse(bool):設(shè)置是否在一個(gè)連接使用后立即關(guān)閉
connect_timeout(Duration):傳入一個(gè)標(biāo)準(zhǔn)庫Struct Duration,設(shè)置連接階段最大等待時(shí)間
ip_resolve(IpResolve):傳入枚舉IpResolve,指定使用的ip協(xié)議版本驮瞧。
connect_only(bool):是否在成功連接主機(jī)后就停止氓扛。
ssl_cert(AsRef<Path>):傳入一個(gè)在標(biāo)準(zhǔn)庫trait AsRef處理后的路徑,通過該路徑傳入ssl 客戶端的證書
ssl_cert_type(&str):設(shè)置ssl證書類型
ssl_key(AsRef<Path>):傳入一個(gè)在標(biāo)準(zhǔn)庫trait AsRef處理后的路徑论笔,通過該路徑指定TLS和SSL客戶端證書的私鑰文件采郎。
ssl_key_type(&str):設(shè)置ssl_key私鑰類型
key_password(&str):設(shè)置私鑰密碼
ssl_engine(&str):設(shè)置ssl引擎識(shí)別碼
ssl_engine_default(bool):是否將該句柄的ssl引擎設(shè)為默認(rèn)值
http_version(HttpVersion):傳入一個(gè)枚舉HttpVersion,設(shè)置http版本
ssl_version(SslVersion):傳入一個(gè)枚舉SslVersion,設(shè)置ssl版本
ssl_verify_host(bool):是否根據(jù)主機(jī)驗(yàn)證ssl名稱,默認(rèn)為true
ssl_verify_host(bool):是否驗(yàn)證對(duì)等主機(jī)的ssl證書狂魔,默認(rèn)是true蒜埋,若要禁止,需非常小心最楷,禁止后幾乎就是禁止了ssl所有安全功能
cainfo(AsRef<Path>):傳入一個(gè)在標(biāo)準(zhǔn)庫trait AsRef處理后的路徑整份,通過該路徑指定CA包位置
issuer_cert(AsRef<Path>):傳入一個(gè)在標(biāo)準(zhǔn)庫trait AsRef處理后的路徑,通過該路徑指定issuer SSL管嬉。
capath(AsRef<Path>):傳入一個(gè)在標(biāo)準(zhǔn)庫trait AsRef處理后的路徑皂林,通過該路徑指定CA證書的文件夾位置
crlfile(AsRef<Path>):傳入一個(gè)在標(biāo)準(zhǔn)庫trait AsRef處理后的路徑,通過該路徑指定證書撤銷列表文件
certinfo(bool):是否請(qǐng)求ssl證書信息
random_file(AsRef<Path>):傳入一個(gè)在標(biāo)準(zhǔn)庫trait AsRef處理后的路徑蚯撩,通過該路徑指定ssl用到的隨機(jī)數(shù)源
egd_socket(AsRef<Path>):傳入一個(gè)在標(biāo)準(zhǔn)庫trait AsRef處理后的路徑础倍,通過該路徑指定EGD socket路徑
ssl_cipher_list(&str):指定TLS用到的密碼
ssl_sessionid_cache(bool):是否使用ssl的session-id緩存
ssl_options(&SslOpt):傳入結(jié)構(gòu)體SslOpt,設(shè)置ssl相應(yīng)選項(xiàng)
effective_url():該函數(shù)返回值簽名為Result<Option<&str>, Error>,返回多次重定向后最后一次的url
effective_url_bytes():該函數(shù)返回值簽名為Result<Option<&[u8]>, Error>,返回多次重定向后最后一次的url胎挎,以字節(jié)為單位
response_code():該函數(shù)返回值簽名為 Result<u32, Error>,返回請(qǐng)求的返回狀態(tài)碼
http_connectcode():該函數(shù)返回值簽名為 Result<u32, Error>,返回連接的狀態(tài)碼
filetime():該函數(shù)返回值簽名為 Result<i64, Error>,返回檢索到文檔的遠(yuǎn)程服務(wù)器時(shí)間
total_time():該函數(shù)返回值簽名為 Result<Duration, Error>,返回傳輸用的總時(shí)間
namelookup_time():該函數(shù)返回值簽名為 Result<Duration, Error>,返回域名解析所花時(shí)間
connect_time():該函數(shù)返回值簽名為 Result<Duration, Error>,返回連接服務(wù)器所花時(shí)間
appconnect_time():該函數(shù)返回值簽名為 Result<Duration, Error>,返回直到SSL/SSH握手花費(fèi)時(shí)間
pretransfer_time():該函數(shù)返回值簽名為 Result<Duration, Error>,返回直到開始傳輸時(shí)花費(fèi)的時(shí)間
starttransfer_time():該函數(shù)返回值簽名為 Result<Duration, Error>,返回直到剛開始收到數(shù)據(jù)時(shí)花費(fèi)的時(shí)間
redirect_time():該函數(shù)返回值簽名為 Result<Duration, Error>,返回所有重定向所花費(fèi)的時(shí)間
redirect_count():該函數(shù)返回值簽名為 Result<u32, Error>,返回重定向的次數(shù)沟启。
redirect_url():該函數(shù)返回值簽名為 Result<Option<&str>, Error>,返回將要重定向的url
redirect_url_bytes:該函數(shù)返回值簽名為 Result<Option<&[u8]>, Error>,返回將要重定向的url,以字節(jié)為單位
header_size():該函數(shù)返回值簽名為 Result<u64, Error>,返回頭部大小
request_size():該函數(shù)返回值簽名為 Result<u64, Error>,返回請(qǐng)求包大小
content_type():該函數(shù)返回值簽名為 Result<Option<&str>, Error>,返回content_type字段內(nèi)容
content_type_bytes():該函數(shù)返回值簽名為 Result<Option<&[u8]>, Error>,返回content_type字段內(nèi)容忆家,以字節(jié)為單位
os_errno():該函數(shù)返回值簽名為 Result<i32, Error>,返回最后一次連接失敗時(shí)的錯(cuò)誤號(hào)
primary_ip():該函數(shù)返回值簽名為 Result<Option<&str>, Error>,返回最后一次連接的ip地址
primary_port():該函數(shù)返回值簽名為 Result<u16, Error>,返回最后一次連接的目的端口
local_ip():該函數(shù)返回值簽名為 Result<Option<&str>, Error>,返回最后一次連接的本地ip地址
local_port():該函數(shù)返回值簽名為 Result<u16, Error>,返回最后一次連接的本地端口
cookies():該函數(shù)返回值簽名為 Result<List, Error>,返回Cookie列表
perform():調(diào)用該函數(shù)后,請(qǐng)求正式發(fā)出5录!Q壳洹!8旄恪卸例!
transfer():該函數(shù)返回值簽名為Transfer<'easy, 'data>,新建一個(gè)Transfer,用于設(shè)置回調(diào)函數(shù)和數(shù)據(jù).
unpause_read():取消讀取的暫停狀態(tài)
unpause_write():取消寫入的暫停狀態(tài)
url_encode(&[u8]):傳入一個(gè)url肌毅,返回一個(gè)url encode后的String
url_decode(&str):傳入一個(gè)url筷转,返回一個(gè)url decode后的vector
reset():重置該句柄所有值為初始值
recv(& mut [u8]):返回值簽名為Result<usize, Error>,從已經(jīng)建立連接的socket里拉取數(shù)據(jù)
send(&[u8]):向已經(jīng)建立連接的socket里寫入數(shù)據(jù)
raw():返回一個(gè) curl_sys::CURL指針
實(shí)例:
模塊enums:
- HttpVersion
- InfoType
- IpResolve
- NetRc
- ProxyType
- ReadError
- SeekResult
- SslVersion
- TimeCondition
- WriteError
3.multi模塊
詳情見:api中文化之Rust-curl(下)