ibrowse API

Module ibrowse

Overview

Module ibrowse

Description
Function Index
Function Details

The ibrowse application implements an HTTP 1.1 client.

Version: 1.4.1

Behaviours: gen_server.

Authors: Chandrashekhar Mullaparthi (chandrashekhar dot mullaparthi at gmail dot com).

Description

The ibrowse application implements an HTTP 1.1 client. This
module implements the API of the HTTP client. There is one named
process called ‘ibrowse’ which assists in load balancing and maintaining configuration. There is one load balancing process per unique webserver. There is
one process to handle one TCP connection to a webserver
(implemented in the module ibrowse_http_client). Multiple connections to a
webserver are setup based on the settings for each webserver. The
ibrowse process also determines which connection to pipeline a
certain request on. The functions to call are send_req/3,
send_req/4, send_req/5, send_req/6.

Here are a few sample invocations.



  ibrowse:send_req(“http://intranet/messenger/”, [], get).

  

 

  ibrowse:send_req(“http://www.google.com/”, [], get, [],

  		 [{proxy_user, "XXXXX"},

  		  {proxy_password, "XXXXX"},

  		  {proxy_host, "proxy"},

  		  {proxy_port, 8080}], 1000).

  

 ibrowse:send_req(“http://www.erlang.org/download/otp_src_R10B-3.tar.gz”, [], get, [],

  		 [{proxy_user, "XXXXX"},

  		  {proxy_password, "XXXXX"},

  		  {proxy_host, "proxy"},

  		  {proxy_port, 8080},

  		  {save_response_to_file, true}], 1000).

  

  ibrowse:send_req(“http://www.erlang.org”, [], head).

 

  ibrowse:send_req(“http://www.sun.com”, [], options).

 

  ibrowse:send_req(“http://www.bbc.co.uk”, [], trace).

 

  ibrowse:send_req(“http://www.google.com”, [], get, [],

                    [{stream_to, self()}]).

A driver exists which implements URL encoding in C, but the
speed achieved using only erlang has been good enough, so the
driver isn’t actually used.

Function Index

code_change/3
get_config_value/1	Internal export.
get_config_value/2	Internal export.
handle_call/3
handle_cast/2
handle_info/2
init/1
rescan_config/0	Clear current configuration for ibrowse and load from the file ibrowse.conf in the IBROWSE_EBIN/../priv directory.
rescan_config/1
send_req/3	This is the basic function to send a HTTP request.
send_req/4	Same as send_req/3.
send_req/5	Same as send_req/4.
send_req/6	Same as send_req/5.
send_req_direct/4	Same as send_req/3 except that the first argument is the PID returned by spawn_worker_process/2 or spawn_link_worker_process/2.
send_req_direct/5	Same as send_req/4 except that the first argument is the PID returned by spawn_worker_process/2 or spawn_link_worker_process/2.
send_req_direct/6	Same as send_req/5 except that the first argument is the PID returned by spawn_worker_process/2 or spawn_link_worker_process/2.
send_req_direct/7	Same as send_req/6 except that the first argument is the PID returned by spawn_worker_process/2 or spawn_link_worker_process/2.
set_dest/3	Deprecated.
set_max_pipeline_size/3	Set the maximum pipeline size for each connection to a specific Host:Port.
set_max_sessions/3	Set the maximum number of connections allowed to a specific Host:Port.
show_dest_status/2	Shows some internal information about load balancing to a specified Host:Port.
spawn_link_worker_process/2	Same as spawn_worker_process/2 except the the calling process is linked to the worker process which is spawned.
spawn_worker_process/2	Creates a HTTP client process to the specified Host:Port which is not part of the load balancing pool.
start/0	Starts the ibrowse process without linking.
start_link/0	Starts the ibrowse process linked to the calling process.
stop/0	Stop the ibrowse process.
stop_worker_process/1	Terminate a worker process spawned using spawn_worker_process/2 or spawn_link_worker_process/2.
terminate/2
trace_off/0	Turn tracing off for the ibrowse process.
trace_off/2	Turn tracing OFF for all connections to the specified HTTP server.
trace_on/0	Turn tracing on for the ibrowse process.
trace_on/2	Turn tracing on for all connections to the specified HTTP server.

Function Details

code_change/3

code_change() -> term()

get_config_value/1

get_config_value() -> term()

Internal export

get_config_value/2

get_config_value() -> term()

Internal export

handle_call/3

handle_call() -> term()

handle_cast/2

handle_cast() -> term()

handle_info/2

handle_info() -> term()

init/1

init() -> term()

rescan_config/0

rescan_config() -> term()

Clear current configuration for ibrowse and load from the file
ibrowse.conf in the IBROWSE_EBIN/../priv directory. Current
configuration is cleared only if the ibrowse.conf file is readable
using file:consult/1

rescan_config/1

rescan_config() -> term()

send_req/3

send_req(Url::string(), Headers::headerList(), Method::method()) -> response()

headerList() = [{header(), value()}]
header() = atom() | string()
value() = term()
method() = get | post | head | options | put | delete | trace | mkcol | propfind | proppatch | lock | unlock | move | copy
Status = string()
ResponseHeaders = [respHeader()]
respHeader() = {headerName(), headerValue()}
headerName() = string()
headerValue() = string()
response() = {ok, Status, ResponseHeaders, ResponseBody} | {error, Reason}
ResponseBody = string() | {file, Filename}
Reason = term()

This is the basic function to send a HTTP request.
The Status return value indicates the HTTP status code returned by the webserver

send_req/4

send_req(Url, Headers, Method::method(), Body::body()) -> response()

body() = [] | string() | binary() | fun_arity_0() | {fun_arity_1(), initial_state()}
initial_state() = term()

Same as send_req/3.
If a list is specified for the body it has to be a flat list. The body can also be a fun/0 or a fun/1.
If fun/0, the connection handling process will repeatdely call the fun until it returns an error or eof.

Fun() = {ok, Data} | eof

If fun/1, the connection handling process will repeatedly call the fun with the supplied state until it returns an error or eof.

Fun(State) = {ok, Data} | {ok, Data, NewState} | eof

send_req/5

send_req(Url::string(), Headers::headerList(), Method::method(), Body::body(), Options::optionList()) -> response()

optionList() = [option()]
option() = {max_sessions, integer()} | {max_pipeline_size, integer()} | {trace, boolean()} | {is_ssl, boolean()} | {ssl_options, [SSLOpt]} | {pool_name, atom()} | {proxy_host, string()} | {proxy_port, integer()} | {proxy_user, string()} | {proxy_password, string()} | {use_absolute_uri, boolean()} | {basic_auth, {username(), password()}} | {cookie, string()} | {content_length, integer()} | {content_type, string()} | {save_response_to_file, srtf()} | {stream_to, process()} | {http_vsn, {MajorVsn, MinorVsn}} | {host_header, string()} | {transfer_encoding, {chunked, ChunkSize}}
process() = pid() | atom()
username() = string()
password() = string()
SSLOpt = term()
ChunkSize = integer()
srtf() = boolean() | filename()
filename() = string()

Same as send_req/4.
For a description of SSL Options, look in the ssl manpage. If the
HTTP Version to use is not specified, the default is 1.1.

The host_header is useful in the case where ibrowse is
connecting to a component such as stunnel which then sets up a
secure connection to a webserver. In this case, the URL supplied to
ibrowse must have the stunnel host/port details, but that won’t
make sense to the destination webserver. This option can then be
used to specify what should go in the Host header in
the request.

When both the options save_response_to_file and stream_to
are specified, the former takes precedence.
For the save_response_to_file option, the response body is saved to
file only if the status code is in the 200-299 range. If not, the response body is returned
as a string.
Whenever an error occurs in the processing of a request, ibrowse will return as much
information as it has, such as HTTP Status Code and HTTP Headers. When this happens, the response
is of the form {error, {Reason, {stat_code, StatusCode}, HTTP_headers}}

send_req/6

send_req(Url, Headers::headerList(), Method::method(), Body::body(), Options::optionList(), Timeout) -> response()

Timeout = integer() | infinity

Same as send_req/5.
All timeout values are in milliseconds.

send_req_direct/4

send_req_direct() -> term()

Same as send_req/3 except that the first argument is the PID
returned by spawn_worker_process/2 or spawn_link_worker_process/2

send_req_direct/5

send_req_direct() -> term()

Same as send_req/4 except that the first argument is the PID
returned by spawn_worker_process/2 or spawn_link_worker_process/2

send_req_direct/6

send_req_direct() -> term()

Same as send_req/5 except that the first argument is the PID
returned by spawn_worker_process/2 or spawn_link_worker_process/2

send_req_direct/7

send_req_direct() -> term()

Same as send_req/6 except that the first argument is the PID
returned by spawn_worker_process/2 or spawn_link_worker_process/2

set_dest/3

set_dest() -> term()

Deprecated. Use set_max_sessions/3 and set_max_pipeline_size/3
for achieving the same effect.

set_max_pipeline_size/3

set_max_pipeline_size(Host::string(), Port::integer(), Max::integer()) -> ok

Set the maximum pipeline size for each connection to a specific Host:Port.

set_max_sessions/3

set_max_sessions(Host::string(), Port::integer(), Max::integer()) -> ok

Set the maximum number of connections allowed to a specific Host:Port.

show_dest_status/2

show_dest_status() -> term()

Shows some internal information about load balancing to a
specified Host:Port. Info about workers spawned using
spawn_worker_process/2 or spawn_link_worker_process/2 is not
included.

spawn_link_worker_process/2

spawn_link_worker_process() -> term()

Same as spawn_worker_process/2 except the the calling process
is linked to the worker process which is spawned.

spawn_worker_process/2

spawn_worker_process(Host::string(), Port::integer()) -> {ok, pid()}

Creates a HTTP client process to the specified Host:Port which
is not part of the load balancing pool. This is useful in cases
where some requests to a webserver might take a long time whereas
some might take a very short time. To avoid getting these quick
requests stuck in the pipeline behind time consuming requests, use
this function to get a handle to a connection process.
Note: Calling this function only creates a worker process. No connection
is setup. The connection attempt is made only when the first
request is sent via any of the send_req_direct/4,5,6,7 functions.
Note: It is the responsibility of the calling process to control
pipeline size on such connections.

{error, closing_on_request}

Host = string()
Port = integer()

Turn tracing on for all connections to the specified HTTP
server. Host is whatever is specified as the domain name in the URL

Overview

Generated by EDoc, Mar 27 2008, 01:20:55.

ibrowse API

Module ibrowse

Clone this wiki locally