Other Library Functions

vfs.open-http

function

Library: File system utilities (OMVFS)
Import : omvfs.xmd

Returns: a VFS file object for the opened file


Declaration 
export external file function open-http
                     value string     URL
       on            value directory  on-dir      optional
       with-headers  read-only stream headers     optional
       post          value string     postdata    optional
       as-raw        value switch     raw         optional initial {false}
       for           value integer    access-type optional initial {read-mode}
       user       value string     user     optional
       password value string   pass     optional
       proxy  value string   proxy     optional

Argument definitions

filename
The URL of the file to be opened.
with-headers
Optional HTTP headers to be added to the request.
postdata
Optional POSTdata to be added to the request.
raw
Specifies whether default HTTP headers will be generated and whether HTTP respose headers will be stripped from the response.
on-dir
A connected vfs.directory object. This parameter is not supported in this release of OMVFS.
access-type
An integer constant signifying the desired mode of access. The default value is vfs.read-mode.
user
For basic authentication when URL encoding of user/password is not supported.
password
Password for basic authentication when URL encoding of user/password is not supported.
proxy
For specification of the proxy server. The format is host:port or http://host:port.


Purpose

You can use vfs.open-http to open a file that resides on an HTTP server. vfs.open-http creates a vfs.file object that represents the file, and which can be used with various OMVFS functions to manipulate the file. 

  import "omvfs.xmd" prefixed by vfs.
  
  process
     local vfs.file input-file
     set input-file to vfs.open-http "http://www.stilo.com/" 
     submit vfs.reader of input-file

Note that the OMVFS library functions do not do "URL fix-up", which means that the URL "http://www.stilo.com" (without the final slash) will not be accepted. Nor will a URL that lacks the introductory "http://".

You may specify the mode in which the file is opened. The default mode is read mode. The following modes are available:

Note that not all OMVFS functions are supported by all protocols. You will receive a runtime error if you attempt to perform an operation on a file on an http server if that operation is not supported by the http protocol, or if that function is not supported in the current version of OMVFS. In the current implementation, the following functions are supported:

GET and POST requests

You can use vfs.open-http to make either a GET or POST request. The default is a GET request. If you supply POST data using the optional postdata argument (heralded by post), then a POST request is made.

You can supply additional headers to a POST or GET request by specifying set of headers using the optional headers argument (heralded by with-headers). The headers argument takes a keyed stream shelf with one header per item and header names as keys.

Raw mode

By default, vfs.open-http generates a minimum necessary set of HTTP headers to create a valid HTTP request, and it strips out any HTTP headers received in an HTTP response. If you specify raw mode by passing a value of true to the optional raw argument (heralded by as-raw, then OMVFS will neither generate or strip headers. You will be responsible for generating the appropriate headers and for interpreting the response. import "omvfs.xmd" prefixed by vfs. 

  process
     local stream headers variable
     local vfs.file input-file
     set new headers{"Host"} to "www.stilo.com"
     set input-file 
      to vfs.open-http "http://www.stilo.com/"
       with-headers headers
       as-raw true
     submit vfs.reader of input-file

Error handling

An HTTP request may return an error code in the form of an HTTP response code. In normal mode, OMVFS will generate a runtime exception VFS400 if it receives an HTTP response code greater than 299. You can examine the error message to determine the error code. In raw mode, OMVFS does not examine the HTTP response code. It is your responsibility to scan the returned data and determine if the expected HTTP response code was received.

Exceptions

The following exceptions may occur:

Other Library Functions