Other Library Functions

vfs.open-https

function

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

Returns: a VFS file object for the opened file


Declaration 
export external file function open-https
                     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
       verify        value switch     verify-peer optional initial    {true}
       certificates-file value string     ca-file     optional  initial    {"./omvfs-certificates-file.crt"}

Argument definitions

filename
TheURL 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
Not supported in this version of OMVFS.
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 formula is host:port or http://host:port
verify-peer
Determines whether the host's certificate is verified or not.
ca-file
Gives the location of the file listing certificate authorities.


Purpose

You can use vfs.open-https to open a file that resides on an HTTPS server. vfs.open-https 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-https "https://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 "https://www.stilo.com" (without the final slash) will not be accepted. Nor will a URL that lacks the introductory "https://".

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 https server if that operation is not supported by the https 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-https 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.

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.

Security

There are two aspects to the security provided by HTTPS, one is encryption, the other is the assurance that you are actually dealing with the host that you have specified. This assurance is obtained by reference to a certificate provided by a certificate authority.

A list of certificate authorities is provided with the OMVFS library, however you will still need to specify the path to the file which contains the list of certificate authorities. You can do this each time you call vfs.open-https by specifying the ca-file argument (heralded by certificates-file) or you can set the default certificates file with the function vfs.set-default-certificates-file. The name of the certificates file supplied with OMVFS is omvfs-certificates-file.crt.

To invoke the verification of the host's certificate, the verify-peer parameter (heralded by verify) must have a value of true, which is the default. When this parameter is set to true, the open operation will fail if the host's certificate cannot be verified. If you set this parameter to false, the connection will still be encrypted, however, the host's certificate will not be verified.

Exceptions

The following exceptions may occur:

Other Library Functions