Module ahttp_client

Data Types
Function Index
Function Details

Data Types

backend()


backend() = gen_tcp | ssl

data_response()


data_response() = {data, reference(), binary()}

done_response()


done_response() = {done, reference()}

error_tuple()


error_tuple() = {error, {backend(), term()}}

header_continuation_response()


header_continuation_response() = {header_continuation, reference(), {binary(), binary()}}

header_response()


header_response() = {header, reference(), {binary(), binary()}}

host()


host() = binary() | string()

option()


option() = gen_tcp:option() | ssl:tls_client_option() | {parse_headers, [binary()]}

protocol()


protocol() = http | https

response()


response() = status_response() | header_response() | header_continuation_response() | data_response() | done_response()

socket_message()


socket_message() = {tcp, inet:socket(), binary()} | {ssl, ssl:sslsocket(), binary()}

status_response()


status_response() = {status, reference(), 0..999}

Function Index

close/1	Closes the connection.
connect/4	Connects to the http(s) server.
recv/2	Receive and parse a number of bytes from the http connection.
request/5	Makes a http request using given method on provided path.
stream/2	This function should be used when in active mode in order to process socket messages.
stream_request_body/3	Uploads a chunk of request body.

Function Details

close/1


close(Conn::connection()) -> ok | error_tuple()

Conn: the connection

returns: Either ok or an error tuple.

Closes the connection.

connect/4


connect(Protocol::protocol(), Host::host(), Port::inet:port_number(), Options::[option()]) -> {ok, connection()} | error_tuple()

Protocol: the protocol, either http or https
Host: the server hostname
Port: the server port number, usually 80 (http) or 443 (https)
Options: the property list with http client and connection options

returns: Either a http connection result tuple or an error tuple

Connects to the http(s) server.

The Host parameter may be a fully qualified host name or a string containing a valid dotted pair IP address. (Currently, only IPv4 is supported). Host can be also a binary.

The Options can be used for providing connection options such as SSL {verify, verify_none}, gen_tcp options such as {active, false} and ahttp_client {parse_headers, [<<"HeaderName">>]}.

recv/2


recv(Conn::connection(), Len::non_neg_integer()) -> {ok, connection(), [response()]} | error_tuple()

Conn: the connection
Len: the number of bytes will be received, when using 0 all pending bytes are received

returns: Either an ok tuple with the updated connection and a list of responses or an error tuple.

Receive and parse a number of bytes from the http connection.

This function should be used when the connection has been opened using {active, false}.

See also stream/2 for more information about the responses list.

request/5


request(Conn::connection(), Method::iodata(), Path::iodata(), Headers::[iodata()], Body::binary() | undefined | nil | stream) -> {ok, connection(), reference()} | error_tuple()

Conn: the connection
Method: a http method such as “GET”, “POST”, “PUT”, etc…
Path: the path to the http resource, such as “/”
Headers: a list of headers
Body: the body that is sent to the server, may be undefined or nil when there is no body

returns: Either a result tuple with the updated http connection and a reference to the http request, or an error tuple.

Makes a http request using given method on provided path.

When using methods such as GET the body should be omited using either undefined or nil (they are both equivalent).

When uploading a smaller body (a single binary that fits in memory) the body binary can be provided.

stream option can be used with stream_request_body/3 in order to upload a bigger binary in streaming mode. This option should be combined with Content-Length header.

As soon as the request is sent to the server, a tuple such as {ok, Conn, Ref} is returned, otherwise an error tuple is returned, such as {error, {gen_tcp, econnrefused}}.

The returned connection should be used for the next call, such as to stream/2 (when using active mode) or recv/3 (when using passive mode). Ref is meant to identify a single request, so any response to a specific request will be identified from the same reference.

stream/2


stream(Conn::connection(), Msg::socket_message()) -> {ok, connection(), [response()]} | {ok, connection(), closed} | unknown | error_tuple()

Conn: the connection
Msg: a received message

returns: Either a list of responses, unknown or an error tuple.

This function should be used when in active mode in order to process socket messages.

If a socket message is streamed using this function, a tuple with a list of http responses is returned (e.g. `{ok, UpdatedConn, Responses}``, or an error tuple.

Otherwise unknown is returned, that means that the message is not a socket message tied to the open connection, and it should be handled in some other way.

The first returned response to a new request is a status {status, Ref, 200} for a successful response. After that headers and data may follow.

Since the response might span multiple socket messages, stream/2 may be called multiple times. Each time the latest UpdatedConn must be used.

stream_request_body/3


stream_request_body(Conn::connection(), Ref::reference(), BodyChunk::binary()) -> ok | error_tuple()

Conn: the connection
Ref: the reference to the pending request
BodyChunk: a chunk of the body that will be sent

returns: Either ok or an error tuple.

Uploads a chunk of request body.

This function should be used when stream has been used as Body parameter.