PrintLinkPrinters & profiles
List printers, read live status and real capabilities, and save reusable settings as profiles.
Last updated
Listing printers
const { queues, devices } = await client.listPrinters();queues— the printable targets;queueIdis what you pass tocompose({ queueId }).devices— physical devices, grouped. One printer may appear as several queues (different drivers or tray configurations, for example).
Each queue carries live status:
| Field | Meaning |
|---|---|
isSystemDefault | The operating system's default printer |
isUserPreferred | Set to "preferred" in the PrintLink console |
status.state | ready / printing / paused / offline and more |
status.reasons | Reason codes (out of paper, jam, door open…) |
The usual selection order is: user preferred, then system default, then the first entry. See quick start step 3.
Live status
const status = await client.printerStatus(queueId);Status changes are pushed, so there is nothing to poll:
const off = client.onPrinterStatusChanged((event) => {
if (event.status.state === 'offline') notifyUser('The printer went offline');
});Reading real capabilities
Do not guess what a printer supports — read it:
const caps = await client.getCapabilities(queueId);
caps.media.supported; // supported paper sizes
caps.media.ready; // currently loaded and usable
caps.media.customSize; // whether custom sizes work, and the range
caps.duplex.modes; // duplex modes
caps.color.supported; // whether colour is possible
caps.copies; // copy range
caps.mediaTypes.supported; // media types (photo paper, transparency…)
caps.borderless; // borderless supportOffer only what is listed here. Showing a user an option that will be discarded is worse than not showing it. The console's printer capabilities page visualises all of this and can refresh it in one click.
Capabilities are cached
getCapabilities(queueId) returns a cached result and is fast to call. Pass
refresh: true to force a re-read after a driver or configuration change.
Profiles: saving common settings
When one printer always uses the same options (label paper, high quality, a specific tray), save them as a profile and reference it:
// Create from the printer's current native configuration
const profile = await client.createProfileFromNative(queueId, 'Label paper · High');
// Add cross-platform standard options
await client.setProfileStandard(profile.id, { copies: 1, quality: 'best' });
// Make it this printer's default profile
await client.setDefaultProfile(profile.id);
// Reference it when printing
await client.compose({ queueId }).profile(profile.id).addDocument(doc).printAndWait();A profile has two layers:
- Standard options — cross-platform parameters (copies, paper, duplex, quality…), editable in the console and overridable per print.
- Native parameters — a complete snapshot of driver-private configuration (Windows DEVMODE, CUPS/IPP options). Captured from the printer's current state with "create from current native configuration". This part never leaves the computer.
When a profile goes stale
After a driver or configuration change, the native parameters inside an old profile may no longer apply. PrintLink marks them instead of forcing them:
| State | Meaning |
|---|---|
| Valid | Matches the current printer; safe to use |
| Needs review | Capabilities or driver changed; re-capture recommended |
| Invalid | Can no longer be applied to this printer |
Referencing an invalid profile returns PROFILE_NOT_FOUND; point the user at the
console to set it up again.
Other printer operations
client.setPreferredPrinter(queueId); // mark as preferred (shows in the list)
client.openPrinterSettings(queueId); // open the OS printer settings
client.listProfiles(queueId); // requires profile.read
client.renameProfile(id, 'New name');
client.deleteProfile(id);