Behaviours: application.
Authors: Oscar Hellström (oscar@hellstrom.st).
request/4
, request/5
and request/6
functions.
body() = binary() | undefined | pid()
bodypart() = iodata() | http_eob
destination() = {string(), pos_integer(), boolean()}
header() = 'Cache-Control' | 'Connection' | 'Date' | 'Pragma' | 'Transfer-Encoding' | 'Upgrade' | 'Via' | 'Accept' | 'Accept-Charset' | 'Accept-Encoding' | 'Accept-Language' | 'Authorization' | 'From' | 'Host' | 'If-Modified-Since' | 'If-Match' | 'If-None-Match' | 'If-Range' | 'If-Unmodified-Since' | 'Max-Forwards' | 'Proxy-Authorization' | 'Range' | 'Referer' | 'User-Agent' | 'Age' | 'Location' | 'Proxy-Authenticate' | 'Public' | 'Retry-After' | 'Server' | 'Vary' | 'Warning' | 'Www-Authenticate' | 'Allow' | 'Content-Base' | 'Content-Encoding' | 'Content-Language' | 'Content-Length' | 'Content-Location' | 'Content-Md5' | 'Content-Range' | 'Content-Type' | 'Etag' | 'Expires' | 'Last-Modified' | 'Accept-Ranges' | 'Set-Cookie' | 'Set-Cookie2' | 'X-Forwarded-For' | 'Cookie' | 'Keep-Alive' | 'Proxy-Connection' | binary() | string()
headers() = [{header(), iodata()}]
host() = string() | {integer(), integer(), integer(), integer()}
http_status() = {integer(), string() | binary()} | {nil, nil}
method() = string() | atom()
option() = {connect_options, socket_options()} | {connect_timeout, timeout()} | {partial_download, [partial_download_option()]} | {partial_upload, non_neg_integer() | infinity} | {pool, pid() | atom()} | {pool_connection_timeout, non_neg_integer()} | {pool_ensure, boolean()} | {pool_max_size, non_neg_integer() | infinity} | {proxy, string()} | {proxy_ssl_options, socket_options()} | {send_retry, non_neg_integer()} | {use_pool, boolean()} | {verify_ssl_cert, boolean()}
options() = [option()]
partial_download_option() = {window_size, window_size()} | {part_size, non_neg_integer() | infinity}
pool_id() = pid() | atom()
poolsize() = non_neg_integer() | atom()
port_num() = 1..65535
pos_timeout() = pos_integer() | infinity
result() = {ok, {{pos_integer(), string()}, headers(), body()}} | {ok, upload_state()} | {error, term()}
socket() = term()
socket_options() = [{atom(), term()} | atom()]
upload_state() = {pid(), window_size()}
window_size() = non_neg_integer() | infinity
add_pool/1 | Add a new named httpc_manager pool to the supervisor tree. |
add_pool/2 | Add a new httpc_manager to the supervisor tree. |
add_pool/3 | Add a new httpc_manager to the supervisor tree. |
delete_pool/1 | Delete a pool. |
get_body_part/1 | Reads a body part from an ongoing response when
{partial_download, PartialDownloadOptions} is used. |
get_body_part/2 | Reads a body part from an ongoing response when
{partial_download, PartialDownloadOptions} is used. |
request/4 | Sends a request without a body. |
request/5 | Sends a request with a body. |
request/6 | Sends a request with a body. |
request/9 | Sends a request with a body. |
send_body_part/2 | Sends a body part to an ongoing request when
{partial_upload, WindowSize} is used. |
send_body_part/3 | Sends a body part to an ongoing request when
{partial_upload, WindowSize} is used. |
send_trailers/2 | Sends trailers to an ongoing request when {partial_upload,
WindowSize} is used and no Content-Length was specified. |
send_trailers/3 | Sends trailers to an ongoing request when
{partial_upload, WindowSize} is used and no Content-Length was
specified. |
start/0 | Start the application. |
stop/0 | Stops the application. |
add_pool(Name::atom()) -> {ok, pid()} | {error, already_exists | term()}
Add a new named httpc_manager pool to the supervisor tree
add_pool(Name::atom(), ConnTimeout::pos_integer()) -> {ok, pid()} | {error, already_exists | term()}
Add a new httpc_manager to the supervisor tree
add_pool(Name::atom(), ConnTimeout::non_neg_integer(), PoolSize::poolsize()) -> {ok, pid()} | {error, already_exists | term()}
Add a new httpc_manager to the supervisor tree
delete_pool(PoolPid::atom() | pid()) -> ok
Delete a pool
get_body_part(Pid::pid()) -> {ok, binary()} | {ok, {http_eob, headers()}} | {error, term()}
Reads a body part from an ongoing response when
{partial_download, PartialDownloadOptions}
is used. The default timeout,
infinity
will be used.
Would be the same as calling
get_body_part(HTTPClient, infinity)
.
get_body_part(Pid::pid(), Timeout::timeout()) -> {ok, binary()} | {ok, {http_eob, headers()}} | {error, term()}
Reads a body part from an ongoing response when
{partial_download, PartialDownloadOptions}
is used.
Timeout
is the timeout for reading the next body part in milliseconds.
http_eob
marks the end of the body. If there were Trailers in the
response those are returned with http_eob
as well.
If it evers returns an error, no further calls to this function should
be done.
request(URL::string(), Method::method(), Hdrs::headers(), Timeout::pos_timeout()) -> result()
Sends a request without a body.
Would be the same as calling request/5
with an empty body,
request(URL, Method, Hdrs, [], Timeout)
or
request(URL, Method, Hdrs, <<>>, Timeout)
.
See also: request/9.
request(URL::string(), Method::method(), Hdrs::headers(), Body::iodata(), Timeout::pos_timeout()) -> result()
Sends a request with a body.
Would be the same as calling request/6
with no options,
request(URL, Method, Hdrs, Body, Timeout, [])
.
See also: request/9.
request(URL::string(), Method::method(), Hdrs::headers(), Body::iodata(), Timeout::pos_timeout(), Options::options()) -> result()
Sends a request with a body. Would be the same as calling
#lhttpc_url{host = Host, port = Port, path = Path, is_ssl = Ssl} = lhttpc_lib:parse_url(URL), request(Host, Port, Path, Ssl, Method, Hdrs, Body, Timeout, Options).
URL
is expected to be a valid URL:
scheme://host[:port][/path]
.
See also: request/9.
request(Host::string(), Port::port_num(), Ssl::boolean(), Path::string(), Method::method(), Hdrs::headers(), Body::iodata(), Timeout::pos_timeout(), Options::options()) -> result()
Sends a request with a body.
Instead of building and parsing URLs the target server is specified with
a host, port, weither SSL should be used or not and a path on the server.
For instance, if you want to request http://example.com/foobar you would
use the following:
Host
= "example.com"
Port
= 80
Ssl
= false
Path
= "/foobar"
Path
must begin with a forward slash /
.
Method
is either a string, stating the HTTP method exactly as in the
protocol, i.e: "POST"
or "GET"
. It could also be an atom, which is
then coverted to an uppercase (if it isn't already) string.
Hdrs
is a list of headers to send. Mandatory headers such as
Host
, Content-Length
or Transfer-Encoding
(for some requests)
are added automatically.
Body
is the entity to send in the request. Please don't include entity
bodies where there shouldn't be any (such as for GET
).
Timeout
is the timeout for the request in milliseconds.
Options
is a list of options.
Options:
{connect_timeout, Milliseconds}
specifies how many milliseconds the
client can spend trying to establish a connection to the server. This
doesn't affect the overall request timeout. However, if it's longer than
the overall timeout it will be ignored. Also note that the TCP layer my
choose to give up earlier than the connect timeout, in which case the
client will also give up. The default value is infinity, which means that
it will either give up when the TCP stack gives up, or when the overall
request timeout is reached.
{connect_options, Options}
specifies options to pass to the socket at
connect time. This makes it possible to specify both SSL options and
regular socket options, such as which IP/Port to connect from etc.
Some options must not be included here, namely the mode, binary
or list
, {active, boolean()}
, {active, once}
or {packet, Packet}
.
These options would confuse the client if they are included.
Please note that these options will only have an effect on *new*
connections, and it isn't possible for different requests
to the same host uses different options unless the connection is closed
between the requests. Using HTTP/1.0 or including the "Connection: close"
header would make the client close the connection after the first
response is received.
{send_retry, N}
specifies how many times the client should retry
sending a request if the connection is closed after the data has been
sent. The default value is 1
. If {partial_upload, WindowSize}
(see below) is specified, the client cannot retry after the first part
of the body has been sent since it doesn't keep the whole entitity body
in memory.
{partial_upload, WindowSize}
means that the request entity body will be
supplied in parts to the client by the calling process. The WindowSize
specifies how many parts can be sent to the process controlling the socket
before waiting for an acknowledgement. This is to create a kind of
internal flow control if the network is slow and the client process is
blocked by the TCP stack. Flow control is disabled if WindowSize
is
infinity
. If WindowSize
is an integer, it must be >= 0. If partial
upload is specified and no Content-Length
is specified in Hdrs
the
client will use chunked transfer encoding to send the entity body.
If a content length is specified, this must be the total size of the entity
body.
The call to request/6
will return {ok, UploadState}
. The
UploadState
is supposed to be used as the first argument to the send_body_part/2
or send_body_part/3
functions to send body parts.
Partial upload is intended to avoid keeping large request bodies in
memory but can also be used when the complete size of the body isn't known
when the request is started.
{partial_download, PartialDownloadOptions}
means that the response body
will be supplied in parts by the client to the calling process. The partial
download option {window_size, WindowSize}
specifies how many part will be
sent to the calling process before waiting for an acknowledgement. This is
to create a kind of internal flow control if the calling process is slow to
process the body part and the network and server are considerably faster.
Flow control is disabled if WindowSize
is infinity
. If WindowSize
is an integer it must be >=0. The partial download option {part_size,
PartSize}
specifies the size the body parts should come in. Note however
that if the body size is not determinable (e.g entity body is termintated
by closing the socket) it will be delivered in pieces as it is read from
the wire. There is no caching of the body parts until the amount reaches
body size. If the body size is bounded (e.g Content-Length
specified or
Transfer-Encoding: chunked
specified) it will be delivered in PartSize
pieces. Note however that the last piece might be smaller than PartSize
.
Size bounded entity bodies are handled the same way as unbounded ones if
PartSize
is infinity
. If PartSize
is integer it must be >= 0.
If {partial_download, PartialDownloadOptions}
is specified the
ResponseBody
will be a pid()
unless the response has no body
(for example in case of HEAD
requests). In that case it will be be
undefined
. The functions get_body_part/1
and
get_body_part/2
can be used to read body parts in the calling
process.
{proxy, ProxyUrl}
if this option is specified, a proxy server is used as
an intermediary for all communication with the destination server. The link
to the proxy server is established with the HTTP CONNECT method (RFC2817).
Example value: {proxy, "http://john:doe@myproxy.com:3128"}
{proxy_ssl_options, SslOptions}
this is a list of SSL options to use for
the SSL session created after the proxy connection is established. For a
list of all available options, please check OTP's ssl module manpage.
send_body_part(X1::upload_state(), IoList::bodypart()) -> result()
Sends a body part to an ongoing request when
{partial_upload, WindowSize}
is used. The default timeout, infinity
will be used. Notice that if WindowSize
is infinity, this call will never
block.
Would be the same as calling
send_body_part(UploadState, BodyPart, infinity)
.
send_body_part(X1::upload_state(), IoList::bodypart(), Timeout::timeout()) -> result()
Sends a body part to an ongoing request when
{partial_upload, WindowSize}
is used.
Timeout
is the timeout for the request in milliseconds.
If the window size reaches 0 the call will block for at maximum Timeout
milliseconds. If there is no acknowledgement received during that time the
the request is cancelled and {error, timeout}
is returned.
As long as the window size is larger than 0 the function will return immediately after sending the body part to the request handling process.
TheBodyPart
http_eob
signals an end of the entity body, the request
is considered sent and the response will be read from the socket. If
there is no response within Timeout
milliseconds, the request is
canceled and {error, timeout}
is returned.
send_trailers(X1::{pid(), window_size()}, Trailers::headers()) -> result()
Sends trailers to an ongoing request when {partial_upload,
WindowSize}
is used and no Content-Length
was specified. The default
timout infinity
will be used. Plase note that after this the request is
considered complete and the response will be read from the socket.
Would be the same as calling
send_trailers(UploadState, BodyPart, infinity)
.
send_trailers(X1::{pid(), window_size()}, Trailers::headers(), Timeout::timeout()) -> result()
Sends trailers to an ongoing request when
{partial_upload, WindowSize}
is used and no Content-Length
was
specified.
Timeout
is the timeout for sending the trailers and reading the
response in milliseconds.
Timeout
milliseconds the request is canceled and {error, timeout}
is
returned.
start() -> ok | {error, any()}
Start the application.
This is a helper function that will call application:start(lhttpc)
to
allow the library to be started using the -s
flag.
For instance:
$ erl -s crypto -s ssl -s lhttpc
application
module.
stop() -> ok | {error, any()}
Stops the application.
This is a helper function that will call application:stop(lhttpc)
.
application
module.
Generated by EDoc