How to insert a custom filter to the filter chain?

[trinhtran-markany]

Hi,

I'm developing a macOS application to trigger any printing action and modify the document content before sending to the printer, such as adding text to printing documents.

What I've tried so far is creating a simple filter and inserting it into the filter chain, then checking if it works. However, once I changed it to my own custom filter, the printer is not working.

Here is custom filter watermark:

#!/bin/bash
tempdir="$(mktemp -d)"

echo "[Watermark] $tempdir" >&2

if [ ! -d "$tempdir" ]; then
   echo "Error: Unable to create temporary directory." >&2
   exit 1
fi

logfile="$tempdir/watermarkpdf.log"
watermark="/etc/cups/watermark.pdf"

echo "[Watermark] $0 $* (tempdir: $tempdir)" >&2
echo "[Watermark] $0 $* (tempdir: $tempdir)" >> $logfile

job="$1"
user="$2"
title="$3"
numcopies="$4"
options="$5"
filename="$6"
output="$7"

echo "[Watermark] $0 - $1 - $2 - $3 - $4 - $5 - $6 - $7" >&2

In PPD file (Canon_LBP3300.ppd) i changed:
*$cupsFilter: "application/pdf 0 /Library/Printers/Canon/CUPSCAPT2/Bins/capdftopdl" to *cupsFilter: "application/pdf 0 watermark"

In the log file:

I [14/Dec/2023:11:20:11 +0700] [Job 8] Started filter /usr/libexec/cups/filter/watermark (PID 1103)
I [14/Dec/2023:11:20:11 +0700] [Job 8] Started backend /usr/libexec/cups/backend/cnbma2 (PID 1104)
....
D [14/Dec/2023:11:20:11 +0700] [Job 8] [Watermark] /var/folders/zz/zyxvpxvq6csfxvn_n000003800000t/T/tmp.L6Y5jNo0vl
D [14/Dec/2023:11:20:11 +0700] [Job 8] [Watermark] /usr/libexec/cups/filter/watermark 8 trinhtran test 1 AP_ColorMatchingMode=AP_ApplicationColorMatching AP_D_InputSlot= BindEdge=Left brightness=100 CNBindEdgeShift=0 CNBrightness=6 CNContrast=6 CNCopies=1 CNDetectPaperSize noCNDraftMode noCNDuplex CNGamma=1.4 CNHalftone=pattern1 noCNLastPagePrintMode CNMatchingMethod=Monitor CNMatchingMode=Gamma CNMonitorProfile=sRGBv1.31 CNPDECALL=CNL330AK CNPrintSetting..b. noCNRotatePrint CNSkipBlank CNSpecialPrintMode=None CNSrcOption=None CNSuperSmooth CNTonerDensity=3 collate ColorModel=Gray com.apple.print.DialogDismissedBy=Print com.apple.print.DocumentTicket.PMSpoolFormat=application/pdf com.apple.print.JobInfo.PMApplicationName=Preview com.apple.print.JobInfo.PMJobName=test com.apple.print.JobInfo.PMJobOwner=trinhtran com.apple.print.PageToPaperMappingMediaName=A4 com.apple.print.PageToPaperMappingType..n.=1 com.apple.print.PDEsUsed=Preview com.apple.print.PrinterInfo.PMColorDeviceID..n.=6206 com.apple.print.PrintSettings.PMColorSpaceModel..n.=1 com.apple.print.PrintSettings.PMCopies..n.=1 com.apple.print.PrintSettings.PMCopyCollate..b. com.apple.print.PrintSettings.PMDestinationType..n.=1 com.apple.print.PrintSettings.PMDuplexing..n.=1 com.apple.print.PrintSettings.PMFirstPage..n.=1 com.apple.print.PrintSettings.PMLastPage..n.=2147483647 com.apple.print.PrintSettings.PMPageRange..a.0..n.=1 com.apple.print.PrintSettings.PMPageRange..a.1..n.=2147483647 com.apple.print.totalPages..n.=1 DestinationPrinterID=Canon_LBP3300 Filter=None gamma=1000 InputSlot=Auto media=A4 MediaType=PlainPaper number-up=1 PageSize=A4 PaperInfoIsSuggested..b. noPDFIsProtected..b. printer-resolution=600x600dpi pserrorhandler-requested=standard Resolution=600 job-uuid=urn:uuid:08d51efb-3676-345b-610c-ca262a7c5477 job-originating-host-name=localhost date-time-at-creation= date-time-at-processing= time-at-creation=1702527257 time-at-processing=1702527611 document-name-supplied=test job-impressions=1 com.apple.print.PrintSettings.PMTotalSidesImaged..n.=1 sides=one-sided Duplex=None com.ap
D [14/Dec/2023:11:20:11 +0700] [Job 8] ple.print.PrintSettings.PMTotalBeginPages..n.=1 /private/var/spool/cups/d00008-001 (tempdir: /var/folders/zz/zyxvpxvq6csfxvn_n000003800000t/T/tmp.L6Y5jNo0vl)
D [14/Dec/2023:11:20:11 +0700] [Job 8] [Watermark] /usr/libexec/cups/filter/watermark - 8 - trinhtran - test - 1 - AP_ColorMatchingMode=AP_ApplicationColorMatching AP_D_InputSlot= BindEdge=Left brightness=100 CNBindEdgeShift=0 CNBrightness=6 CNContrast=6 CNCopies=1 CNDetectPaperSize noCNDraftMode noCNDuplex CNGamma=1.4 CNHalftone=pattern1 noCNLastPagePrintMode CNMatchingMethod=Monitor CNMatchingMode=Gamma CNMonitorProfile=sRGBv1.31 CNPDECALL=CNL330AK CNPrintSetting..b. noCNRotatePrint CNSkipBlank CNSpecialPrintMode=None CNSrcOption=None CNSuperSmooth CNTonerDensity=3 collate ColorModel=Gray com.apple.print.DialogDismissedBy=Print com.apple.print.DocumentTicket.PMSpoolFormat=application/pdf com.apple.print.JobInfo.PMApplicationName=Preview com.apple.print.JobInfo.PMJobName=test com.apple.print.JobInfo.PMJobOwner=trinhtran com.apple.print.PageToPaperMappingMediaName=A4 com.apple.print.PageToPaperMappingType..n.=1 com.apple.print.PDEsUsed=Preview com.apple.print.PrinterInfo.PMColorDeviceID..n.=6206 com.apple.print.PrintSettings.PMColorSpaceModel..n.=1 com.apple.print.PrintSettings.PMCopies..n.=1 com.apple.print.PrintSettings.PMCopyCollate..b. com.apple.print.PrintSettings.PMDestinationType..n.=1 com.apple.print.PrintSettings.PMDuplexing..n.=1 com.apple.print.PrintSettings.PMFirstPage..n.=1 com.apple.print.PrintSettings.PMLastPage..n.=2147483647 com.apple.print.PrintSettings.PMPageRange..a.0..n.=1 com.apple.print.PrintSettings.PMPageRange..a.1..n.=2147483647 com.apple.print.totalPages..n.=1 DestinationPrinterID=Canon_LBP3300 Filter=None gamma=1000 InputSlot=Auto media=A4 MediaType=PlainPaper number-up=1 PageSize=A4 PaperInfoIsSuggested..b. noPDFIsProtected..b. printer-resolution=600x600dpi pserrorhandler-requested=standard Resolution=600 job-uuid=urn:uuid:08d51efb-3676-345b-610c-ca262a7c5477 job-originating-host-name=localhost date-time-at-creation= date-time-at-processing= time-at-creation=1702527257 time-at-processing=1702527611 document-name-supplied=test job-impressions=1 com.apple.print.PrintSettings.PMTotalSidesImaged..n.=1 sides=one-sided Duplex=N
D [14/Dec/2023:11:20:11 +0700] [Job 8] one com.apple.print.PrintSettings.PMTotalBeginPages..n.=1 - /private/var/spool/cups/d00008-001 - 
D [14/Dec/2023:11:20:11 +0700] [Job 8] PID 1103 (/usr/libexec/cups/filter/watermark) exited with no errors.
E [14/Dec/2023:11:20:11 +0700] [Job 8] cnbma2 send_data error, exit
D [14/Dec/2023:11:20:11 +0700] cupsdMarkDirty(---J-)
D [14/Dec/2023:11:20:11 +0700] cupsdSetBusyState: newbusy="Printing jobs and dirty files", busy="Printing jobs and dirty files"
D [14/Dec/2023:11:20:11 +0700] cupsdMarkDirty(---J-)
D [14/Dec/2023:11:20:11 +0700] cupsdSetBusyState: newbusy="Printing jobs and dirty files", busy="Printing jobs and dirty files"
D [14/Dec/2023:11:20:11 +0700] [Job 8] Set job-printer-state-message to "cnbma2 send_data error, exit", current level=ERROR
D [14/Dec/2023:11:20:11 +0700] Discarding unused job-progress event...
D [14/Dec/2023:11:20:11 +0700] Discarding unused printer-state-changed event...
D [14/Dec/2023:11:20:11 +0700] [Job 8] PID 1104 (/usr/libexec/cups/backend/cnbma2) stopped with status 1.
I [14/Dec/2023:11:20:11 +0700] [Job 8] Backend returned status 1 (failed)

I have a couple questions:

1. Do you know what the issue is?
2. Regarding PPD files, I see that there are different *cupFilter: entries in different printers. Can my own filter apply to all printers?

Regards,

[zdohnal]

If you develop a new application, please don't use any PPDs or filters - write a printer application which will serve as printer driver. PPDs and additional filters are deprecated for long time and CUPS is on its way to remove their support in CUPS 3.0.

But before you write a driver, you can check if IPP 2.0 does not provide something similar and your printer does not support it.

About error - the backend accepts a specific file type, which your filter does not create , and which comes from the original printer. Your filter would have to create such type, or you have to apply your changes before sending the file to the original filter.

Ad the second question - it depends on PPD and printer. Your filter has to create a file in the document format accepted by backend and printer.

[trinhtran-markany]

@zdohnal How do I know the input backend type?

[zdohnal]

Since your PPD file uses only *cupsFilter directive (which tells you only input MIME type), you have to inspect the file which goes out from the filter capdftopdl.

Every filter should have a common structure of parameters, so you can run it by hand (substitute every <> with your settings):

/Library/Printers/Canon/CUPSCAPT2/Bins/capdftopdl 1 <username> '' 1 '' <input.pdf> > out

and then inspect file out - maybe the filter will need some env variables to be passed together with it - cups debug logging will show you which env variables are used, so you can try them (usually filters wants PPD env variable).

If I were you, I would try to put your filter before the original filter - you will have to define a new MIME type (in /etc/cups/mime.types) which will be output of your filter and it will be input for capdftopdl, so in the end it have to be a PDF, because that's what the filter accepts.

So e.g.:

*cupsFilter2: application/pdf application/vnd.pdf-watermark 0 watermark
*cupsFilter: application/vnd.pdf-watermark 0 /Library/Printers/Canon/CUPSCAPT2/Bins/capdftopdl

And of course be sure that your filter actually produces your file on stdout, because filters are connected by pipes and one filter's stdout becomes other's stdin, which makes the file to be passed through filter chain.

[trinhtran-markany]

Thanks @zdohnal ,I think now I'm figuring out step by step what I can do right now. Adapting a filter for every PDD file can be hard work and may seem impossible?

[trinhtran-markany]

@zdohnal My last question: I'm unable to add application/vnd.pdf-watermark to the mine.types file due to permission issue. Do you know how to resolve it?

[zdohnal]

Superusers/root have permissions to write into /etc/cups, transitionally into /etc/cups/mime.types. You have to be one of them to make this work - normal users do not have access there, because /etc is for system configurations.

[zdohnal]

Ad writing printer applications - https://openprinting.github.io/documentation/02-designing-printer-drivers/

[trinhtran-markany]

@zdohnal ,
Developing a new printer driver might take us a lot of time and effort, since my original problem was modify the filter, it's much more simple. I'm also quite confuse between Apple Cups vs OpenPrinting Cups. In macOS, what is the type of Cups?

[trinhtran-markany]

@zdohnal Once I succeed in developing a printer driver, is it possible for our application to trigger any printer action and modify the printer data e.g adding the watermark to pdf file?

[trinhtran-markany]

@zdohnal Sorry, I'm quite new in CUPS so I have a lot of questions in my mind!

[zdohnal]

It is simple now, but soon you might need to figure out if an existing printer application accepts and works with your current driver which you are trying to create here. So you will be creating the driver twice instead of creating driver as printer application right now. Apple CUPS is the default in MacOS, but you can build and use OpenPrinting CUPS in MacOS.

If the application communicates with CUPS, it can do any IPP operation it has permission to do. Regarding modifying the document, the application can add a job option which will tell the driver what to apply.

[jsmeix]

@zdohnal
I think there are typos in your
#845 (comment)
because it reads

the backend accepts a specific file type

and

Your printer has to create a file in the document format
accepted by backend and printer.

As far as I know for CUPS up to 2.x
(things could be different in CUPS 3.x)
a usual CUPS backend accepts any data
and
it is not the printer that creates something in a certain format.

[trinhtran-markany]

@jsmeix If the backend filter accepts any data, so do you know why is the issue happens? How can we know what is the backend input?

[jsmeix]

I know basically nothing about macOS.

I assume Apple CUPS i.e. CUPS in macOS is CUPS up to 2.x
so for current macOS CUPS up to 2.x would matter.

I use Linux and for Linux my meanwhile rather old
https://en.opensuse.org/SDB:Using_Your_Own_Filters_to_Print_with_CUPS
describes how one could use own filters to print with CUPS up to 2.x
under Linux with the traditional filtering system and backends there.
The nowadays driverless printing workflow is rather different.

I know nothing about the filtering system and backends on macOS
so I don't know how far (or if at all)
https://en.opensuse.org/SDB:Using_Your_Own_Filters_to_Print_with_CUPS
could help for using own filters to print with CUPS under macOS
in particular because - as far as I noticed - it seems macOS
enforces a rather strict "sandbox" where CUPS is run inside
so that it could be almost impossible in practice to
use own filters to print with CUPS under macOS.

[trinhtran-markany]

Thanks @jsmeix . My CUPS version is 2.3.4. So far, I'm struggling to manage the input/output of filters and don't know what the input type of the backend is. In Linux, how can one determine this?

[zdohnal]

@jsmeix you are correct about CUPS backends in general, but this is a backend from printer manufacturer, where we can't be sure whether it does not expect something to be present in the filtered file after it went through that special filter capdftopdl (I wouldn't be surprised if there was something like that...)

Ad the "printer" - yes, that should be a filter, thank you for checking!