.TH httpc 3erl "inets 5.9" "Ericsson AB" "Erlang Module Definition"
.SH NAME
httpc \- An HTTP/1.1 client 
.SH DESCRIPTION
.LP
This module provides the API to a HTTP/1\&.1 compatible client according to RFC 2616, caching is currently not supported\&.
.LP

.RS -4
.B
Note:
.RE
When starting the Inets application a manager process for the default profile will be started\&. The functions in this API that do not explicitly use a profile will access the default profile\&. A profile keeps track of proxy options, cookies and other options that can be applied to more than one request\&.
.LP
If the scheme https is used the ssl application needs to be started\&.
.LP
Also note that pipelining will only be used if the pipeline timeout is set, otherwise persistent connections without pipelining will be used e\&.i\&. the client always waits for the previous response before sending the next request\&.

.LP
There are some usage examples in the \fBInets User\&'s Guide\&.\fR\&
.SH "COMMON DATA TYPES "

.LP
Type definitions that are used more than once in this module:
.LP
.nf

boolean()    = true | false 
string()     = list of ASCII characters 
request_id() = ref() 
profile()    = atom()
path()       = string() representing a file path or directory path 
ip_address() = See inet(3erl)
socket_opt() = See the Options used by gen_tcp(3erl) and 
               ssl(3erl) connect(s)
    
.fi
.SH "HTTP DATA TYPES "

.LP
Type definitions that are related to HTTP:
.LP
For more information about HTTP see rfc 2616
.LP
.nf

method()         = head | get | put | post | trace | options | delete
request()        = {url(), headers()} | 
                   {url(), headers(), content_type(), body()}
url()            = string() - Syntax according to the URI definition in rfc 2396, ex: "http://www.erlang.org"
status_line()    = {http_version(), status_code(), reason_phrase()}
http_version()   = string() ex: "HTTP/1.1"
status_code()    = integer()
reason_phrase()  = string()
content_type()   = string()
headers()        = [header()]
header()         = {field(), value()}
field()          = string() 
value()          = string() 
body()           = string() | 
                   binary() |
                   {fun(accumulator()) -> body_processing_result(), 
                    accumulator()} |
                   {chunkify, 
                    fun(accumulator()) -> body_processing_result(), 
                    accumulator()}
body_processing_result() = eof | {ok, iolist(), accumulator()}
accumulator()    = term()
filename()       = string() 
    
.fi
.SH "SSL DATA TYPES "

.LP
See \fBssl(3erl)\fR\& for information about ssl options (\fIssloptions()\fR\&)\&.
.SH "HTTP CLIENT SERVICE START/STOP "

.LP
A HTTP client can be configured to start when starting the inets application or started dynamically in runtime by calling the inets application API \fIinets:start(httpc, ServiceConfig)\fR\&, or \fIinets:start(httpc, ServiceConfig, How)\fR\& see \fBinets(3erl)\fR\&\&. Below follows a description of the available configuration options\&.
.RS 2
.TP 2
.B
{profile, profile()}:
Name of the profile, see common data types below, this option is mandatory\&.
.TP 2
.B
{data_dir, path()}:
Directory where the profile may save persistent data, if omitted all cookies will be treated as session cookies\&.
.RE
.LP
The client can be stopped using \fIinets:stop(httpc, Pid)\fR\& or \fIinets:stop(httpc, Profile)\fR\&\&.
.SH EXPORTS
.LP
.B
request(Url) -> 
.br
.B
request(Url, Profile) -> {ok, Result} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Url = url() 
.br
Result = {status_line(), headers(), Body} | {status_code(), Body} | request_id() 
.br
Body = string() | binary()
.br
Profile = profile() | pid() (when started \fIstand_alone\fR\&)
.br
Reason = term() 
.br
.RE
.RE
.RS
.LP
Equivalent to \fIhttpc:request(get, {Url, []}, [], [])\fR\&\&.
.RE

.LP
.B
request(Method, Request, HTTPOptions, Options) -> 
.br
.B
request(Method, Request, HTTPOptions, Options, Profile) -> {ok, Result} | {ok, saved_to_file} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Method = method() 
.br
Request = request()
.br
HTTPOptions = http_options()
.br
http_options() = [http_option()]
.br
http_option() = {timeout, timeout()} | {connect_timeout, timeout()} | {ssl, ssloptions()} | {essl, ssloptions()} | {autoredirect, boolean()} | {proxy_auth, {userstring(), passwordstring()}} | {version, http_version()} | {relaxed, boolean()} | {url_encode, boolean()}
.br
timeout() = integer() >= 0 | infinity
.br
Options = options()
.br
options() = [option()]
.br
option() = {sync, boolean()} | {stream, stream_to()} | {body_format, body_format()} | {full_result, boolean()} | {headers_as_is, boolean() | {socket_opts, socket_opts()} | {receiver, receiver()}, {ipv6_host_with_brackets, boolean()}}
.br
stream_to() = none | self | {self, once} | filename() 
.br
socket_opts() = [socket_opt()]
.br
receiver() = pid() | function()/1 | {Module, Function, Args} 
.br
Module = atom() 
.br
Function = atom() 
.br
Args = list() 
.br
body_format() = string | binary 
.br
Result = {status_line(), headers(), Body} | {status_code(), Body} | request_id() 
.br
Body = string() | binary()
.br
Profile = profile() | pid() (when started \fIstand_alone\fR\&)
.br
Reason = {connect_failed, term()} | {send_failed, term()} | term() 
.br
.RE
.RE
.RS
.LP
Sends a HTTP-request\&. The function can be both synchronous and asynchronous\&. In the later case the function will return \fI{ok, RequestId}\fR\& and later on the information will be delivered to the \fIreceiver\fR\& depending on that value\&.
.LP
Http option (\fIhttp_option()\fR\&) details:
.RS 2
.TP 2
.B
\fItimeout\fR\&:
Timeout time for the request\&.
.RS 2
.LP
The clock starts ticking as soon as the request has been sent\&.
.RE

.RS 2
.LP
Time is in milliseconds\&.
.RE

.RS 2
.LP
Defaults to \fIinfinity\fR\&\&.
.RE

.TP 2
.B
\fIconnect_timeout\fR\&:
Connection timeout time, used during the initial request, when the client is \fIconnecting\fR\& to the server\&.
.RS 2
.LP
Time is in milliseconds\&.
.RE

.RS 2
.LP
Defaults to the value of the \fItimeout\fR\& option\&.
.RE

.TP 2
.B
\fIssl\fR\&:
This is the default ssl config option, currently defaults to \fIessl\fR\&, see below\&.
.RS 2
.LP
Defaults to \fI[]\fR\&\&.
.RE

.TP 2
.B
\fIessl\fR\&:
If using the Erlang based implementation of SSL, these SSL-specific options are used\&.
.RS 2
.LP
Defaults to \fI[]\fR\&\&.
.RE

.TP 2
.B
\fIautoredirect\fR\&:
Should the client automatically retrieve the information from the new URI and return that as the result instead of a 30X-result code\&.
.RS 2
.LP
Note that for some 30X-result codes automatic redirect is not allowed\&. In these cases the 30X-result will always be returned\&.
.RE

.RS 2
.LP
Defaults to \fItrue\fR\&\&.
.RE

.TP 2
.B
\fIproxy_auth\fR\&:
A proxy-authorization header using the provided user name and password will be added to the request\&.
.TP 2
.B
\fIversion\fR\&:
Can be used to make the client act as an \fIHTTP/1\&.0\fR\& or \fIHTTP/0\&.9\fR\& client\&. By default this is an \fIHTTP/1\&.1\fR\& client\&. When using \fIHTTP/1\&.0\fR\& persistent connections will not be used\&.
.RS 2
.LP
Defaults to the string \fI"HTTP/1\&.1"\fR\&\&.
.RE

.TP 2
.B
\fIrelaxed\fR\&:
If set to \fItrue\fR\& workarounds for known server deviations from the HTTP-standard are enabled\&.
.RS 2
.LP
Defaults to \fIfalse\fR\&\&.
.RE

.TP 2
.B
\fIurl_encode\fR\&:
Will apply Percent-encoding, also known as URL encoding on the URL\&.
.RS 2
.LP
Defaults to \fIfalse\fR\&\&.
.RE

.RE
.LP
Option (\fIoption()\fR\&) details:
.RS 2
.TP 2
.B
\fIsync\fR\&:
Shall the request be synchronous or asynchronous\&.
.RS 2
.LP
Defaults to \fItrue\fR\&\&.
.RE

.TP 2
.B
\fIstream\fR\&:
Streams the body of a 200 or 206 response to the calling process or to a file\&. When streaming to the calling process using the option \fIself\fR\& the following stream messages will be sent to that process: \fI{http, {RequestId, stream_start, Headers}, {http, {RequestId, stream, BinBodyPart}, {http, {RequestId, stream_end, Headers}\fR\&\&. When streaming to to the calling processes using the option \fI{self, once}\fR\& the first message will have an additional element e\&.i\&. \fI{http, {RequestId, stream_start, Headers, Pid}\fR\&, this is the process id that should be used as an argument to \fIhttp:stream_next/1\fR\& to trigger the next message to be sent to the calling process\&.
.RS 2
.LP
Note that it is possible that chunked encoding will add headers so that there are more headers in the \fIstream_end\fR\& message than in the \fIstream_start\fR\&\&. When streaming to a file and the request is asynchronous the message \fI{http, {RequestId, saved_to_file}}\fR\& will be sent\&.
.RE

.RS 2
.LP
Defaults to \fInone\fR\&\&.
.RE

.TP 2
.B
\fIbody_format\fR\&:
Defines if the body shall be delivered as a string or as a binary\&. This option is only valid for the synchronous request\&.
.RS 2
.LP
Defaults to \fIstring\fR\&\&.
.RE

.TP 2
.B
\fIfull_result\fR\&:
Should a "full result" be returned to the caller (that is, the body, the headers and the entire status-line) or not (the body and the status code)\&.
.RS 2
.LP
Defaults to \fItrue\fR\&\&.
.RE

.TP 2
.B
\fIheader_as_is\fR\&:
Shall the headers provided by the user be made lower case or be regarded as case sensitive\&.
.RS 2
.LP
Note that the http standard requires them to be case insenstive\&. This feature should only be used if there is no other way to communicate with the server or for testing purpose\&. Also note that when this option is used no headers will be automatically added, all necessary headers have to be provided by the user\&.
.RE

.RS 2
.LP
Defaults to \fIfalse\fR\&\&.
.RE

.TP 2
.B
\fIsocket_opts\fR\&:
Socket options to be used for this and subsequent request(s)\&.
.RS 2
.LP
Overrides any value set by the \fBset_options\fR\& function\&.
.RE

.RS 2
.LP
Note that the validity of the options are \fInot\fR\& checked in any way\&.
.RE

.RS 2
.LP
Note that this may change the socket behaviour (see \fBinet:setopts/2\fR\&) for an already existing one, and therefore an already connected request handler\&.
.RE

.RS 2
.LP
By default the socket options set by the \fBset_options/1,2\fR\& function are used when establishing a connection\&.
.RE

.TP 2
.B
\fIreceiver\fR\&:
Defines how the client will deliver the result of an asynchroneous request (\fIsync\fR\& has the value \fIfalse\fR\&)\&.
.RS 2
.TP 2
.B
\fIpid()\fR\&:
Message(s) will be sent to this process in the format:
.LP
.nf

{http, ReplyInfo}

.fi
.TP 2
.B
\fIfunction/1\fR\&:
Information will be delivered to the receiver via calls to the provided fun:
.LP
.nf

Receiver(ReplyInfo)

.fi
.TP 2
.B
\fI{Module, Funcion, Args}\fR\&:
Information will be delivered to the receiver via calls to the callback function:
.LP
.nf

apply(Module, Function, [ReplyInfo | Args])

.fi
.RE
.RS 2
.LP
In all of the above cases, \fIReplyInfo\fR\& has the following structure:
.RE

.LP
.nf

{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}

.fi
.RS 2
.LP
Defaults to the \fIpid()\fR\& of the process calling the request function (\fIself()\fR\&)\&.
.RE

.TP 2
.B
\fIipv6_host_with_brackets\fR\&:
When parsing the Host-Port part of an URI with a IPv6 address with brackets, shall we retain those brackets (\fItrue\fR\&) or strip them (\fIfalse\fR\&)\&.
.RS 2
.LP
Defaults to \fIfalse\fR\&\&.
.RE

.RE
.RE

.LP
.B
cancel_request(RequestId) -> 
.br
.B
cancel_request(RequestId, Profile) -> ok
.br
.RS
.LP
Types:

.RS 3
RequestId = request_id() - A unique identifier as returned by request/4
.br
Profile = profile() | pid() (when started \fIstand_alone\fR\&)
.br
.RE
.RE
.RS
.LP
Cancels an asynchronous HTTP-request\&.
.RE

.LP
.B
set_options(Options) -> 
.br
.B
set_options(Options, Profile) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Options = [Option]
.br
Option = {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, socket_opts()} | {verbose, VerboseMode} 
.br
Proxy = {Hostname, Port}
.br
Hostname = string() 
.br
.RS 2
ex: "localhost" or "foo\&.bar\&.se"
.RE
Port = integer()
.br
.RS 2
ex: 8080 
.RE
socket_opts() = [socket_opt()]
.br
.RS 2
The options are appended to the socket options used by the client\&. 
.RE
.RS 2
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) \fIwithout\fR\& verification! 
.RE
NoProxy = [NoProxyDesc]
.br
NoProxyDesc = DomainDesc | HostName | IPDesc
.br
DomainDesc = "*\&.Domain"
.br
.RS 2
ex: "*\&.ericsson\&.se"
.RE
IpDesc = string()
.br
.RS 2
ex: "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)\&.
.RE
MaxSessions = integer() 
.br
.RS 2
Default is \fI2\fR\&\&. Maximum number of persistent connections to a host\&.
.RE
MaxKeepAlive = integer() 
.br
.RS 2
Default is \fI5\fR\&\&. Maximum number of outstanding requests on the same connection to a host\&.
.RE
KeepAliveTimeout = integer() 
.br
.RS 2
Default is \fI120000\fR\& (= 2 min)\&. If a persistent connection is idle longer than the \fIkeep_alive_timeout\fR\& the client will close the connection\&. The server may also have such a time out but you should not count on it!
.RE
MaxPipeline = integer() 
.br
.RS 2
Default is \fI2\fR\&\&. Maximum number of outstanding requests on a pipelined connection to a host\&.
.RE
PipelineTimeout = integer() 
.br
.RS 2
Default is \fI0\fR\&, which will result in pipelining not being used\&. If a persistent connection is idle longer than the \fIpipeline_timeout\fR\& the client will close the connection\&. 
.RE
CookieMode = enabled | disabled | verify 
.br
.RS 2
Default is \fIdisabled\fR\&\&. If Cookies are enabled all valid cookies will automatically be saved in the client manager\&'s cookie database\&. If the option \fIverify\fR\& is used the function \fIstore_cookies/2\fR\& has to be called for the cookies to be saved\&.
.RE
IpFamily = inet | inet6 | inet6fb4 
.br
.RS 2
By default \fIinet\fR\&\&. When it is set to \fIinet6fb4\fR\& you can use both ipv4 and ipv6\&. It first tries \fIinet6\fR\& and if that does not works falls back to \fIinet\fR\&\&. The option is here to provide a workaround for buggy ipv6 stacks to ensure that ipv4 will always work\&.
.RE
IpAddress = ip_address() 
.br
.RS 2
If the host has several network interfaces, this option specifies which one to use\&. See \fBgen_tcp:connect/3,4\fR\& for more info\&. 
.RE
Port = integer() 
.br
.RS 2
Specify which local port number to use\&. See \fBgen_tcp:connect/3,4\fR\& for more info\&. 
.RE
VerboseMode = false | verbose | debug | trace 
.br
.RS 2
Default is \fIfalse\fR\&\&. This option is used to switch on (or off) different levels of erlang trace on the client\&. It is a debug feature\&.
.RE
Profile = profile() | pid() (when started \fIstand_alone\fR\&)
.br
.RE
.RE
.RS
.LP
Sets options to be used for subsequent requests\&.
.LP

.RS -4
.B
Note:
.RE
If possible the client will keep its connections alive and use 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 would be ideal to be sent on a persistent connection, this very much depends on the application\&. Note that a very long queue of requests may cause a user perceived delay as earlier requests may take a long time to complete\&. The HTTP/1\&.1 specification does suggest a limit of 2 persistent connections per server, which is the default value of the \fImax_sessions\fR\& option\&.

.RE

.LP
.B
get_options(OptionItems) -> {ok, Values} | {error, Reason}
.br
.B
get_options(OptionItems, Profile) -> {ok, Values} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
OptionItems = all | [option_item()]
.br
option_item() = proxy | max_sessions | keep_alive_timeout | max_keep_alive_length | pipeline_timeout | max_pipeline_length | cookies | ipfamily | ip | port | socket_opts | verbose
.br
Profile = profile() | pid() (when started \fIstand_alone\fR\&)
.br
Values = [{option_item(), term()}]
.br
Reason = term() 
.br
.RE
.RE
.RS
.LP
Retrieves the options currently used by the client\&.
.RE

.LP
.B
stream_next(Pid) -> ok
.br
.RS
.LP
Types:

.RS 3
Pid = pid() - as received in the stream_start message
.br
.RE
.RE
.RS
.LP
Triggers the next message to be streamed, e\&.i\&. same behavior as active once for sockets\&.
.RE

.LP
.B
store_cookies(SetCookieHeaders, Url) -> 
.br
.B
store_cookies(SetCookieHeaders, Url, Profile) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
SetCookieHeaders = headers() - where field = "set-cookie"
.br
Url = url()
.br
Profile = profile() | pid() (when started \fIstand_alone\fR\&)
.br
.RE
.RE
.RS
.LP
Saves the cookies defined in SetCookieHeaders in the client profile\&'s cookie database\&. You need to call this function if you have set the option \fIcookies\fR\& to \fIverify\fR\&\&. If no profile is specified the default profile will be used\&.
.RE

.LP
.B
cookie_header(Url) -> 
.br
.B
cookie_header(Url, Profile | Opts) -> header() | {error, Reason}
.br
.B
cookie_header(Url, Opts, Profile) -> header() | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Url = url()
.br
Opts = [cookie_header_opt()]
.br
Profile = profile() | pid() (when started \fIstand_alone\fR\&)
.br
cookie_header_opt() = {ipv6_host_with_brackets, boolean()}
.br
.RE
.RE
.RS
.LP
Returns the cookie header that would be sent when making a request to \fIUrl\fR\& using the profile \fIProfile\fR\&\&. If no profile is specified the default profile will be used\&.
.LP
The option \fIipv6_host_with_bracket\fR\& deals with how to parse IPv6 addresses\&. See the \fIOptions\fR\& argument of the \fBrequest/4,5\fR\& for more info\&.
.RE

.LP
.B
reset_cookies() -> void()
.br
.B
reset_cookies(Profile) -> void()
.br
.RS
.LP
Types:

.RS 3
Profile = profile() | pid() (when started \fIstand_alone\fR\&)
.br
.RE
.RE
.RS
.LP
Resets (clears) the cookie database for the specified \fIProfile\fR\&\&. If no profile is specified the default profile will be used\&.
.RE

.LP
.B
which_cookies() -> cookies()
.br
.B
which_cookies(Profile) -> cookies()
.br
.RS
.LP
Types:

.RS 3
Profile = profile() | pid() (when started \fIstand_alone\fR\&)
.br
cookies() = [cookie_stores()]
.br
cookie_stores() = {cookies, cookies()} | {session_cookies, cookies()}
.br
cookies() = [cookie()]
.br
cookie() = term()
.br
.RE
.RE
.RS
.LP
This function produces a list of the entire cookie database\&. It is intended for debugging/testing purposes\&. If no profile is specified the default profile will be used\&.
.RE

.SH "SEE ALSO"

.LP
RFC 2616, \fBinets(3erl)\fR\&, \fBgen_tcp(3erl)\fR\&, \fBssl(3erl)\fR\&