Documentation

• ✅ 2.2 | ✅ 2.1 | ⛔ 2.0 | ⛔ 1.9 | ...

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

For security reasons, File Communication will only work if messages are signed. To disable this behavior, set the property security.file.strict=false in prefs.properties or qz-tray.properties and restart QZ Tray.

• READ, WRITE, APPEND, DELETE, LIST, LISTEN

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.

• The default data storage can be changed to all desktop users with the param shared: true.
• To disable the sandbox/<CN> suffix, use the param sandbox: false.

Custom Shared Locations

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

• Paths are separated with a semicolon ;
• A semicolon ; is a special delimiter and must be escaped as ^; if exist within a path or <CN> field.

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

• Note when listening to a shared drive, UNC paths (e.g. \\\\server\\share appear to work better than mapped drives, e.g. G:\\)
• Restart QZ Tray for changes to take effect.

Custom Sandbox Locations

• If followed by a pipe character |, the folder behaves as a sandboxed location. The content after the pipe character | will be the <CN>
• A pipe | is a special delimiter and must be escaped as ^| if exist within a path or <CN> field

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

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

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

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);
});

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 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 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);
});

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.

// 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);
});

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);
});

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);
});

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);
});