This is a true HTTP 1.1 client. See http_client.mli for details.

The installation of this client is "findlib"-based. "findlib" is a
simple library that organizes the installation of "packages", i.e.
collections of ocaml modules. (The client works without "findlib",
but you have to heavily modify the Makefile.)

THIS VERSION OF NETCLIENT WORKS ONLY WITH O'CAML 3.04!

You need the following packages:

	- netstring

(or netstring).

If you want support for multi-threaded applications, you need
additionally

	- xstr

You find "findlib" and the packages in the Ocaml link database,

	http://www.npc.de/ocaml/linkdb/

Note that there is online documentation for "findlib":

	http://www.ocaml-programming.de/packages/documentation/findlib/

------------------------------------------------------------------------
Installation:
------------------------------------------------------------------------

- It is assumed that "findlib" and "netstring" are properly installed.
  (And "xstr" if you want MT-support.)

- Do 
	make all
  to compile with the bytecode compiler. This creates netclient.cma and
  netclient_mt.cma, the library variant for multi-threading. If you do 
  not want the latter, compile with
	make non_mt

- Do 
	make non_mt_opt
  to compile with the native compiler if present. This creates netclient.cmxa.
  If your O'Caml installation supports POSIX threads, you can also do
	make opt
  to get the thread-safe variant, too (netclient_mt.cmxa).

- Do
	make install
  to install.

- Do
	make uninstall
  to uninstall.



------------------------------------------------------------------------
How to link in netclient.cma:
------------------------------------------------------------------------

To link something which uses netclient.cma, use the following command
which demonstrates how to link:

ocamlc  -custom -o output 
	`ocamlfind use cgi base64 netclient`     # this line is explained below
	unix.cma str.cma netstring.cma netclient.cma 
	<your objects>
	-cclib -lunix -cclib -lstr

Explanation:
The command "ocamlfind use netclient" results in a string
like
	-I /somewhere/netstring -I /somewhere/netclient

ocamlfind is part of the "findlib" module. You can of course put several
"-I" options into the link command instead, but if you use ocamlfind you
do not need to remember where you installed cgi, base64, and so on.


IF YOU HAVE FINDLIB-0.2 OR NEWER:

This version of "findlib" is much more convenient. It comes with a new
frontend for "ocamlc" that is intelligent enought to find out most of
the compiler/linker options itself.
Link with

ocamlfind ocamlc -custom -o output -package netclient -linkpkg <your objects>


SUPPORT FOR MULTI-THREADING:

This is simply enabled by giving the -thread option, e.g. 

ocamlfind ocamlc -custom -thread -o output -package netclient -linkpkg 
	  <your objects>

If you have POSIX threads, include '-predicates mt_posix', too.

------------------------------------------------------------------------
Example:
------------------------------------------------------------------------

- Create a new toploop that supports Str and Unix:
  ocamlmktop -o fat -custom unix.cma str.cma -cclib -lunix -cclib -lstr

  FINDLIB-0.2:

  ocamlfind ocamlmktop -o fat -custom -package unix,str,findlib -linkpkg

- Invoke this toploop:
  fat `ocamlfind use cgi base64 netclient`

  (The "ocamlfind" adds several "-I" options to the "fat" command.)

  FINDLIB-0.2:

  fat

- load what you need:
  #load "cgi.cma";;
  #load "base64.cma";;
  #load "netclient.cma";;

  FINDLIB-0.2:

  #require "netclient";;

- make your HTTP message:

  open Http_client;;
  let g = new get "http://somewhere.com/file";;

- make a new "pipeline":

  let p = new pipeline;;

- push your message into the pipeline:

  p # add g;;

- process all pending messages:

  p # run();;

- get the result:

  g # get_resp_body();;

------------------------------------------------------------------------
New Convenience Module
------------------------------------------------------------------------

From release 0.2, there is a convenience module which simplifies the
usage of the client.

- open the module:

  open Http_client.Convenience;;

- get the result in one step:

  http_get "http://somewhere.com/file"

The convenience module also interprets the environment variables
http_proxy and no_proxy. Furthermore, user and password can be
given directly in the URL (http://user:password@location.domain/path).


------------------------------------------------------------------------
RESTRICTED MULTI-THREADING SAFETY
------------------------------------------------------------------------

If used in a certain way, release 0.3 of "netclient" is thread-safe. 
See the comment in "http_client.mli" for details.


------------------------------------------------------------------------
Restrictions
------------------------------------------------------------------------

- Some rarely used features of HTTP/1.1 have not been implemented,
  such as multipart messages. 

- Some features of HTTP/1.1 are not supported by this module, but can 
  be implemented on top of it:
  content encoding, content digests, conditional/partial GET, caching

- HTTP/1.0 persistent connections are not implemented. If you need this,
  ask Netscape to improve their servers.

- HTTP/1.1 pipelining is not yet implemented, but this is planned.


A lot of fun!

Author:

Gerd Stolpmann, gerd@gerd-stolpmann.de


