libcupsfilters, libppd: cfFilterExternal() filter function
Moved the core functionality of the ppdFilterExternalCUPS() filter
function from libppd into libcupsfilters, as the new
cfFilterExternal() filter function.
This way also in applications without PPD file support, not using
libppd, external filter executables can be easily integrated in filter
function chains. This is for example needed if filters are not written
in C and conversion gets too awkward and error-prone, or is not even
possible (like with closed-source filters).
The Braille embosser printer driver for example contains filters which
are shell scripts.
External filters must use the call scheme of either CUPS filters or
System V interface scripts. Both call schemes are merely the same,
only in the CUPS filters there got added that input can come from
stdin instead of only via files named in the 6th and further command
line arguments.
ppdFilterExternalCUPS() is a wrapper around cfFilterExternal() now and
does not more than setting the cups-specific environment variables
CUPS_DATADIR, CUPS_SERVERBIN, CUPS_SERVERROOT, CUPS_STATEDIR,
SOFTWARE, CONTENT_TYPE, FINAL_CONTENT_TYPE, PRINTER, PPD, DEVICE_URI
to emulate a cUPS environment as good as possible. The PPD's file name
for the PPD environment variable is taken from the "libppd" extension
for the filter data.
For calling CUPS backends for job execution, the DEVICE_URI
environment variable must be set to the CUPS device URI of the
printer. This can be done by setting the variable right away or adding
it to the environment variable list in the parameters.
The parameters data structure for both cfFilterExternal() and
ppdFilterExternalCUPS() is cf_filter_external_t (in
cupsfilters/filter.h) now and not ppd_filter_external_cups_t any
more. Here the device_uri field got removed (the DEVICE_URI
environment variable has to be used instead) and the is_backend field
got replaced by exec_mode. exec_mode allows 4 setting: -1 for System V
interface scripts (input is file named by 6th command line argument),
0 for CUPS filter (input via stdin), 1 for CUPS backend in job
execution mode, 2 for CUPS backend in device discovery mode (no
command line arguments).
To allow easy handling of the environment variable list in the
parameters, the envp field, the internal helper functions
add_env_var() and get_env_var() got promoted into the API, as
cfFilterAddEnvVar() and cfFilterGetEnvVar(). This allows also libppd
to use these functions.
For testing and debugging any changes on cfFilterExternal() and
ppdFilterExternalCUPS() a new wrapper pseudo CUPS filter,
"test-external", source file filter/test-external.c, got added. This
one is mainly intended to be called manually. To tell which filter or
backend should be called and in which mode, one of the environment
variables INTERFACE, FILTER, CUPSFILTER, or CUPSBACKEND has to be set
to the filter/backend executable.