Wiki - File

Compatibility

Background

Provide an interface for two-way file communication between QZ Tray and the local file system.

File Operations

Local Storage

By default, data is stored local to the logged-in user next to the QZ Tray logs in a folder called sandbox/<CN> where <CN> is the Common Name from the digital-certificate.txt. Folders may contain ^ to escape special characters, such as One/Half Inc would be One^fHalf Inc on the filesystem.

👤 User 👤 + 🔒 User Sandbox 👥 Shared 👥 + 🔒 Shared Sandbox
Windows %AppData%/qz/data %AppData%/qz/sandbox/<CN> %ProgramData%/qz/data %ProgramData%/qz/sandbox/<CN>
MacOS ~/Library/Application Support/qz/data ~/Library/Application Support/qz/sandbox/<CN> /Users/Shared/QZ Tray/data /Users/Shared/QZ Tray/sandbox/<CN>
Linux ~/.qz/data ~/.qz/sandbox/<CN> /srv/qz-tray/data/ /srv/qz-tray/sandbox/<CN>

Custom Storage Locations

Custom Shared Locations

Custom local storage locations may be added via qz-tray.properties.

file.whitelist=C:\\FirstFolder\\;C:\\SecondFolder\\

Custom Sandbox Locations

file.whitelist=C:\\FirstFolder\\|ABC Inc.;C:\\SecondFolder\\|XYZ Inc.

Read Data

Read data via qz.file.read(...) from a shared location and display it to the console.

Parameters
  • Parameter path can be absolute or relative file
  • Parameter sandbox: false will prevent appending sandbox/<CN> to file names; an optional security measure to avoid other trusted sites from reading from each other's folders.
  • Parameter shared: true will use a shared location accessible to all computer users
qz.file.read('file.txt', { sandbox: false, shared: true }).then(function(data) {
   console.log(data);
}).catch(function(err) {
   console.error(err);
});

Write Data

Write the specified data via qz.file.write(...) to the specified shared location, overwriting if exists. Will create any parent directories as needed. Path 'file.txt' would normally be relative path. Absolute file paths are allowed so as long as they're part of the approved local storage locations.

qz.file.write('file.txt', { sandbox: false, shared: true, data: "Hi!\n" }).then(function() {
   console.log("OK");
}).catch(function(err) {
   console.error(err);
});

Append Data

Use append: true to bypass default overwrite file behavior. Path 'file.txt' would normally be relative path. Absolute file paths are allowed so as long as they're part of the approved local storage locations.

qz.file.write('file.txt', { sandbox: false, shared: true, append: true, data: "There!\n" }).then(function() {
   console.log("OK");
}).catch(function(err) {
   console.error(err);
});

List Files

List files within the specified folder qz.file.list(...). Path '.' must be a folder and normally would be a relative path. Absolute file paths are allowed so as long as they're part of the approved local storage locations.

qz.file.list('.', { sandbox: false, shared: true }).then(function(data) {
   console.log("Files:");
   for (var n = 0; n < data.length; n++) {
      console.log(data[n]);
   }
}).catch(function(err) {
   console.error(err);
});

Delete File

Delete the specified file or folder via qz.file.remove(...). Path 'file.txt' normally would be a relative path. Absolute file paths are allowed so as long as they're part of the approved local storage locations.

qz.file.remove('file.txt', { sandbox: false, shared: true }).then(function(data) {
   console.log("OK");
}).catch(function(err) {
   console.error(err);
});

Listen For Changes

Listens for file change events within the specified folder qz.file.startListening(...). Path '.' must be a folder and normally would be a relative path. Absolute file paths are allowed so as long as they're part of the approved local storage locations. Some applications will fire duplicate events for Windows. This is a limitation of WatchService on Windows.

Parameters
  • Parameter include: [] Files to include when listening. (Since 2.1.1)
  • Parameter exclude: [] Since 2.1.1: Files to exclude when listening. (Since 2.1.1)
  • Parameter caseSensitive: true Since 2.1.1: Whether to use case-sensitive file matching. (Since 2.1.1)
  • Parameter listener set to null to prevent file data from being returned along with file change events.
// Setup our callback for when an event occurs
qz.file.setFileCallbacks(function(streamEvent) {
   if (streamEvent.type !== 'ERROR') {
      console.log("Type: " + streamEvent.eventType);
      console.log("File: " + streamEvent.file);
      // Data is optional, toggled off by setting params to null
      console.log("Data: " + streamEvent.fileData ? streamEvent.fileData : "<none>");
   } else {
      console.error(streamEvent.message);
   }
});

// Fetch up to 10 line changes at a time, reading from the bottom
var params = { sandbox: false, shared: true, listener: { lines: 10, reverse: true } };

qz.file.startListening('.', params).then(function() {
   console.log('OK');
}).catch(function(err) {
   console.error(err);
});

Filter Results

Since 2.1.1, the { include: [], exclude: [] } parameters are supported to filter the files returned when listening.

// Only listen to 'foo*.txt' files, unless they're called 'foobar*.txt'
var params = { include: 'foo*.txt', exclude: 'foobar*.txt' };
// Providing multiple filters
// var params = { include: ['foo*.txt', 'foo*.log'], exclude: ['foobar*.txt', 'foobar*.log'] };

qz.file.startListening('.', params).then(function() {
   console.log('OK');
}).catch(function(err) {
   console.error(err);
});

Stop Listening

Stops listening for file change events for the specified folder qz.file.stopListening(...). Path '.' must be a folder and normally would be a relative path. Absolute file paths are allowed so as long as they're part of the approved local storage locations.

qz.file.stopListening('.', { sandbox: false, shared: true }).then(function() {
   console.log('OK');
}).catch(function(err) {
   console.error(err);
});

Stop All Listeners

Stops listening for all file change events qz.file.stopListening() for the current, active websocket connection. If running QZ Tray in print-server mode, concurrent but separate clients will remain actively listening.

qz.file.stopListening().then(function() {
   console.log('OK');
}).catch(function(err) {
   console.error(err);
});
Edit this page