cancel_request(RequestId) -> ok
cancel_request(RequestId, Profile) -> ok
Types:
RequestId = any()
A unique identifier as returned by request/4
Profile = atom() | pid()
When started stand_alone only the pid can be used.
Cancels an asynchronous HTTP request. Notice that this does not
guarantee that the request response is not delivered. Because it is
asynchronous, the request can already have been completed when the
cancellation arrives.
cookie_header(Url) -> HttpHeader | {error, Reason}
cookie_header(Url, ProfileOrOpts) -> HttpHeader | {error, Reason}
Types:
Url = uri_string:uri_string()
HttpHeader = {Field :: [byte()], Value :: binary() | iolist()}
ProfileOrOpts = Profile | Opts
Profile = atom() | pid()
When started stand_alone only the pid can be used.
Opts = [CookieHeaderOpt]
CookieHeaderOpt = {ipv6_host_with_brackets, boolean()}
Reason = term()
Returns the cookie header that would have been sent when making a
request to Url using profile Profile. If no profile is
specified, the default profile is used.
Option ipv6_host_with_bracket deals with how to parse IPv6
addresses. For details, see argument Options of request/[4,5].
cookie_header(Url, Opts, Profile) -> HttpHeader | {error, Reason}
Types:
Url = uri_string:uri_string()
HttpHeader = {Field :: [byte()], Value :: binary() | iolist()}
Profile = atom() | pid()
When started stand_alone only the pid can be used.
Opts = [CookieHeaderOpt]
CookieHeaderOpt = {ipv6_host_with_brackets, boolean()}
Reason = term()
Returns the cookie header that would have been sent when making a
request to Url using profile Profile. If no profile is
specified, the default profile is used.
Option ipv6_host_with_bracket deals with how to parse IPv6
addresses. For details, see argument Options of request/[4,5].
get_options(OptionItems) -> {ok, Values} | {error, Reason}
get_options(OptionItems, Profile) ->
{ok, Values} | {error, Reason}
Types:
OptionItems = all | [OptionItem]
OptionItem =
proxy | https_proxy | max_sessions | keep_alive_timeout |
max_keep_alive_length | pipeline_timeout |
max_pipeline_length | cookies | ipfamily | ip | port |
socket_opts | verbose | unix_socket
Values = [{OptionItem, term()}]
Profile = atom() | pid()
When started stand_alone only the pid can be used.
Reason = term()
Retrieves the options currently used by the client.
info() -> list() | {error, Reason}
info(Profile) -> list() | {error, Reason}
Types:
Reason = term()
Profile = atom() | pid()
When started stand_alone only the pid can be used.
Produces a list of miscellaneous information. Intended for
debugging. If no profile is specified, the default profile is used.
reset_cookies() -> Void
reset_cookies(Profile) -> Void
Types:
Profile = atom() | pid()
When started stand_alone only the pid can be used.
Void = term()
Resets (clears) the cookie database for the specified
Profile. If no profile is specified the default profile is used.
request(Url :: uri_string:uri_string()) ->
{ok, Result} | {error, term()}
request(Url, Profile) -> {ok, Result} | {error, term()}
Types:
Url = uri_string:uri_string()
Profile = atom() | pid()
When started stand_alone only the pid can be used.
Result =
{StatusLine, [HttpHeader], HttpBodyResult} |
{StatusCode, HttpBodyResult} |
RequestId | saved_to_file
HttpHeader = {Field :: [byte()], Value :: binary() | iolist()}
HttpBodyResult = uri_string:uri_string() | binary()
StatusLine = {HttpVersion, StatusCode, string()}
HttpVersion = uri_string:uri_string()
StatusCode = integer() >= 0
RequestId = any()
Equivalent to httpc:request(get, {Url, []}, [], []).
request(Method, Request, HttpOptions, Options) ->
{ok, Result} | {error, term()}
request(Method, Request, HttpOptions, Options, Profile) ->
{ok, Result} | {error, term()}
Types:
Method =
head | get | put | patch | post | trace | options | delete
Request =
{uri_string:uri_string(), [HttpHeader]} |
{uri_string:uri_string(),
[HttpHeader],
ContentType :: uri_string:uri_string(),
HttpBody}
HttpBody =
iolist() |
binary() |
{fun((Accumulator :: term()) ->
eof | {ok, iolist(), Accumulator :: term()}),
Accumulator :: term()} |
{chunkify,
fun((Accumulator :: term()) ->
eof | {ok, iolist(), Accumulator :: term()}),
Accumulator :: term()}
HttpHeader = {Field :: [byte()], Value :: binary() | iolist()}
HttpOptions = [HttpOption]
HttpOption =
{timeout, timeout()} |
{connect_timeout, timeout()} |
{ssl, [ssl:tls_option()]} |
{autoredirect, boolean()} |
{proxy_auth, {string(), string()}} |
{version, HttpVersion} |
{relaxed, boolean()}
Options = [OptionRequest]
OptionRequest =
{sync, boolean()} |
{stream, StreamTo} |
{body_format, BodyFormat} |
{full_result, boolean()} |
{headers_as_is, boolean()} |
{socket_opts, [SocketOpt]} |
{receiver, Receiver} |
{ipv6_host_with_brackets, boolean()}
StreamTo = none | self | {self, once} | file:name_all()
BodyFormat = string() | binary() | atom()
SocketOpt = term()
Receiver =
pid() |
fun((term()) -> term()) |
{ReceiverModule :: atom(),
ReceiverFunction :: atom(),
ReceiverArgs :: list()}
Profile = atom() | pid()
When Profile is stand_alone only the pid can be used.
HttpVersion = uri_string:uri_string()
Result =
{StatusLine, [HttpHeader], HttpBodyResult} |
{StatusCode, HttpBodyResult} |
RequestId | saved_to_file
StatusLine = {HttpVersion, StatusCode, string()}
StatusCode = integer() >= 0
HttpBodyResult = uri_string:uri_string() | binary()
RequestId = any()
Sends an HTTP request. The function can be both synchronous and
asynchronous. In the latter case, the function returns {ok,
RequestId} and then the information is delivered to the receiver
depending on that value.
When Profile is stand_alone only the pid can be
used.
HTTP options:
- timeout:
- Time-out time for the request.
The clock starts ticking when the request is sent.
- connect_timeout:
- Connection time-out time, used during the initial request, when the client
is connecting to the server.
Default is the value of option timeout.
- ssl:
- This is the SSL/TLS connecting configuration option.
Defaults to []. See ssl:connect/[2,3,4] for available
options.
- autoredirect:
- The client automatically retrieves the information from the new URI and
returns that as the result, instead of a 30X-result code.
For some 30X-result codes, automatic redirect is not allowed. In
these cases the 30X-result is always returned.
- proxy_auth:
- A proxy-authorization header using a tuple where the first element is the
username and the second element of the tuple is the password
added to the request.
- version:
- Can be used to make the client act as an HTTP/1.0 client. By
default this is an HTTP/1.1 client. When using HTTP/1.0
persistent connections are not used.
Default is the string "HTTP/1.1".
- relaxed:
- If set to true, workarounds for known server deviations from the
HTTP-standard are enabled.
Options details:
- sync:
- Option for the request to be synchronous or asynchronous.
- stream:
- Streams the body of a 200 or 206 response to the calling process or to a
file. When streaming to the calling process using option self, the
following stream messages are sent to that process: {http, {RequestId,
stream_start, Headers}}, {http, {RequestId, stream, BinBodyPart}}, and
{http, {RequestId, stream_end, Headers}}.
When streaming to the calling processes using option {self,
once}, the first message has an extra element, that is, {http,
{RequestId, stream_start, Headers, Pid}}. This is the process id to be
used as an argument to httpc:stream_next/1 to trigger the next
message to be sent to the calling process.
Notice that chunked encoding can add headers so that there are
more headers in the stream_end message than in stream_start.
When streaming to a file and the request is asynchronous, the message
{http, {RequestId, saved_to_file}} is sent.
- body_format:
- Defines if the body is to be delivered as a string or binary. This option
is only valid for the synchronous request.
- full_result:
- Defines if a "full result" is to be returned to the caller (that
is, the body, the headers, and the entire status line) or not (the body
and the status code).
- Defines if the headers provided by the user are to be made lower case or
to be regarded as case sensitive.
The HTTP standard requires them to be case insensitive. Use this
feature only if there is no other way to communicate with the server or for
testing purpose. When this option is used, no headers are automatically
added. All necessary headers must be provided by the user.
- socket_opts:
- Socket options to be used for this request.
Overrides any value set by function set_options.
The validity of the options is not checked by the HTTP
client they are assumed to be correct and passed on to ssl application and
inet driver, which may reject them if they are not correct.
Note:
Persistent connections are not supported when setting the
socket_opts
option. When
socket_opts is not set the current implementation assumes
the requests to the same host, port combination will use the same socket
options.
By default the socket options set by function set_options/[1,2]
are used when establishing a connection.
- receiver:
- Defines how the client delivers the result of an asynchronous request
(sync has the value false).
- pid():
- Messages are sent to this process in the format {http,
ReplyInfo}.
- function/1:
- Information is delivered to the receiver through calls to the provided fun
Receiver(ReplyInfo).
- {Module, Function, Args}:
- Information is delivered to the receiver through calls to the callback
function apply(Module, Function, [ReplyInfo | Args]).
In all of these cases, ReplyInfo has the following
structure:
{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}
Default is the pid of the process calling the request
function (self()).
- ipv6_host_with_brackets:
- Defines when parsing the Host-Port part of an URI with an IPv6 address
with brackets, if those brackets are to be retained (true) or
stripped (false).
set_options(Options) -> ok | {error, Reason}
set_options(Options, Profile) -> ok | {error, Reason}
Types:
Options = [Option]
Option =
{proxy, {Proxy, NoProxy}} |
{https_proxy, {Proxy, NoProxy}} |
{max_sessions, MaxSessions} |
{max_keep_alive_length, MaxKeepAlive} |
{keep_alive_timeout, KeepAliveTimeout} |
{max_pipeline_length, MaxPipeline} |
{pipeline_timeout, PipelineTimeout} |
{cookies, CookieMode} |
{ipfamily, IpFamily} |
{ip, IpAddress} |
{port, Port} |
{socket_opts, [SocketOpt]} |
{verbose, VerboseMode} |
{unix_socket, UnixSocket}
Profile = atom() | pid()
SocketOpt = term()
Proxy = {HostName, Port}
Port = integer() >= 0
NoProxy = [DomainDesc | HostName | IpAddressDesc]
MaxSessions = MaxKeepAlive = KeepAliveTimeout = MaxPipeline = PipelineTimeout =
integer()
CookieMode = enabled | disabled | verify
IpFamily = inet | inet6 | local | inet6fb4
IpAddressDesc = uri_string:uri_string()
IpAddress = inet:ip_address()
VerboseMode = false | verbose | debug | trace
UnixSocket = string()
Reason = term()
DomainDesc = string()
HostName = uri_string:uri_string()
Sets options to be used for subsequent requests.
- HostName:
-
Example: "localhost" or "foo.bar.se"
- DomainDesc:
-
Example "*.Domain" or
"*.ericsson.se"
- IpAddressDesc:
-
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.
- MaxSessions:
- MaxSessions Maximum number of persistent connections to a host.
Default is 2.
- MaxKeepAlive:
- MaxKeepAlive Maximum number of outstanding requests on the same
connection to a host. Default is 5.
- KeepAliveTimeout:
- KeepAliveTimeout 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).
- MaxPipeline:
- MaxPipeline Maximum number of outstanding requests on a pipelined
connection to a host. Default is 2.
- PipelineTimeout:
- PipelineTimeout If a persistent connection is idle longer than the
pipeline_timeout in milliseconds, the client closes the connection.
Default is 0, which results in pipelining not being used.
- CookieMode:
-
If cookies are enabled, all valid cookies are automatically saved in the
cookie database of the client manager. If option verify is used,
function store_cookies/2 has to be called for the cookies to be
saved. Default is disabled.
- IpFamily:
-
Default is inet. With inet6fb4 option, IPv6 will be preferred
but if connection fails, an IPv4 fallback connection attempt will be
made.
- IpAddress:
-
If the host has several network interfaces, this option specifies which one
to use. See gen_tcp:connect/3,4 for details.
- Port:
-
Example: 8080. Local port number to use. See gen_tcp:connect/3,4 for
details.
- SocketOpts:
-
The options are appended to the socket options used by the client. These
are the default values when a new request handler is started (for the
initial connect). They are passed directly to the underlying transport
(gen_tcp or SSL) without verification.
- VerboseMode:
-
Default is false. This option is used to switch on (or off)
different levels of Erlang trace on the client. It is a debug
feature.
- Profile:
-
When started stand_alone only the pid can be used.
- UnixSocket:
-
Experimental option for sending HTTP requests over a unix domain socket.
The value of unix_socket shall be the full path to a unix domain
socket file with read/write permissions for the erlang process. Default is
undefined.
Note:
If possible, the client keeps its connections alive and uses persistent
connections with or without pipeline depending on configuration and current
circumstances. The HTTP/1.1 specification does not provide a guideline for how
many requests that are ideal to be sent on a persistent connection. This
depends much on the application.
A long queue of requests can cause a user-perceived delay, as
earlier requests can take a long time to complete. The HTTP/1.1
specification suggests a limit of two persistent connections per server,
which is the default value of option max_sessions.
The current implementation assumes the requests to the same host,
port combination will use the same socket options.
ssl_verify_host_options(WildcardHostName) -> list()
Types:
WildcardHostName = boolean()
Returns ssl options which can be used to verify the host, uses
public_key:cacerts_get() to read CA certicates and if
WildcardHostName is true adds the hostname check from
public_key:public_key:pkix_verify_hostname_match_fun(https) to the
options.
store_cookies(SetCookieHeaders, Url) -> ok | {error, Reason}
store_cookies(SetCookieHeaders, Url, Profile) ->
ok | {error, Reason}
Types:
SetCookieHeaders = [HttpHeader]
Where field = "set-cookie"
HttpHeader = {Field :: [byte()], Value :: binary() | iolist()}
Url = term()
Profile = atom() | pid()
When started stand_alone only the pid can be used.
Reason = term()
Saves the cookies defined in SetCookieHeaders in the client
profile cookie database. Call this function if option cookies is set
to verify. If no profile is specified, the default profile is
used.
stream_next(Pid) -> ok
Types:
Pid = pid()
As received in the stream_start message
Triggers the next message to be streamed, that is, the same
behavior as active ones for sockets.
which_cookies() -> [CookieStores]
which_cookies(Profile) -> [CookieStores]
Types:
Profile = atom() | pid()
When started stand_alone only the pid can be used.
CookieStores = {cookies, Cookies} | {session_cookies, Cookies}
Cookies = [term()]
Produces a list of the entire cookie database. Intended for
debugging/testing purposes. If no profile is specified, the default profile
is used.
which_sessions() -> SessionInfo
which_sessions(Profile) -> SessionInfo
Types:
Profile = atom() | pid()
When started stand_alone only the pid can be used.
SessionInfo = {GoodSession, BadSessions, NonSessions}
GoodSession = [Session]
BadSessions = NonSessions = [term()]
Session = term()
Internal representation of a session.
This function is intended for debugging only. It produces a
slightly processed dump of the session database. The first list of the
session information tuple will contain session information on an internal
format. The last two lists of the session information tuple should always be
empty if the code is working as intended. If no profile is specified, the
default profile is used.