api 中文化之 Rust-curl（上）

内容简介：api 中文化之 Rust-curl（上）

本文目录

• 简介
• api
  1. 简介
  2. easy模块
  3. multi模块

简介

api中文化系列是为了辅助Rust常用库翻译计划而做的文章，用于简单整理对应库的api文档暴露的接口，方便整理后梳理成对应的简洁的教程。

Rust常用库翻译之curl传送门(翻译中)

Rust翻译计划总传送门

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):传入一个StructForm,设置使用multipart/formdata 格式传输数据，数据通过Form Struct实例传入
• referer(&str):设置引用头，refer字段
• useragent(&str):设置头部user-agent字段

• http_headers(List):传入一个StructList,批量设置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):传入一个标准库StructDuration,设置请求最大等待时间
• low_speed_limit(u32):设置请求时最最低速度，字节/秒
• low_speed_time(Duration):传入一个标准库StructDuration,设置低速限制时间段，在该时间段内速度低于low_speed_limit的窗口将会被关闭
• max_send_speed(u32):告诉限制，设置最高速度，字节每秒
• max_recv_speed(u64):限制下载速度
• max_connects(u64):设置最大连接缓存大小，默认是5，（注：修改此值并无使益处）
• fresh_connect(bool):是否强制重新建立一个新连接
• forbid_reuse(bool):设置是否在一个连接使用后立即关闭
• connect_timeout(Duration):传入一个标准库StructDuration,设置连接阶段最大等待时间
• 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>, Error>，返回多次重定向后最后一次的url
• effective_url_bytes():该函数返回值签名为Result <&[u8]>, Error>,返回多次重定向后最后一次的url，以字节为单位
• 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>, Error>,返回将要重定向的url
• redirect_url_bytes:该函数返回值签名为 Result <&[u8]>, Error>,返回将要重定向的url,以字节为单位
• header_size():该函数返回值签名为 Result ,返回头部大小
• request_size():该函数返回值签名为 Result ,返回请求包大小
• content_type():该函数返回值签名为 Result <&str>, Error>,返回content_type字段内容
• content_type_bytes():该函数返回值签名为 Result <&[u8]>, Error>,返回content_type字段内容，以字节为单位
• os_errno():该函数返回值签名为 Result ,返回最后一次连接失败时的错误号
• primary_ip():该函数返回值签名为 Result <&str>, Error>,返回最后一次连接的ip地址
• primary_port():该函数返回值签名为 Result ,返回最后一次连接的目的端口
• local_ip():该函数返回值签名为 Result <&str>, Error>,返回最后一次连接的本地ip地址
• 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指针

实例：

• 实现了Send实例
• 实现了Drop实例

模块enums：

• HttpVersion
• InfoType
• IpResolve
• NetRc
• ProxyType
• ReadError
• SeekResult
• SslVersion
• TimeCondition
• WriteError

3.multi模块

详情见：api中文化之Rust-curl（下）

以上就是本文的全部内容，希望对大家的学习有所帮助，也希望大家多多支持 码农网

查看所有标签

猜你喜欢:

• FriceEngine试用与API中文化
• 草蟒 12 月更新：核心功能文档和坑属性/方法完成中文化
• 草蟒完成操作系统模块，谈谈 python os 模块的中文化

本站部分资源来源于网络，本站转载出于传递更多信息之目的，版权归原作者或者来源机构所有，如转载稿涉及版权问题，请联系我们。