qz | Printer Status

FAQ

Code Examples

Overview HTML Printing PDF Printing Image Printing Advanced Pixel Printing

Overview Raw Encoding ZPL EPL ESC/POS ESC/P DPL PGL SBPL

Printer Status File Communication HID Communication Serial Communication

Network Information Data Filtering Getting Started Using QZ Tray Signing Messages API Overrides Command Line Usage

Licensing/Renewing

Generate Certificate Certificate Renewal Company Branded Signing Messages General Licensing Information

Printer Emulators

Deployment Options

Print Server Deployment Multiple Instances Windows Service Headless Operation Unattended Deployment Custom Provisioning Client Side Substitutions

Configure Raw Printer

Windows Ubuntu Linux macOS

Compiling

Install Dependencies Compile (QZ Tray)

Printer Status

Compatibility

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

Objective

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

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

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

Documentation