Wiki - 2.1 File Communication

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 Storage Locations

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

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 eachother'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 options set to null to prevent file data from being returned along with file change events.
  • Parameter lines: 10 max number of lines to read at a time. -1 to disable.
  • Parameter bytes: 4048 max number of bytes to read at a time. -1 to disable.
  • Parameter reverse: true toggles whether to read from the bottom of the file.
// 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 options 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 options = { lines: 10, reversed: true };

qz.file.startListening('.', { sandbox: false, shared: true }, options).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