[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.12 rfc.http - HTTP

Module: rfc.http
This module provides a simple client API for HTTP/1.1, defined in RFC2616, "Hypertext Transfer Protocol -- HTTP/1.1" (RFC2616).

Current API implements only a part of the protocol. Only GET, HEAD, and POST requests are supported, it doesn't talk with HTTP/1.0 server yet, and it doesn't support HTTP/1.1 advanced features such as persistent connection. Support for those features may be added in the future versions.

Function: http-get server request-uri &keyword sink flusher no-redirect ...
Function: http-head server request-uri &keyword no-redirect ...
Function: http-post server request-uri body &keyword sink flusher no-redirect ...

Send http GET, HEAD and POST requests to the http server, and returns the server's reply.

If the server returns "3xx" redirection reply, these procedures try to follow the URI returned in the "location" reply message header by default. See the "keyword arguments" heading below to suppress redirection following.

Required arguments: The server argument specifies http server name in a string. A server name can be optionally followed by colon and a port number. Examples: "w3c.org", "mycompany.com:8080".

The request-uri argument is the request-uri specified in RFC2616; usually, this is the path part of http url.

Http-post takes the third argument, body, which is a string to be posted to the server. The body is sent "as is"; the caller has to take care of necessary escaping or encoding.

So, the most simple form of retrieving the content will be something like this:

 
(http-get "www.shiro.dreamhost.com" "/scheme/index.html")

Access via proxy can be done by specifying proxy server to server and passing the entire URI to request-uri, but the author haven't tested yet.

Return values: All procedures return three values.

The first value is the status code defined in RFC2616 in a string (such as "200" for success, "404" for "not found").

The second value is a list of parsed headers--each element of list is a list of (header-name value ...), where header-name is a string name of the header (such as "content-type" or "location"), and value is the corresponding value in a string. The header name is converted to lowercase letters. The value is untouched except that "soft line breaks" are removed, as defined in RFC2822. If the server returns more than one headers with the same name, their values are consolidated to one list. Except that, the order of the header list in the second return value is the same as the order in the server's reply.

The third value is for the message body of the server's reply. By default, it is a message body itself in a string. If the server's reply doesn't have a body, the third value is #f. You can change how the message body is handled by keyword arguments; for example, you can directly store the returned message body to a file without creating intermediate string. The details are explained below.

Keyword arguments: By default, these procedures only attaches "Host" header field to the request message. You can give keyword arguments to add more header fields.

 
(http-get "foo.bar.com" "/index.html"
  :accept-language "ja"
  :user-agent "My Scheme Program/1.0")

The following keyword arguments are recognized by the procedure and do not appear in the request headers.

no-redirect
If a true value is given, suppress the redirection tracking; i.e. the procedures return "3xx" message as is.

sink, flusher
You can customize how the message body is handled by these keyword arguments. You have to pass an output port to sink, and a procedure that takes two arguments to flusher.

When the procedure starts receiving the message body, it feeds the received chunk to sink. When the procedure receives entire message body, flusher method is called with sink and a list of message header fields (in the same format to be returned in the second value from the procedure). The return value of flusher becomes the third return value from the procedure.

So, the default value of sink is a newly opened string port and the default value of flusher is (lambda (sink headers) (get-output-string sink)).

The following example saves the message body directly to a file, without allocating (potentially very big) string buffer.

 
(call-with-output-file "page.html"
  (lambda (out)
    (http-get "www.schemers.org" "/"
       :sink out :flusher (lambda _ #t))))


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated by Ken Dickey on November, 28 2002 using texi2html