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)