lhttpc (lhttpc v4.3.2)
request/4
, request/5
and request/6
functions.
Summary
Functions
{partial_download, PartialDownloadOptions}
is used. The default timeout, infinity
will be used. Would be the same as calling get_body_part(HTTPClient, infinity)
.{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. #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.
Sends a request with a body.
{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)
.Sends a body part to an ongoing request when {partial_upload, WindowSize}
is used. Timeout
is the timeout for the request in milliseconds.
{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)
.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.
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
Stops the application. This is a helper function that will call application:stop(lhttpc)
.
Types
body/0
bodypart/0
-type bodypart() :: iodata() | http_eob.
destination/0
-type destination() :: {string(), pos_integer(), boolean()}.
header/0
-type 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/0
host/0
http_status/0
method/0
option/0
-type 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/0
-type options() :: [option()].
partial_download_option/0
-type partial_download_option() :: {window_size, window_size()} | {part_size, non_neg_integer() | infinity}.
pool_id/0
poolsize/0
-type poolsize() :: non_neg_integer() | atom().
port_num/0
-type port_num() :: 1..65535.
pos_timeout/0
-type pos_timeout() :: pos_integer() | infinity.
result/0
-type result() :: {ok, {{pos_integer(), string()}, headers(), body()}} | {ok, upload_state()} | {error, term()}.
socket/0
-type socket() :: _.
socket_options/0
upload_state/0
-type upload_state() :: {pid(), window_size()}.
window_size/0
-type window_size() :: non_neg_integer() | infinity.
Functions
add_pool(Name)
add_pool(Name, ConnTimeout)
-spec add_pool(atom(), pos_integer()) -> {ok, pid()} | {error, already_exists | term()}.
add_pool(Name, ConnTimeout, PoolSize)
-spec add_pool(atom(), non_neg_integer(), poolsize()) -> {ok, pid()} | {error, already_exists | term()}.
delete_pool(PoolPid)
get_body_part(Pid)
{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, Timeout)
-spec get_body_part(pid(), timeout()) -> {ok, binary()} | {ok, {http_eob, headers()}} | {error, term()}.
{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, Method, Hdrs, Timeout)
-spec request(string(), method(), headers(), pos_timeout()) -> result().
request/5
with an empty body, request(URL, Method, Hdrs, [], Timeout)
or request(URL, Method, Hdrs, <<>>, Timeout)
.See also: request/9.
request(URL, Method, Hdrs, Body, Timeout)
request/6
with no options, request(URL, Method, Hdrs, Body, Timeout, [])
.See also: request/9.
request(URL, Method, Hdrs, Body, Timeout, Options)
#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, Port, Ssl, Path, Method, Hdrs, Body, Timeout, Options)
-spec request(string(), port_num(), boolean(), string(), method(), headers(), iodata(), pos_timeout(), 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(_, IoList)
-spec send_body_part(upload_state(), bodypart()) -> result().
{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(_, IoList, Timeout)
-spec send_body_part(upload_state(), bodypart(), 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(_, Trailers)
-spec send_trailers({pid(), window_size()}, headers()) -> result().
{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(_, Trailers, Timeout)
-spec send_trailers({pid(), window_size()}, headers(), 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()
-spec 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.
start(_, _)
stop()
-spec stop() -> ok | {error, any()}.
Stops the application. This is a helper function that will call application:stop(lhttpc)
.
application
module.
stop(_)
-spec stop(any()) -> ok.