Documentation

Printer Status

Compatibility

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

Objective

  • Retrieve status information from printers (.e.g. out of paper, offline, etc.).

Outline

Listen for Printer Status

Select the printers to get statuses on using qz.printers.startListening(...)

// Specific printer
qz.printers.startListening("ZDesigner LP2844")
   .catch(err => console.error(err);

// All printers
qz.printers.startListening()
   .catch(err => console.error(err)

// Based on best-match
qz.printers.find("ZDesigner").then(printer => {
   console.log("Listening for printer events", printer));
   return qz.printers.startListening(printerName);
}).catch(err => console.error(err));

Setup Callback

Setup a callback to fire when status changes and request status using qz.printers.setPrinterCallbacks(...) and request immediate status using qz.printers.getStatus().

qz.printers.setPrinterCallbacks(evt => console.log(evt.severity, evt.eventType, evt.message));

qz.printers.getStatus().then(() => console.log("Listening on printer status"));
   .catch(err => console.error(err));

Sample Event

{
   printerName: "PDFwriter",
   jobName: "My Sample PDF",                                  /* since 2.1.3 */
   eventType: "JOB",                                          /* since 2.1.3 */
   statusText: "PAUSED",                                      /* since 2.1.3 */
   severity: "WARN",
   statusCode: "media-empty", // (or for Windows, 0x00000040) /* since 2.1.3 */
   message: ...
}

Stop listening

Stop listening to all printers

qz.printers.stopListening().then(() => console.log("Stopped listening"))
   .catch(err => console.error(err));

Full example

//setup a callback
qz.printers.setPrinterCallbacks((evt) => { console.log(evt.severity, evt.eventType, evt.message); });

function getPrintersStatus () {
    // get the status of a specific printer
    qz.printers.find("Printer Name").then(printer => {
        // listen to the printer
        qz.printers.startListening(printer).then(() => {
            return qz.printers.getStatus();
        });
    }).catch(function(e) { console.error(e); });
};

image

Advanced

Printer Contents Monitoring

Since 2.2.2, QZ Tray has the ability to receive raw job data (e.g. .PRN file), but has the following requirements:

  • This feature is Windows only (this feature is not yet supported on macOS, Linux)

  • User must be able to read the spool file location

  • qz-tray.properties must be modified to toggle this feature on or you will receive the error Job data listeners are currently disabled.

    #Wed Dec 14 16:16:09 EST 2022
    printer.status.jobdata=true
  • An additional parameter jobData must be provided to startListening(...).

    var options = {
        jobData: true,      // toggle job data
    };
    
    qz.printers.startListening(null /* all printers */, options);
  • The format and size of the data can be manipulated using flavor and maxJobData, respectively.

    var options = {
        jobData: true,      // toggle job data
        flavor: 'base64',   // return spool file content as 'base64' (default is 'plain')
        maxJobData: 64      // only return data less than or equal to 64 bytes (default is -1)
    };
    
    qz.printers.startListening(null /* all printers */, options);
Edit this page