File Protocol :: RCP Communications Protocols

navigation bar

Table of Contents >Quanser Rapid Control Prototyping Toolkit >Communication Protocols >

File Protocol

The file protocol supports reading from and writing to a file on the local filesystem.

Syntax

file://hostname/path % Access a file on host 'hostname' at absolute path 'path'
file:/path           % Access a file on current machine at absolute path 'path'
file:path            % Access a file on current machine at relative path 'path'

Description

The file protocol supports reading from and writing to a file on the local filesystem. It is identified by using file as the protocol name in a URI.

The hostname and port in the URI are ignored, if specified. To specify an absolute path, either include the authority (hostname and optional port) followed by a "/" and the absolute path to the file, or omit the authority entirely and just specify the absolute path preceded by a "/". For example, the following URIs all specify the absolute path "/home/drmadill/myfile.dat".

file://localhost/home/drmadill/myfile.dat

file:/home/drmadill/myfile.dat

Likewise, the following URIs all specify the absolute path "C:\myfile.dat". Note that the drive letter may be followed by a ":" or by a "|". Forward slashes ("/") should always be used to separate folders in a path. The path will be converted internally to the appropriate operating-system specific format as required.

file://localhost/C:/Temp/myfile.dat

file:/C:/Temp/myfile.dat

To specify a path relative to the current directory omit the authority and leading "/". URIs that contain an authority (hostname and optional port) must use absolute paths for the file path because the "/" separates the authority component from the path. For example, the following URIs are relative paths:

file:../Temp/myfile.dat

file:myfile.dat

While the default access mode for files is read access, all file URIs should contain the mode option as specified below. Options appear after the "?" in the URI. For example,

file:myfile.dat?mode=w

Files are opened using the CL Stream Connect vi. To write to the file, use the CL Stream Write vi. To read from the file, use the CL Stream Read vi. Note that it is only possible to write to the file if the mode option (see below) is specified as write-only, append, or read-write access. Similarly, it is only possible to read from the file if the mode option is specified as read-only, or read-write access. The default mode is read-only access. To avoid confusion it is always best to specify the mode.

Files are always accessed as binary files. Using text is accomplished by using the appropriate Stream VIs, not through the underlying file protocol. This technique ensures that text may be used with any protocol, not just files.

There are instances where it is convenient to know when a file has just been created or deleted. Listening streams, created using the CL Stream Listen VI, are used for this purpose. When a listening stream is created for the file protocol it monitors the directory associated with the file for changes.

The CL Stream Accept VI will return with a client stream representing the file specified in the URI when the listening stream detects that the file exists. Hence, the CL Stream Accept VI can be used to wait for the file to be created (either directly or through renaming another file). It then opens the file with read-only access and outputs a handle to the file as the "client stream". Since the file is opened with read-only access it is only possible to read from the file returned by the CL Stream Accept VI.

This mechanism is useful for designing a VI that begins reading a file as soon as it is created. For example, the user may have an application that generates offline trajectory data that they want the VI to read as soon as they have generated the trajectory. The best way to use this feature is to create the file in the same directory under a different name (from an application, for example) and then rename the file to the file name specified in the URI of the CL Stream Listen VI once the data has been generated. The CL Stream Accept VI associated with the listening stream will wake up as soon as the file is renamed and open the file for reading, outputting the file handle as the "client stream". A CL Stream Read VI may then be used with the returned stream to read the contents of the file. Note that the CL Stream Accept VI opens the file immediately if it already exists at the time the CL Stream Accept VI is executed.

It is also possible to detect when a file is deleted (or renamed). When used with a listening stream the CL Stream Poll VI may be used for this purpose. Polling for the "Wait for a client connection to be ready to accept" (QCOMM_POLL_ACCEPT) condition causes the CL Stream Poll VI to wait for the file to be created (either directly or through renaming another file). Polling for the "Wait for space available to send" (QCOMM_POLL_SEND) condition causes the CL Stream Poll VI to wait for the file to be deleted (either directly or through renaming the file). This functionality allows a VI to be designed in which a file is read every time it is created (if the application producing it renames or deletes the file each time it recreates it).

Limitations

Performance

Warning

The performance of the file protocol depends on the performance of the underlying file system. Clearly a floppy disk is going to be slower than a hard drive.

Sharing

Warning

The file protocol supports different sharing modes. Whether more than one process can read or write to the file at the same time depends on the sharing mode.

Listening

Warning

Not all operating systems support file system notification. Thus, the file protocol may not support the CL Stream Listen and CL Stream Accept VIs on those operating systems. Currently only the RCP Target for Windows supports these two VIs with the file protocol.

Options

mode

Sets the access mode used when opening the file. Valid access modes are:

Mode	Description
r	opens for reading. If the file does not exist or cannot be found, an error is returned. (default)
r+	opens for both reading and writing. If the file does not exist or cannot be found, an error is returned.
w	opens for writing. If the file does not exist, it is created. If the file does exist, its contents are deleted.
w+	opens for both reading and writing. If the file does not exist, it is created. If the file does exist, its contents are deleted.
a	opens for appending. If the file does not exist, it is created. If the file does exist, writes begin at the end of the file. The contents are not deleted.
a+	opens for reading and appending. If the file does not exist, it is created. If the file does exist, writes begin at the end of the file. The contents are not deleted.

Set this option to the desired sharing mode. The sharing mode determines whether more than one process can access the file at the same time as the VI. Valid sharing modes are:

Mode	Description
no	Do not allow other processes to read from or write to the file. (default)
r	allows other processes to read from the file.
w	allows other processes to write to the file.
rw	allow other processes to read from or write to the file.

If no share option is specified then sharing is not allowed.

Driver

The driver supporting the file protocol is called qrt_file.

Targets

Target	Supported	Comments
RCP Windows (64-bit) Target	Yes	Fully supported.