Module lhttpc

Main interface to the lightweight http client.

Behaviours: application.

Authors: Oscar Hellström (oscar@hellstrom.st).

Description

Main interface to the lightweight http client. See request/4, request/5 and request/6 functions.

Data Types

body()

body() = binary() | undefined | pid()

bodypart()

bodypart() = iodata() | http_eob

destination()

destination() = {string(), pos_integer(), boolean()}

header()

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()

headers() = [{header(), iodata()}]

host()

host() = string() | {integer(), integer(), integer(), integer()}

http_status()

http_status() = {integer(), string() | binary()} | {nil, nil}

method()

method() = string() | atom()

option()

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()

options() = [option()]

partial_download_option()

partial_download_option() = {window_size, window_size()} | {part_size, non_neg_integer() | infinity}

pool_id()

pool_id() = pid() | atom()

poolsize()

poolsize() = non_neg_integer() | atom()

port_num()

port_num() = 1..65535

pos_timeout()

pos_timeout() = pos_integer() | infinity

result()

result() = {ok, {{pos_integer(), string()}, headers(), body()}} | {ok, upload_state()} | {error, term()}

socket()

socket() = term()

socket_options()

socket_options() = [{atom(), term()} | atom()]

upload_state()

upload_state() = {pid(), window_size()}

window_size()

window_size() = non_neg_integer() | infinity

Function Index

add_pool/1Add a new named httpc_manager pool to the supervisor tree.
add_pool/2Add a new httpc_manager to the supervisor tree.
add_pool/3Add a new httpc_manager to the supervisor tree.
delete_pool/1Delete a pool.
get_body_part/1Reads a body part from an ongoing response when {partial_download, PartialDownloadOptions} is used.
get_body_part/2Reads a body part from an ongoing response when {partial_download, PartialDownloadOptions} is used.
request/4Sends a request without a body.
request/5Sends a request with a body.
request/6Sends a request with a body.
request/9Sends a request with a body.
send_body_part/2Sends a body part to an ongoing request when {partial_upload, WindowSize} is used.
send_body_part/3Sends a body part to an ongoing request when {partial_upload, WindowSize} is used.
send_trailers/2Sends trailers to an ongoing request when {partial_upload, WindowSize} is used and no Content-Length was specified.
send_trailers/3Sends trailers to an ongoing request when {partial_upload, WindowSize} is used and no Content-Length was specified.
start/0Start the application.
stop/0Stops the application.

Function Details

add_pool/1

add_pool(Name::atom()) -> {ok, pid()} | {error, already_exists | term()}

Add a new named httpc_manager pool to the supervisor tree

add_pool/2

add_pool(Name::atom(), ConnTimeout::pos_integer()) -> {ok, pid()} | {error, already_exists | term()}

Add a new httpc_manager to the supervisor tree

add_pool/3

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/1

delete_pool(PoolPid::atom() | pid()) -> ok

Delete a pool

get_body_part/1

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/2

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/4

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/5

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/6

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/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/2

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/3

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.

The BodyPart 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/2

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/3

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.

Sending trailers also signals the end of the entity body, which means that no more body parts, or trailers can be sent and the response to the request will be read from the socket. If no response is received within Timeout milliseconds the request is canceled and {error, timeout} is returned.

start/0

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

For more info on possible return values the application module.

stop/0

stop() -> ok | {error, any()}

Stops the application. This is a helper function that will call application:stop(lhttpc).

For more info on possible return values the application module.


Generated by EDoc