The capsprinter is a small tool to get some status information about the currently running CAPS universe components. At most it provides information about the currently online printer devices, - on demand - their state and even more on demand their PPD file.

It talks to the CAPS Printing Coordinator and query the state of printer devices.

This tool is more intended for debugging purposes and troubleshooting. Since it uses the libcapsclient API (Client side API description), it can also be a helper tool for a developer using this API.

Usage

 $ capsprinter [options] <command>

Generic Options

-v/--verbose: increase the verbosity
--version: print program's version
-h/--help: guess what…

Commands:

list: print a list of names of currently known active printer devices
- with an additional -v/--verbose state details are added
state: print the state of the first printer device found or of a specified one
- -d <name>/–device=<name> can specify a printer device (if more than one is available)
ppd: retrieve the PPD content of the first printer device found or of a specified one
- -d <name>/–device=<name> can specify a printer device (if more than one is available)
- -p <filename>/–ppd=<filename> defines a filename to store the PPD content to, else stdout is used instead.

Return values

This tool returns EXIT_FAILURE (e.g. '1') on all kind of failures including an empty list of printers. If it has generated the desired output it returns EXIT_SUCCESS (e.g. '0).

Usage examples

Just print the list of names of currently online printer devices:

 $ capsprinter list

The output can be empty (e.g. No printer available), which just means the CAPS Printing Coordinator doesn't know any printer devices. Else it could look like:

 $ capsprinter list
 'Brother_HL-2030 series_M5J510108'

For more information about this printer device, increase the tool's verbosity:

 $ capsprinter --verbose list
 name: 'Brother_HL-2030 series_M5J510108'
  description: 'Monochrome Laser Printer'
  location: 'Office'
  state: Idle (ID 3)
  reason: Okay (ID 16)
  message: 'Idle'

If you are interested only in the printer device's state, run a:

 $ capsprinter state
  state: Idle (ID 3)
  reason: Okay (ID 16)
  message: 'Idle'

If more than one printer device is currently online, the capsprinter tool always picks up the first one. You need to specify the printer device of interest in this case, if you want a different printer than the first one.

 $ capsprinter list
 'Brother_HL-2030 series_M5J510108'
 'Samsung ML1640'

With this name information you can specify the printer device you want to see the state of:

 $ capsprinter --device="Samsung ML1640" status
  state: Printing (ID 5)
  reason: Okay (ID 16)
  message: 'Printing'

To retrieve the PPD (aka. PostScript Printer Description) file, run the tool with:

 $ capsprinter --device="Samsung ML1640" --ppd=samsung_ml1640.ppd ppd

If you omit the -p/--ppd option, the PPD content gets output to stdout instead.

Error messages

Unknown parameter: <some text>

You seem to give <some text> as an unknown parameter. Typo?

Missing useful command

You should use at least one of the supported commands. Else the tools cannot do anything.

Unknown command: <some text>

The command is unknown. Typo?

No printer available

The printing coordinator currently doesn't know an attached and online printer device. This isn't a real failure. More some kind of a hint.

Failed to retrieve printer's <some-id> base information

DBUS communication issue with the printing coordinator. Maybe a version mismatch of libcapsclient and the running printing coordinator.

Failed to retrieve printer's <some-id> state information

DBUS communication issue with the printing coordinator. Maybe a version mismatch of libcapsclient and the running printing coordinator.

Failed to retrieve printer list: <error type>

DBUS communication issue with the printing coordinator. Maybe a version mismatch of libcapsclient and the running printing coordinator.

Warning: no printer specified, but more than one available. Continue with the first available one.

More than one printer device is available. But without specifying the one you want, still the first will be used. This might not match your expectation.

<some name>: failed to retrieve printer's identifier: <error type>

It wasn't possible to retrieve an ID for the specified printer. E.g. the name isn't known to the system (…anymore).

Failed to retrieve printer's name

It wasn't possible to retrieve the name of the first available printer. Maybe a version mismatch of libcapsclient and the running printing coordinator.

<some name>: failed to open/create PPD file '<some filename>': <error type>

A PPD file should be created and filled, but its creation failed somehow. The <error type> and the <some filename> should help you to fix it.

<some name>: failed to retrieve printer's PPD info: <error type>

The PPD content couldn't retrieved from the printing coordinator. Maybe a version mismatch of libcapsclient and the running printing coordinator.

<some name>: failed to retrieve printer's PPD info: No such device

Cannot exchange the PPD's filehandle due to insufficient directory setup in CAPS Document Storage Directory