Internet utilities

This document explains the various Isis Internet utilities, including
functions for retrieving documents and images from the World Wide Web,
manipulating URLs and query strings, and using HTTP.

Reading documents from URLs

(retrieve-url-image url) # returns image buffer
(retrieve-url-image-sequence url) # returns list of image buffers
(display-url-image url)
(display-url-image-sequence url { frame-delay cycles } )
(download-url-document url filename)
These are extremely high-level functions that accept a URL and, using
whatever protocol and decoding necessary, retrieve a document. For
the image functions, the URL you pass must point to either a JPEG or
GIF image or animation. retrieve-url-image returns an Isis
image buffer, and retrieve-url-image-sequence returns a list
of images buffers, one for each frame in a sequence. If there are
multiple frames, retrieve-url-image just returns the first
one. If there is only one frame, retrieve-url-image-sequence
will return a list of just one item.

display-url-image and display-url-image-sequence
display the image or sequence in a window (using the image window library).
display-url-image returns a list of the window handle and the
image buffer or list of buffers. An optional frame delay (in seconds)
and number of cycles may be passed to
display-url-image-sequence, but this function closes the
window after playing the sequence and returns Null.

download-url-document saves the data pointed to by the URL to
the specified filename. Null is returned if there is an
error at any stage.

URLs

(parse-url url) # returns [protocol host portnumber document]
parse-url accepts a string URL and separates it into its
component parts for easier use. The protocol, host name, and document
name are returned as strings, and the port number is returned as an
integer.

HTTP

(http-open host portnumber document) # returns open file handle
(http-header file) # reads header, returns as list of pairs
(http-header-structure file) # returns same thing in Isis structure
http-open opens a connection to the host and port for reading
the specified document and returns an open file handle. You should
immediately read the header from the file using http-header
or http-header-structure. These functions return a
name/value pair database in the form of a list or an Isis structure
(more convenient for searches). The "names" will be strings and will
be one of the following, if they exist in the header:

Query strings

(parse-query-string query-string) # returns list of pairs
(query-string-structure query-string) # returns same thing in Isis structure
These functions provide a way of separating each name/value pair in a
query string. You can get the result in the form of a list or an Isis
structure (more convenient for searches). Control characters are
automatically converted into their single character representation.