Internet utilities Isis software documentation

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.

-> (display-url-image "http://www.media.mit.edu/~stefan/photos/nana.jpg") [ Proc [ 2 True 3 [ 485 343 ] [ 1 485 ] [ 0x1402ce8c0 0x1402f7293 0x14031fc66 ] ] ]

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.
-> (parse-url "http://westner.www.media.mit.edu/people/westner/vin2.jpg") [ "http" "westner.www.media.mit.edu" 80 "/people/westner/vin2.jpg" ] -> (parse-url "file:/mas/garden/grad/stefan/blah.txt") [ "file" Null Null "/mas/garden/grad/stefan/blah.txt" ]

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:
"error-code" "content-length" "content-type" "date" "server" "mime-version"
All other headers are currently ignored. The values associated with each name will be whatever type is most appropriate.

After the header has been read, the actual document data is ready to be received from the same port. You could use one of the port utilities for reading the text or data from the connection.

-> (set webfile (http-open "web.media.mit.edu" 80 "~stefan")) [ "TCP socket" "FD" 3 True True Cfunc Cfunc Cfunc Cfunc Cfunc Cfunc Cfunc Cfunc Cfunc ] -> (http-header webfile) [ [ "date" "Tue, 02 Apr 2002 14:22:19 GMT" ] [ "server" "Apache/1.3.23 (Unix) PHP/4.1.2 mod_perl/1.26 mod_ssl/2.8.6 OpenSSL/0.9.6c" ] [ "content-type" "text/html; charset=iso-8859-1" ] ]

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.

Requirements:
Scripts: (load "internet-utilities.isis")