 |
|
|
|
||||
|
|||||
|
|
||||||
| Other Library Functions | ||||||
| function |
vfs.open-https |
|
Library: General, File system utilities (OMVFS)
Import: omvfs.xmd |
Return type: vfsFile Returns: A VFS file object for the opened file. |
export external file function open-https
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
verify value switch verify-peer optional initial {true}
certificates-file value stream ca-file optional initial {./omvfs-certificates-file.crt}
Argument definitions
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:
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.
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.
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.
The following exceptions may occur:
