httpc
httpc
模块
httpc
模块摘要
HTTP/1.1客户端
描述
此模块向 HTTP/1.1兼容客户端提供 APIRFC 2616不支持缓存。
注意
启动Inets应用程序时，会启动默认配置文件的管理器进程。此 API 中未明确使用配置文件的功能会访问默认配置文件。配置文件会跟踪代理选项，Cookie 以及可应用于多个请求的其他选项。
如果该计划https被使用时，SSL必须启动应用程序。何时https链接需要通过代理，连接方法扩展到 HTTP-#number0#用于建立隧道，然后将连接升级到 tls。然而，根据RFC 2817不支持。
只有在设置管道超时时才使用流水线，否则使用不使用流水线的持久连接。也就是说，客户端总是在发送下一个请求之前等待上一个响应。
中提供了一些示例。Inets User's Guide。
数据类型
在此模块中多次使用的类型定义：
boolean() = true | false
string()=ASCII 字符列表
request_id() = reference()
profile() = atom()
path() = string()表示文件路径或目录路径。
ip_address()=见inet(3)内核中的手册页。
socket_opt()=请参阅使用的选项gen_tcp(3) gen_tcp(3)和ssl(3)连接（s）
http 数据类型
与 HTTP相关的类型定义：
method() = head | get | put | post | trace | options | delete | patch
request()
={url(), headers()}
|{url(), headers(), content_type(), body()}
url() = string()中的 URI 定义的语法。RFC 2396，例如"http://www.erlang.org"
status_line() = {http_version(), status_code(), reason_phrase()}
http_version() = string()例如，"HTTP/1.1"
status_code() = integer()
reason_phrase() = string()
content_type() = string()
headers() = [header()]
header() = {field(), value()}
field() = string()
value() = string()
body()
=string() | binary()
|{fun(accumulator())
-> body_processing_result(), accumulator()}
|{chunkify, fun(accumulator())
-> body_processing_result(), accumulator()}
body_processing_result() = eof | {ok, iolist(), accumulator()}
accumulator() = term()
filename() = string()
有关 HTTP 的更多信息，请参阅RFC 2616。
SSL 数据类型
查看ssl(3)有关SSL选项（ssloptions()）的信息。
http 客户端服务的启动/停止
可以将 HTTP 客户端配置为在启动Inets应用程序或通过调用Inets应用 APIinets:start(httpc, ServiceConfig)或inets:start(httpc, ServiceConfig, How)，见inets(3)配置选项如下：
{profile，profile（）}
配置文件的名称，请参见DATA TYPES.这一选择是强制性的。
{data_dir，path（）}
配置文件可以保存持久性数据的目录。如果省略，则所有 Cookie 都被视为会话 Cookie。
客户端可以使用inets:stop(httpc, Pid)或inets:stop(httpc, Profile)。
出口
cancel_request(RequestId) ->cancel_request(RequestId, Profile) -> ok
类型
启动时stand_alone只能使用 pid。
取消异步 HTTP 请求。请注意，这并不保证请求响应不被传递。因为它是异步的，所以当取消到达时，请求可能已经完成了。
cookie_header(Url) ->cookie_header(Url, Profile | Opts) -> header() | {error, Reason}cookie_header(Url, Opts, Profile) -> header() | {error, Reason}
类型
When started `stand_alone`.
返回在向Url使用剖面Profile如果未指定配置文件，则使用默认配置文件。
选项ipv6_host_with_bracket处理如何解析 IPv6 地址。有关详细信息，请参阅说法Options的request/[4,5]。
get_options(OptionItems) -> {ok, Values} | {error, Reason}get_options(OptionItems, Profile) -> {ok, Values} | {error, Reason}
类型
When started `stand_alone` only the pid can used.
检索客户端当前使用的选项。
info() -> list()info(Profile) -> list()
类型
当开始stand_alone只能使用 PID。
生成杂项信息列表。用于调试。如果未指定配置文件，则使用默认配置文件。
reset_cookies() -> void()reset_cookies(Profile) -> void()
类型
当开始stand_alone只能使用 PID。
重置（清除）指定的 cookie 数据库Profile。如果未指定配置文件，则使用默认配置文件。
request(Url) ->request(Url, Profile) -> {ok, Result} | {error, Reason}
类型
When started `stand_alone` only the pid can be used.
相当于httpc:request(get, {Url, []}, [], [])。
request(Method, Request, HTTPOptions, Options) ->request(Method, Request, HTTPOptions, Options, Profile) -> {ok, Result} | {ok, saved_to_file} | {error, Reason}
类型
When started `stand_alone` only the pid can be used.
发送 HTTP 请求。该函数可以是同步的，也可以是异步的。在后一种情况下，函数返回{ok, RequestId}然后将信息传递给receiver取决于这个价值。
HTTP 选项（http_option()）的详细信息：
timeout
请求的暂停时间。
当发送请求时，时钟开始滴答作响。
时间以毫秒为单位。
默认是infinity。
connect_timeout
连接超时时间，当客户端是连接到服务器。
时间以毫秒为单位。
默认值是选项的值timeout。
ssl
这是SSL/TLS连接素配置选项。
默认为[].见ssl:connect/[2,3,4]可供选择。
autoredirect
客户端自动从新 URI 获取信息并返回结果，而不是 30X 结果代码。
对于某些30X 结果代码，不允许自动重定向。在这些情况下，总是返回30X 结果。
默认是true。
proxy_auth
使用提供的用户名和密码的代理 - 授权标题被添加到请求中。
version
可用于使客户端充当HTTP/1.0或HTTP/0.9客户。默认情况下，这是一个HTTP/1.1客户。使用时HTTP/1.0不使用持久连接。
默认是字符串"HTTP/1.1"。
relaxed
如果设置为true，则启用已知服务器与 HTTP 标准偏差的解决方法。
默认是false。
url_encode
应用百分比编码，也称为 URL 编码。
默认值是false...
Option（option()）详细信息：
sync
选项，使请求是同步的或异步的。
默认是true。
stream
将200或206响应的主体流到调用进程或文件。当使用选项流到调用进程时self，将向该进程发送以下流消息：{http, {RequestId, stream_start, Headers}}, {http, {RequestId, stream, BinBodyPart}}, and {http, {RequestId, stream_end, Headers}}...
当使用选项流向调用进程时{self, once}，第一条消息有一个额外的元素，即{http, {RequestId, stream_start, Headers, Pid}}。这是要用作参数httpc:stream_next/1来触发下一条消息发送到调用进程的进程标识。
请注意，分块编码可以添加标题，以便stream_end消息中的标题比标题更多stream_start。当流式传输到文件并且请求异步时，{http, {RequestId, saved_to_file}}会发送消息。
默认是none。
body_format
定义主体是以字符串还是二进制形式传递的。此选项仅对同步请求有效。
默认是string。
full_result
定义是否要将“完整结果”返回给调用者（即，主体，标题和整个状态行）或不是（主体和状态代码）。
默认是true。
headers_as_is
定义用户提供的标头是小写还是区分大小写。
HTTP 标准要求它们不区分大小写。只有在没有其他方法与服务器通信或用于测试目的时，才使用此功能。使用此选项时，将不会自动添加任何标头。所有必要的标头必须由用户提供。
默认是false。
socket_opts
套接字选项将用于此请求和后续请求。
覆盖由set_options函数设置的任何值
这些选项的有效性并未被 HTTP 客户端检查，而是被认为是正确的，并被传递给 ssl 应用程序和 inet 驱动程序，如果它们不正确，可能会拒绝它们。请注意，当前实现假定对同一主机的请求，端口组合将使用相同的套接字选项。
默认情况下，套接字选项按函数设置。set_options/[1,2]在建立连接时使用。
receiver
定义客户端如何传递异步请求的结果（sync具有值false）。
pid()
消息以格式发送到此进程{http, ReplyInfo}。
function/1
通过调用提供的乐趣将信息传递给接收者Receiver(ReplyInfo)。
{Module, Function, Args}
通过调用回调函数将信息传递给接收者apply(Module, Function, [ReplyInfo | Args])。
在所有这些案例中，ReplyInfo有以下结构：
{RequestId, saved_to_file}
{RequestId, {error, Reason}}
{RequestId, Result}
{RequestId, stream_start, Headers}
{RequestId, stream_start, Headers, HandlerPid}
{RequestId, stream, BinBodyPart}
{RequestId, stream_end, Headers}
缺省值是pid调用请求函数（self()）的进程。
ipv6_host_with_brackets
定义何时使用带括号的IPv6地址解析URI的主机端口部分，如果这些括号要保留（true）或剥离（false）。
默认是false。
set_options(Options) ->set_options(Options, Profile) -> ok | {error, Reason}
类型
示例：“localhost”或“foo.bar.se”
示例：8080
例如：“* .ericsson.se”
Example: "134.138" or "[FEDC:BA98" (all IP addresses starting with 134.138 or FEDC:BA98), "66.35.250.150" or "2010:836B:4179::836B:4179" (a complete IP address). proxy defaults to {undefined, []}, that is, no proxy is configured and https_proxy defaults to the value of proxy. Maximum number of persistent connections to a host. Default is 2. Maximum number of outstanding requests on the same connection to a host. Default is 5. If a persistent connection is idle longer than the keep_alive_timeout in milliseconds, the client closes the connection. The server can also have such a time-out but do not take that for granted. Default is 120000 (= 2 min). Maximum number of outstanding requests on a pipelined connection to a host. Default is 2。如果持续连接空闲时间超过pipeline_timeout以毫秒为单位，则客户端将关闭连接。缺省值是0，这会导致不使用流水线。如果启用了Cookie，则所有有效的Cookie都会自动保存在客户经理的Cookie数据库中。如果使用选项verify，store_cookies/2则必须调用函数才能保存cookie。默认是disabled。默认是inet。如果主机有多个网络接口，则此选项指定要使用哪一个。详情请参阅gen_tcp:connect/3,4。使用本地端口号。详情请参阅gen_tcp:connect/3,4。这些选项会附加到客户端使用的套接字选项。这些是新的请求处理程序启动时的默认值（用于初始连接）。它们被直接传递到底层交通工具（gen_tcp或者SSL）未经验证。默认是false。该选项用于在客户端上打开（或关闭）不同级别的Erlang跟踪。这是一个调试功能。启动时stand_alone只能使用pid。
设置用于后续请求的选项。
注意
如果可能，客户端将保持其连接活动，并根据配置和当前环境使用具有或不含管道的持久连接。HTTP/1.1规范没有提供关于在持久连接上发送多少请求的指导方针。这在很大程度上取决于应用程序。
长时间的请求队列可能会导致用户感知延迟，因为以前的请求可能需要很长时间才能完成。HTTP / 1.1规范建议每个服务器有两个持久连接的限制，这是选项的默认值max_sessions。
store_cookies(SetCookieHeaders, Url) ->store_cookies(SetCookieHeaders, Url, Profile) -> ok | {error, Reason}
类型
When started `stand_alone` only the pid can be used.
保存SetCookieHeaders在客户端配置文件cookie数据库中。调用此函数如果选项cookies设置为verify如果未指定配置文件，则使用默认配置文件。
stream_next(Pid) -> ok
类型
stream_start message中收到的
触发要流的下一条消息，即与套接字的活动消息相同的行为。
which_cookies() -> cookies()which_cookies(Profile) -> cookies()
类型
何时开始stand_alone只能使用PID。
生成整个Cookie数据库的列表。用于调试/测试目的。如果未指定配置文件，则使用默认配置文件。
which_sessions() -> session_info()which_sessions(Profile) -> session_info()
类型
何时开始stand_alone只能使用PID。
生成会话数据库的稍微处理的转储。它用于调试。如果未指定配置文件，则使用默认配置文件。
另见
RFC 2616，inets(3)，gen_tcp(3)，ssl(3)
