swirl
Guide to OmniMark 7   OmniMark home
docs home 
IndexConceptsTasksSyntaxLibrariesLegacy LibrariesErrors
 
      Other Library Functions  
function  

vfs.open-http

 
 

Library: General, File system utilities (OMVFS)
Import: omvfs.xmd
Return type: vfsFile
Returns: 

A VFS file object for the opened file.


Declaration

  export external file function open-http
                       value stream     URL
         on            value directory  on-dir      optional
         with-headers  read-only stream headers     optional
         post          value stream     postdata    optional
         as-raw        value switch     raw         optional initial {false}
         for           value integer    access-type optional initial {read-mode}
         user       value stream     user     optional
         password value stream   pass     optional
         proxy  value stream   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
   vfs.change-directory
   vfs.change-owner
   vfs.change-permissions
   vfs.close
   vfs.connect
   vfs.connect-directory
   vfs.copy
   vfs.cursor-position
   vfs.default-certificates-file
   vfs.delete-directory
   vfs.delete-file
   vfs.describe
   vfs.describe-file
   vfs.directory
   vfs.directory-name
   vfs.disconnect
   vfs.file
   vfs.file-directory
   vfs.file-name
   vfs.link
   vfs.list
   vfs.lock
   vfs.make-directory
   vfs.move
   vfs.move-cursor
   vfs.omvfs-version
   vfs.open
   vfs.open-file-system
   vfs.open-ftp
   vfs.open-http
   vfs.open-https
   vfs.reader
   vfs.set-default-certificates-file
   vfs.truncate
   vfs.unlock
   vfs.writer
 
 

Top [ INDEX ] [ CONCEPTS ] [ TASKS ] [ SYNTAX ] [ LIBRARIES ] [ LEGACYLIBRARIES ] [ ERRORS ]

OmniMark 7.1.2 Documentation Generated: June 28, 2005 at 5:46:02 pm
If you have any comments about this section of the documentation, send email to [email protected]

Copyright © Stilo Corporation, 1988-2005.