# 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.0 HTTP/0.9 HTTP/1.1
HTTP/1.0 relaxed
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

RFC 2616, inets(3), ssl(3)

inets 5.0.2
Copyright © 1991-2008 Ericsson AB