Next: , Previous: Top, Up: Top


1 (www http)

The (www http) module includes procedures for high-level HTTP operation, low-level HTTP message object access, and common messages.

1.1 High-Level HTTP Operation

— Procedure: http:connect proto addrfam address [address-rest...]

Return a TCP stream socket connected to the location specified by protocol proto, addrfam and address. proto is PF_INET or PF_UNIX, and the other args take corresponding forms:

PF_INET
(AF_INET ipaddr portno), where ipaddr is an integer. Use (car (hostent:addr-list (gethost host))) to compute the ipaddr of host (a string).
PF_UNIX
(AF_UNIX filename), made, for example, by
(list AF_UNIX "/tmp/foo-control").

Note that PF_foo and AF_foo are names of variables that have constant values, not symbols.

— Procedure: http:open host [port]

Return an HTTP connection (a socket) to host (a string) on TCP port port (default 80 if unspecified).

— Procedure: http:request method url [headers [body]]

Submit an HTTP request using method and url, wait for a response, and return the response as an HTTP message object.

method is the name of some HTTP method, e.g. "GET" or "POST". url is a url object returned by url:parse. Optional args headers and body are lists of strings that comprise the lines of an HTTP message. The strings should not end with ‘CR’ or ‘LF’ or ‘CRLF’; http:request handles that. Also, the Content-Length header and Host header are calculated automatically and should not be supplied. Here are two examples:

          (http:request "get" parsed-url
            (list "User-Agent: Anonymous/0.1"
                  "Content-Type: text/plain"))
          
          (http:request "post" parsed-url
            (list "User-Agent: Fred/0.1"
                  "Content-Type: application/x-www-form-urlencoded")
            (list (string-append "search=Gosper"
                                 "&case=no"
                                 "&max_hits=50")))

As a special case (demonstrated in the second example above), when Content-Type is application/x-www-form-urlencoded and there is only one line in the body, the final ‘CRLF’ is omitted and the Content-Length is adjusted accordingly.

1.2 Low-Level HTTP Message Object Access

— Procedure: http:message-version msg

Return the HTTP version in use in HTTP message msg.

— Procedure: http:message-status-code msg

Return the status code returned in HTTP message msg.

— Procedure: http:message-status-text msg

Return the text of the status line from HTTP message msg.

— Procedure: http:message-status-ok? msg

Return #t iff status code of msg indicates a successful request.

— Procedure: http:status-ok? status

Return #t iff status (a string) begins with "2".

— Procedure: http:message-body msg

Return the body of the HTTP message msg.

An HTTP message header is represented by a pair. The car is a symbol representing the header name, and the cdr is a string containing the header text. E.g.:

     '((date . "Thu, 29 May 1997 23:48:27 GMT")
       (server . "NCSA/1.5.1")
       (last-modified . "Tue, 06 May 1997 18:32:03 GMT")
       (content-type . "text/html")
       (content-length . "8097"))

Note: these symbols are all lowercase, although the original headers may be mixed-case. Clients using this library should keep this in mind, since Guile symbols are case-sensitive.

— Procedure: http:message-headers msg

Return a list of the headers from HTTP message msg.

— Procedure: http:message-header header msg

Return the header field named header from HTTP message msg, or #f if no such header is present in the message.

1.3 Common Messages

— Procedure: http:head url

Submit an http request using the HEAD method on the url. The Host header is automatically included.

— Procedure: http:get url

Submit an http request using the GET method on the url. The Host header is automatically included.

— Procedure: http:post-form url extra-headers fields

Submit an http request using the POST method on the url. extra-headers is a list of extra headers, each a string of form "name: value ...".

The "Content-Type" and "Host" headers are sent automatically and do not need to be specified. fields is a list of elements of the form (fkey . fvalue), where fkey is a symbol and fvalue is normally a string.

fvalue can also be a list of file-upload specifications, each of which has the form (source name mime-type transfer-encoding). source can be a string or a thunk that returns a string.

The rest of the elements are strings or symbols: name is the filename (only the non-directory part is used); mime-type is a type/subtype pair such as "image/jpeg", or #f to mean "text/plain". transfer-encoding is one of the tokens specified by RFC 1521, or #f to mean "binary". File-upload spec elements with invalid types result in a "bad upload spec" error prior to the http request.

Note that source is used directly without further processing; it is the caller's responsibility to ensure that the MIME type and transfer encoding specified describe source accurately.