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 stream_connect function. To write to the file, use the stream_send functions. To read from the file, use the stream_receive functions.

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 blocks, 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 stream_listen function, 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 stream_accept function will return with a client stream representing the file specified in the URI when the listening stream detects that the file exists. Hence, the stream_accept function 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 stream_accept function.

This mechanism is useful for designing a model 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 model 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 Stream Listen block once the data has been generated. The Stream Accept block 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 Stream Receive block may then be used with the returned stream to read the contents of the file. Note that the Stream Accept block opens the file immediately if it already exists at the time the Stream Accept block is executed.

It is also possible to detect when a file is deleted (or renamed). When used with a listening stream the stream_poll function 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 stream_poll function 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 stream_poll function to wait for the file to be deleted (either directly or through renaming the file). This functionality allows a model 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

Sharing

Listening

Options

mode

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

share

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 model. Valid sharing modes are:

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

Driver

The driver supporting the file protocol is called qrt_file.

Targets

See Also

• Communications
• QUARC Communications Protocols
• Communications Using the C Language

Copyright ©2024 Quanser Inc. This page was generated 2024-10-17. Submit feedback to Quanser about this page.