http
MODULE
http
MODULE SUMMARY
An HTTP/1.1 client
DESCRIPTION
This module provides the API to a HTTP/1.1 client according to
RFC 2616, caching is currentyl not supported.
Note
When starting the Inets application a manager process for the
default profile will be started. The functions in this API
that does not explicitly use a profile will acesses the
default profile. A profile keeps track of proxy options,
cookies and other options that can be applied to more than one
request.
If the scheme
https is used the ssl application needs to be started.
Also note that an application that does not set the
pipeline-timeout value will benefit very little from
pipelining as the default timeout is 0.
There are some usage examples in the Inets User's Guide.
COMMON DATA TYPES
Type definitions that are used more than once in
this module:
boolean() = true | false
string() = list of ASCII characters
request_id() = ref()
profile() = atom()
path() = string() representing a file path or directory path
HTTP CLIENT SERVICE START/STOP
A HTTP client can be configured to start when starting the inets
application or started dynamically in runtime by calling the
inets application API inets:start(httpc, ServiceConfig), or
inets:start(httpc, ServiceConfig, How)
see inets(3) Below follows a
description of the available configuration options.
-
{profile, profile()}
-
Name of the profile, see
common data types below, this option is mandantory.
-
{data_dir, path()}
-
Directory where the profile
may save persistent data, if omitted all cookies will be treated
as session cookies.
The client can be stopped using inets:stop(httpc, Pid) or
inets:stop(httpc, Profile).
HTTP DATA TYPES
Type definitions that are related to HTTP:
For more information about HTTP see rfc 2616
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() = [{field(), value()}]
field() = string()
value() = string()
body() = string() | binary()
filename = string()
SSL DATA TYPES
Some type definitions relevant when using https,
for details ssl(3):
ssl_options() =
{verify, code()} | {depth, depth()} | {certfile, path()}
| {keyfile, path()} | {password, string()} | {cacertfile, path()}
| {ciphers, string()}
EXPORTS
cancel_request(RequestId) ->
cancel_request(RequestId, Profile) -> ok
Types:
RequestId = request_id() - A unique identifier as returned
by request/4
Profile = profile()
Cancels an asynchronous HTTP-request.
request(Url) ->
request(Url, Profile) -> {ok, Result} | {error, Reason}
Types:
Url = url()
Result = {status_line(), headers(),
body()} | {status_code(), body()} | request_id()
Profile = profile()
Reason = term()
Equivalent to http:request(get, {Url, []}, [], []).
request(Method, Request, HTTPOptions, Options) ->
request(Method, Request, HTTPOptions, Options, Profile) -> {ok, Result} | {ok, saved_to_file} | {error, Reason}
Types:
Method = method()
Request - request()
HTTPOptions - [HttpOption]
HTTPOption - {timeout, integer()} | {ssl, ssl_options()} | {autoredirect, boolean()} | {proxy_auth, {userstring(), passwordstring()}} | {version, http_version()} | {relaxed, boolean()}
autoredirect
proxy_auth
version
HTTP/1.0HTTP/0.9HTTP/1.1
HTTP/1.0relaxed
Options - [option()]
Option - {sync, boolean()} | {stream, StreamTo} | {body_format, body_format()} | {full_result, boolean()} | {headers_as_is, boolean()}
StreamTo = self | {self, once} | filename()
self{self once}
body_format() = string() | binary()
headers_as_is
Result = {status_line(), headers(), body()} | {status_code(), body()} | request_id()
Profile = profile()
Reason = term()
Sends a HTTP-request. The function can be both synchronous
and asynchronous in the later case the function will return
{ok, RequestId} and later on message/messages will be sent to the
calling process on the format {http, {RequestId, Result}}
{http, {RequestId, {error, Reason}}},
{http, {RequestId, stream_start, Headers},
{http, {RequestId, stream, BinBodyPart},
{http, {RequestId, stream_end, Headers} or
{http, {RequestId, saved_to_file}}.
set_options(Options) ->
set_options(Options, Profile) -> ok | {error, Reason}
Types:
Options = [Option]
Option = {proxy, {Proxy, NoProxy}} | {max_sessions, MaxSessions} | {max_pipeline_length, MaxPipeline} | {pipeline_timeout, PipelineTimeout} | {cookies | CookieMode} | {ipv6, Ipv6Mode} | {verbose, VerboseMode}
Proxy = {Hostname, Port}
Hostname = string()
Port = integer()
NoProxy = [NoProxyDesc]
NoProxyDesc = DomainDesc | HostName | IPDesc
DomainDesc = "*.Domain"
IpDesc = string()
MaxSessions = integer()
MaxPipeline = integer()
PipelineTimeout = integer()
CookieMode = enabled | disabled | verify
ipv6Mode = enabled | disabled
VerboseMode = false | verbose |debug | trace
Profile = profile()
Sets options to be used for subsequent
requests.
Note
If possible the client will keep its connections
alive and use them to pipeline requests whenever the
circumstances allow. The HTTP/1.1 specification does not
provide a guideline for how many requests that would be
ideal to pipeline, this very much depends on the
application. Note that a very long pipeline may cause a
user perceived delays as earlier request 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 max_sessions option.
stream_next(Pid) -> ok
Types:
Pid = pid() - as received in the stream_start message
Triggers the next message to be streamed, e.i.
same behavior as active once for sockets.
verify_cookie(SetCookieHeaders, Url) ->
verify_cookie(SetCookieHeaders, Url, Profile) -> ok | {error, Reason}
Types:
SetCookieHeaders = headers() - where field = "set-cookie"
Url = url()
Profile = profile()
Saves the cookies defined in SetCookieHeaders
in the client profile's cookie database. You need to
call this function if you set the option cookies to verify.
If no profile is specifed the default profile will be used.
cookie_header(Url) ->
cookie_header(Url, Profile) -> header() | {error, Rason}
Types:
Url = url()
Profile = profile()
Returns the cookie header that would be sent
when making a request to Url using the profile Profile.
If no profile is specifed the default profile will be used.
SEE ALSO
inets 5.0.2
Copyright © 1991-2008
Ericsson AB