[Ericsson AB]

http

MODULE

http

MODULE SUMMARY

A HTTP/1.1 client

DESCRIPTION

This module provides the API to a HTTP/1.1 client according to RFC 2616, however this first version is somewhat limited for instance caching and cookies are not supported.

Note!

The functions request/4, and set_options/1, will start the inets application if it was not already started. When starting the inets application the client manager process that spawns request handlers, keeps track of proxy options etc will be started. Normaly the application using this API should have started inets application. This is also true for the ssl application when using https.

Note that there are some usage examples in the Inets User's Guide.

COMMON DATA TYPES

Here follows type definitions that are used more than once in this module.

boolean() = true | false 
string() = list of ASCII characters
request_id() = ref() 

HTTP DATA TYPES

Here follows type definitions that are related to the HTTP protocol. For more information about the HTTP protocol 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()}] 
 filed() = string()  
 value() = string()  
 body() = string() | binary() - HTLM-code

SSL DATA TYPES

Here follows 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) -> ok

Types:

RequestId = request_id() - A unique identifier as returned by request/4

Cancels an asynchronous HTTP-request.

request(Method, Request, HTTPOptions, Options) -> {ok, Result} | {error, Reason}

Types:

Method = method()
Request - request()
HTTPOptions - [HttpOption]
HTTPOption - {timeout, integer()} | {ssl, ssl_options()}
Options - [option()]
Option - {sync, boolean()} | {body_format, BodyFormat} | {full_result, boolean()}

The request function will be synchronous and return a full http response by default.
BodyFormat = string() | binary()
The body_format options is only valid for the syncronus request and the defult is string, when making an asynchronous request the body will always be received as a binary.
Result = {status_line(), headers(), body()} | {status_code(), body()} | request_id()

Sends a HTTP-request. The function can be both syncronus and asynchronous in the later case the function will return {ok, RequestId} and later on a message will be sent to the calling process on the format {http, {RequestId, Result}} or {http, {RequestId, {error, Reason}}}.

set_options(Options) -> ok

Types:

Options = [Option]
Option = {proxy, {Proxy, NoProxy}}

Currently only the proxy option is supported.
Proxy = {Hostname, Port}
Hostname = string() ex: "localhost" or "foo.bar.se"
Port = integer() ex:8080
NoProxy = [NoProxyDesc]
NoProxyDesc = DomainDesc | HostName | IPDesc
DomainDesc = "*.Domain" ex: "*.ericsson.se"
IpDesc = string() ex: "134.138" or "[FEDC:BA98" (all IP-adresses starting with 134.138 or FEDC:BA98), "66.35.250.150" or "[2010:836B:4179::836B:4179]" (a compleat IP-address).

Sets options to be used for subsequent requests. Later implementations may support user profiles, but currently these are global settings for all clients running on the same erlang node.

SEE ALSO

RFC 2616, ssl(3)

AUTHORS

Ingela Anderton Andin - support@erlang.ericsson.se

inets 4.0
Copyright © 1991-2004 Ericsson AB