-
Notifications
You must be signed in to change notification settings - Fork 34
Boomaga backed, how it works
Documentation is up to date for versions 2.0 and later.
Boomaga is a virtual printer and receives jobs from the CUPS. The program consists of two executable files:
- The Boomaga backend. On Linux the backend is usually located in the /usr/lib/cups/backend directory.
- The Boomaga GUI. On Linux GUI part usually located in the /usr/bin/ or /usr/local/bin directory.
Every time you print something on Boomaga printer, CUPS gets a job for printing, it determines the best programs (filters, printer drivers) to convert the pages into a printable format and then runs them to actually print the job. At the end CUPS runs the boomaga backend and passes the job to it.
Backend run with a standard set of command-line arguments:
- argv[1] - The job ID
- argv[2] - The user printing the job
- argv[3] - The job name/title
- argv[4] - The number of copies to print
- argv[5] - The options that were provided when the job was submitted
- argv[6] - The file to print (first program only)
If sixth argument is omitted, then the backend read document from the standard input.
The backend run as a root user and off of graphical session (XOrg or wayland). The main task of the backend is to run the GUI part of the Boomaga and pass document to it.
In the modern Linux operation systems, backends are run inside a security "sandbox" which further limits (beyond the normal UNIX user/group permissions) сommunication between the CUPS backend and the usual programs. So GUI part of the Boomaga can't directly read the file passed in the sixth argument.
To solve this problem, the backend copies the files to a separate directory for sharing (usually /var/spool/boomaga/$USER on Linux). The internal file format are used for the exchange, see details in the section "CBOO file format".
At the end, the backend changes the GID and UID to the user printing the job and run the /usr/bin/boomaga, with the following arguments boomaga --started-from-cups PATH_TO_CBOO_FILE
So we ran /usr/bin/boomaga, but there are two problems:
- The program is running off of the GUI session.
- We don't want to see each document in a separate instance of the program, and therefore in a separate window. We need to run the program once, and then add the document to it.
To solve these problems, the program runs its own executable file using DBUS. Something like:
dbus-send \
--session \
--type=method_call \
--print-reply \
--dest=org.boomaga /boomaga org.boomaga.add \
string:"CBOO_FILE.cboo"
After that, the program terminates.
Now program is running in a graphical user session. The program moves the CBOO file from the /var/spool/boomaga/$USER to the ~/.cache directory and shows it contents to the user.
This format is intended only for internal usage, and may change in future releases. Do not use this format for any purposes other than debugging!
The first line of a CBOO file is a header identifying the file type. The header should be
<ESC>CUPS_BOOMAGA
identifies a escape control character (ASCII 27).
The header is followed by a section with the parameters of the job received from CUPS. The parameters are structured similarly to a UNIX environment variable. That is, comment fields consist of a field name and a corresponding value and look like:
JOB=1030
USER=sokoloff
TITLE=Create%20New%20Page%20%C2%B7%20Boomaga%2Fboomaga%20Wiki
COUNT=1
OPTIONS=PageSize%3DA4%20Collate%20ColorModel%3DGrayscale%20Duplex%3DNone
String values are percent-encoded.
All keys are case-insensitive. Below is a proposed, list of field names with a description of its. No single or group of field names is mandatory; a parameters header may contain one, all or none of the names in this list.
- JOB - The job ID
- USER - The user printing the job
- TITLE - The job name/title
- COUNT - The number of copies to print
- OPTIONS - The options that were provided when the job was submitted
The list of parameters ends with the string CUPS_BOOMAGA_DATA. After this line, the file contains the printed document as is.