How to get reason CUPS job was stopped?

Question

How do I get the reason a CUPS print job failed, via the CUPS API?

Using the CUPS API, I printed two jobs that failed to print. On the CUPS web interface, I can see why they failed: "Unsupported print data." and "Unable to write print data."

However, the API doesn't seem to contain these reasons. The cupsGetJobs() method returns cups_job_s structs, which look like this:

struct cups_job_s {
    time_t completed_time;
    time_t creation_time;
    char *dest;
    char *format;
    int id;
    int priority;
    time_t processing_time;
    int size;
    ipp_jstate_t state;
    char *title;
    char *user;
};

I have inspected all of these fields, none of them contain the error strings seen in the screenshot.

Answer 1

I believe this boils down to the job-state-message attribute. To retrieve the job attributes, I believe you'll have to use the IPP API though, for example (untested):

ipp_t *request = ippNewRequest(IPP_GET_JOBS);
...
ipp_t *response = cupsDoRequest(CUPS_HTTP_DEFAULT, request, "/");
...
ipp_attribute_t *attr = ippFindAttribute(response, "job-state-message", IPP_TAG_TEXT);

It's important to note that attributes related to job-state may be updated at some point after a job has already been accepted. Since the server doesn't know if the printing will actually succeed (because of Murphy's Law many factors), the job is accepted and upon failure it updates job-state and related attributes accordingly. The job-state-message is not mandatory though.

If you want your application to be reactive to these events rather than to keep querying the CUPS server at a fixed interval, you could subscribe to some D-Bus events (see Apple's implementation). If you want an example of consumer implementation, you may read the Printer's Panel code from gnome-control-center.

Below I attempt to quote some relevant parts of the RFC 2911 (IPP 1.1):

3.1.9 Job Creation Operations

...

At job processing time, since the Printer object has already responded with a successful status code in the response to the create request, if the Printer object detects an error, the Printer object is unable to inform the end user of the error with an operation status code. In this case, the Printer, depending on the error, can set the job object's "job-state", "job-state-reasons", or "job- state-message" attributes to the appropriate value(s) so that later queries can report the correct job status.

Note: Asynchronous notification of events is outside the scope of this IPP/1.1 document.

4.3.7 job-state (type1 enum)

...

6' 'processing-stopped': The job has stopped while processing for any number of reasons and will return to the 'processing' state as soon as the reasons are no longer present.

The job's "job-state-reason" attribute MAY indicate why the job has stopped processing. For example, if the output device is stopped, the 'printer-stopped' value MAY be included in the job's "job-state-reasons" attribute.

Note: When an output device is stopped, the device usually indicates its condition in human readable form locally at the device. A client can obtain more complete device status remotely by querying the Printer object's "printer-state", "printer-state-reasons" and "printer- state-message" attributes.

4.3.9 job-state-message (text(MAX))

This attribute specifies information about the "job-state" and "job- state-reasons" attributes in human readable text. If the Printer object supports this attribute, the Printer object MUST be able to generate this message in any of the natural languages identified by the Printer's "generated-natural-language-supported" attribute (see the "attributes-natural-language" operation attribute specified in Section 3.1.4.1).

The value SHOULD NOT contain additional information not contained in the values of the "job-state" and "job-states-reasons" attributes, such as interpreter error information. Otherwise, application programs might attempt to parse the (localized text). For such additional information such as interpreter errors for application program consumption or specific document access errors, new attributes with keyword values, needs to be developed and registered.

footnote: I haven't done it personally, but the RFC does tell you exactly what you should expect.