From 29d7fa7e98b858ab69acfd6b5ed49d299fe49c88 Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Sat, 21 Feb 2026 04:07:21 +0530 Subject: [PATCH 01/24] Improve API documentation in raster.h and filter.h --- cupsfilters/filter.h | 118 ++++++++++++++++++++++++++----------------- cupsfilters/raster.h | 20 +++++++- 2 files changed, 91 insertions(+), 47 deletions(-) diff --git a/cupsfilters/filter.h b/cupsfilters/filter.h index c9a66923f..2caa29e7f 100644 --- a/cupsfilters/filter.h +++ b/cupsfilters/filter.h @@ -209,17 +209,49 @@ extern int cfFilterPClose(int fd, cf_filter_data_t *data); +// +// 'cfFilterChain()' - Execute a chain of filter functions. +// +// Executes multiple filters in sequence. The output of one +// filter becomes the input of the next filter. All filters +// receive the same cf_filter_data_t structure. +// +// Parameters: +// inputfd - Input file descriptor. +// outputfd - Output file descriptor. +// inputseekable - Non-zero if input supports seeking. +// data - Job and printer data. +// parameters - Unsorted CUPS array of +// cf_filter_filter_in_chain_t* entries. +// +// Returns 0 on success and non-zero on error. +// + extern int cfFilterChain(int inputfd, int outputfd, int inputseekable, cf_filter_data_t *data, void *parameters); -// Parameters: Unsorted (!) CUPS array of cf_filter_filter_in_chain_t* -// List of filters to execute in a chain, next filter takes output of -// previous filter as input, all get the same filter data, parameters -// are supplied individually in the array +// +// 'cfFilterExternal()' - Execute an external CUPS filter, +// backend, or System V interface script. +// +// This function runs an external program as part of the filter +// chain. It can call a CUPS filter, a CUPS backend (including +// device discovery mode), or a System V interface script. +// +// Parameters: +// inputfd - Input file descriptor. +// outputfd - Output file descriptor. +// inputseekable - Non-zero if input supports seeking. +// data - Job and printer data. +// parameters - Pointer to a cf_filter_external_t structure +// describing the external program to execute. +// +// Returns 0 on success and non-zero on error. +// extern int cfFilterExternal(int inputfd, int outputfd, @@ -227,23 +259,6 @@ extern int cfFilterExternal(int inputfd, cf_filter_data_t *data, void *parameters); -// Parameters: cf_filter_external_t* -// -// Path/Name of the external CUPS/System V filter or backend to be -// called by this filter function, specification whether we call a -// filter or a backend, and in case of backend, whether in job -// processing or discovery mode, extra options for the 5th command -// line argument, and extra environment variables -// -// CUPS filter: -// See "man filter" -// -// CUPS Backend: -// See "man backend" -// -// System V interface script: -// https://www.ibm.com/docs/en/aix/7.2?topic=configuration-printer-interface-scripts - extern int cfFilterOpenBackAndSidePipes(cf_filter_data_t *data); @@ -251,27 +266,28 @@ extern int cfFilterOpenBackAndSidePipes(cf_filter_data_t *data); extern void cfFilterCloseBackAndSidePipes(cf_filter_data_t *data); + +// +// 'cfFilterGhostscript()' - Convert input data using Ghostscript. +// +// Uses Ghostscript to convert the input data to the desired +// output format. The output format must be specified via +// data->final_content_type or by passing a +// cf_filter_out_format_t parameter. +// +// Supported output formats include PDF, raster-only PDF, +// PCLm, CUPS Raster, PWG Raster, Apple Raster, and PCL-XL. +// +// Returns 0 on success and non-zero on error. +// + + extern int cfFilterGhostscript(int inputfd, int outputfd, int inputseekable, cf_filter_data_t *data, void *parameters); -// Requires specification of output format via data->final_content_type -// or alternatively as parameter of type cf_filter_out_format_t. -// -// Output formats: PDF, raster-only PDF, PCLm, PostScript, CUPS Raster, -// PWG Raster, Apple Raster, PCL-XL -// -// Note: With the Apple Raster selection and a Ghostscript version -// without "appleraster" output device (9.55.x and older) the output -// is actually CUPS Raster but information about available color -// spaces and depths is taken from the urf-supported printer IPP -// attribute. This mode is for further processing with -// rastertopwg. With Ghostscript supporting Apple Raster output -// (9.56.0 and newer), we actually produce Apple Raster and no further -// filter is required. - extern int cfFilterBannerToPDF(int inputfd, int outputfd, @@ -432,6 +448,26 @@ extern int cfFilterTextToText(int inputfd, cf_filter_data_t *data, void *parameters); + +// +// 'cfFilterUniversal()' - Automatically select and execute +// the appropriate filter conversion pipeline. +// +// Determines the required data conversion based on the job's +// input content type (data->content_type) and the desired +// final output type (data->final_content_type). +// +// Parameters: +// inputfd - Input file descriptor. +// outputfd - Output file descriptor. +// inputseekable - Non-zero if input supports seeking. +// data - Job and printer data. +// parameters - Pointer to a +// cf_filter_universal_parameter_t structure +// providing additional conversion settings. +// +// Returns 0 on success and non-zero on error. +// extern int cfFilterUniversal(int inputfd, int outputfd, @@ -439,16 +475,6 @@ extern int cfFilterUniversal(int inputfd, cf_filter_data_t *data, void *parameters); -// Requires specification of input format via data->content_type and -// job's final output format via data->final_content_type -// -// Parameters: cf_filter_universal_parameter_t -// -// Contains: actual_output_type: Format which the filter should -// actually produce if different from job's final output -// format, otherwise NULL to produce the job's final output -// format -// texttopdf_params: parameters for texttopdf # ifdef __cplusplus diff --git a/cupsfilters/raster.h b/cupsfilters/raster.h index b9a832a2b..314c670db 100644 --- a/cupsfilters/raster.h +++ b/cupsfilters/raster.h @@ -46,10 +46,19 @@ extern "C" { // -// Prototypes... +// 'cfRasterColorSpaceString()' - Return a human-readable +// name for the given raster color space. // extern const char *cfRasterColorSpaceString(cups_cspace_t cspace); + +// +// 'cfRasterPrepareHeader()' - Prepare a CUPS/PWG raster page +// header based on job and printer data. +// +// Returns 0 on success and non-zero on error. +// + extern int cfRasterPrepareHeader(cups_page_header_t *h, cf_filter_data_t *data, cf_filter_out_format_t @@ -58,6 +67,15 @@ extern int cfRasterPrepareHeader(cups_page_header_t *h, header_outformat, int no_high_depth, cups_cspace_t *cspace); + +// +// 'cfRasterSetColorSpace()' - Update a raster header with the +// appropriate color space and color depth based on printer +// capabilities and job settings. +// +// Returns 0 on success and -1 on error. +// + extern int cfRasterSetColorSpace(cups_page_header_t *h, const char *available, const char *color_mode, From d00b623053659caad318b9633bc58d783e69c5cb Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Sun, 1 Mar 2026 02:41:53 +0530 Subject: [PATCH 02/24] Improve documentation of filter and raster files --- cupsfilters/filter.c | 169 ++++++++++------------- cupsfilters/filter.h | 320 ++++++++++++++++++++++++++++--------------- cupsfilters/raster.h | 7 +- 3 files changed, 281 insertions(+), 215 deletions(-) diff --git a/cupsfilters/filter.c b/cupsfilters/filter.c index c1d5545d1..6d5e97910 100644 --- a/cupsfilters/filter.c +++ b/cupsfilters/filter.c @@ -69,14 +69,14 @@ fcntl_add_nonblock(int fd) // File descriptor to add O_NONBLOCK to // 'cfCUPSLogFunc()' - Output log messages on stderr, compatible to // CUPS, meaning that the debug level is // represented by a prefix like "DEBUG: ", "INFO: -// ", ... +// ", .... // -void -cfCUPSLogFunc(void *data, - cf_loglevel_t level, - const char *message, - ...) +void // O - None +cfCUPSLogFunc(void *data, // I - User data (not used) + cf_loglevel_t level, // I - Log level + const char *message, // I - Message format string + ...) // I - Additional arguments { va_list arglist; @@ -117,8 +117,8 @@ cfCUPSLogFunc(void *data, // by data is not zero. // -int -cfCUPSIsCanceledFunc(void *data) +int // O - 1 if canceled, 0 otherwise +cfCUPSIsCanceledFunc(void *data) // I - Pointer to canceled flag (int *) { return (*((int *)data) != 0 ? 1 : 0); } @@ -143,17 +143,14 @@ get_filter_data_ext_entry(cups_array_t *ext_array, } -void * // O - Extension record which got - // replaced, NULL if there was - // no record under this name, - // the added record is the one - // there, or no record was - // added. If not NULL the - // returned record should usually - // be deleted or freed. +// +// 'cfFilterDataAddExt()' - Add or replace an extension record in the filter data. +// + +void * // O - Replaced extension record, or NULL if none was replaced cfFilterDataAddExt(cf_filter_data_t *data, // I - Filter data record - const char *name, // I - Name of extension - void *ext) // I - Extension record to be added + const char *name, // I - Name of extension + void *ext) // I - Extension record to be added { cf_filter_data_ext_t *entry; void *old_ext = NULL; @@ -187,9 +184,13 @@ cfFilterDataAddExt(cf_filter_data_t *data, // I - Filter data record } -void * -cfFilterDataGetExt(cf_filter_data_t *data, - const char *name) +// +// 'cfFilterDataGetExt()' - Get an extension record from the filter data. +// + +void * // O - Extension record, or NULL +cfFilterDataGetExt(cf_filter_data_t *data, // I - Filter data record + const char *name) // I - Name of extension { cf_filter_data_ext_t *entry; @@ -203,9 +204,13 @@ cfFilterDataGetExt(cf_filter_data_t *data, } -void * -cfFilterDataRemoveExt(cf_filter_data_t *data, - const char *name) +// +// 'cfFilterDataRemoveExt()' - Remove an extension record from the filter data and return it. +// + +void * // O - Extension record, or NULL +cfFilterDataRemoveExt(cf_filter_data_t *data, // I - Filter data record + const char *name) // I - Name of extension { cf_filter_data_ext_t *entry; void *ext = NULL; @@ -232,16 +237,13 @@ cfFilterDataRemoveExt(cf_filter_data_t *data, // -// 'cfFilterGetEnvVar()' - Auxiliary function for cfFilterExternal(), -// gets value of an environment variable in a -// list of environment variables as used by -// the execve() function +// 'cfFilterGetEnvVar()' - Get the value of an environment variable from the +// supplied environment list. // -char * // O - The value, NULL if variable is not in - // list +char * // O - Value of variable, or NULL cfFilterGetEnvVar(char *name, // I - Name of environment variable to read - char **env) // I - List of environment variable serttings + char **env) // I - List of environment variable { int i = 0; @@ -258,17 +260,13 @@ cfFilterGetEnvVar(char *name, // I - Name of environment variable to read // -// 'cfFilterAddEnvVar()' - Auxiliary function for cfFilterExternal(), -// adds/sets an environment variable in a list of -// environment variables as used by the execve() -// function +// 'cfFilterAddEnvVar()' - Add or replace an environment variable in an environment list. // -int // O - Index of where the new value got - // inserted in the list -cfFilterAddEnvVar(char *name, // I - Name of environment variable to set - char *value, // I - Value of environment variable to set - char ***env) // I - List of environment variable serttings +int // O - Index of inserted entry, or -1 on error +cfFilterAddEnvVar(char *name, // I - Name of environment variable to set + char *value, // I - Value of environment variable to set + char ***env) // I - List of environment variable { char *p; int i = 0, @@ -316,28 +314,15 @@ cfFilterAddEnvVar(char *name, // I - Name of environment variable to set // -// 'cfFilterTee()' - This filter function is mainly for debugging. it -// resembles the "tee" utility, passing through the -// data unfiltered and copying it to a file. The -// file name is simply given as parameter. This -// makes using the function easy (add it as item of -// a filter chain called via cfFilterChain()) and -// can even be used more than once in the same -// filter chain (using different file names). In -// case of write error to the copy file, copying is -// stopped but the rest of the job is passed on to -// the next filter. If NULL is supplied as file -// name, the data is simply passed through without -// getting copied. -// +// 'cfFilterTee()' - Copy input data to a file (for debugging) while +// passing it unchanged to the output. -int // O - Error status +int // O - 0 on success, -1 on error cfFilterTee(int inputfd, // I - File descriptor input stream - int outputfd, // I - File descriptor output stream - int inputseekable, // I - Is input stream seekable? (unused) - cf_filter_data_t *data, // I - Job and printer data - void *parameters) // I - Filter-specific parameters (File - // name) + int outputfd, // I - File descriptor output stream + int inputseekable, // I - Is input stream seekable? (unused) + cf_filter_data_t *data, // I - Job and printer data + void *parameters) // I - File name (const char *) { const char *filename = (const char *)parameters; ssize_t bytes, total = 0; // Bytes read/written @@ -396,12 +381,11 @@ cfFilterTee(int inputfd, // I - File descriptor input stream // -// 'cfFilterPOpen()' - Pipe a stream to or from a filter function Can -// be the input to or the output from the filter -// function. +// 'cfFilterPOpen()' - Create a pipe to a filter function and +// return a file descriptor for communicating with it. // -int // O - File decriptor +int // O - File descriptor cfFilterPOpen(cf_filter_function_t filter_func, // I - Filter function int inputfd, // I - File descriptor input stream or -1 @@ -542,13 +526,13 @@ cfFilterPOpen(cf_filter_function_t filter_func, // // 'cfFilterPClose()' - Close a piped stream created with -// cfFilterPOpen(). +// cfFilterPOpen() and wait for the filter process to finish. // -int // O - Error status +int // O - 0 on success, -1 on error cfFilterPClose(int fd, // I - Pipe file descriptor - int filter_pid, // I - PID of forked filter process - cf_filter_data_t *data) + int filter_pid, // I - PID of forked filter process + cf_filter_data_t *data) // O - Job and printer data { int status, // Exit status retval; // Return value @@ -610,12 +594,12 @@ compare_filter_pids(filter_function_pid_t *a, // I - First filter // -// 'cfFilterChain()' - Call filter functions in a chain to do a data -// format conversion which non of the individual -// filter functions does +// 'cfFilterChain()' - Call filter functions in a chain to perform a data +// format conversion which none of the individual +// filter functions can do alone. // -int // O - Error status +int // O - 0 on success, -1 on error cfFilterChain(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream int inputseekable, // I - Is input stream seekable? @@ -955,16 +939,12 @@ sanitize_device_uri(const char *uri, // I - Device URI // -// 'cfFilterExternal()' - Filter function which calls an external -// classic CUPS filter or System V interface -// script, for example a (proprietary) printer -// driver which cannot be converted to a filter -// function or if it is too awkward or risky to -// convert for example when the printer -// hardware is not available for testing +// 'cfFilterExternal()' - Filter function that executes an ezternal CUPS filter +// or System V interface script, typically used when conversion +// to a native filter function is not possible. // -int // O - Error status +int // O - 0 on success, -1 on error cfFilterExternal(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream int inputseekable, // I - Is input stream seekable? @@ -1603,24 +1583,14 @@ cfFilterExternal(int inputfd, // I - File descriptor input stream // -// 'cfFilterOpenBackAndSidePipes()' - Open the pipes for the back -// channel and the side channel, so -// that the filter functions can -// communicate with a backend. Only -// needed if a CUPS backend (either -// implemented as filter function -// or called via -// cfFilterExternal()) is called -// with the same filter_data record -// as the filters. Usually to be -// called when populating the -// filter_data record. +// 'cfFilterOpenBackAndSidePipes()' - Open the pipes for the back and side channels +// to allow communication between filter functions and a +// backend. Used when a CUPS backend runs with the same filter_data. +// // -int // O - 0 on success, - // -1 on error -cfFilterOpenBackAndSidePipes(cf_filter_data_t *data) // O - FDs in filter_data - // record +int // O - 0 on success, -1 on error +cfFilterOpenBackAndSidePipes(cf_filter_data_t *data) // O - FDs in filter_data record { cf_logfunc_t log = data->logfunc; void *ld = data->logdata; @@ -1699,14 +1669,13 @@ cfFilterOpenBackAndSidePipes(cf_filter_data_t *data) // O - FDs in filter_data // // 'cfFilterCloseBackAndSidePipes()' - Close the pipes for the back -// hannel and the side channel. -// sually to be called when done +// channel and the side channel. +// Usually to be called when done // with the filter chain . // void -cfFilterCloseBackAndSidePipes(cf_filter_data_t *data) // I - FDs in filter_data - // record +cfFilterCloseBackAndSidePipes(cf_filter_data_t *data) // I - FDs in filter_data record { cf_logfunc_t log = data->logfunc; void *ld = data->logdata; diff --git a/cupsfilters/filter.h b/cupsfilters/filter.h index 2caa29e7f..24b87b4a8 100644 --- a/cupsfilters/filter.h +++ b/cupsfilters/filter.h @@ -159,43 +159,101 @@ typedef struct cf_filter_universal_parameter_s // Contains input and output // // Prototypes... // +//'cfCUPSLogFunc()' - Logging callback functions used by filters. +// +// data: User-defined logging context. +// level: Log level of the message. +// message: printf-style format string. +// ...: Optional arguments for the format string. +// +// This function is used by filters to report status, debug +// information, warnings, and errors. +// extern void cfCUPSLogFunc(void *data, cf_loglevel_t level, const char *message, ...); +// +// 'cfCUPSIsCanceledFunc()' - Check whether the current job has been canceled. +// +// data: User-defined job context. +// Returns 1 if canceled, 0 otherwise. +// extern int cfCUPSIsCanceledFunc(void *data); +// 'cfFilterDataAddExt()' - Add an extension to the filter data. +// +// data: Filter data structure. +// name: Name of the extension. +// ext: Pointer to the extension data. +// + extern void *cfFilterDataAddExt(cf_filter_data_t *data, const char *name, void *ext); +// +// '*cfFilterDataGetExt()' - Retrieve an extension from the filter data. +// extern void *cfFilterDataGetExt(cf_filter_data_t *data, const char *name); +// +// '*cfFilterDataRemoveExt()'- Remove an extension from the filter data. +// extern void *cfFilterDataRemoveExt(cf_filter_data_t *data, const char *name); +// +// '*cfFilterGetEnvVar()' - Get the value of an environment variable from a given +// environment array. +// name: Name of the variable. +// env: Environment array. +// +// Returns a pointer to value string, or NULL if not found. +// + extern char *cfFilterGetEnvVar(char *name, char **env); +// +// 'cfFilterAddEnvVar()' - Add or update an environment variable. +// +// name: Name of the variable. +// value: Value of the variable. +// env: Environment array. +// +// Returns 0 on success, -1 on failure. +// extern int cfFilterAddEnvVar(char *name, char *value, char ***env); +// +// 'cfFilterTee()' - Filter function that copies input to output and optionally to a file. +// +// Parameters: parameters points to a const char* specifying the +// filename/path to copy the data to. +// + extern int cfFilterTee(int inputfd, int outputfd, int inputseekable, cf_filter_data_t *data, void *parameters); -// Parameters: Filename/path (const char *) to copy the data to - +// +// 'cfFilterPOpen()' - Start a filter function in a separate process. +// +// filter_func: Filter function to execute. +// parameters: Filter-specific parameters passed to the filter. +// filter_pid: Receives the process ID of the started filter. +// -extern int cfFilterPOpen(cf_filter_function_t filter_func, // I - Filter - // function +extern int cfFilterPOpen(cf_filter_function_t filter_func, int inputfd, int outputfd, int inputseekable, @@ -204,6 +262,15 @@ extern int cfFilterPOpen(cf_filter_function_t filter_func, // I - Filter int *filter_pid); +// +// 'cfFilterPClose()' - Wait for a filter process started by cfFilterPOpen(). +// +// fd: Input pipe file descriptor. +// filter_pid: Process ID of the filter. +// data: Job and printer. +// Return: 0 on success, -1 on failure. +// + extern int cfFilterPClose(int fd, int filter_pid, cf_filter_data_t *data); @@ -212,20 +279,10 @@ extern int cfFilterPClose(int fd, // // 'cfFilterChain()' - Execute a chain of filter functions. // -// Executes multiple filters in sequence. The output of one -// filter becomes the input of the next filter. All filters -// receive the same cf_filter_data_t structure. -// -// Parameters: -// inputfd - Input file descriptor. -// outputfd - Output file descriptor. -// inputseekable - Non-zero if input supports seeking. -// data - Job and printer data. -// parameters - Unsorted CUPS array of -// cf_filter_filter_in_chain_t* entries. -// -// Returns 0 on success and non-zero on error. -// +// Parameters: Pointer to an array of cf_filter_filter_in_chain_t defining the +// list of filters to execute. Each filter receives the previous filter's +// output as input. +// extern int cfFilterChain(int inputfd, int outputfd, @@ -233,26 +290,19 @@ extern int cfFilterChain(int inputfd, cf_filter_data_t *data, void *parameters); - // -// 'cfFilterExternal()' - Execute an external CUPS filter, -// backend, or System V interface script. +// 'cfFilterExternal()' - Executes an external filter or backend. // -// This function runs an external program as part of the filter -// chain. It can call a CUPS filter, a CUPS backend (including -// device discovery mode), or a System V interface script. +// This function runs a CUPS/System V filter or backend based on the input and output types +// specified in the parameters. // -// Parameters: -// inputfd - Input file descriptor. -// outputfd - Output file descriptor. -// inputseekable - Non-zero if input supports seeking. -// data - Job and printer data. -// parameters - Pointer to a cf_filter_external_t structure -// describing the external program to execute. +// See "man filter" and "man backend" for more information on CUPS filters and backends. // -// Returns 0 on success and non-zero on error. +// System V interface script: +// https://www.ibm.com/docs/en/aix/7.2?topic=configuration-printer-interface-scripts // + extern int cfFilterExternal(int inputfd, int outputfd, int inputseekable, @@ -260,25 +310,38 @@ extern int cfFilterExternal(int inputfd, void *parameters); -extern int cfFilterOpenBackAndSidePipes(cf_filter_data_t *data); +// +// 'cfFilterOpenBackAndSidePipes()' - Open the back and side pipes for communication with filters. +// -extern void cfFilterCloseBackAndSidePipes(cf_filter_data_t *data); +extern int cfFilterOpenBackAndSidePipes(cf_filter_data_t *data); +// +// 'cfFilterCloseBackAndSidePipes()' - Close the back and side pipes for communication with filters. +// +extern void cfFilterCloseBackAndSidePipes(cf_filter_data_t *data); + // -// 'cfFilterGhostscript()' - Convert input data using Ghostscript. -// -// Uses Ghostscript to convert the input data to the desired -// output format. The output format must be specified via -// data->final_content_type or by passing a -// cf_filter_out_format_t parameter. +// 'cfFilterGhostscript()' - Run Ghostscript to generate printer output. +// +// Converts input data using Ghostscript to the specified output format. +// The output format must be set via data->final_content_type or alternatively as parameter of type +// cf_filter_out_format_t. // -// Supported output formats include PDF, raster-only PDF, -// PCLm, CUPS Raster, PWG Raster, Apple Raster, and PCL-XL. +// Output formats: PDF, raster-only PDF, PCLm, PostScript, CUPS Raster, +// PWG Raster, Apple Raster, PCL-XL // -// Returns 0 on success and non-zero on error. +// Note: With the Apple Raster selection and a Ghostscript version +// without "appleraster" output device (9.55.x and older) the output +// is actually CUPS Raster but information about available color +// spaces and depths is taken from the urf-supported printer IPP +// attribute. This mode is for further processing with +// rastertopwg. With Ghostscript supporting Apple Raster output +// (9.56.0 and newer), we actually produce Apple Raster and no further +// filter is required. // @@ -288,6 +351,16 @@ extern int cfFilterGhostscript(int inputfd, cf_filter_data_t *data, void *parameters); +// +// 'cfFilterBannerToPDF()' - Generate a PDF banner page. +// +// Creates a banner or test page in PDF format. +// The parameter is a const char* specifying the template directory. +// CUPS uses /usr/share/cups/data/ by default. +// If a PDF file with added banner instructions is provided as input, +// the template directory is not required. +// + extern int cfFilterBannerToPDF(int inputfd, int outputfd, @@ -295,12 +368,9 @@ extern int cfFilterBannerToPDF(int inputfd, cf_filter_data_t *data, void *parameters); -// Parameters: const char* -// Template directory: In this directory there are the PDF template files -// for the banners and test pages. CUPS uses /usr/share/cups/data/ for that. -// If you submit a PDF file with added banner instructions as input file -// the template directory is not needed as the PDF input file itself is used -// as template. +// +// 'cfFilterImageToPDF()' - Convert an image to PDF format. +// extern int cfFilterImageToPDF(int inputfd, @@ -309,13 +379,9 @@ extern int cfFilterImageToPDF(int inputfd, cf_filter_data_t *data, void *parameters); - -extern int cfFilterImageToRaster(int inputfd, - int outputfd, - int inputseekable, - cf_filter_data_t *data, - void *parameters); - +// +// 'cfFilterImageToRaster()' - Convert an image to raster format. +// // Requires specification of output format via data->final_content_type // // Output formats: CUPS Raster, PWG Raster, Apple Raster, PCLM @@ -328,6 +394,30 @@ extern int cfFilterImageToRaster(int inputfd, // processing with rastertopwg and/or pwgtopclm. This can change in the // future when we add Apple Raster and PWG Raster output support to // this filter function. +// + + +extern int cfFilterImageToRaster(int inputfd, + int outputfd, + int inputseekable, + cf_filter_data_t *data, + void *parameters); + +// +// 'cfFilterMuPDFToPWG()' - Convert PDF or XPS input to PWG Raster format using MuPDF. +// +// Requires specification of output format via data->final_content_type. +// +// Output formats: CUPS Raster, PWG Raster, Apple Raster, PCLm +// +// Note: With CUPS Raster, Apple Raster, or PCLm selections the output +// is actually PWG Raster but information about available color spaces +// and depths is taken from the urf-supported printer IPP attribute, the +// pclm- attributes, or from a supplied CUPS Raster sample header +// (PCLM is always sGray/sRGB 8-bit). These modes are for further processing +// with pwgtoraster or pwgtopclm. This can change in the future when +// MuPDF adds further output formats. +// extern int cfFilterMuPDFToPWG(int inputfd, @@ -336,18 +426,13 @@ extern int cfFilterMuPDFToPWG(int inputfd, cf_filter_data_t *data, void *parameters); +// +// 'cfFilterPCLmToRaster()' - Convert PCLm input to raster format. +// // Requires specification of output format via data->final_content_type // -// Output formats: CUPS Raster, PWG Raster, Apple Raster, PCLm +// Output formats: CUPS Raster, Apple Raster, PWG Raster // -// Note: With CUPS Raster, Apple Raster, or PCLm selections the output -// is actually PWG Raster but information about available color spaces -// and depths is taken from the urf-supported printer IPP attribute, -// the pclm- attributes, or from a supplied CUPS Raster sample header -// (PCLM is always sGray/sRGB 8-bit). These modes are for further -// processing with pwgtoraster or pwgtopclm. This can change in the -// future when MuPDF adds further output formats. - extern int cfFilterPCLmToRaster(int inputfd, int outputfd, @@ -355,9 +440,18 @@ extern int cfFilterPCLmToRaster(int inputfd, cf_filter_data_t *data, void *parameters); -// Requires specification of output format via data->final_content_type // -// Output formats: CUPS Raster, Apple Raster, or PWG Raster +// 'cfFilterPDFToPDF()' - Process PDF input and produce PDF output. +// +// (Optional) Specification of output format via +// data->final_content_type is used for determining whether this +// filter function does page logging for CUPS (output of "PAGE: XX YY" +// log messages) or not and also to determine whether the printer or +// driver generates copies or whether we have to send the pages +// repeatedly. +// Alternatively, the options "pdf-filter-page-logging", +// "hardware-copies", and "hardware-collate" can be used to manually do these selections. +// extern int cfFilterPDFToPDF(int inputfd, @@ -366,16 +460,17 @@ extern int cfFilterPDFToPDF(int inputfd, cf_filter_data_t *data, void *parameters); -// (Optional) Specification of output format via -// data->final_content_type is used for determining whether this -// filter function does page logging for CUPS (output of "PAGE: XX YY" -// log messages) or not and also to determine whether the printer or -// driver generates copies or whether we have to send the pages -// repeatedly. // -// Alternatively, the options "pdf-filter-page-logging", -// "hardware-copies", and "hardware-collate" can be used to manually -// do these selections. +// 'cfFilterPDFToRaster()' - Convert PDF input to raster format. +// +// Requires specification of output format via data->final_content_type +// +// Output formats: CUPS Raster, PWG Raster, Apple Raster, PCLm +// +// Note: With PCLm selection the output is actually PWG Raster but color space and +// depth will be 8-bit sRGB or SGray, the only color spaces supported by PCLm. +// This mode is for further processing with pwgtopclm. +// extern int cfFilterPDFToRaster(int inputfd, @@ -384,15 +479,14 @@ extern int cfFilterPDFToRaster(int inputfd, cf_filter_data_t *data, void* parameters); +// +// 'cfFilterPWGToRaster()' - Convert PWG Raster input to raster format. +// // Requires specification of output format via data->final_content_type // -// Output formats: CUPS Raster, PWG Raster, Apple Raster, PCLm +// Output formats: CUPS Raster, Apple Raster, PWG Raster +// // -// Note: With PCLm selection the output is actually PWG Raster but -// color space and depth will be 8-bit sRGB or SGray, the only color -// spaces supported by PCLm. This mode is for further processing with -// pwgtopclm. - extern int cfFilterPWGToRaster(int inputfd, int outputfd, @@ -400,9 +494,14 @@ extern int cfFilterPWGToRaster(int inputfd, cf_filter_data_t *data, void *parameters); +// +// 'cfFilterPWGToPDF()' - Convert PWG Raster input to PDF format. +// // Requires specification of output format via data->final_content_type +// or alternatively as parameter of type cf_filter_out_format_t. // -// Output formats: CUPS Raster, PWG Raster, Apple Raster +// Output formats: PDF, PCLm +// extern int cfFilterPWGToPDF(int inputfd, @@ -411,11 +510,13 @@ extern int cfFilterPWGToPDF(int inputfd, cf_filter_data_t *data, void *parameters); -// Requires specification of output format via data->final_content_type -// or alternatively as parameter of type cf_filter_out_format_t. +// 'cfFilterRasterToPWG()' - Convert raster input to PWG Raster format. +// +// Requires specification of output format via data->final_content_type. +// +// Output formats: Apple Raster or PWG Raster, if PCLM is specified PWG +// Raster is produced to feed into the cfFilterPWGToPDF() filter function // -// Output formats: PDF, PCLm - extern int cfFilterRasterToPWG(int inputfd, int outputfd, @@ -423,12 +524,14 @@ extern int cfFilterRasterToPWG(int inputfd, cf_filter_data_t *data, void *parameters); -// Requires specification of output format via data->final_content_type // -// Output formats: Apple Raster or PWG Raster, if PCLM is specified -// PWG Raster is produced to feed into the cfFilterPWGToPDF() filter -// function. - +// 'cfFilterTextToPDF()' - Convert text input to PDF format. +// +// Parameters: cf_filter_texttopdf_parameter_t* +// +// Data directory (fonts, charsets), charset, content type (for prettyprint), +// classification (for overprint/watermark) +// extern int cfFilterTextToPDF(int inputfd, int outputfd, @@ -436,11 +539,9 @@ extern int cfFilterTextToPDF(int inputfd, cf_filter_data_t *data, void *parameters); -// Parameters: cf_filter_texttopdf_parameter_t* // -// Data directory (fonts, charsets), charset, content type (for prettyprint), -// classification (for overprint/watermark) - +// 'cfFilterTextToText()' - Process plain text input and produce plain text output. +// extern int cfFilterTextToText(int inputfd, int outputfd, @@ -448,27 +549,21 @@ extern int cfFilterTextToText(int inputfd, cf_filter_data_t *data, void *parameters); - // -// 'cfFilterUniversal()' - Automatically select and execute -// the appropriate filter conversion pipeline. +// 'cfFilterUniversal()' - Universal filter function for various conversions. // -// Determines the required data conversion based on the job's -// input content type (data->content_type) and the desired -// final output type (data->final_content_type). +// Requires specification of input format via data->content_type and +// job's final output format via data->final_content_type. // -// Parameters: -// inputfd - Input file descriptor. -// outputfd - Output file descriptor. -// inputseekable - Non-zero if input supports seeking. -// data - Job and printer data. -// parameters - Pointer to a -// cf_filter_universal_parameter_t structure -// providing additional conversion settings. +// Parameters: cf_filter_universal_parameter_t* // -// Returns 0 on success and non-zero on error. +// Contains: actual_output_type: Format which the filter should +// actually produce if different from job's final output +// format, otherwise NULL to produce the job's final output +// format +// texttopdf_params: parameters for texttopdf // - + extern int cfFilterUniversal(int inputfd, int outputfd, int inputseekable, @@ -476,7 +571,6 @@ extern int cfFilterUniversal(int inputfd, void *parameters); - # ifdef __cplusplus } # endif // __cplusplus diff --git a/cupsfilters/raster.h b/cupsfilters/raster.h index 314c670db..91470b932 100644 --- a/cupsfilters/raster.h +++ b/cupsfilters/raster.h @@ -45,6 +45,9 @@ extern "C" { #endif +// +// Prototypes... +// // // 'cfRasterColorSpaceString()' - Return a human-readable // name for the given raster color space. @@ -56,7 +59,7 @@ extern const char *cfRasterColorSpaceString(cups_cspace_t cspace); // 'cfRasterPrepareHeader()' - Prepare a CUPS/PWG raster page // header based on job and printer data. // -// Returns 0 on success and non-zero on error. +// Returns 0 on success, non-zero on error. // extern int cfRasterPrepareHeader(cups_page_header_t *h, @@ -73,7 +76,7 @@ extern int cfRasterPrepareHeader(cups_page_header_t *h, // appropriate color space and color depth based on printer // capabilities and job settings. // -// Returns 0 on success and -1 on error. +// Returns 0 on success, -1 on error. // extern int cfRasterSetColorSpace(cups_page_header_t *h, From 836ae2aa60953348bf23ab2c5ab57e8000746b30 Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Thu, 9 Jul 2026 01:50:01 +0530 Subject: [PATCH 03/24] Improve API documentation in bannertopdf.c --- cupsfilters/bannertopdf.c | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/cupsfilters/bannertopdf.c b/cupsfilters/bannertopdf.c index 60769e7b2..f7618e0b1 100644 --- a/cupsfilters/bannertopdf.c +++ b/cupsfilters/bannertopdf.c @@ -883,14 +883,17 @@ generate_banner_pdf(banner_t *banner, return (0); } +// +// 'cfFilterBannerToPDF()' - Convert banner instructions to PDF. +// + int cfFilterBannerToPDF(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream int inputseekable, // I - Is input stream seekable? // (unused) cf_filter_data_t *data, // I - Job and printer data - void *parameters) // I - Filter-specific parameters - - // Template/Banner data directory + void *parameters) // I - Filter-specific parameters (Template/Banner data directory) { banner_t *banner; int num_options = 0; From f1b5bb1d4f50dca1801b07c41fd59a31631b4f2e Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Thu, 9 Jul 2026 01:52:00 +0530 Subject: [PATCH 04/24] Improve API documentation in bitmap.c --- cupsfilters/bitmap.c | 27 ++++++++++++--------------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/cupsfilters/bitmap.c b/cupsfilters/bitmap.c index 03fe7678b..bfb8e3d31 100644 --- a/cupsfilters/bitmap.c +++ b/cupsfilters/bitmap.c @@ -76,8 +76,7 @@ cfConvertBits(unsigned char *src, // I - Input string unsigned char *dst, // I - Destination string unsigned int x, // I - Column unsigned int y, // I - Row - unsigned int cupsNumColors,// I - Number of color components of - // output data + unsigned int cupsNumColors,// I - Number of color components of output data unsigned int bitspercolor) // I - Bitspercolor of output data { // assumed that max number of colors is 4 @@ -156,13 +155,12 @@ cfConvertBits(unsigned char *src, // I - Input string // color order. // -void // O - Exit status +void cfWritePixel(unsigned char *dst, // I - Destination string unsigned int plane, // I - Plane/Band unsigned int pixeli, // I - Pixel unsigned char *pixelBuf, // I - Input string - unsigned int cupsNumColors,// I - Number of color components of - // output data + unsigned int cupsNumColors,// I - Number of color components of output data unsigned int bitspercolor, // I - Bitspercolor of output data cups_order_t colororder) // I - Color Order of output data { @@ -395,7 +393,7 @@ cfReverseOneBitLineSwap(unsigned char *src, // I - Input line // raster data using ordered dithering. // -void // O - Output line +void cfOneBitLine(unsigned char *src, // I - Input line unsigned char *dst, // O - Destination line unsigned int width, // I - Width of raster image in pixels @@ -434,11 +432,10 @@ cfOneBitLine(unsigned char *src, // I - Input line // 8-bit raster data. // -void // O - Output line +void cfOneBitToGrayLine(unsigned char *src, // I - Input line unsigned char *dst, // O - Destination line - unsigned int width) // I - Width of raster image in - // pixels + unsigned int width) // I - Width of raster image in pixels { unsigned char mask = 0x80; for (unsigned int w = 0; w < width; w += 1) @@ -460,13 +457,13 @@ cfOneBitToGrayLine(unsigned char *src, // I - Input line // raster data. // -unsigned char -*cfRGB8toKCMYcm(unsigned char *src, - unsigned char *dst, - unsigned int x, - unsigned int y) +unsigned char // O - Output pixel +*cfRGB8toKCMYcm(unsigned char *src, // I - Input pixel (RGB) + unsigned char *dst, // I - Destination pixel (KCMYcm) + unsigned int x, // I - Column + unsigned int y) // I - Row { - unsigned char cmyk[4]; + unsigned char cmyk[4]; unsigned char c; unsigned char d; From ef257443f98afc6e9333bf2cfe4071e3fe27a7db Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Thu, 9 Jul 2026 01:53:21 +0530 Subject: [PATCH 05/24] Improve API documentation in catalog.c --- cupsfilters/catalog.c | 142 ++++++++++++++++++++++++++++-------------- 1 file changed, 94 insertions(+), 48 deletions(-) diff --git a/cupsfilters/catalog.c b/cupsfilters/catalog.c index b45e5abeb..04c5ea81a 100644 --- a/cupsfilters/catalog.c +++ b/cupsfilters/catalog.c @@ -25,12 +25,14 @@ #include #include +// +// 'cfGetURI()' - Get a file from the given URI and save it to a temporary file. +// -int // O - 1 on success, 0 on failure -cfGetURI(const char *url, // I - URL to get - char *name, // I - Temporary filename - size_t namesize) // I - Size of temporary filename - // buffer +int // O - 1 on success, 0 on failure +cfGetURI(const char *url, // I - URL to get + char *name, // I - Temporary filename + size_t namesize) // I - Size of temporary filename buffer { http_t *http = NULL; char scheme[32], // URL scheme @@ -76,15 +78,14 @@ cfGetURI(const char *url, // I - URL to get return (1); } - // -// 'cfCatalogFind()' - Find a CUPS message catalog file containing -// human-readable standard option and choice names -// for IPP printers +// 'cfCatalogSearchDirLocale()' - Search a directory for a CUPS message catalog file +// matching the given locale. // -char * -cfCatalogSearchDirLocale(const char *dirname, const char *locale) +char * // O - Catalog file path, or NULL if not found +cfCatalogSearchDirLocale(const char *dirname, // I - Directory name + const char *locale) // I - Locale name { char *catalog = NULL; char catalogpath[2048]; @@ -101,8 +102,14 @@ cfCatalogSearchDirLocale(const char *dirname, const char *locale) return (catalog); } -char * -cfCatalogSearchDirLang(const char *dirname, const char *lang) +// +// 'cfCatalogSearchDirLang()' - Search a directory for a CUPS message catalog file +// matching the given language. +// + +char * // O - Catalog file path, or NULL if not found +cfCatalogSearchDirLang(const char *dirname, // I - Directory name + const char *lang) // I - Language name { size_t lang_len; const char *c1, *c2; @@ -161,8 +168,13 @@ cfCatalogSearchDirLang(const char *dirname, const char *lang) return (catalog); } -char * -cfCatalogSearchDir(const char *dirname, const char *preferredlocale) +// +// 'cfCatalogSearchDir()' - Search a directory for a CUPS message catalog file matching +// the preferred locale. + +char * // O - Catalog file path, or NULL if not found +cfCatalogSearchDir(const char *dirname, // I - Directory name + const char *preferredlocale) // I - Preferred locale name { const char *c1, *c2; char *catalog = NULL; @@ -268,9 +280,15 @@ cfCatalogSearchDir(const char *dirname, const char *preferredlocale) return (catalog); } +// +// 'cfCatalogFind()' - Find a CUPS message catalog file containing +// human-readable standard option and choice names +// for IPP printers. +// -char * -cfCatalogFind(const char *preferreddir, const char *preferredlocale) +char * // O - Catalog file path, or NULL if not found +cfCatalogFind(const char *preferreddir, // I - Preferred directory + const char *preferredlocale) // I - Preferred locale name { const char *c; char buf[1024]; @@ -332,10 +350,14 @@ compare_options(void *a, ((catalog_opt_strings_t *)b)->name)); } +// +// 'cfCatalogFreeChoiceStrings()' - Free a choice strings entry containing the +// localized human-readable choice name. +// -void -cfCatalogFreeChoiceStrings(void* entry, - void* user_data) +void +cfCatalogFreeChoiceStrings(void* entry, // I - Choice strings entry + void* user_data) // I - User data (unused) { catalog_choice_strings_t *entry_rec = (catalog_choice_strings_t *)entry; @@ -347,10 +369,14 @@ cfCatalogFreeChoiceStrings(void* entry, } } +// +// 'cfCatalogFreeOptionStrings()' - Free memory allocated for an option strings +// entry in the catalog. +// void -cfCatalogFreeOptionStrings(void* entry, - void* user_data) +cfCatalogFreeOptionStrings(void* entry, // I - Option strings entry + void* user_data) // I - User data (unused) { catalog_opt_strings_t *entry_rec = (catalog_opt_strings_t *)entry; @@ -363,18 +389,24 @@ cfCatalogFreeOptionStrings(void* entry, } } +// +// 'cfCatalogOptionArrayNew()' - Create a new array to store catalog option string entries. +// -cups_array_t * +cups_array_t * // O - New array cfCatalogOptionArrayNew() { return (cupsArrayNew(compare_options, NULL, NULL, 0, NULL, cfCatalogFreeOptionStrings)); } +// +// 'cfCatalogFindOption()' - Find a catalog option strings entry by name. +// -catalog_opt_strings_t * -cfCatalogFindOption(cups_array_t *options, - char *name) +catalog_opt_strings_t * // O - Option strings entry, or NULL if not found +cfCatalogFindOption(cups_array_t *options, // I - Catalog choice array + char *name) // I - Option name { catalog_opt_strings_t opt; @@ -385,10 +417,13 @@ cfCatalogFindOption(cups_array_t *options, return (cupsArrayFind(options, &opt)); } +// +// 'cfCatalogFindChoice()' - Find a catalog choice strings entry by name. +// -catalog_choice_strings_t * -cfCatalogFindChoice(cups_array_t *choices, - char *name) +catalog_choice_strings_t * // O - Choice strings entry, or NULL if not found +cfCatalogFindChoice(cups_array_t *choices, // I - Catalog choice array + char *name) // I - Choice name { catalog_choice_strings_t choice; @@ -399,11 +434,14 @@ cfCatalogFindChoice(cups_array_t *choices, return (cupsArrayFind(choices, &choice)); } +// +// 'cfCatalogAddOption()' - Add a catalog option strings entry to the options array. +// -catalog_opt_strings_t * -cfCatalogAddOption(char *name, - char *human_readable, - cups_array_t *options) +catalog_opt_strings_t * // O - Option strings entry +cfCatalogAddOption(char *name, // I - Option name + char *human_readable, // I - Human-readable option text + cups_array_t *options) // I - Catalog option array { catalog_opt_strings_t *opt = NULL; @@ -437,12 +475,15 @@ cfCatalogAddOption(char *name, return (opt); } +// +// 'cfCatalogAddChoice()' - Add a catalog choice strings entry to the option's choices array. +// -catalog_choice_strings_t * -cfCatalogAddChoice(char *name, - char *human_readable, - char *opt_name, - cups_array_t *options) +catalog_choice_strings_t * // O - Catalog choice entry +cfCatalogAddChoice(char *name, // I - Choice name + char *human_readable, // I - Human-readable choice text + char *opt_name, // I - Parent option name + cups_array_t *options) // I - Catalog option array { catalog_choice_strings_t *choice = NULL; catalog_opt_strings_t *opt; @@ -474,12 +515,14 @@ cfCatalogAddChoice(char *name, return (choice); } +// +// 'cfCatalogLookUpOption()' - Look up the human-readable text for a catalog option. +// - -char * -cfCatalogLookUpOption(char *name, - cups_array_t *options, - cups_array_t *printer_options) +char * // O - Human-readable option text or NULL +cfCatalogLookUpOption(char *name, // I - Option name + cups_array_t *options, // I - Catalog option array + cups_array_t *printer_options) // I - Printer-specific option array { catalog_opt_strings_t *opt = NULL; @@ -495,12 +538,15 @@ cfCatalogLookUpOption(char *name, return (NULL); } +// +// 'cfCatalogLookUpChoice()' - Look up the human-readable text for a catalog choice. +// -char * -cfCatalogLookUpChoice(char *name, - char *opt_name, - cups_array_t *options, - cups_array_t *printer_options) +char * // O - Human-readable choice text or NULL +cfCatalogLookUpChoice(char *name, // I - Choice name + char *opt_name, // I - Parent option name + cups_array_t *options, // I - Catalog option array + cups_array_t *printer_options) // I - Printer-specific option array { catalog_opt_strings_t *opt = NULL; catalog_choice_strings_t *choice = NULL; From 8e6a34a7ea50d53f8a73b67ee210d91c4f0950ac Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Sat, 11 Jul 2026 15:50:06 +0530 Subject: [PATCH 06/24] improved documentaion of filter.c file --- cupsfilters/filter.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cupsfilters/filter.c b/cupsfilters/filter.c index 6d5e97910..1c2d11985 100644 --- a/cupsfilters/filter.c +++ b/cupsfilters/filter.c @@ -72,7 +72,7 @@ fcntl_add_nonblock(int fd) // File descriptor to add O_NONBLOCK to // ", .... // -void // O - None +void cfCUPSLogFunc(void *data, // I - User data (not used) cf_loglevel_t level, // I - Log level const char *message, // I - Message format string From e6d19df4e66bb254ea97e767ba063668c95f7b9b Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Thu, 16 Jul 2026 04:27:40 +0530 Subject: [PATCH 07/24] Improved API documentation in bannertopdf.c --- cupsfilters/bannertopdf.c | 48 +++++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/cupsfilters/bannertopdf.c b/cupsfilters/bannertopdf.c index f7618e0b1..e750da81a 100644 --- a/cupsfilters/bannertopdf.c +++ b/cupsfilters/bannertopdf.c @@ -28,34 +28,34 @@ #include #include - -typedef enum banner_info_e +// Banner information flags. +typedef enum banner_info_e { - INFO_IMAGEABLE_AREA = 1, - INFO_JOB_BILLING = 1 << 1, - INFO_JOB_ID = 1 << 2, - INFO_JOB_NAME = 1 << 3, - INFO_JOB_ORIGINATING_HOST_NAME = 1 << 4, - INFO_JOB_ORIGINATING_USER_NAME = 1 << 5, - INFO_JOB_UUID = 1 << 6, - INFO_OPTIONS = 1 << 7, - INFO_PAPER_NAME = 1 << 8, - INFO_PAPER_SIZE = 1 << 9, - INFO_PRINTER_DRIVER_NAME = 1 << 10, - INFO_PRINTER_DRIVER_VERSION = 1 << 11, - INFO_PRINTER_INFO = 1 << 12, - INFO_PRINTER_LOCATION = 1 << 13, - INFO_PRINTER_MAKE_AND_MODEL = 1 << 14, - INFO_PRINTER_NAME = 1 << 15, - INFO_TIME_AT_CREATION = 1 << 16, - INFO_TIME_AT_PROCESSING = 1 << 17 + INFO_IMAGEABLE_AREA = 1, // I - Imageable area + INFO_JOB_BILLING = 1 << 1, // I - Job billing + INFO_JOB_ID = 1 << 2, // I - Job ID + INFO_JOB_NAME = 1 << 3, // I - Job name + INFO_JOB_ORIGINATING_HOST_NAME = 1 << 4, // I - Job originating host name + INFO_JOB_ORIGINATING_USER_NAME = 1 << 5, // I - Job originating user name + INFO_JOB_UUID = 1 << 6, // I - Job UUID + INFO_OPTIONS = 1 << 7, // I - Options + INFO_PAPER_NAME = 1 << 8, // I - Paper name + INFO_PAPER_SIZE = 1 << 9, // I - Paper size + INFO_PRINTER_DRIVER_NAME = 1 << 10, // I - Printer driver name + INFO_PRINTER_DRIVER_VERSION = 1 << 11, // I - Printer driver version + INFO_PRINTER_INFO = 1 << 12, // I - Printer info + INFO_PRINTER_LOCATION = 1 << 13, // I - Printer location + INFO_PRINTER_MAKE_AND_MODEL = 1 << 14, // I - Printer make and model + INFO_PRINTER_NAME = 1 << 15, // I - Printer name + INFO_TIME_AT_CREATION = 1 << 16, // I - Time at creation + INFO_TIME_AT_PROCESSING = 1 << 17 // I - Time at processing } banner_info_t; -typedef struct banner_s +typedef struct banner_s //*** Banner data structure *** // { - char *template_file; - char *header, *footer; - unsigned infos; + char *template_file; // I - Template file path + char *header, *footer; // I - Header and footer text + unsigned infos; // I - Banner information flags } banner_t; static void From 238dcac93927b7bfcd84cf9c0ae3bc8caca19b6c Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Thu, 16 Jul 2026 04:34:45 +0530 Subject: [PATCH 08/24] Imporved API documentation in catalog.c --- cupsfilters/catalog.c | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/cupsfilters/catalog.c b/cupsfilters/catalog.c index 04c5ea81a..7b118652d 100644 --- a/cupsfilters/catalog.c +++ b/cupsfilters/catalog.c @@ -565,11 +565,14 @@ cfCatalogLookUpChoice(char *name, // I - Choice name return (NULL); } +// +// 'cfCatalogLoad()' - Load a catalog file. +// void -cfCatalogLoad(const char *location, - const char *preferredlocale, - cups_array_t *options) +cfCatalogLoad(const char *location, // I - Catalog file location (path or URL) + const char *preferredlocale, // I - Preferred locale name + cups_array_t *options) // I - Catalog option array { char tmpfile[1024]; const char *filename = NULL; From 3038977cd54c701a178a8769102488ff2e0f22d9 Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Thu, 16 Jul 2026 04:37:20 +0530 Subject: [PATCH 09/24] Imporved API documentation in catalog.h --- cupsfilters/catalog.h | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/cupsfilters/catalog.h b/cupsfilters/catalog.h index 90a886a2d..62ae6ed62 100644 --- a/cupsfilters/catalog.h +++ b/cupsfilters/catalog.h @@ -73,15 +73,15 @@ extern "C" { // Data structure for IPP choice name and human-readable string typedef struct catalog_choice_strings_s { - char *name, - *human_readable; + char *name, // I - IPP choice name + *human_readable; // I - Human-readable string } catalog_choice_strings_t; // Data structure for IPP option name, human-readable string, and choice list typedef struct catalog_opt_strings_s { - char *name, - *human_readable; - cups_array_t *choices; + char *name, // I - IPP option name + *human_readable; // I - Human-readable string + cups_array_t *choices; // I - Array of choices for this option } catalog_opt_strings_t; From 6c3bbf8d40d57533ef562630f594b2d34cec3c60 Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Thu, 16 Jul 2026 04:39:41 +0530 Subject: [PATCH 10/24] Imporved API documentation in cmyk.c --- cupsfilters/cmyk.c | 51 ++++++++++++++++------------------------------ 1 file changed, 17 insertions(+), 34 deletions(-) diff --git a/cupsfilters/cmyk.c b/cupsfilters/cmyk.c index f9da7ecd3..c16ef0278 100644 --- a/cupsfilters/cmyk.c +++ b/cupsfilters/cmyk.c @@ -61,14 +61,10 @@ cfCMYKDelete(cf_cmyk_t *cmyk) // I - Color separation // void -cfCMYKDoBlack(const cf_cmyk_t *cmyk, - // I - Color separation - const unsigned char *input, - // I - Input grayscale pixels - short *output, - // O - Output Device-N pixels - int num_pixels) - // I - Number of pixels +cfCMYKDoBlack(const cf_cmyk_t *cmyk, // I - Color separation + const unsigned char *input, // I - Input grayscale pixels + short *output, // O - Output Device-N pixels + int num_pixels) // I - Number of pixels { int k; // Current black value const short **channels; // Copy of channel LUTs @@ -244,14 +240,10 @@ cfCMYKDoBlack(const cf_cmyk_t *cmyk, // void -cfCMYKDoCMYK(const cf_cmyk_t *cmyk, - // I - Color separation - const unsigned char *input, - // I - Input grayscale pixels - short *output, - // O - Output Device-N pixels - int num_pixels) - // I - Number of pixels +cfCMYKDoCMYK(const cf_cmyk_t *cmyk, // I - Color separation + const unsigned char *input, // I - Input grayscale pixels + short *output, // O - Output Device-N pixels + int num_pixels) // I - Number of pixels { int c, // Current cyan value m, // Current magenta value @@ -516,14 +508,10 @@ cfCMYKDoCMYK(const cf_cmyk_t *cmyk, // void -cfCMYKDoGray(const cf_cmyk_t *cmyk, - // I - Color separation - const unsigned char *input, - // I - Input grayscale pixels - short *output, - // O - Output Device-N pixels - int num_pixels) - // I - Number of pixels +cfCMYKDoGray(const cf_cmyk_t *cmyk, // I - Color separation + const unsigned char *input, // I - Input grayscale pixels + short *output, // O - Output Device-N pixels + int num_pixels) // I - Number of pixels { int k, // Current black value kc; // Current black color value @@ -743,14 +731,10 @@ cfCMYKDoGray(const cf_cmyk_t *cmyk, // void -cfCMYKDoRGB(const cf_cmyk_t *cmyk, - // I - Color separation - const unsigned char *input, - // I - Input grayscale pixels - short *output, - // O - Output Device-N pixels - int num_pixels) - // I - Number of pixels +cfCMYKDoRGB(const cf_cmyk_t *cmyk, // I - Color separation + const unsigned char *input, // I - Input grayscale pixels + short *output, // O - Output Device-N pixels + int num_pixels) // I - Number of pixels { int c, // Current cyan value m, // Current magenta value @@ -1188,8 +1172,7 @@ cfCMYKSetBlack(cf_cmyk_t *cmyk, // I - CMYK color separation void cfCMYKSetCurve(cf_cmyk_t *cmyk, // I - CMYK color separation int channel, // I - Color channel - int num_xypoints, - // I - Number of X,Y points + int num_xypoints, // I - Number of X,Y points const float *xypoints, // I - X,Y points cf_logfunc_t log, // I - Log function void *ld) // I - Log function data From 11f3fe963cdc2d8cad690bf5d87174a2612e76d6 Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Thu, 16 Jul 2026 04:42:02 +0530 Subject: [PATCH 11/24] Imporved API documentation in colord.c --- cupsfilters/colord.c | 65 ++++++++++++++++++++++++++++++-------------- 1 file changed, 45 insertions(+), 20 deletions(-) diff --git a/cupsfilters/colord.c b/cupsfilters/colord.c index cca1ac57d..14cc28f57 100644 --- a/cupsfilters/colord.c +++ b/cupsfilters/colord.c @@ -24,12 +24,17 @@ #define QUAL_RESOLUTION 2 #define QUAL_SIZE 3 -char ** -cfColordGetQualifier(cf_filter_data_t *data, - const char *color_space, - const char *media_type, - int x_res, - int y_res) +// +// 'cfColordGetQualifier()' - Get the qualifier strings for the specified color space, +// media type, and resolution. +// + +char ** // O - Qualifier strings +cfColordGetQualifier(cf_filter_data_t *data, // I - Filter data + const char *color_space, // I - Color space + const char *media_type, // I - Media type + int x_res, // I - Horizontal resolution + int y_res) // I - Vertical resolution { int i, len; const char *val; @@ -311,10 +316,15 @@ get_device_path_for_device_id(cf_filter_data_t *data, return (device_path); } -char * -cfColordGetProfileForDeviceID(cf_filter_data_t *data, - const char *device_id, - const char **qualifier_tuple) +// +// 'cfColordGetProfileForDeviceID()' - Get the color profile for the specified +// device ID and qualifier tuple. +// + +char * // O - Profile filename +cfColordGetProfileForDeviceID(cf_filter_data_t *data, // I - Filter data + const char *device_id, // I - Device ID + const char **qualifier_tuple) // I - Qualifier tuple { cf_logfunc_t log = data->logfunc; void *ld = data->logdata; @@ -438,9 +448,14 @@ get_profile_inhibitors(cf_filter_data_t *data, return (inhibitors); } -int -cfColordGetInhibitForDeviceID(cf_filter_data_t *data, - const char *device_id) +// +// 'cfColordGetInhibitForDeviceID()' - Get the number of inhibitors for the specified +// device ID. +// + +int // O - Non-zero if inhibited, 0 otherwise +cfColordGetInhibitForDeviceID(cf_filter_data_t *data, // I - Filter data + const char *device_id) // I - Device ID { cf_logfunc_t log = data->logfunc; void* ld = data->logdata; @@ -478,10 +493,15 @@ cfColordGetInhibitForDeviceID(cf_filter_data_t *data, #else -char * -cfColordGetProfileForDeviceID(cf_filter_data_t *data, - const char *device_id, - const char **qualifier_tuple) +// +// 'cfColordGetQualifier()' - Get the qualifier strings for the specified color space, +// media type, and resolution. +// + +char * // O - Qualifier strings +cfColordGetProfileForDeviceID(cf_filter_data_t *data, // I - Filter data + const char *device_id, // I - Device ID + const char **qualifier_tuple) // I - Qualifier tuple { cf_logfunc_t log = data->logfunc; void *ld = data->logdata; @@ -490,9 +510,14 @@ cfColordGetProfileForDeviceID(cf_filter_data_t *data, return (NULL); } -int -cfColordGetInhibitForDeviceID(cf_filter_data_t *data, - const char *device_id) +// +// 'cfColordGetInhibitForDeviceID()' - Get the number of inhibitors for the specified +// device ID. +// + +int // O - Non-zero if inhibited, 0 otherwise +cfColordGetInhibitForDeviceID(cf_filter_data_t *data, // I - Filter data + const char *device_id) // I - Device ID { cf_logfunc_t log = data->logfunc; void *ld = data->logdata; From c4388df420c6e26da43b389f882698635d200a92 Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Thu, 16 Jul 2026 04:44:16 +0530 Subject: [PATCH 12/24] Imporved API documentation in colormanager.c --- cupsfilters/colormanager.c | 32 ++++++++++++++------------------ 1 file changed, 14 insertions(+), 18 deletions(-) diff --git a/cupsfilters/colormanager.c b/cupsfilters/colormanager.c index f25788c68..bcfb061e4 100644 --- a/cupsfilters/colormanager.c +++ b/cupsfilters/colormanager.c @@ -33,15 +33,11 @@ double blackpoint_default[3] = {0.0, 0.0, 0.0}; // -// Public functions +// 'cfCmIsPrinterCmDisabled()' - Check if color management is disabled for the printer. // -// -// Get printer color management status from the system's color manager -// - -int -cfCmIsPrinterCmDisabled(cf_filter_data_t *data) +int // O - Non-zero if disabled, 0 otherwise +cfCmIsPrinterCmDisabled(cf_filter_data_t *data) // I - Filter data { cf_logfunc_t log = data->logfunc; void *ld = data->logdata; @@ -72,16 +68,16 @@ cfCmIsPrinterCmDisabled(cf_filter_data_t *data) // -// Get printer ICC profile from the system's color manager +// 'cfCmGetPrinterIccProfile()' - Get the ICC profile for the printer from colord or fallback option. // -int -cfCmGetPrinterIccProfile(cf_filter_data_t *data, - const char *color_space, - const char *media_type, - int x_res, - int y_res, - char **profile) // ICC Profile Path +int // O - Non-zero if profile found, 0 otherwise +cfCmGetPrinterIccProfile(cf_filter_data_t *data, // I - Filter data + const char *color_space, // I - Color space string + const char *media_type, // I - Media type string + int x_res, // I - X resolution + int y_res, // I - Y resolution + char **profile) // I - ICC profile path string { cf_logfunc_t log = data->logfunc; void *ld = data->logdata; @@ -152,11 +148,11 @@ cfCmGetPrinterIccProfile(cf_filter_data_t *data, // -// Find the "cm-calibration" CUPS option +// 'cfCmGetCupsColorCalibrateMode()' - Get the color calibration mode from CUPS options. // -cf_cm_calibration_t -cfCmGetCupsColorCalibrateMode(cf_filter_data_t *data) +cf_cm_calibration_t // O - Color calibration mode +cfCmGetCupsColorCalibrateMode(cf_filter_data_t *data) // I - Filter data { int num_options = 0; cups_option_t *options = NULL; From 042f09ac796317ec09db90e0ebd192ac93158487 Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Thu, 16 Jul 2026 04:45:50 +0530 Subject: [PATCH 13/24] Imporved API documentation in colormanager.h --- cupsfilters/colormanager.h | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/cupsfilters/colormanager.h b/cupsfilters/colormanager.h index 2d0e9b5e0..daed09618 100644 --- a/cupsfilters/colormanager.h +++ b/cupsfilters/colormanager.h @@ -21,15 +21,13 @@ extern "C" { #include -#define CF_CM_CALIBRATION_STRING "cm-calibration" // String for "Color - // Calibration Mode" +#define CF_CM_CALIBRATION_STRING "cm-calibration" // String for "Color Calibration Mode" // Enum for status of CUPS color calibration typedef enum cf_cm_calibration_e { - CF_CM_CALIBRATION_DISABLED = 0, // "cm-calibration" option - // not found + CF_CM_CALIBRATION_DISABLED = 0, // "cm-calibration" option not found CF_CM_CALIBRATION_ENABLED = 1 // "cm-calibration" found } cf_cm_calibration_t; From ebfe9a29d8b02247b320d278c9a50cc2dc2e23ca Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Thu, 16 Jul 2026 04:47:09 +0530 Subject: [PATCH 14/24] Imporved API documentation in dither.c --- cupsfilters/dither.c | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/cupsfilters/dither.c b/cupsfilters/dither.c index 018fe21bb..2ee4b51eb 100644 --- a/cupsfilters/dither.c +++ b/cupsfilters/dither.c @@ -25,8 +25,6 @@ // // 'cfDitherDelete()' - Free a dithering buffer. // -// Returns 0 on success, -1 on failure. -// void cfDitherDelete(cf_dither_t *d) // I - Dithering buffer @@ -41,12 +39,11 @@ cfDitherDelete(cf_dither_t *d) // I - Dithering buffer // void -cfDitherLine(cf_dither_t *d, // I - Dither data - const cf_lut_t *lut, // I - Lookup table - const short *data, // I - Separation data - int num_channels, - // I - Number of components - unsigned char *p) // O - Pixels +cfDitherLine(cf_dither_t *d, // I - Dither data + const cf_lut_t *lut, // I - Lookup table + const short *data, // I - Separation data + int num_channels, // I - Number of components + unsigned char *p) // O - Pixels { register int x, // Horizontal position in line... pixel, // Current adjusted pixel... From 57445250f2f2914c8c6447707037a3e3167f5236 Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Thu, 16 Jul 2026 04:48:20 +0530 Subject: [PATCH 15/24] Imporved API documentation in driver.h --- cupsfilters/driver.h | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/cupsfilters/driver.h b/cupsfilters/driver.h index 40e5d2716..ca5744278 100644 --- a/cupsfilters/driver.h +++ b/cupsfilters/driver.h @@ -86,10 +86,8 @@ typedef struct cf_rgb_s // *** Color separation lookup table *** int cube_size; // Size of color cube (2-N) on a side int num_channels; // Number of colors per sample unsigned char ****colors; // 4-D array of sample values - int cube_index[256]; // Index into cube for a given sRGB - // value - int cube_mult[256]; // Multiplier value for a given sRGB - // value + int cube_index[256]; // Index into cube for a given sRGB value + int cube_mult[256]; // Multiplier value for a given sRGB value int cache_init; // Are cached values initialized? unsigned char black[CF_MAX_RGB]; // Cached black (sRGB = 0,0,0) unsigned char white[CF_MAX_RGB]; // Cached white (sRGB = 255,255,255) From 6528335f5f6b40c00e24d96c2812e9d404f220fa Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Thu, 16 Jul 2026 04:49:54 +0530 Subject: [PATCH 16/24] Imporved API documentation in ghostscript.c --- cupsfilters/ghostscript.c | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/cupsfilters/ghostscript.c b/cupsfilters/ghostscript.c index 72e1c2f12..ae727b217 100644 --- a/cupsfilters/ghostscript.c +++ b/cupsfilters/ghostscript.c @@ -34,26 +34,28 @@ #define PDF_MAX_CHECK_COMMENT_LINES 20 +// Ghostscript document type. typedef enum gs_doc_e { - GS_DOC_TYPE_PDF, - GS_DOC_TYPE_PS, - GS_DOC_TYPE_EMPTY, - GS_DOC_TYPE_UNKNOWN -} gs_doc_t; + GS_DOC_TYPE_PDF, // PDF document + GS_DOC_TYPE_PS, // PostScript document + GS_DOC_TYPE_EMPTY, // Empty document + GS_DOC_TYPE_UNKNOWN // Unknown document type +} gs_doc_t; typedef cups_page_header_t gs_page_header; +// Ghostscript halftone type. typedef enum cups_halftone_type_e { - HALFTONE_DEFAULT, - HALFTONE_STOCHASTIC, - HALFTONE_FOO2ZJS, - HALFTONE_BI_LEVEL, - HALFTONE_DITHERING, - HALFTONE_GENORDERED, - HALFTONE_SPOT -} cups_halftone_type_t; + HALFTONE_DEFAULT, // Default halftone type + HALFTONE_STOCHASTIC, // Stochastic halftone type + HALFTONE_FOO2ZJS, // foo2zjs halftone type + HALFTONE_BI_LEVEL // Bi-level halftone type + HALFTONE_DITHERING, // Dithering halftone type + HALFTONE_GENORDERED, // Generalized ordered halftone type + HALFTONE_SPOT, // Spot halftone type +} cups_halftone_type_t; static const char *ht_spot_functions[] = { @@ -831,10 +833,8 @@ gs_spawn (const char *filename, // int // O - Error status -cfFilterGhostscript(int inputfd, // I - File descriptor input - // stream - int outputfd, // I - File descriptor output - // stream +cfFilterGhostscript(int inputfd, // I - File descriptor input stream + int outputfd, // I - File descriptor output stream int inputseekable, // I - Is input stream seekable? cf_filter_data_t *data, // I - Job and printer data void *parameters) // I - Filter-specific parameters From a7bcdb7e5e85f2bf5072f4ebcb22441e25ea85f9 Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Thu, 16 Jul 2026 05:21:49 +0530 Subject: [PATCH 17/24] fixed missing comma --- cupsfilters/ghostscript.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cupsfilters/ghostscript.c b/cupsfilters/ghostscript.c index ae727b217..1a06816ba 100644 --- a/cupsfilters/ghostscript.c +++ b/cupsfilters/ghostscript.c @@ -51,7 +51,7 @@ typedef enum cups_halftone_type_e HALFTONE_DEFAULT, // Default halftone type HALFTONE_STOCHASTIC, // Stochastic halftone type HALFTONE_FOO2ZJS, // foo2zjs halftone type - HALFTONE_BI_LEVEL // Bi-level halftone type + HALFTONE_BI_LEVEL, // Bi-level halftone type HALFTONE_DITHERING, // Dithering halftone type HALFTONE_GENORDERED, // Generalized ordered halftone type HALFTONE_SPOT, // Spot halftone type From 2a3939f86f31676c0d2af161f6c735f90a060646 Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Tue, 21 Jul 2026 04:28:39 +0530 Subject: [PATCH 18/24] fix trailing whitespace across multiple files --- cupsfilters/bannertopdf.c | 2 +- cupsfilters/bitmap.c | 4 ++-- cupsfilters/catalog.c | 2 +- cupsfilters/filter.c | 2 +- cupsfilters/ghostscript.c | 4 ++-- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/cupsfilters/bannertopdf.c b/cupsfilters/bannertopdf.c index e750da81a..973f586d4 100644 --- a/cupsfilters/bannertopdf.c +++ b/cupsfilters/bannertopdf.c @@ -29,7 +29,7 @@ #include // Banner information flags. -typedef enum banner_info_e +typedef enum banner_info_e { INFO_IMAGEABLE_AREA = 1, // I - Imageable area INFO_JOB_BILLING = 1 << 1, // I - Job billing diff --git a/cupsfilters/bitmap.c b/cupsfilters/bitmap.c index bfb8e3d31..26d9f1cd4 100644 --- a/cupsfilters/bitmap.c +++ b/cupsfilters/bitmap.c @@ -432,7 +432,7 @@ cfOneBitLine(unsigned char *src, // I - Input line // 8-bit raster data. // -void +void cfOneBitToGrayLine(unsigned char *src, // I - Input line unsigned char *dst, // O - Destination line unsigned int width) // I - Width of raster image in pixels @@ -463,7 +463,7 @@ unsigned char // O - Output pixel unsigned int x, // I - Column unsigned int y) // I - Row { - unsigned char cmyk[4]; + unsigned char cmyk[4]; unsigned char c; unsigned char d; diff --git a/cupsfilters/catalog.c b/cupsfilters/catalog.c index 7b118652d..eafca50de 100644 --- a/cupsfilters/catalog.c +++ b/cupsfilters/catalog.c @@ -355,7 +355,7 @@ compare_options(void *a, // localized human-readable choice name. // -void +void cfCatalogFreeChoiceStrings(void* entry, // I - Choice strings entry void* user_data) // I - User data (unused) { diff --git a/cupsfilters/filter.c b/cupsfilters/filter.c index 1c2d11985..6262928d6 100644 --- a/cupsfilters/filter.c +++ b/cupsfilters/filter.c @@ -72,7 +72,7 @@ fcntl_add_nonblock(int fd) // File descriptor to add O_NONBLOCK to // ", .... // -void +void cfCUPSLogFunc(void *data, // I - User data (not used) cf_loglevel_t level, // I - Log level const char *message, // I - Message format string diff --git a/cupsfilters/ghostscript.c b/cupsfilters/ghostscript.c index 1a06816ba..d32845fd4 100644 --- a/cupsfilters/ghostscript.c +++ b/cupsfilters/ghostscript.c @@ -41,7 +41,7 @@ typedef enum gs_doc_e GS_DOC_TYPE_PS, // PostScript document GS_DOC_TYPE_EMPTY, // Empty document GS_DOC_TYPE_UNKNOWN // Unknown document type -} gs_doc_t; +} gs_doc_t; typedef cups_page_header_t gs_page_header; @@ -55,7 +55,7 @@ typedef enum cups_halftone_type_e HALFTONE_DITHERING, // Dithering halftone type HALFTONE_GENORDERED, // Generalized ordered halftone type HALFTONE_SPOT, // Spot halftone type -} cups_halftone_type_t; +} cups_halftone_type_t; static const char *ht_spot_functions[] = { From 08a30d36e5f8386550cb519d656240a824d2b6a3 Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Mon, 3 Aug 2026 00:35:20 +0530 Subject: [PATCH 19/24] doc: improve API documentation across multiple files --- cupsfilters/bannertopdf.c | 7 +- cupsfilters/colormanager.c | 45 ++- cupsfilters/filter.h | 394 ++++++++----------------- cupsfilters/ieee1284.c | 77 ++--- cupsfilters/ieee1284.h | 62 ++-- cupsfilters/image.c | 13 +- cupsfilters/imagetopdf.c | 32 +- cupsfilters/imagetoraster.c | 3 +- cupsfilters/ipp-options-private.h | 2 +- cupsfilters/ipp.c | 469 ++++++++++++++++-------------- cupsfilters/ipp.h | 26 +- cupsfilters/libcups2.c | 9 +- cupsfilters/mupdftopwg.c | 13 +- cupsfilters/pack.c | 6 +- cupsfilters/pdf.c | 37 +-- cupsfilters/pdf.h | 8 +- cupsfilters/pdftopdf-private.h | 34 +-- cupsfilters/pdftopdf.c | 125 +++++--- cupsfilters/pdftoraster.c | 91 +++--- cupsfilters/pwgtoraster.c | 79 ++--- cupsfilters/raster.c | 50 +--- cupsfilters/testfilters.c | 82 +++--- cupsfilters/testpdf2.c | 10 +- cupsfilters/texttopdf.c | 22 +- cupsfilters/texttotext.c | 26 +- cupsfilters/universal.c | 4 + 26 files changed, 835 insertions(+), 891 deletions(-) diff --git a/cupsfilters/bannertopdf.c b/cupsfilters/bannertopdf.c index 973f586d4..bac711fc4 100644 --- a/cupsfilters/bannertopdf.c +++ b/cupsfilters/bannertopdf.c @@ -51,7 +51,7 @@ typedef enum banner_info_e INFO_TIME_AT_PROCESSING = 1 << 17 // I - Time at processing } banner_info_t; -typedef struct banner_s //*** Banner data structure *** // +typedef struct banner_s //*** Banner data structure *** { char *template_file; // I - Template file path char *header, *footer; // I - Header and footer text @@ -887,11 +887,10 @@ generate_banner_pdf(banner_t *banner, // 'cfFilterBannerToPDF()' - Convert banner instructions to PDF. // -int +int // O - 0 on success, 1 on error cfFilterBannerToPDF(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream - int inputseekable, // I - Is input stream seekable? - // (unused) + int inputseekable, // I - Is input stream seekable? (unused) cf_filter_data_t *data, // I - Job and printer data void *parameters) // I - Filter-specific parameters (Template/Banner data directory) { diff --git a/cupsfilters/colormanager.c b/cupsfilters/colormanager.c index bcfb061e4..aa482af7d 100644 --- a/cupsfilters/colormanager.c +++ b/cupsfilters/colormanager.c @@ -180,46 +180,61 @@ cfCmGetCupsColorCalibrateMode(cf_filter_data_t *data) // I - Filter data // -// Accessor functions to return specific calibration data +// 'cfCmGammaAdobeRGB()' - Get the gamma value for Adobe RGB. // -// Gamma values - -double *cfCmGammaAdobeRGB(void) +double // O - Gamma value + *cfCmGammaAdobeRGB(void) { return (adobergb_gamma); } -double *cfCmGammaSGray(void) +// +// 'cfCmGammaSGray()' - Get the gamma value for sGray. +// + +double // O - Gamma value +*cfCmGammaSGray(void) { return (sgray_gamma); } +// +// 'cfCmWhitePointAdobeRGB()' - Get the whitepoint value for Adobe RGB. +// -// Whitepoint values - -double *cfCmWhitePointAdobeRGB(void) +double // O - Whitepoint value + *cfCmWhitePointAdobeRGB(void) { return (adobergb_wp); } -double *cfCmWhitePointSGray(void) +// +// 'cfCmWhitePointSGray()' - Get the whitepoint value for sGray. +// + +double // O - Whitepoint value + *cfCmWhitePointSGray(void) { return (sgray_wp); } +// +// 'cfCmMatrixAdobeRGB()' - Get the adapted primaries matrix for Adobe RGB. +// -// Adapted primaries matrix - -double *cfCmMatrixAdobeRGB(void) +double // O - Adapted primaries matrix +*cfCmMatrixAdobeRGB(void) { return (adobergb_matrix); } +// +// 'cfCmBlackPointDefault()' - Get the default blackpoint value. +// -// Blackpoint value - -double *cfCmBlackPointDefault(void) +double // O - Blackpoint value +*cfCmBlackPointDefault(void) { return (blackpoint_default); } diff --git a/cupsfilters/filter.h b/cupsfilters/filter.h index 24b87b4a8..da17d8c6e 100644 --- a/cupsfilters/filter.h +++ b/cupsfilters/filter.h @@ -52,50 +52,40 @@ extern "C" { typedef int (*cf_filter_iscanceledfunc_t)(void *data); -typedef struct cf_filter_data_s +typedef struct cf_filter_data_s // *** Data structure for filter functions *** { char *printer; // Print queue name or NULL int job_id; // Job ID or 0 char *job_user; // Job user or NULL char *job_title; // Job title or NULL - int copies; // Number of copies - // (1 if filter(s) should not treat it) - char *content_type; // Input MIME type (CUPS env variable - // CONTENT_TYPE) or NULL - char *final_content_type; // Output MIME type (CUPS env variable - // FINAL_CONTENT_TYPE) or NULL + int copies; // Number of copies (1 if filter(s) should not treat it) + char *content_type; // Input MIME type (CUPS env variable CONTENT_TYPE) or NULL + char *final_content_type; // Output MIME type (CUPS env variable FINAL_CONTENT_TYPE) or NULL ipp_t *job_attrs; // IPP attributes passed along with the job - ipp_t *printer_attrs; // Printer capabilities in IPP format - // (what is answered to get-printer-attributes - cups_page_header_t *header; - // CUPS/PWG Raster header (optional) - int num_options; + ipp_t *printer_attrs; // Printer capabilities in IPP format (what is answered to get-printer-attributes) + cups_page_header_t *header; // CUPS/PWG Raster header (optional) + int num_options; // Number of job options cups_option_t *options; // Job options as key/value pairs int back_pipe[2]; // File descriptors of backchannel pipe int side_pipe[2]; // File descriptors of sidechannel pipe cups_array_t *extension; // Extension data cf_logfunc_t logfunc; // Logging function, NULL for no logging void *logdata; // User data for logging function, can be NULL - cf_filter_iscanceledfunc_t iscanceledfunc; - // Function returning 1 when job is - // canceled, NULL for not supporting stop - // on cancel - void *iscanceleddata; // User data for is-canceled function, can be - // NULL + cf_filter_iscanceledfunc_t iscanceledfunc; // Function returning 1 when job is canceled, NULL for not supporting stop on cancel + void *iscanceleddata; // User data for is-canceled function, can be NULL } cf_filter_data_t; -typedef struct cf_filter_data_ext_s +typedef struct cf_filter_data_ext_s // *** Extension data for cf_filter_data_t *** { - char *name; - void *ext; + char *name; // Name of the extension data + void *ext; // Pointer to the extension data } cf_filter_data_ext_t; typedef int (*cf_filter_function_t)(int inputfd, int outputfd, int inputseekable, cf_filter_data_t *data, void *parameters); -typedef enum cf_filter_out_format_e // Possible output formats for filter - // functions +typedef enum cf_filter_out_format_e // *** Possible output formats for filter functions *** { CF_FILTER_OUT_FORMAT_PDF, // PDF CF_FILTER_OUT_FORMAT_PDF_IMAGE, // Raster-only PDF @@ -106,154 +96,78 @@ typedef enum cf_filter_out_format_e // Possible output formats for filter CF_FILTER_OUT_FORMAT_PXL // PCL-XL } cf_filter_out_format_t; -typedef struct cf_filter_filter_in_chain_s // filter entry for CUPS array to - // be supplied to cfFilterChain() - // filter function +typedef struct cf_filter_filter_in_chain_s // *** Filter entry for CUPS array to be supplied to cfFilterChain() filter function *** { cf_filter_function_t function; // Filter function to be called void *parameters; // Parameters for this filter function call char *name; // Name/comment, only for logging } cf_filter_filter_in_chain_t; -typedef struct cf_filter_external_s // Parameters for the - // cfFilterExternal() filter - // function +typedef struct cf_filter_external_s // *** Parameters for the cfFilterExternal() filter function *** { - const char *filter; // Path/Name of the CUPS filter to be called by - // this filter function, required - int exec_mode; // 0 if we call a CUPS filter, -1 if we call - // a System V interface script, 1 if we call a CUPS - // backend, 2 if we call a CUPS backend in - // device discovery mode + const char *filter; // Path/Name of the CUPS filter to be called by this filter function, required + int exec_mode; // 0 if we call a CUPS filter, -1 if we call a System V interface script, 1 if we call a CUPS backend, 2 if we call a CUPS backend in device discovery mode int num_options; // Extra options for the 5th command line - cups_option_t *options; // argument, options of filter_data have - // priority, 0/NULL if none - char **envp; // Additional environment variables, the already - // defined ones stay valid but can be overwritten - // by these ones, NULL if none + cups_option_t *options; // argument, options of filter_data have priority, 0/NULL if none + char **envp; // Additional environment variables, the already defined ones stay valid but can be overwritten by these ones, NULL if none } cf_filter_external_t; -typedef struct cf_filter_texttopdf_parameter_s // parameters container of - // environemnt variables needed - // by texttopdf filter - // function +typedef struct cf_filter_texttopdf_parameter_s // *** parameters container of environemnt variables needed by texttopdf filter function *** { - char *data_dir; - char *char_set; - char *content_type; - char *classification; + char *data_dir; // Data directory to be used for fonts and charsets, or NULL for default + char *char_set; // Charset to be used for prettyprint, or NULL for default + char *content_type; // Content type to be used for prettyprint, or NULL for default + char *classification; // Classification to be used for overprint/watermark, or NULL for default } cf_filter_texttopdf_parameter_t; -typedef struct cf_filter_universal_parameter_s // Contains input and output - // type to be supplied to the - // universal function, and also - // parameters for - // cfFilterTextToPDF() +typedef struct cf_filter_universal_parameter_s // *** Contains input and output type to be supplied to the universal function, and also parameters for cfFilterTextToPDF() *** { - char *actual_output_type; - cf_filter_texttopdf_parameter_t texttopdf_params; - const char *bannertopdf_template_dir; + char *actual_output_type; // Output MIME type + cf_filter_texttopdf_parameter_t texttopdf_params; // Parameters for cfFilterTextToPDF() filter function + const char *bannertopdf_template_dir; // Template directory for cfFilterBannerToPDF() filter function } cf_filter_universal_parameter_t; // // Prototypes... // -//'cfCUPSLogFunc()' - Logging callback functions used by filters. -// -// data: User-defined logging context. -// level: Log level of the message. -// message: printf-style format string. -// ...: Optional arguments for the format string. -// -// This function is used by filters to report status, debug -// information, warnings, and errors. -// extern void cfCUPSLogFunc(void *data, cf_loglevel_t level, const char *message, ...); -// -// 'cfCUPSIsCanceledFunc()' - Check whether the current job has been canceled. -// -// data: User-defined job context. -// Returns 1 if canceled, 0 otherwise. -// extern int cfCUPSIsCanceledFunc(void *data); -// 'cfFilterDataAddExt()' - Add an extension to the filter data. -// -// data: Filter data structure. -// name: Name of the extension. -// ext: Pointer to the extension data. -// - extern void *cfFilterDataAddExt(cf_filter_data_t *data, const char *name, void *ext); -// -// '*cfFilterDataGetExt()' - Retrieve an extension from the filter data. -// extern void *cfFilterDataGetExt(cf_filter_data_t *data, const char *name); -// -// '*cfFilterDataRemoveExt()'- Remove an extension from the filter data. -// extern void *cfFilterDataRemoveExt(cf_filter_data_t *data, const char *name); -// -// '*cfFilterGetEnvVar()' - Get the value of an environment variable from a given -// environment array. -// name: Name of the variable. -// env: Environment array. -// -// Returns a pointer to value string, or NULL if not found. -// - extern char *cfFilterGetEnvVar(char *name, char **env); -// -// 'cfFilterAddEnvVar()' - Add or update an environment variable. -// -// name: Name of the variable. -// value: Value of the variable. -// env: Environment array. -// -// Returns 0 on success, -1 on failure. -// extern int cfFilterAddEnvVar(char *name, char *value, char ***env); -// -// 'cfFilterTee()' - Filter function that copies input to output and optionally to a file. -// -// Parameters: parameters points to a const char* specifying the -// filename/path to copy the data to. -// - extern int cfFilterTee(int inputfd, int outputfd, int inputseekable, cf_filter_data_t *data, void *parameters); -// -// 'cfFilterPOpen()' - Start a filter function in a separate process. -// -// filter_func: Filter function to execute. -// parameters: Filter-specific parameters passed to the filter. -// filter_pid: Receives the process ID of the started filter. -// +// Parameters: Filename/path (const char *) to copy the data to -extern int cfFilterPOpen(cf_filter_function_t filter_func, + +extern int cfFilterPOpen(cf_filter_function_t filter_func, // I - Filter + // function int inputfd, int outputfd, int inputseekable, @@ -262,45 +176,21 @@ extern int cfFilterPOpen(cf_filter_function_t filter_func, int *filter_pid); -// -// 'cfFilterPClose()' - Wait for a filter process started by cfFilterPOpen(). -// -// fd: Input pipe file descriptor. -// filter_pid: Process ID of the filter. -// data: Job and printer. -// Return: 0 on success, -1 on failure. -// - extern int cfFilterPClose(int fd, int filter_pid, cf_filter_data_t *data); -// -// 'cfFilterChain()' - Execute a chain of filter functions. -// -// Parameters: Pointer to an array of cf_filter_filter_in_chain_t defining the -// list of filters to execute. Each filter receives the previous filter's -// output as input. -// - extern int cfFilterChain(int inputfd, int outputfd, int inputseekable, cf_filter_data_t *data, void *parameters); -// -// 'cfFilterExternal()' - Executes an external filter or backend. -// -// This function runs a CUPS/System V filter or backend based on the input and output types -// specified in the parameters. -// -// See "man filter" and "man backend" for more information on CUPS filters and backends. -// -// System V interface script: -// https://www.ibm.com/docs/en/aix/7.2?topic=configuration-printer-interface-scripts -// +// Parameters: Unsorted (!) CUPS array of cf_filter_filter_in_chain_t* +// List of filters to execute in a chain, next filter takes output of +// previous filter as input, all get the same filter data, parameters +// are supplied individually in the array extern int cfFilterExternal(int inputfd, @@ -309,27 +199,38 @@ extern int cfFilterExternal(int inputfd, cf_filter_data_t *data, void *parameters); - +// Parameters: cf_filter_external_t* // -// 'cfFilterOpenBackAndSidePipes()' - Open the back and side pipes for communication with filters. -// +// Path/Name of the external CUPS/System V filter or backend to be +// called by this filter function, specification whether we call a +// filter or a backend, and in case of backend, whether in job +// processing or discovery mode, extra options for the 5th command +// line argument, and extra environment variables +// +// CUPS filter: +// See "man filter" +// +// CUPS Backend: +// See "man backend" +// +// System V interface script: +// https://www.ibm.com/docs/en/aix/7.2?topic=configuration-printer-interface-scripts extern int cfFilterOpenBackAndSidePipes(cf_filter_data_t *data); -// -// 'cfFilterCloseBackAndSidePipes()' - Close the back and side pipes for communication with filters. -// - extern void cfFilterCloseBackAndSidePipes(cf_filter_data_t *data); -// -// 'cfFilterGhostscript()' - Run Ghostscript to generate printer output. -// -// Converts input data using Ghostscript to the specified output format. -// The output format must be set via data->final_content_type or alternatively as parameter of type -// cf_filter_out_format_t. + +extern int cfFilterGhostscript(int inputfd, + int outputfd, + int inputseekable, + cf_filter_data_t *data, + void *parameters); + +// Requires specification of output format via data->final_content_type +// or alternatively as parameter of type cf_filter_out_format_t. // // Output formats: PDF, raster-only PDF, PCLm, PostScript, CUPS Raster, // PWG Raster, Apple Raster, PCL-XL @@ -342,24 +243,6 @@ extern void cfFilterCloseBackAndSidePipes(cf_filter_data_t *data); // rastertopwg. With Ghostscript supporting Apple Raster output // (9.56.0 and newer), we actually produce Apple Raster and no further // filter is required. -// - - -extern int cfFilterGhostscript(int inputfd, - int outputfd, - int inputseekable, - cf_filter_data_t *data, - void *parameters); - -// -// 'cfFilterBannerToPDF()' - Generate a PDF banner page. -// -// Creates a banner or test page in PDF format. -// The parameter is a const char* specifying the template directory. -// CUPS uses /usr/share/cups/data/ by default. -// If a PDF file with added banner instructions is provided as input, -// the template directory is not required. -// extern int cfFilterBannerToPDF(int inputfd, @@ -368,9 +251,12 @@ extern int cfFilterBannerToPDF(int inputfd, cf_filter_data_t *data, void *parameters); -// -// 'cfFilterImageToPDF()' - Convert an image to PDF format. -// +// Parameters: const char* +// Template directory: In this directory there are the PDF template files +// for the banners and test pages. CUPS uses /usr/share/cups/data/ for that. +// If you submit a PDF file with added banner instructions as input file +// the template directory is not needed as the PDF input file itself is used +// as template. extern int cfFilterImageToPDF(int inputfd, @@ -379,9 +265,13 @@ extern int cfFilterImageToPDF(int inputfd, cf_filter_data_t *data, void *parameters); -// -// 'cfFilterImageToRaster()' - Convert an image to raster format. -// + +extern int cfFilterImageToRaster(int inputfd, + int outputfd, + int inputseekable, + cf_filter_data_t *data, + void *parameters); + // Requires specification of output format via data->final_content_type // // Output formats: CUPS Raster, PWG Raster, Apple Raster, PCLM @@ -394,30 +284,6 @@ extern int cfFilterImageToPDF(int inputfd, // processing with rastertopwg and/or pwgtopclm. This can change in the // future when we add Apple Raster and PWG Raster output support to // this filter function. -// - - -extern int cfFilterImageToRaster(int inputfd, - int outputfd, - int inputseekable, - cf_filter_data_t *data, - void *parameters); - -// -// 'cfFilterMuPDFToPWG()' - Convert PDF or XPS input to PWG Raster format using MuPDF. -// -// Requires specification of output format via data->final_content_type. -// -// Output formats: CUPS Raster, PWG Raster, Apple Raster, PCLm -// -// Note: With CUPS Raster, Apple Raster, or PCLm selections the output -// is actually PWG Raster but information about available color spaces -// and depths is taken from the urf-supported printer IPP attribute, the -// pclm- attributes, or from a supplied CUPS Raster sample header -// (PCLM is always sGray/sRGB 8-bit). These modes are for further processing -// with pwgtoraster or pwgtopclm. This can change in the future when -// MuPDF adds further output formats. -// extern int cfFilterMuPDFToPWG(int inputfd, @@ -426,13 +292,18 @@ extern int cfFilterMuPDFToPWG(int inputfd, cf_filter_data_t *data, void *parameters); -// -// 'cfFilterPCLmToRaster()' - Convert PCLm input to raster format. -// // Requires specification of output format via data->final_content_type // -// Output formats: CUPS Raster, Apple Raster, PWG Raster +// Output formats: CUPS Raster, PWG Raster, Apple Raster, PCLm // +// Note: With CUPS Raster, Apple Raster, or PCLm selections the output +// is actually PWG Raster but information about available color spaces +// and depths is taken from the urf-supported printer IPP attribute, +// the pclm- attributes, or from a supplied CUPS Raster sample header +// (PCLM is always sGray/sRGB 8-bit). These modes are for further +// processing with pwgtoraster or pwgtopclm. This can change in the +// future when MuPDF adds further output formats. + extern int cfFilterPCLmToRaster(int inputfd, int outputfd, @@ -440,18 +311,9 @@ extern int cfFilterPCLmToRaster(int inputfd, cf_filter_data_t *data, void *parameters); +// Requires specification of output format via data->final_content_type // -// 'cfFilterPDFToPDF()' - Process PDF input and produce PDF output. -// -// (Optional) Specification of output format via -// data->final_content_type is used for determining whether this -// filter function does page logging for CUPS (output of "PAGE: XX YY" -// log messages) or not and also to determine whether the printer or -// driver generates copies or whether we have to send the pages -// repeatedly. -// Alternatively, the options "pdf-filter-page-logging", -// "hardware-copies", and "hardware-collate" can be used to manually do these selections. -// +// Output formats: CUPS Raster, Apple Raster, or PWG Raster extern int cfFilterPDFToPDF(int inputfd, @@ -460,17 +322,16 @@ extern int cfFilterPDFToPDF(int inputfd, cf_filter_data_t *data, void *parameters); +// (Optional) Specification of output format via +// data->final_content_type is used for determining whether this +// filter function does page logging for CUPS (output of "PAGE: XX YY" +// log messages) or not and also to determine whether the printer or +// driver generates copies or whether we have to send the pages +// repeatedly. // -// 'cfFilterPDFToRaster()' - Convert PDF input to raster format. -// -// Requires specification of output format via data->final_content_type -// -// Output formats: CUPS Raster, PWG Raster, Apple Raster, PCLm -// -// Note: With PCLm selection the output is actually PWG Raster but color space and -// depth will be 8-bit sRGB or SGray, the only color spaces supported by PCLm. -// This mode is for further processing with pwgtopclm. -// +// Alternatively, the options "pdf-filter-page-logging", +// "hardware-copies", and "hardware-collate" can be used to manually +// do these selections. extern int cfFilterPDFToRaster(int inputfd, @@ -479,14 +340,15 @@ extern int cfFilterPDFToRaster(int inputfd, cf_filter_data_t *data, void* parameters); -// -// 'cfFilterPWGToRaster()' - Convert PWG Raster input to raster format. -// // Requires specification of output format via data->final_content_type // -// Output formats: CUPS Raster, Apple Raster, PWG Raster -// +// Output formats: CUPS Raster, PWG Raster, Apple Raster, PCLm // +// Note: With PCLm selection the output is actually PWG Raster but +// color space and depth will be 8-bit sRGB or SGray, the only color +// spaces supported by PCLm. This mode is for further processing with +// pwgtopclm. + extern int cfFilterPWGToRaster(int inputfd, int outputfd, @@ -494,14 +356,9 @@ extern int cfFilterPWGToRaster(int inputfd, cf_filter_data_t *data, void *parameters); -// -// 'cfFilterPWGToPDF()' - Convert PWG Raster input to PDF format. -// // Requires specification of output format via data->final_content_type -// or alternatively as parameter of type cf_filter_out_format_t. // -// Output formats: PDF, PCLm -// +// Output formats: CUPS Raster, PWG Raster, Apple Raster extern int cfFilterPWGToPDF(int inputfd, @@ -510,13 +367,11 @@ extern int cfFilterPWGToPDF(int inputfd, cf_filter_data_t *data, void *parameters); -// 'cfFilterRasterToPWG()' - Convert raster input to PWG Raster format. -// -// Requires specification of output format via data->final_content_type. -// -// Output formats: Apple Raster or PWG Raster, if PCLM is specified PWG -// Raster is produced to feed into the cfFilterPWGToPDF() filter function +// Requires specification of output format via data->final_content_type +// or alternatively as parameter of type cf_filter_out_format_t. // +// Output formats: PDF, PCLm + extern int cfFilterRasterToPWG(int inputfd, int outputfd, @@ -524,14 +379,12 @@ extern int cfFilterRasterToPWG(int inputfd, cf_filter_data_t *data, void *parameters); +// Requires specification of output format via data->final_content_type // -// 'cfFilterTextToPDF()' - Convert text input to PDF format. -// -// Parameters: cf_filter_texttopdf_parameter_t* -// -// Data directory (fonts, charsets), charset, content type (for prettyprint), -// classification (for overprint/watermark) -// +// Output formats: Apple Raster or PWG Raster, if PCLM is specified +// PWG Raster is produced to feed into the cfFilterPWGToPDF() filter +// function. + extern int cfFilterTextToPDF(int inputfd, int outputfd, @@ -539,9 +392,11 @@ extern int cfFilterTextToPDF(int inputfd, cf_filter_data_t *data, void *parameters); +// Parameters: cf_filter_texttopdf_parameter_t* // -// 'cfFilterTextToText()' - Process plain text input and produce plain text output. -// +// Data directory (fonts, charsets), charset, content type (for prettyprint), +// classification (for overprint/watermark) + extern int cfFilterTextToText(int inputfd, int outputfd, @@ -549,30 +404,27 @@ extern int cfFilterTextToText(int inputfd, cf_filter_data_t *data, void *parameters); -// -// 'cfFilterUniversal()' - Universal filter function for various conversions. -// + +extern int cfFilterUniversal(int inputfd, + int outputfd, + int inputseekable, + cf_filter_data_t *data, + void *parameters); + // Requires specification of input format via data->content_type and -// job's final output format via data->final_content_type. +// job's final output format via data->final_content_type // -// Parameters: cf_filter_universal_parameter_t* +// Parameters: cf_filter_universal_parameter_t // // Contains: actual_output_type: Format which the filter should // actually produce if different from job's final output // format, otherwise NULL to produce the job's final output // format // texttopdf_params: parameters for texttopdf -// - -extern int cfFilterUniversal(int inputfd, - int outputfd, - int inputseekable, - cf_filter_data_t *data, - void *parameters); # ifdef __cplusplus } # endif // __cplusplus -#endif // !_CUPS_FILTERS_FILTER_H_ +#endif // !_CUPS_FILTERS_FILTER_H_ \ No newline at end of file diff --git a/cupsfilters/ieee1284.c b/cupsfilters/ieee1284.c index 95d580d4b..069fc94dc 100644 --- a/cupsfilters/ieee1284.c +++ b/cupsfilters/ieee1284.c @@ -634,44 +634,49 @@ move_right_part( // to produce a clean make-and-model string we can use. // -char * // O - Normalized make-and-model string - // or NULL on error +char * // O - Normalized make-and-model string or NULL on error cfIEEE1284NormalizeMakeModel( - const char *make_and_model, // I - Original make-and-model string - // or device ID - const char *make, // I - Manufacturer name as hint for - // correct separation of - // make_and_model or adding - // make, or pointer into input - // string where model name starts - // or NULL, - // ignored on device ID with "MFG" - // field or for NO_MAKE_MODEL - cf_ieee1284_normalize_modes_t mode, // I - Bit field to describe how to - // normalize - regex_t *extra_regex, // I - Compiled regex to determine - // where the extra info after - // the driver name starts, also - // mark with parentheses which - // sub string should be the - // driver name - char *buffer, // O - String buffer, to hold the - // normalized input string, plus, - // after the terminating zero, the - // driver name if an appropriate - // extra_regex is supplied - // (*drvname will point to it) + const char *make_and_model, // I - Original make-and-model string or device ID + const char *make, /* + * I - Manufacturer name as hint for correct separation of + * make_and_model or adding + * make, or pointer into input + * string where model name starts + * or NULL, + * ignored on device ID with "MFG" + * field or for NO_MAKE_MODEL + */ + cf_ieee1284_normalize_modes_t mode, // I - Bit field to describe how to normalize + regex_t *extra_regex, /* + * I - Compiled regex to determine + * where the extra info after + * the driver name starts, also + * mark with parentheses which + * sub string should be the + * driver name + */ + char *buffer, /* + * O - String buffer, to hold the + * normalized input string, plus, + * after the terminating zero, the + * driver name if an appropriate + * extra_regex is supplied + * (*drvname will point to it) + */ size_t bufsize, // O - Size of string buffer - char **model, // O - Pointer to where model name - // starts in buffer or NULL - char **extra, // O - Pointer to where extra info - // starts in buffer (after comma, - // semicolon, parenthese, or - // start of extra_regex - // match) or NULL - char **drvname) // O - Driver name, string of the first - // matching parenthese expression - // in the extra_regex + char **model, // O - Pointer to where model name starts in buffer or NULL + char **extra, /* + * O - Pointer to where extra info + * starts in buffer (after comma, + * semicolon, parenthese, or + * start of extra_regex + * match) or NULL + */ + char **drvname) /* + * O - Driver name, string of the first + * matching parenthese expression + * in the extra_regex + */ { int i; char *bufptr; // Pointer into buffer diff --git a/cupsfilters/ieee1284.h b/cupsfilters/ieee1284.h index a87521106..c321f50b6 100644 --- a/cupsfilters/ieee1284.h +++ b/cupsfilters/ieee1284.h @@ -60,41 +60,43 @@ extern "C" { // Bit field to describe how to normalize make/model/device ID strings enum cf_ieee1284_normalize_modes_e { - CF_IEEE1284_NORMALIZE_COMPARE = 0x01, // Optimized for comparing, - // replacing any sequence of - // non-alpha-numeric characters - // by a single separator char, - // at any letter-number boundary - // and any camel-case boundary - // add a single separator char, - // 2 separator chars between - // make/model/extra, - // make all letters lowercase (or - // uppercase) - CF_IEEE1284_NORMALIZE_IPP = 0x02, // Only chars allowed in - // IPP keywords - CF_IEEE1284_NORMALIZE_ENV = 0x04, // Environment variable format - // upparcase and underscore - CF_IEEE1284_NORMALIZE_HUMAN = 0x08, // Human-readable, conserves - // spaces and special characters - // but does some clean-up + CF_IEEE1284_NORMALIZE_COMPARE = 0x01, /* + * Optimized for comparing, + * replacing any sequence of + * non-alpha-numeric characters + * by a single separator char, + * at any letter-number boundary + * and any camel-case boundary + * add a single separator char, + * 2 separator chars between + * make/model/extra, + * make all letters lowercase (or uppercase) + */ + CF_IEEE1284_NORMALIZE_IPP = 0x02, // Only chars allowed in IPP keywords + CF_IEEE1284_NORMALIZE_ENV = 0x04, // Environment variable format upparcase and underscore + CF_IEEE1284_NORMALIZE_HUMAN = 0x08, /* + * Human-readable, conserves + * spaces and special characters + * but does some clean-up + */ CF_IEEE1284_NORMALIZE_LOWERCASE = 0x10, // All letters lowercase CF_IEEE1284_NORMALIZE_UPPERCASE = 0x20, // All letters uppercase CF_IEEE1284_NORMALIZE_SEPARATOR_SPACE = 0x40,// Separator char is ' ' CF_IEEE1284_NORMALIZE_SEPARATOR_DASH = 0x80, // Separator char is '-' CF_IEEE1284_NORMALIZE_SEPARATOR_UNDERSCORE = 0x100,// Separator char is '_' - CF_IEEE1284_NORMALIZE_PAD_NUMBERS = 0x200, // Zero-pad numbers in strings - // to get better list sorting - // results - CF_IEEE1284_NORMALIZE_SEPARATE_COMPONENTS = 0x400,// In the output buffer put - // '\0' bytes between make, - // model, and extra, to use - // as separate strings - CF_IEEE1284_NORMALIZE_NO_MAKE_MODEL = 0x800, // No make/model/extra separation, - // do not try to identify, add, - // or clean up manufacturer - // name -}; + CF_IEEE1284_NORMALIZE_PAD_NUMBERS = 0x200, // Zero-pad numbers in strings to get better list sorting results + CF_IEEE1284_NORMALIZE_SEPARATE_COMPONENTS = 0x400, /* + * In the output buffer put + * '\0' bytes between make, + * model, and extra, to use + * as separate strings + */ + CF_IEEE1284_NORMALIZE_NO_MAKE_MODEL = 0x800, /* + * No make/model/extra separation, + * do not try to identify, add, + * or clean up manufacturer + * name + */ typedef unsigned cf_ieee1284_normalize_modes_t; // diff --git a/cupsfilters/image.c b/cupsfilters/image.c index 34556aa81..34f3bc81a 100644 --- a/cupsfilters/image.c +++ b/cupsfilters/image.c @@ -642,13 +642,14 @@ cfImageSetMaxTiles( // 'cfImageCrop()' - Crop an image. // (posw, posh): Position of left corner // (width, height): Width and height of required image. +// -cf_image_t* -cfImageCrop(cf_image_t* img, - int posw, - int posh, - int width, - int height) +cf_image_t* // O - New image +cfImageCrop(cf_image_t* img, // I - Image to crop + int posw, // I - Position of left corner + int posh, // I - Position of left corner + int width, // I - Width of required image + int height) // I - Height of required image { int image_width = cfImageGetWidth(img); cf_image_t* temp = calloc(1, sizeof(cf_image_t)); diff --git a/cupsfilters/imagetopdf.c b/cupsfilters/imagetopdf.c index 8ce51dd36..0d9f75fd4 100644 --- a/cupsfilters/imagetopdf.c +++ b/cupsfilters/imagetopdf.c @@ -35,9 +35,9 @@ // Types... // -struct pdfObject +struct pdfObject // **** PDF object information **** { - int offset; + int offset; // Offset of object in output file }; typedef struct imagetopdf_doc_s // **** Document information **** @@ -58,14 +58,14 @@ typedef struct imagetopdf_doc_s // **** Document information **** PageTop, // Top margin PageWidth, // Total page width PageLength; // Total page length - struct pdfObject *objects; - int currentObjectNo; - int allocatedObjectNum; - int currentOffset; - int xrefOffset; - int *pageObjects; - int catalogObj; - int pagesObj; + struct pdfObject *objects; // PDF objects + int currentObjectNo; // Current object number + int allocatedObjectNum; // Allocated number of objects + int currentOffset; // Current offset in output file + int xrefOffset; // Offset of xref table + int *pageObjects; // Page objects + int catalogObj; // Catalog object + int pagesObj; // Pages object const char *title; int xpages, // # x pages ypages, // # y pages @@ -82,15 +82,15 @@ typedef struct imagetopdf_doc_s // **** Document information **** float xsize, // Total size in points ysize, xsize2, - ysize2; + ysize2; // Total size in points for 2-up printing float aspect; // Aspect ratio cf_image_t *img; // Image to print int colorspace; // Output colorspace cf_ib_t *row; // Current row float gammaval; // Gamma correction value float brightness; // Gamma correction value - char linebuf[LINEBUFSIZE]; - FILE *outputfp; + char linebuf[LINEBUFSIZE]; // Line buffer for output + FILE *outputfp; // Output file pointer } imagetopdf_doc_t; @@ -582,11 +582,9 @@ out_image(imagetopdf_doc_t *doc, int // O - Error status cfFilterImageToPDF(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream - int inputseekable, // I - Is input stream seekable? - // (unused) + int inputseekable, // I - Is input stream seekable? (unused) cf_filter_data_t *data, // I - Job and printer data - void *parameters) // I - Filter-specific parameters - // (unused) + void *parameters) // I - Filter-specific parameters (unused) { imagetopdf_doc_t doc; // Document information cups_page_header_t h; // CUPS Raster page header, to diff --git a/cupsfilters/imagetoraster.c b/cupsfilters/imagetoraster.c index eea5602da..b6b3c7f86 100644 --- a/cupsfilters/imagetoraster.c +++ b/cupsfilters/imagetoraster.c @@ -183,8 +183,7 @@ cfFilterImageToRaster(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream int inputseekable, // I - Is input stream seekable? cf_filter_data_t *data, // I - Job and printer data - void *parameters) // I - Filter-specific parameters - // (unused) + void *parameters) // I - Filter-specific parameters (unused) { imagetoraster_doc_t doc; // Document information int i; // Looping var diff --git a/cupsfilters/ipp-options-private.h b/cupsfilters/ipp-options-private.h index 10fbb6313..ab254b8a5 100644 --- a/cupsfilters/ipp-options-private.h +++ b/cupsfilters/ipp-options-private.h @@ -226,7 +226,7 @@ typedef struct cf_filter_options_s // All filter options in one structure bool mirror; // "mirror" value char page_border[128]; // "page-border" value int page_top, page_left, // Margin values - page_right, page_bottom; + page_right, page_bottom; // "page-top", "page-left", "page-right", "page-bottom" values char page_label[256]; // "page-label" value bool pdf_auto_rotate; // "pdfAutoRotate" value cf_filter_imgpos_t x_image_position; // "x-image-position" value diff --git a/cupsfilters/ipp.c b/cupsfilters/ipp.c index 813ebbaec..d02f4473d 100644 --- a/cupsfilters/ipp.c +++ b/cupsfilters/ipp.c @@ -46,8 +46,7 @@ typedef struct cf_size_s // **** Media Size (cups_size_t of libcups2) **** // millimeters right, // Right margin in hundredths of // millimeters - top; // Top margin in hundredths of - // millimeters + top; // Top margin in hundredths of millimeters } cf_size_t; @@ -66,15 +65,22 @@ log_printf(char *log, va_end(arglist); } -char * -cfResolveURI(const char *raw_uri) +// +// 'cfResolveURI()' - Resolve a URI, for example a DNS-SD-service-name-based URI to a host-name-based URI. +// + +char * // O - Resolved URI +cfResolveURI(const char *raw_uri) // I - Raw URI { return (cfResolveURI2(raw_uri, 0)); } -// Check how the driverless support is provided -int -cfCheckDriverlessSupport(const char* uri) +// +// 'cfCheckDriverlessSupport()' - Check how the driverless support is provided by the printer +// + +int // O - Support status +cfCheckDriverlessSupport(const char* uri) // I - Printer URI { int support_status = CF_DRVLESS_CHECKERR; ipp_t *response = NULL; @@ -87,80 +93,95 @@ cfCheckDriverlessSupport(const char* uri) return (support_status); } -// Get attributes of a printer specified only by URI -ipp_t * -cfGetPrinterAttributes(const char* raw_uri, - const char* const pattrs[], - int pattrs_size, - const char* const req_attrs[], - int req_attrs_size, - int debug) +// +// 'cfGetPrinterAttributes()' - Get attributes of a printer specified only by URI. +// + +ipp_t * // O - IPP printer attributes +cfGetPrinterAttributes(const char* raw_uri, // I - Printer URI + const char* const pattrs[], // I - Requested printer attributes + int pattrs_size, // I - Number of requested attributes + const char* const req_attrs[], // I - Required response attributes + int req_attrs_size, // I - Number of required attributes + int debug) // I - Debug mode { return (cfGetPrinterAttributes2(NULL, raw_uri, pattrs, pattrs_size, req_attrs, req_attrs_size, debug)); } -// Get attributes of a printer specified by URI and under a given HTTP -// connection, for example via a domain socket -ipp_t * -cfGetPrinterAttributes2(http_t *http_printer, - const char* raw_uri, - const char* const pattrs[], - int pattrs_size, - const char* const req_attrs[], - int req_attrs_size, - int debug) +// +// 'cfGetPrinterAttributes2()' - Get attributes of a printer specified by URI and under a given HTTP +// connection, for example via a domain socket. +// + +ipp_t * // O - IPP printer attributes +cfGetPrinterAttributes2(http_t *http_printer, // I - HTTP connection to printer + const char* raw_uri, // I - Printer URI + const char* const pattrs[], // I - Requested printer attributes + int pattrs_size, // I - Number of requested attributes + const char* const req_attrs[], // I - Required response attributes + int req_attrs_size, // I - Number of required attributes + int debug) // I - Debug mode { return (cfGetPrinterAttributes3(http_printer, raw_uri, pattrs, pattrs_size, req_attrs, req_attrs_size, debug, NULL)); } -// Get attributes of a printer specified by URI and under a given HTTP -// connection, for example via a domain socket, and give info about used -// fallbacks -ipp_t * -cfGetPrinterAttributes3(http_t *http_printer, - const char* raw_uri, - const char* const pattrs[], - int pattrs_size, - const char* const req_attrs[], - int req_attrs_size, - int debug, - int* driverless_info) +// +// 'cfGetPrinterAttributes3()' - Get attributes of a printer specified by URI and under a given HTTP +// connection, for example via a domain socket, and give info about used +// fallbacks +// + +ipp_t * // O - IPP printer attributes +cfGetPrinterAttributes3(http_t *http_printer, // I - HTTP connection to printer + const char* raw_uri, // I - Printer URI + const char* const pattrs[], // I - Requested printer attributes + int pattrs_size, // I - Number of requested attributes + const char* const req_attrs[], // I - Required response attributes + int req_attrs_size, // I - Number of required attributes + int debug, // I - Debug mode + int* driverless_info) // I - Pointer to variable to return driverless support status, or NULL { return (cfGetPrinterAttributes5(http_printer, raw_uri, pattrs, pattrs_size, req_attrs, req_attrs_size, debug, driverless_info, 0)); } +// +// 'cfGetPrinterAttributes4()' - Get attributes of a printer specified only by URI and given info about +// fax-support. +// -// Get attributes of a printer specified only by URI and given info about -// fax-support -ipp_t *cfGetPrinterAttributes4(const char* raw_uri, - const char* const pattrs[], - int pattrs_size, - const char* const req_attrs[], - int req_attrs_size, - int debug, - int is_fax) +ipp_t * // O - IPP printer attributes +cfGetPrinterAttributes4(const char* raw_uri, // I - Printer URI + const char* const pattrs[], // I - Requested printer attributes + int pattrs_size, // I - Number of requested attributes + const char* const req_attrs[], // I - Required response attributes + int req_attrs_size, // I - Number of required attributes + int debug, // I - Debug mode + int is_fax) // I - 1: Fax printer; 0: Not a fax printer { return (cfGetPrinterAttributes5(NULL, raw_uri, pattrs, pattrs_size, req_attrs, req_attrs_size, debug, NULL, is_fax)); } -// Get attributes of a printer specified by URI and under a given HTTP -// connection, for example via a domain socket, and give info about used -// fallbacks -ipp_t * -cfGetPrinterAttributes5(http_t *http_printer, - const char* raw_uri, - const char* const pattrs[], - int pattrs_size, - const char* const req_attrs[], - int req_attrs_size, - int debug, - int* driverless_info, - int is_fax) +// +// 'cfGetPrinterAttributes5()' - Get attributes of a printer specified by URI and under a given HTTP +// connection, for example via a domain socket, and give info about used +// fallbacks +// + +ipp_t * // O - IPP printer attributes +cfGetPrinterAttributes5(http_t *http_printer, // I - HTTP connection to printer + const char* raw_uri, // I - Printer URI + const char* const pattrs[], // I - Requested printer attributes + int pattrs_size, // I - Number of requested attributes + const char* const req_attrs[], // I - Required response attributes + int req_attrs_size, // I - Number of required attributes + int debug, // I - Debug mode + int* driverless_info, // I - Pointer to variable to return driverless support status, or NULL + int is_fax) // I - 1: Fax printer; 0: Not a fax printer { char *uri; int have_http, uri_status, host_port, i = 0, total_attrs = 0, fallback, @@ -454,8 +475,14 @@ cfGetPrinterAttributes5(http_t *http_printer, #ifndef HAVE_LIBCUPS2 -char* -cfResolveURI2(const char *raw_uri, int is_fax) + +// +// 'cfResolveURI2()' - Resolve a URI, for example a DNS-SD-service-name-based URI to a host-name-based URI. +// + +char* // O - Resolved URI +cfResolveURI2(const char *raw_uri, // I - Raw URI + int is_fax) // I - 1: Fax printer; 0: Not a fax printer { int options = HTTP_RESOLVE_DEFAULT; const char* auth_info_required = getenv("AUTH_INFO_REQUIRED"); @@ -483,13 +510,15 @@ is_string_tag(ipp_attribute_t *attr) // I - Attribute to check tag == IPP_TAG_KEYWORD); } -const char* // O - Attribute value as string -cfIPPAttrEnumValForPrinter(ipp_t *printer_attrs, // I - Printer attributes, same - // as to respond - // get-printer-attributes, - // or NULL to not consider +// +// 'cfIPPAttrEnumValForPrinter()' - Get the value of an enumerated attribute for a job, using the printer's +// attributes to validate the value and to provide a default if needed. +// + +const char* // O - Attribute value as string +cfIPPAttrEnumValForPrinter(ipp_t *printer_attrs, // I - Printer attributes, same as to respond get-printer-attributes, or NULL to not consider ipp_t *job_attrs, // I - Job attributes - const char *attr_name)// I - Attribute name + const char *attr_name) // I - Attribute name { ipp_attribute_t *attr; char printer_attr_name[256]; @@ -549,16 +578,16 @@ cfIPPAttrEnumValForPrinter(ipp_t *printer_attrs, // I - Printer attributes, same return (res); } +// +// 'cfIPPAttrIntValForPrinter()' - Get the value of an integer attribute for a job, using the printer's +// attributes to validate the value and to provide a default if needed. +// -int // O - 1: Success; 0: Error -cfIPPAttrIntValForPrinter(ipp_t *printer_attrs, // I - Printer attributes, same - // as to respond - // get-printer-attributes, - // or NULL to not consider +int // O - 1: Success; 0: Error +cfIPPAttrIntValForPrinter(ipp_t *printer_attrs, // I - Printer attributes, same as to respond get-printer-attributes, or NULL to not consider ipp_t *job_attrs, // I - Job attributes const char *attr_name,// I - Attribute name - int *value) // O - Attribute value as - // integer + int *value) // O - Attribute value as integer { ipp_attribute_t *attr; char printer_attr_name[256]; @@ -617,11 +646,15 @@ cfIPPAttrIntValForPrinter(ipp_t *printer_attrs, // I - Printer attributes, same return (retval); } +// +// 'cfIPPAttrResolutionForPrinter()' - Get the value of a resolution attribute for a job, using the printer's +// attributes to validate the value and to provide a default if needed. +// int // O - 1: Success; 0: Error -cfIPPAttrResolutionForPrinter(ipp_t *printer_attrs,// I - Printer attributes +cfIPPAttrResolutionForPrinter(ipp_t *printer_attrs, // I - Printer attributes ipp_t *job_attrs, // I - Job attributes - const char *attr_name,// I - Attribute name + const char *attr_name, // I - Attribute name int *xres, // O - X resolution (dpi) int *yres) // O - Y resolution (dpi) { @@ -716,10 +749,14 @@ cfIPPAttrResolutionForPrinter(ipp_t *printer_attrs,// I - Printer attributes return (retval); } +// +// 'cfIPPReverseOutput()' - Get the output order for a job, using the printer's +// attributes to validate the value and to provide a default if needed. +// -int -cfIPPReverseOutput(ipp_t *printer_attrs, - ipp_t *job_attrs) +int // O - 0: Original order; 1: Reverse order +cfIPPReverseOutput(ipp_t *printer_attrs, // I - Printer attributes + ipp_t *job_attrs) // I - Job attributes { int i; ipp_attribute_t *attr1, *attr2; @@ -776,64 +813,35 @@ cfIPPReverseOutput(ipp_t *printer_attrs, return (0); } - // -// 'cfGetBackSideOrientation()' - This functions returns the back -// side orientation using printer -// attributes. Meaning and reason for -// backside orientation: It only makes -// sense if printer supports duplex, -// so, if printer reports that it -// supports duplex printing via -// sides-supported IPP attribute, then -// it also reports back-side -// orientation for each PDL in PDL -// specific IPP attributes. Backside -// orientation is specially needed for -// raster PDLs as raster PDLs are -// specially made for raster printers -// which do not have sufficient memory -// to hold a full page bitmap(raster -// page). So they cannot build the -// whole page in memory before -// starting to print it. For one-sided -// printing it is easy to manage. The -// printer's mechanism pulls the page -// in on its upper edge and starts to -// print, from top to bottom, after -// that it ejects the page. For -// double-sided printing it does the -// same for the front side, but for -// the back side the mechanics of the -// printer has to turn over the sheet, -// and now, depending on how the sheet -// is turned over it happens that the -// edge arriving in the printing -// mechanism is the lower edge of the -// back side. And if the printer -// simply prints then, the back side -// is the wrong way around. The -// printer reports its need via back -// side orientation in such a case, so -// that the client knows to send the -// back side upside down for example. -// In vector PDLs, PDF and PostScript, -// always the full page's raster image -// is completely generated in the -// printer before the page is started, -// and therefore the printer can start -// to take the pixels from the lower -// edge of the raster image if needed, -// so back side orientation is always -// "normal" for these PDLs. And if a -// printer does not support duplex, -// back side orientation is not -// needed. -// - -int // O - Backside orientation (bit 0-2) - // Requires flipped margin? - // Yes: bit 4 set; No: bit 3 set +// 'cfGetBackSideOrientation()' - This functions returns the back side orientation using printer +// attributes. Meaning and reason for backside orientation: It only makes +// sense if printer supports duplex, so, if printer reports that it +// supports duplex printing via sides-supported IPP attribute, then +// it also reports back-side orientation for each PDL in PDL +// specific IPP attributes. Backside orientation is specially needed for +// raster PDLs as raster PDLs are specially made for raster printers +// which do not have sufficient memory to hold a full page bitmap(raster +// page). So they cannot build the whole page in memory before +// starting to print it. For one-sided printing it is easy to manage. The +// printer's mechanism pulls the page in on its upper edge and starts to +// print, from top to bottom, after that it ejects the page. For +// double-sided printing it does the same for the front side, but for +// the back side the mechanics of the printer has to turn over the sheet, +// and now, depending on how the sheet is turned over it happens that the +// edge arriving in the printing mechanism is the lower edge of the +// back side. And if the printer simply prints then, the back side +// is the wrong way around. The printer reports its need via back +// side orientation in such a case, so that the client knows to send the +// back side upside down for example. In vector PDLs, PDF and PostScript, +// always the full page's raster image is completely generated in the +// printer before the page is started, and therefore the printer can start +// to take the pixels from the lower edge of the raster image if needed, +// so back side orientation is always "normal" for these PDLs. And if a +// printer does not support duplex, back side orientation is not needed. +// + +int // O - Backside orientation (bit 0-2) Requires flipped margin? Yes: bit 4 set; No: bit 3 set cfGetBackSideOrientation(cf_filter_data_t *data) // I - Filter data { ipp_t *printer_attrs = data->printer_attrs; @@ -930,11 +938,14 @@ cfGetBackSideOrientation(cf_filter_data_t *data) // I - Filter data return (backside); } +// +// 'cfGetPrintRenderIntent()' - Get the print rendering intent from job attributes and printer attributes. +// -const char * -cfGetPrintRenderIntent(cf_filter_data_t *data, - char *ri, - int ri_len) +const char * // O - Rendering intent string, or NULL +cfGetPrintRenderIntent(cf_filter_data_t *data, // I - Filter data + char *ri, // O - Rendering intent buffer + int ri_len) // I - Buffer size { const char *val; int num_options = 0; @@ -1023,12 +1034,9 @@ cfGetPrintRenderIntent(cf_filter_data_t *data, // option list, together with the options // -int // O - New number of options - // in new option list +int // O - New number of options in new option list cfJoinJobOptionsAndAttrs(cf_filter_data_t* data, // I - Filter data - int num_options, // I - Current mumber of - // options in new option - // list + int num_options, // I - Current mumber of options in new option list cups_option_t **options) // IO - New option lsit { ipp_t *job_attrs = data->job_attrs; // Job attributes @@ -1166,11 +1174,14 @@ cfStrFormatd(char *buf, // I - String return (bufptr); } +// +// 'cfStrFormatf()' - Format a floating-point number with a given number of decimal places. +// -int -cfCompareResolutions(void *resolution_a, - void *resolution_b, - void *user_data) +int // O - Number of characters written +cfCompareResolutions(void *resolution_a, // I - First resolution + void *resolution_b, // I - Second resolution + void *user_data) // I - User data (not used) { cf_res_t *res_a = (cf_res_t *)resolution_a; cf_res_t *res_b = (cf_res_t *)resolution_b; @@ -1191,9 +1202,13 @@ cfCompareResolutions(void *resolution_a, return ((a > b) - (a < b)); } -void * -cfCopyResolution(void *resolution, - void *user_data) +// +// 'cfCopyResolution()' - Copy a resolution structure. +// + +void * // O - Copy of resolution +cfCopyResolution(void *resolution, // I - Resolution to copy + void *user_data) // I - User data (not used) { cf_res_t *res = (cf_res_t *)resolution; cf_res_t *copy; @@ -1208,25 +1223,37 @@ cfCopyResolution(void *resolution, return copy; } +// +// 'cfFreeResolution()' - Free a resolution structure. +// + void -cfFreeResolution(void *resolution, - void *user_data) +cfFreeResolution(void *resolution, // I - Resolution to free + void *user_data) // I - User data (not used) { cf_res_t *res = (cf_res_t *)resolution; if (res) free(res); } -cups_array_t * +// +// 'cfNewResolutionArray()' - Create a new array of resolutions. +// + +cups_array_t * // O - New array of resolutions cfNewResolutionArray() { return (cupsArrayNew(cfCompareResolutions, NULL, NULL, 0, cfCopyResolution, cfFreeResolution)); } -cf_res_t * -cfNewResolution(int x, - int y) +// +// 'cfNewResolution()' - Create a new resolution structure. +// + +cf_res_t * // O - New resolution structure +cfNewResolution(int x, // I - X resolution (dpi) + int y) // I - Y resolution (dpi) { cf_res_t *res = (cf_res_t *)calloc(1, sizeof(cf_res_t)); if (res) @@ -1237,13 +1264,16 @@ cfNewResolution(int x, return (res); } -// Read a single resolution from an IPP attribute, take care of -// obviously wrong entries (printer firmware bugs), ignoring -// resolutions of less than 60 dpi in at least one dimension and -// fixing Brother's "600x2dpi" resolutions. -cf_res_t * -cfIPPResToResolution(ipp_attribute_t *attr, - int index) +// +// 'cfIPPResToResolution()' - Read a single resolution from an IPP attribute, take care of +// obviously wrong entries (printer firmware bugs), ignoring +// resolutions of less than 60 dpi in at least one dimension and +// fixing Brother's "600x2dpi" resolutions. +// + +cf_res_t * // O - Resolution structure or NULL on error +cfIPPResToResolution(ipp_attribute_t *attr, // I - IPP attribute + int index) // I - Index of resolution to read { cf_res_t *res = NULL; int x = 0, y = 0; @@ -1271,8 +1301,12 @@ cfIPPResToResolution(ipp_attribute_t *attr, return (res); } -cups_array_t * -cfIPPAttrToResolutionArray(ipp_attribute_t *attr) +// +// 'cfIPPAttrToResolutionArray()' - Convert an IPP attribute to an array of resolutions. +// + +cups_array_t * // O - Array of resolutions +cfIPPAttrToResolutionArray(ipp_attribute_t *attr) // I - IPP attribute { cups_array_t *res_array = NULL; cf_res_t *res; @@ -1307,27 +1341,27 @@ cfIPPAttrToResolutionArray(ipp_attribute_t *attr) return (res_array); } -// Build up an array of common resolutions and most desirable default -// resolution from multiple arrays of resolutions with an optional -// default resolution. -// Call this function with each resolution array you find as "new", and -// in "current" an array of the common resolutions will be built up. -// You do not need to create an empty array for "current" before -// starting. Initialize it with NULL. -// "current_default" holds the default resolution of the array "current". -// It will get replaced by "new_default" if "current_default" is either -// NULL or a resolution which is not in "current" any more. -// "new" and "new_default" will be deleted/freed and set to NULL after -// each, successful or unsuccssful operation. -// Note that when calling this function the addresses of the pointers -// to the resolution arrays and default resolutions have to be given -// (call by reference) as all will get modified by the function. - -int // 1 on success, 0 on failure -cfJoinResolutionArrays(cups_array_t **current, - cups_array_t **new_arr, - cf_res_t **current_default, - cf_res_t **new_default) +// +// 'cfJoinResolutionArrays()' - Build up an array of common resolutions and most desirable default +// resolution from multiple arrays of resolutions with an optional +// default resolution. Call this function with each resolution array +// you find as "new", and in "current" an array of the common resolutions +// will be built up. You do not need to create an empty array for "current" +// before starting. Initialize it with NULL. "current_default" holds the +// default resolution of the array "current". It will get replaced by +// "new_default" if "current_default" is either +// NULL or a resolution which is not in "current" any more. +// "new" and "new_default" will be deleted/freed and set to NULL after +// each, successful or unsuccssful operation. +// Note that when calling this function the addresses of the pointers +// to the resolution arrays and default resolutions have to be given +// (call by reference) as all will get modified by the function. + +int // O - 1 on success, 0 on failure +cfJoinResolutionArrays(cups_array_t **current, // IO - Current array of common resolutions + cups_array_t **new_arr, // I - New array of resolutions to join with current + cf_res_t **current_default, // IO - Current default resolution of current array + cf_res_t **new_default) // I - New default resolution of new array { cf_res_t *res; int retval; @@ -1438,12 +1472,12 @@ pwg_copy_size(cf_size_t *size) // I - Media size to copy return (newsize); } +// +// 'cfGetPageDimensions()' - Get page dimensions from job attributes and options. +// -int // O - 1: Requested page size supported - // 2: Requested page size supported - // when rotated by 90 degrees - // 0: No page size requested - // -1: Requested size unsupported +int // O - 1: Requested page size supported; 2: Requested page size supported when rotated by 90 degrees; 0: No page size requested; -1: Requested size unsupported + cfGetPageDimensions(ipp_t *printer_attrs, // I - Printer attributes ipp_t *job_attrs, // I - Job attributes int num_options, // I - Number of options @@ -1457,8 +1491,7 @@ cfGetPageDimensions(ipp_t *printer_attrs, // I - Printer attributes float *right, // O - Right margin float *top, // O - Top margin char *name, // O - Page size name - ipp_t **media_col_entry)// O - media-col-database record of - // match + ipp_t **media_col_entry)// O - media-col-database record of match { int i; const char *attr_name; @@ -1768,6 +1801,9 @@ cfGetPageDimensions(ipp_t *printer_attrs, // I - Printer attributes return (size_requested ? -1 : 0); } +// +// 'cfSetPageDimensionsToDefault()' - Set page dimensions to default values if they are invalid. +// void cfSetPageDimensionsToDefault(float *width, // IO - Width (in pt, 1/72 inches) @@ -1856,28 +1892,31 @@ dimensions_for_name(char *size_name, return (search); } +// +// 'cfGenerateSizes()' - Generate a list of sizes from the printer attributes. +// void -cfGenerateSizes(ipp_t *response, - cf_gen_sizes_mode_t mode, - cups_array_t **sizes, - ipp_attribute_t **defattr, - int *width, - int *length, - int *left, - int *bottom, - int *right, - int *top, - int *min_width, - int *min_length, - int *max_width, - int *max_length, - int *custom_left, - int *custom_bottom, - int *custom_right, - int *custom_top, - char *size_name, - ipp_t **media_col_entry) +cfGenerateSizes(ipp_t *response, // I - Printer attributes + cf_gen_sizes_mode_t mode, // I - Mode of operation + cups_array_t **sizes, // IO - Array of sizes + ipp_attribute_t **defattr, // IO - Default media attribute + int *width, // IO - Width (in 1/2540 inches) + int *length, // IO - Length + int *left, // IO - Left margin + int *bottom, // IO - Bottom margin + int *right, // IO - Right margin + int *top, // IO - Top margin + int *min_width, // IO - Minimum width (in 1/2540 inches) + int *min_length, // IO - Minimum length + int *max_width, // IO - Maximum width (in 1/2540 inches) + int *max_length, // IO - Maximum length + int *custom_left, // IO - Minimum left margin (in 1/2540 inches) + int *custom_bottom, // IO - Minimum bottom margin + int *custom_right, // IO - Minimum right margin + int *custom_top, // IO - Minimum top margin + char *size_name, // IO - Page size name + ipp_t **media_col_entry) // IO - media-col-database record of match { ipp_attribute_t *default_attr, *attr, // xxx-supported diff --git a/cupsfilters/ipp.h b/cupsfilters/ipp.h index 25e585690..4ba8d9832 100644 --- a/cupsfilters/ipp.h +++ b/cupsfilters/ipp.h @@ -47,7 +47,7 @@ extern "C" { #define CF_GET_PRINTER_ATTRIBUTES_MAX_OUTPUT_LEN 8192 #define CF_GET_PRINTER_ATTRIBUTES_MAX_URI_LEN 2048 -extern char cf_get_printer_attributes_log[CF_GET_PRINTER_ATTRIBUTES_LOGSIZE]; +extern char cf_get_printer_attributes_log[CF_GET_PRINTER_ATTRIBUTES_LOGSIZE]; // Log for cfGetPrinterAttributes() and related functions // @@ -66,27 +66,27 @@ enum cf_driverless_support_modes_e }; // Backside orientations for duplex printing -typedef enum cf_backside_orient_e +typedef enum cf_backside_orient_e // Backside orientation for duplex printing { - CF_BACKSIDE_MANUAL_TUMBLE, - CF_BACKSIDE_ROTATED, - CF_BACKSIDE_FLIPPED, - CF_BACKSIDE_NORMAL + CF_BACKSIDE_MANUAL_TUMBLE, // Backside orientation for manual duplex printing + CF_BACKSIDE_ROTATED, // Backside orientation for rotated duplex printing + CF_BACKSIDE_FLIPPED, // Backside orientation for flipped duplex printing + CF_BACKSIDE_NORMAL // Backside orientation for normal duplex printing } cf_backside_orient_t; // Data structure for resolution (X x Y dpi) -typedef struct cf_res_s +typedef struct cf_res_s // **** Resolution (X x Y dpi) **** { - int x, y; + int x, y; // X and Y resolution in dpi } cf_res_t; -typedef enum cf_gen_sizes_mode_e +typedef enum cf_gen_sizes_mode_e // Mode for generating sizes { - CF_GEN_SIZES_DEFAULT = 0, - CF_GEN_SIZES_SEARCH, - CF_GEN_SIZES_SEARCH_BORDERLESS_ONLY -} cf_gen_sizes_mode_t; + CF_GEN_SIZES_DEFAULT = 0, // Default mode, generate all sizes + CF_GEN_SIZES_SEARCH, // Search for a specific size, return only that size + CF_GEN_SIZES_SEARCH_BORDERLESS_ONLY // Search for a specific size, return only that size if it is borderless +} cf_gen_sizes_mode_t; // diff --git a/cupsfilters/libcups2.c b/cupsfilters/libcups2.c index c60d5aae4..2db0e00ed 100644 --- a/cupsfilters/libcups2.c +++ b/cupsfilters/libcups2.c @@ -34,10 +34,13 @@ convert_to_port(char *a) return (port); } +// +// 'cfResolveURI2()' - Resolve a URI, for example a DNS-SD-service-name-based URI to a host-name-based URI. +// -char * -cfResolveURI2(const char *uri, - int is_fax) +char * // O - Resolved URI +cfResolveURI2(const char *uri, // I - Raw URI + int is_fax) // I - 1: Fax printer; 0: Not a fax printer { int ippfind_pid = 0, // Process ID of ippfind for IPP post_proc_pipe[2], // Pipe to post-processing for IPP diff --git a/cupsfilters/mupdftopwg.c b/cupsfilters/mupdftopwg.c index 9c8484fe7..49a6cc0dd 100644 --- a/cupsfilters/mupdftopwg.c +++ b/cupsfilters/mupdftopwg.c @@ -34,7 +34,7 @@ #define CUPS_IPTEMPFILE "/tmp/ip-XXXXXX" #define CUPS_OPTEMPFILE "/tmp/op-XXXXXX" -typedef cups_page_header_t mupdf_page_header; +typedef cups_page_header_t mupdf_page_header; // Use the same page header structure as in libcupsfilters/raster.h static int @@ -419,15 +419,16 @@ mutool_spawn(const char *filename, return (status); } +// +// 'cfFilterMuPDFToPWG()' - Filter function for converting PDF to PWG Raster using mutool. +// -int +int // O - Exit status of filter function: 0 on success, 1 on error cfFilterMuPDFToPWG(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream - int inputseekable, // I - Is input stream seekable? - // (unused) + int inputseekable, // I - Is input stream seekable? (unused) cf_filter_data_t *data, // I - Job and printer data - void *parameters) // I - Filter-specific parameters - // (unused) + void *parameters) // I - Filter-specific parameters (unused) { cf_filter_out_format_t outformat; char *val; diff --git a/cupsfilters/pack.c b/cupsfilters/pack.c index 1278da13f..3d8389a22 100644 --- a/cupsfilters/pack.c +++ b/cupsfilters/pack.c @@ -170,8 +170,7 @@ void cfPackHorizontalBit(const unsigned char *ipixels, // I - Input pixels unsigned char *obytes, // O - Output bytes int width, // I - Number of pixels - const unsigned char clearto, // I - Initial value of - // bytes + const unsigned char clearto, // I - Initial value of bytes const unsigned char bit) // I - Bit to check { register unsigned char b; // Current byte @@ -251,8 +250,7 @@ cfPackVertical(const unsigned char *ipixels, // I - Input pixels unsigned char *obytes, // O - Output bytes int width, // I - Number of input pixels const unsigned char bit, // I - Output bit - const int step) // I - Number of bytes between - // columns + const int step) // I - Number of bytes between columns { // // Loop through the entire array... diff --git a/cupsfilters/pdf.c b/cupsfilters/pdf.c index 4399b65d4..252f85b80 100644 --- a/cupsfilters/pdf.c +++ b/cupsfilters/pdf.c @@ -73,22 +73,24 @@ cfPDFLoadTemplate(const char *filename) // I - Filename of the PDF file // 'cf_pdf_write()' - helper which writes the PDF file to a FILE* // -ssize_t -cf_pdf_write_cb(void *context, const void *buffer, size_t bytes) +ssize_t // O - Number of bytes written +cf_pdf_write_cb(void *context, // I - Output FILE context + const void *buffer, // I - Data buffer + size_t bytes) // I - Number of bytes to write { return (ssize_t)fwrite(buffer, 1, bytes, (FILE *)context); } // // 'cfCopyPDFdoc()' - Copy the PDF file to another using PDFio, as PDFio doesn't -// explicitly support file modification. -// Thus we will copy contents into new streams and modify there. +// explicitly support file modification. +// Thus we will copy contents into new streams and modify there. // -cf_pdf_t* -cfCopyPDFdoc(cf_pdf_t *input_doc, - FILE *output_file, - iterate_data_t *iterate_helper) +cf_pdf_t* // O - Pointer to cf_pdf_t struct +cfCopyPDFdoc(cf_pdf_t *input_doc, // I - Pointer to input PDF file + FILE *output_file, // I - Pointer to output PDF file + iterate_data_t *iterate_helper) // I - PDF iteration helper data { cf_pdf_t *pdf = (cf_pdf_t*)pdfioFileCreateOutput(cf_pdf_write_cb, output_file, pdfioFileGetVersion((pdfio_file_t *)input_doc), NULL, NULL, NULL, NULL); @@ -258,13 +260,13 @@ cfPDFPrependStream(cf_pdf_t *pdf, // I - Pointer to PDF file // // 'cfPDFPrependStream1()' - Replacement API for the original above. -// Prepend a stream to the contents of a specified +// Prepend a stream to the contents of a specified // page in PDF file. // int // O - 0 on success, 1 on error cfPDFPrependStream1(cf_pdf_t *pdf, // I - Pointer to PDF file - iterate_data_t *iterate_helper, + iterate_data_t *iterate_helper, // I - PDF iteration helper data unsigned page_num, // I - page number to prepend to const char *buf, // I - Buffer containing stream data size_t len) // I - Length of Buffer @@ -356,13 +358,13 @@ cfPDFAddType1Font(cf_pdf_t *pdf, // I - Pointer to PDF object // // 'cfPDFAddType1Font1()' - Replacement to the API just above -// Add the specified type1 font face to the specified -// page in a PDF document. +// Add the specified type1 font face to the specified +// page in a PDF document. // int // O - 0 on success , 1 on error cfPDFAddType1Font1(cf_pdf_t *pdf, // I - Pointer to PDF object - iterate_data_t *iterate_helper, + iterate_data_t *iterate_helper, // I/O - PDF iteration helper data unsigned page_num, // I - Page number to add font to const char *name) // I - Name of the font { @@ -596,8 +598,8 @@ cfPDFDuplicatePage(cf_pdf_t *pdf, // I - pointer to PDF file // void -cfPDFWrite(cf_pdf_t *pdf, - FILE *file) +cfPDFWrite(cf_pdf_t *pdf, // I - Pointer to PDF object + FILE *file) // I - Output FILE { // PDFio doesn't work this way. } @@ -606,8 +608,9 @@ cfPDFWrite(cf_pdf_t *pdf, // 'cfPDFFillForm()' - Fill recognized fields with information // -int -cfPDFFillForm(cf_pdf_t *doc, cf_opt_t *opt) +int // O - 0 on sucess, 1 on failure +cfPDFFillForm(cf_pdf_t *doc, // I - PDF document + cf_opt_t *opt) // I - PDF form options { // TODO: PDFio does not directly support form filling. return 1; diff --git a/cupsfilters/pdf.h b/cupsfilters/pdf.h index 5f7afe06e..f40410117 100644 --- a/cupsfilters/pdf.h +++ b/cupsfilters/pdf.h @@ -36,11 +36,11 @@ struct _cf_opt cf_opt_t *next; }; -typedef struct iterate_data_s +typedef struct iterate_data_s // *** Helper structure for PDF page iteration *** { - cf_pdf_t *pdf; - pdfio_dict_t *page_dict; - pdfio_dict_t *page_resdict; + cf_pdf_t *pdf; // PDF document + pdfio_dict_t *page_dict; // Current page dictionary + pdfio_dict_t *page_resdict; // Current page resources dictionary }iterate_data_t; cf_pdf_t* cfPDFLoadTemplate(const char *filename); diff --git a/cupsfilters/pdftopdf-private.h b/cupsfilters/pdftopdf-private.h index 2f42e4e79..70d58240e 100644 --- a/cupsfilters/pdftopdf-private.h +++ b/cupsfilters/pdftopdf-private.h @@ -44,47 +44,43 @@ typedef struct { pdfio_obj_t *obj; // Track object pointers for cycle detection } VisitedObj; -typedef struct xform_document_s // Document information -{ - const char *filename, // Document filename +typedef struct xform_document_s // *** Document information *** +{ + const char *filename, // Document filename *format; // Document format - char tempfile[1024]; // Temporary PDF file, if any + char tempfile[1024]; // Temporary PDF file, if any const char *pdf_filename; // PDF filename pdfio_file_t *pdf; // PDF file for document int first_page, // First page number in document last_page, // Last page number in document - num_pages; // Number of pages to print in document + num_pages; // Number of pages to print in document } xform_document_t; -typedef struct xform_page_s // Output page +typedef struct xform_page_s // *** Output page *** { pdfio_file_t *pdf; // Output PDF file size_t layout; // Current layout cell - pdfio_obj_t *input[XFORM_MAX_LAYOUT]; - // Input page objects + pdfio_obj_t *input[XFORM_MAX_LAYOUT]; // Input page objects pdfio_dict_t *pagedict; // Page dictionary pdfio_dict_t *resdict; // Resource dictionary - pdfio_dict_t *resmap[XFORM_MAX_LAYOUT]; - // Resource name map + pdfio_dict_t *resmap[XFORM_MAX_LAYOUT]; // Resource name map pdfio_dict_t *restype; // Current resource type dictionary pdfio_stream_t *output; // Output page stream } xform_page_t; -typedef struct xform_page_ext_s // Output page +typedef struct xform_page_ext_s // *** Output page *** { pdfio_file_t *pdf; // Output PDF file - pdfio_obj_t **input; - // Input page objects + pdfio_obj_t **input; // Input page objects pdfio_dict_t *pagedict; // Page dictionary pdfio_dict_t *resdict; // Resource dictionary - pdfio_dict_t *resmap[XFORM_MAX_LAYOUT]; - // Resource name map + pdfio_dict_t *resmap[XFORM_MAX_LAYOUT]; // Resource name map pdfio_dict_t *restype; // Current resource type dictionary pdfio_stream_t *output; // Output page stream } xform_page_ext_t; -typedef struct xform_prepare_s // Preparation data +typedef struct xform_prepare_s // *** Preparation data *** { cf_filter_options_t *options; // Print options cups_array_t *errors; // Error messages @@ -95,11 +91,9 @@ typedef struct xform_prepare_s // Preparation data pdfio_rect_t media; // Default media box pdfio_rect_t crop; // Default crop box size_t num_outpages; // Number of output pages - xform_page_t outpages[XFORM_MAX_PAGES]; - // Output pages + xform_page_t outpages[XFORM_MAX_PAGES]; // Output pages size_t num_layout; // Number of layout rectangles - pdfio_rect_t layout[XFORM_MAX_LAYOUT]; - // Layout rectangles + pdfio_rect_t layout[XFORM_MAX_LAYOUT]; // Layout rectangles bool use_duplex_xform; // Use the back side transform matrix? pdfio_matrix_t duplex_xform; // Back side transform matrix bool has_form; // does PDF have Acroform(is flattening required?) diff --git a/cupsfilters/pdftopdf.c b/cupsfilters/pdftopdf.c index f5397f479..e7f859498 100644 --- a/cupsfilters/pdftopdf.c +++ b/cupsfilters/pdftopdf.c @@ -860,9 +860,13 @@ prepare_pages( } } +// +// 'getArrayAsMatrix()' - Convert a PDF array into a transformation matrix. +// + void -getArrayAsMatrix(pdfio_array_t *array, - pdfio_matrix_t cm) +getArrayAsMatrix(pdfio_array_t *array, // I - PDF array containing 6 matrix values + pdfio_matrix_t cm) // O - Transformation matrix { size_t array_size = pdfioArrayGetSize(array); if(array_size != 6) @@ -882,8 +886,12 @@ getArrayAsMatrix(pdfio_array_t *array, return; } -double -get_flags(pdfio_dict_t *annots_dict) +// +// 'get_flags()' - Get the annotation flags from a PDF annotation dictionary. +// + +double // O - Annotation flags +get_flags(pdfio_dict_t *annots_dict) // I - PDF annotation dictionary { double val = pdfioDictGetNumber(annots_dict, "F"); return val; @@ -1027,9 +1035,13 @@ transform_point(const pdfio_matrix_t matrix, *yp = matrix[0][1] * x + matrix[1][1] * y + matrix[2][1]; } -pdfio_rect_t -transform_rectangle(const pdfio_matrix_t matrix, - pdfio_rect_t r) +// +// 'transform_rectangle()' - Transform a rectangle using a transformation matrix. +// + +pdfio_rect_t // O - Transformed rectangle +transform_rectangle(const pdfio_matrix_t matrix, // I - Transformation matrix + pdfio_rect_t r) // I - Rectangle to transform { double min_x = DBL_MAX, min_y = DBL_MAX; double max_x = -DBL_MAX, max_y = -DBL_MAX; @@ -1061,8 +1073,12 @@ transform_rectangle(const pdfio_matrix_t matrix, return transformed; } -char* -unparse_matrix(pdfio_matrix_t matrix) +// +// 'unparse_matrix()' - Convert a transformation matrix into a PDF matrix string. +// + +char* // O - Matrix string, or NULL on error +unparse_matrix(pdfio_matrix_t matrix) // I - Transformation matrix { double comps[6] = {matrix[0][0], matrix[0][1], matrix[1][0], matrix[1][1], matrix[2][0], matrix[2][1]}; @@ -1111,8 +1127,13 @@ unparse_matrix(pdfio_matrix_t matrix) return result; } -pdfio_obj_t* -getAppearance(pdfio_dict_t *Annot_dict, char* value) +// +// 'getAppearance()' - Get the appearance object for a PDF annotation. +// + +pdfio_obj_t* // O - Appearance object, or NULL if not found +getAppearance(pdfio_dict_t *Annot_dict, // I - Annotation dictinonary + char* value) // I - Appearance key { pdfio_dict_t *AP_dict = pdfioDictGetDict(Annot_dict, "AP"); pdfio_obj_t* appearance_obj = pdfioDictGetObj(AP_dict, value); @@ -1193,12 +1214,16 @@ get_pdf_matrix(pdfio_dict_t *d, return 1; } -char* -special_pdfio_annotation_get_content(pdfio_obj_t *annot, - const char *name, - int page_rotate, - int forbidden_flags, - int required_flags) +// +// 'pdfio_annotation_get_content()' - Get the content stream for a PDF annotation. +// + +char* // O - Content stream string, or NULL on error +special_pdfio_annotation_get_content(pdfio_obj_t *annot, // I - PDF annotation object + const char *name, // I - XObject name + int page_rotate, // I - Page rotation angle + int forbidden_flags, // I - Annoation flag that must not be set + int required_flags) // I - Annoation flag that must be set { if (!annot || !name) { @@ -1280,12 +1305,16 @@ special_pdfio_annotation_get_content(pdfio_obj_t *annot, return out; } -char* -pdfio_annotation_get_content(pdfio_obj_t *annot, - const char *name, - int page_rotate, - int forbidden_flags, - int required_flags) +// +// 'pdfio_annotation_get_content()' - Get the content stream for a PDF annotation. +// + +char* // O - Content stream string, or NULL on error +pdfio_annotation_get_content(pdfio_obj_t *annot, // I - PDF annotation object + const char *name, // I - XObject name + int page_rotate, // I - Page rotation angle + int forbidden_flags, // I - Annotation flags that must not be set + int required_flags) // I - Annotation flags that must be set { if (!annot || !name) { @@ -1423,17 +1452,26 @@ pdfio_annotation_get_content(pdfio_obj_t *annot, return out; } +// +// 'merge_resources()' - Merge resources from the PDF dictionary into another. +// + void -merge_resources(pdfio_dict_t *dest, - pdfio_dict_t *source) +merge_resources(pdfio_dict_t *dest, // I - Destination resource dictionary + pdfio_dict_t *source) // I - Source resource dictionary { pdfioDictIterateKeys(source, (pdfio_dict_cb_t)merge_resources_cb, dest); } -bool -extractFontDetails(const char *da, - char *font_key, size_t keylen, - double *font_size) +// +// 'extractFontDetails()' - Extract the font key and size from a font description string. +// + +bool // O - Returns true on success, false on failure. +extractFontDetails(const char *da, // I - input string + char *font_key, // O - parsed font name output + size_t keylen, // I - buffer size + double *font_size) // O - parsed size output { if (!da || !font_key || keylen == 0 || !font_size) return false; @@ -2725,10 +2763,14 @@ prepare_documents( return (ret); } -// coping inputfp data to temp_fp, so that we have a filename, as it is required in pdfioFileOpen API -int -copy_fd_to_tempfile(int inputfd, - FILE *temp_file) +// +// 'copy_fd_to_tempfile()' - Coping inputfp data to temp_fp, so that we have a filename, +// as it is required in pdfioFileOpen API. +// + +int // O - 0 on success, -1 on failure +copy_fd_to_tempfile(int inputfd, // I - Input file descriptor + FILE *temp_file) // I - Temporary output file { char buffer[BUFSIZ]; ssize_t bytes_read, bytes_written; @@ -2752,12 +2794,17 @@ copy_fd_to_tempfile(int inputfd, return 0; } -int -cfFilterPDFToPDF(int inputfd, - int outputfd, - int inputseekable, - cf_filter_data_t *data, - void *parameters) +// +// 'cfFilterPDFToPDF()' - Filter a PDF file and write the processed +// PDF to the output. +// + +int // O - Returns 0 on success, 1 on failure +cfFilterPDFToPDF(int inputfd, // I - Input file descriptor + int outputfd, // I - Output file descriptor + int inputseekable, // I - Whether input is seekable + cf_filter_data_t *data, // I - Filter data + void *parameters) // I - Filter parameters { cf_logfunc_t log = data->logfunc; void *ld = data->logdata; diff --git a/cupsfilters/pdftoraster.c b/cupsfilters/pdftoraster.c index dd2359f13..5d4c9432c 100644 --- a/cupsfilters/pdftoraster.c +++ b/cupsfilters/pdftoraster.c @@ -75,16 +75,16 @@ #define MAX_BYTES_PER_PIXEL 32 extern int errno; -typedef struct cms_profile_s +typedef struct cms_profile_s // *** Color Management System profile structure *** { // for color profiles - cmsHPROFILE colorProfile; - cmsHPROFILE popplerColorProfile; - cmsHTRANSFORM colorTransform; - cmsCIEXYZ D65WhitePoint; - int renderingIntent; - int cm_disabled; - cf_cm_calibration_t cm_calibrate; + cmsHPROFILE colorProfile; // color profile + cmsHPROFILE popplerColorProfile; // color profile used by poppler + cmsHTRANSFORM colorTransform; // color transform + cmsCIEXYZ D65WhitePoint; // D65 white point + int renderingIntent; // rendering intent + int cm_disabled; // whether color management is disabled + cf_cm_calibration_t cm_calibrate; // whether color calibration is enabled } cms_profile_t; // @@ -101,34 +101,32 @@ init_cms_profile_t(cms_profile_t *profile) // I - profile structure to init profile->cm_disabled = 0; } -typedef struct pdftoraster_doc_s +typedef struct pdftoraster_doc_s // *** PDF to Raster Document Structure *** { - char *input_filename; - int pwgraster; - int bi_level; - bool allocLineBuf; - unsigned int bitspercolor; - unsigned int popplerNumColors; - unsigned int bitmapoffset[2]; - pdfio_file_t *pdf_doc; - cups_page_header_t header; - cf_logfunc_t logfunc; // Logging function, NULL for no - // logging - void *logdata; // User data for logging function, can - // be NULL + char *input_filename; // Input PDF file name + int pwgraster; // Whether to output PWG Raster (1) or CUPS Raster (0) + int bi_level; // Whether to output bi-level (1) or not (0) + bool allocLineBuf; // Whether to allocate a line buffer for the conversion function + unsigned int bitspercolor; // Bits per color + unsigned int popplerNumColors; // Number of colors in the poppler output + unsigned int bitmapoffset[2]; // Bitmap offset for the poppler output + pdfio_file_t *pdf_doc; // PDF document structure + cups_page_header_t header; // CUPS page header structure + cf_logfunc_t logfunc; // Logging function, NULL for no logging + void *logdata; // User data for logging function, can be NULL cups_file_t *inputfp; // Temporary file, if any FILE *outputfp; // Temporary file, if any - bool swap_image_x; - bool swap_image_y; + bool swap_image_x; // Whether to swap the image in the x direction + bool swap_image_y; // Whether to swap the image in the y direction // margin swapping - bool swap_margin_x; - bool swap_margin_y; - unsigned int nplanes; - unsigned int nbands; + bool swap_margin_x; // Whether to swap the margin in the x direction + bool swap_margin_y; // Whether to swap the margin in the y direction + unsigned int nplanes; // number of planes + unsigned int nbands; // number of bands unsigned int bytesPerLine; // number of bytes per line // Note: When CUPS_ORDER_BANDED, // cupsBytesPerLine = bytesPerLine * cupsNumColors - cms_profile_t *colour_profile; + cms_profile_t *colour_profile; // Color Management System profile structure } pdftoraster_doc_t; typedef unsigned char *(*convert_cspace_func)(unsigned char *src, @@ -146,12 +144,11 @@ typedef unsigned char *(*convert_line_func)(unsigned char *src, pdftoraster_doc_t* doc, convert_cspace_func convertCSpace); -typedef struct pdf_conversion_function_s +typedef struct pdf_conversion_function_s // *** PDF Conversion Function Structure *** { convert_cspace_func convertCSpace; // Function for conversion of colorspaces - convert_line_func convertLineOdd; // Function tom modify raster data of a - // line - convert_line_func convertLineEven; + convert_line_func convertLineOdd; // Function to modify raster data of a line + convert_line_func convertLineEven; // Function to modify raster data of a line } pdf_conversion_function_t; // @@ -159,7 +156,7 @@ typedef struct pdf_conversion_function_s // void -init_pdftoraster_doc_t(pdftoraster_doc_t *doc) // 0 - document structure. +init_pdftoraster_doc_t(pdftoraster_doc_t *doc) // I - document structure. { doc->pwgraster = 0; doc->bi_level = 0; @@ -792,16 +789,16 @@ line_swap_bit(unsigned char *src, return (dst); } -typedef struct func_table_s +typedef struct func_table_s // *** Function Table for Special Edge Cases *** { - enum cups_cspace_e cspace; - unsigned int bitsPerPixel; - unsigned int bitsPerColor; - convert_line_func convertLine; - bool allocLineBuf; - convert_line_func convertLineSwap; - bool allocLineBufSwap; -} func_table_t; + enum cups_cspace_e cspace; // Colour Space + unsigned int bitsPerPixel; // Bits per Pixel + unsigned int bitsPerColor; // Bits per Color + convert_line_func convertLine; // Function to modify raster data of a line + bool allocLineBuf; // Whether to allocate a line buffer for the conversion function + convert_line_func convertLineSwap; // Function to modify raster data of a line with swapping + bool allocLineBufSwap; // Whether to allocate a line buffer for the conversion function with swapping +} func_table_t; // Function table for Special Edge Cases static func_table_t specialCaseFuncs[] = @@ -2429,14 +2426,12 @@ set_color_profile(pdftoraster_doc_t *doc, // 'cfFilterPDFToRaster()' - Main Function for PDFtoRaster Conversion // -int +int // O - Exit status cfFilterPDFToRaster(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream - int inputseekable, // I - Is input stream seekable? - // (unused) + int inputseekable, // I - Is input stream seekable? (unused) cf_filter_data_t *data, // I - Job and printer data - void *parameters) // I - Filter-specific parameters - // (unused) + void *parameters) // I - Filter-specific parameters (unused) { // Constants for Printing Attributes or data const char *val; diff --git a/cupsfilters/pwgtoraster.c b/cupsfilters/pwgtoraster.c index 3af6e641c..daaf0f50f 100644 --- a/cupsfilters/pwgtoraster.c +++ b/cupsfilters/pwgtoraster.c @@ -67,40 +67,40 @@ #define MAX_BYTES_PER_PIXEL 32 -typedef struct cms_profile_s +typedef struct cms_profile_s // *** for color management *** { // for color profiles - cmsHPROFILE colorProfile; - cmsHPROFILE outputColorProfile; - cmsHTRANSFORM colorTransform; - cmsCIEXYZ D65WhitePoint; - int renderingIntent; - int cm_disabled; - cf_cm_calibration_t cm_calibrate; + cmsHPROFILE colorProfile; // ICC profile + cmsHPROFILE outputColorProfile; // ICC profile for output device + cmsHTRANSFORM colorTransform; // Color transform for color management + cmsCIEXYZ D65WhitePoint; // D65 white point + int renderingIntent; // Rendering intent for color management + int cm_disabled; // Flag raised if color management is disabled + cf_cm_calibration_t cm_calibrate; // Status of CUPS color management } cms_profile_t; -typedef struct pwgtoraster_doc_s -{ // **** Document information **** - cf_filter_data_t *data; - bool page_size_requested; - int bi_level; - bool allocLineBuf; - unsigned int bitspercolor; - unsigned int outputNumColors; - unsigned int bitmapoffset[2]; - cups_page_header_t inheader; - cups_page_header_t outheader; +typedef struct pwgtoraster_doc_s // *** Document information *** +{ + cf_filter_data_t *data; // Filter data + bool page_size_requested; // Flag indicating if page size is requested + int bi_level; // Bilevel flag + bool allocLineBuf; // Flag to allocate line buffer for conversion + unsigned int bitspercolor; // Bits per color + unsigned int outputNumColors; // Number of output colors + unsigned int bitmapoffset[2]; // Offset for bitmap data + cups_page_header_t inheader; // Input page header + cups_page_header_t outheader; // Output page header cups_file_t *inputfp; // Temporary file, if any FILE *outputfp; // Temporary file, if any // margin swapping - bool swap_margin_x; - bool swap_margin_y; - unsigned int nplanes; - unsigned int nbands; + bool swap_margin_x; // Flag to swap margins in x direction + bool swap_margin_y; // Flag to swap margins in y direction + unsigned int nplanes; // Number of planes in the output raster + unsigned int nbands; // Number of bands in the output raster unsigned int bytesPerLine; // number of bytes per line // Note: When CUPS_ORDER_BANDED, // cupsBytesPerLine = bytesPerLine * cupsNumColors - cms_profile_t color_profile; + cms_profile_t color_profile; // Color profile information for color management } pwgtoraster_doc_t; typedef unsigned char *(*convert_cspace_func)(unsigned char *src, @@ -117,11 +117,11 @@ typedef unsigned char *(*convert_line_func)(unsigned char *src, pwgtoraster_doc_t* doc, convert_cspace_func convertCSpace); -typedef struct conversion_function_s +typedef struct conversion_function_s // *** Conversion function information *** { convert_cspace_func convertCSpace; // Function for conversion of colorspaces convert_line_func convertLineOdd; // Function to modify raster data of a line - convert_line_func convertLineEven; + convert_line_func convertLineEven; // Function to modify raster data of a line } conversion_function_t; @@ -609,15 +609,15 @@ line_swap_bit(unsigned char *src, } -typedef struct func_table_s +typedef struct func_table_s // *** Conversion function table for special cases *** { - enum cups_cspace_e cspace; - unsigned int bitsPerPixel; - unsigned int bitsPerColor; - convert_line_func convertLine; - bool allocLineBuf; - convert_line_func convertLineSwap; - bool allocLineBufSwap; + enum cups_cspace_e cspace; // CUPS colorspace + unsigned int bitsPerPixel; // Bits per pixel + unsigned int bitsPerColor; // Bits per color + convert_line_func convertLine; // Function to modify raster data of a line + bool allocLineBuf; // Flag to allocate line buffer for conversion + convert_line_func convertLineSwap; // Function to modify raster data of a line with swapping + bool allocLineBufSwap; // Flag to allocate line buffer for conversion with swapping } func_table_t; @@ -2405,15 +2405,16 @@ set_color_profile(pwgtoraster_doc_t *doc, return (0); } +// +// 'cfFilterPWGToRaster()' - Convert a PWG raster stream to a CUPS raster stream. +// -int +int // O - 0 on success, 1 on error cfFilterPWGToRaster(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream - int inputseekable, // I - Is input stream seekable? - // (unused) + int inputseekable, // I - Is input stream seekable? (unused) cf_filter_data_t *data,// I - Job and printer data - void *parameters) // I - Filter-specific parameters - // (unused) + void *parameters) // I - Filter-specific parameters (unused) { cf_filter_out_format_t outformat; pwgtoraster_doc_t doc; diff --git a/cupsfilters/raster.c b/cupsfilters/raster.c index ca78cac49..d331a6d01 100644 --- a/cupsfilters/raster.c +++ b/cupsfilters/raster.c @@ -76,7 +76,7 @@ _strlcpy(char *dst, // O - Destination string // 'cfRasterColorSpaceString()' - Return the color space name for a // cupsColorSpace value. -const char * +const char * // O - Color space name cfRasterColorSpaceString(cups_cspace_t cspace) // I - cupsColorSpace value { static const char * const cups_color_spaces[] = @@ -172,26 +172,13 @@ cfRasterColorSpaceString(cups_cspace_t cspace) // I - cupsColorSpace value // attributes/options. // -int // O - 0 on success, - // -1 on error +int // O - 0 on success, -1 on error cfRasterPrepareHeader(cups_page_header_t *h, // I - Raster header cf_filter_data_t *data, // I - Job and printer data - cf_filter_out_format_t final_outformat, - // I - Job output format - // (determines color space, - // and resolution) - cf_filter_out_format_t header_outformat, - // I - This filter's output - // format (determines - // header format) - int no_high_depth, // I - Suppress use of - // > 8 bit per color - cups_cspace_t *cspace) // IO - Color space we want to - // use, -1 for auto, we - // return color space - // actually used, -1 if - // no suitable color space - // found. + cf_filter_out_format_t final_outformat, // I - Job output format (determines color space, and resolution) + cf_filter_out_format_t header_outformat, // I - This filter's output format (determines header format) + int no_high_depth, // I - Suppress use of > 8 bit per color + cups_cspace_t *cspace) // IO - Color space we want to use, -1 for auto, we return color space actually used, -1 if no suitable color space found. { int i; ipp_t *printer_attrs, *job_attrs; @@ -595,27 +582,12 @@ cfRasterPrepareHeader(cups_page_header_t *h, // I - Raster header // requested, the highest. // -int // O - 0 on success, - // -1 on error +int // O - 0 on success, -1 on error cfRasterSetColorSpace(cups_page_header_t *h, // I - Raster header - const char *available, // I - Available color spaces - // from IPP attribute - // urf-supported or - // pwg-raster-document-type-supported - const char *color_mode, // I - print-color-mode IPP - // attribute setting - cups_cspace_t *cspace, // IO - Color space we want to - // use, -1 for auto, we - // return color space - // actually used, -1 if - // no suitable color space - // found. - int *high_depth) // IO - Do we want to print in - // high color depth? We - // reset to 0 if high - // quality not supported - // in the color space - // used. + const char *available, // I - Available color spaces from IPP attribute urf-supported or pwg-raster-document-type-supported + const char *color_mode, // I - print-color-mode IPP attribute setting + cups_cspace_t *cspace, // IO - Color space we want to use, -1 for auto, we return color space actually used, -1 if no suitable color space found. + int *high_depth) // IO - Do we want to print in high color depth? We reset to 0 if high quality not supported in the color space used. { int min_depth = 999; int max_depth = 0; diff --git a/cupsfilters/testfilters.c b/cupsfilters/testfilters.c index 9c0e2b27f..4edfaef8c 100644 --- a/cupsfilters/testfilters.c +++ b/cupsfilters/testfilters.c @@ -18,15 +18,15 @@ # define cupsParseOptions(arg, end, num_options, options) cupsParseOptions(arg, num_options, options) #endif -/* - * 'remove_white_space()' - Remove white spaces from beginning and end of a string - */ typedef int (*cf_filter_func_t)(int input_fd, int output_fd, int input_seekable, cf_filter_data_t *data, void *parameters); -char* -remove_white_space( - char* str) +// +// 'remove_white_space()' - Remove white spaces from beginning and end of a string +// + +char* // O - Pointer to the modified string +remove_white_space(char* str) // I - Input string { char *end; while(isspace((unsigned char)*str)) str++; @@ -49,8 +49,12 @@ typedef struct { void *(*param_generator)(const char *output_mime); } FilterMapping; -void -*ghostscript_param_gen(const char *output_mime) +// +// 'ghostscript_param_gen()' - Generate parameters for the ghostscript filter based on output MIME type. +// + +void // O - Pointer to parameters structure, or NULL on error +*ghostscript_param_gen(const char *output_mime) // I - Output MIME type { cf_filter_out_format_t *out = malloc(sizeof(cf_filter_out_format_t)); if (strcasecmp(output_mime, "application/pdf") == 0) { @@ -78,9 +82,13 @@ FilterMapping filter_mappings[] = { { "texttopdf", cfFilterTextToPDF, NULL }, }; -cups_array_t* -parse_filter_chain(const char *filter_chain_str, - const char *output_mime) +// +// 'cfFilterFilterInChain()' - Call a filter function in the chain. +// + +cups_array_t* // O - Array of filters in the chain +parse_filter_chain(const char *filter_chain_str, // I - Comma-separated list of filter names + const char *output_mime) // I - Output MIME type { cups_array_t *chain = cupsArrayNew(NULL, NULL, NULL, 0, NULL, NULL); char *saveptr; @@ -196,10 +204,10 @@ create_media_size(int width, /* I - x-dimension in 2540ths */ return (media_size); } -/* - * 'test_wrapper()' - Utilizes libcupsfilters API for running a particular test - * - */ +// +// 'test_wrapper()' - Utilizes libcupsfilters API for running a particular test +// +// /* @@ -217,18 +225,18 @@ test_wrapper( { */ -int +int // O - Exit status test_wrapper( - int num_clargs, - char *clargs[], - void *parameters, - int *JobCanceled, - ipp_t* emulated_ipp, - char* inputMIME, - char* outputMIME, - char* inputFile, - char* outputFile, - cups_array_t *filter_chain) + int num_clargs, // I - Number of command-line args + char *clargs[], // I - Command-line arguments + void *parameters, // I - Filter function parameters + int *JobCanceled, // I - Var set to 1 when job canceled + ipp_t* emulated_ipp, // I - Emulated printer IPP attributes + char* inputMIME, // I - Input MIME type + char* outputMIME, // I - Output MIME type + char* inputFile, // I - Input file name + char* outputFile, // I - Output file name + cups_array_t *filter_chain) { int inputfd; // Print file descriptor int outputfd; // File Descriptor for Output File @@ -1110,15 +1118,14 @@ load_legacy_attributes( } -/* - * 'run_test()' - Runs a particular test case - * - */ +// +// 'run_test()' - Runs a particular test case +// -int +int // O - Exit status run_test( - char * test_case, - char * currentFile) + char * test_case, // I - Test case string + char * currentFile) // I - Current file name { cups_array_t *filter_chain = NULL; @@ -1267,8 +1274,13 @@ run_test( } -int main(int argc, // I - Number of command-line args - char *argv[]) // I - Command-line arguments{ +// +// 'main()' - Main entry point for the test filter program. +// + +int // O - Exit status + main(int argc, // I - Number of command-line args + char *argv[]) // I - Command-line arguments { char *file_name; // File Name of Input Test File FILE *fp; // File Pointer diff --git a/cupsfilters/testpdf2.c b/cupsfilters/testpdf2.c index 628e10e6b..be4e292c3 100644 --- a/cupsfilters/testpdf2.c +++ b/cupsfilters/testpdf2.c @@ -43,12 +43,14 @@ write_string(_cf_pdf_out_t *pdf, _cfPDFOutputString(pdf, str, -1); } } -// }}} +// +// 'main()' - Main entry point for the test program. +// -int -main(int argc, - char *argv[]) +int // O - Exit status +main(int argc, // I - Number of command-line args + char *argv[]) // I - Command-line arguments { _cf_pdf_out_t *pdf; diff --git a/cupsfilters/texttopdf.c b/cupsfilters/texttopdf.c index 81e5f7f0e..f7a665284 100644 --- a/cupsfilters/texttopdf.c +++ b/cupsfilters/texttopdf.c @@ -481,7 +481,7 @@ typedef struct // **** Character/attribute structure... **** attr; // Any attributes } lchar_t; -typedef struct texttopdf_doc_s +typedef struct texttopdf_doc_s // *** Document data for texttopdf filter *** { int NumFonts; // Number of fonts to use _cf_fontembed_emb_params_t *Fonts[256][4]; // Fonts to use @@ -489,23 +489,21 @@ typedef struct texttopdf_doc_s unsigned char Codes[65536]; // Unicode glyph mapping to font int Widths[256]; // Widths of each font int Directions[256];// Text directions for each font - _cf_pdf_out_t *pdf; + _cf_pdf_out_t *pdf; // PDF output stream int FontResource; // Object number of font resource dictionary float FontScaleX, FontScaleY; // The font matrix lchar_t *Title, *Date; // The title and date strings - cups_page_header_t h; // CUPS Raster page header, to - // accommodate results of command - // line/IPP attribute parsing - cf_filter_texttopdf_parameter_t env_vars; - int NumKeywords; + cups_page_header_t h; // CUPS Raster page header, to accommodate results of command line/IPP attribute parsing + cf_filter_texttopdf_parameter_t env_vars; // Environment variables for texttopdf filter + int NumKeywords; // Number of keywords in the list float PageLeft, // Left margin PageRight, // Right margin PageBottom, // Bottom margin PageTop, // Top margin PageWidth, // Total page width - PageLength; - int NumPages; + PageLength; // Total page length + int NumPages; // Number of pages in the document int WrapLines, // Wrap text in lines SizeLines, // Number of lines on a page SizeColumns, // Number of columns on a line @@ -516,14 +514,14 @@ typedef struct texttopdf_doc_s Copies; // Number of copies to produce float CharsPerInch, // Number of character columns per inch LinesPerInch; // Number of lines per inch - int UTF8; + int UTF8; // Use UTF-8 encoding? char **Keywords; // List of known keywords... int Orientation, // 0 = portrait, 1 = landscape, etc. Duplex, // Duplexed? LanguageLevel, // Language level of printer - ColorDevice; - lchar_t **Page; + ColorDevice; // Color device? + lchar_t **Page; // The pages of the document, each page is a string of lchar_t } texttopdf_doc_t; diff --git a/cupsfilters/texttotext.c b/cupsfilters/texttotext.c index 0c241174c..c9bce02e5 100644 --- a/cupsfilters/texttotext.c +++ b/cupsfilters/texttotext.c @@ -39,18 +39,18 @@ // Type definitions // -typedef enum overlong_line_e +typedef enum overlong_line_e // How to treat overlong lines { - TRUNCATE = 0, - WORDWRAP = 1, - WRAPATWIDTH = 2 + TRUNCATE = 0, // Truncate lines to the page width + WORDWRAP = 1, // Wrap lines at word boundaries + WRAPATWIDTH = 2 // Wrap lines at the page width } overlong_line_t; -typedef enum newline_char_e +typedef enum newline_char_e // Character to send at end of line { - LF = 0, - CR = 1, - CRLF = 2 + LF = 0, // Line Feed + CR = 1, // Carriage Return + CRLF = 2 // Carriage Return + Line Feed } newline_char_t; @@ -63,11 +63,15 @@ static int is_false(const char *value); static int check_range(char *page_ranges, int even_pages, int odd_pages, int page); -int + +// +// 'cfFilterTextToText()' - Filter a text file to a text-only printer. +// + +int // O - Exit status cfFilterTextToText(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream - int inputseekable, // I - Is input stream seekable? - // (unused) + int inputseekable, // I - Is input stream seekable? (unused) cf_filter_data_t *data, // I - Job and printer data void *parameters) // I - Filter-specific parameters { diff --git a/cupsfilters/universal.c b/cupsfilters/universal.c index 69488741b..c2b98b9af 100644 --- a/cupsfilters/universal.c +++ b/cupsfilters/universal.c @@ -28,6 +28,10 @@ #include #include +// +// 'cfFilterUniversal()' - Filter a file from any input format to any output format. +// + int // O - Error status cfFilterUniversal(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream From 284bfce7742fb441df5d46216a38539455953444 Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Fri, 11 Sep 2026 01:26:00 +0530 Subject: [PATCH 20/24] Improve Documentation across multiple files --- cupsfilters/bannertopdf.c | 2 +- cupsfilters/driver.h | 10 +- cupsfilters/filter.c | 52 +++++-- cupsfilters/filter.h | 14 +- cupsfilters/gen-lorem-text.c | 52 ++++--- cupsfilters/ieee1284.c | 65 ++++----- cupsfilters/ieee1284.h | 21 +-- cupsfilters/image-private.h | 10 +- cupsfilters/image-zoom.c | 3 +- cupsfilters/image.h | 8 +- cupsfilters/imagetopdf.c | 4 +- cupsfilters/imagetoraster.c | 2 +- cupsfilters/ipp.c | 2 +- cupsfilters/ipp.h | 2 +- cupsfilters/log.h | 4 +- cupsfilters/pclmtoraster.c | 13 +- cupsfilters/pdf.h | 2 +- cupsfilters/pdftopdf-private.h | 10 +- cupsfilters/pdftoraster.c | 8 +- cupsfilters/pwgtopdf.c | 159 +++++++++------------ cupsfilters/pwgtoraster.c | 8 +- cupsfilters/raster.c | 4 +- cupsfilters/raster.h | 21 --- cupsfilters/rastertopwg.c | 6 +- cupsfilters/test-pdftoraster-copy-height.c | 6 +- cupsfilters/testfilters.c | 130 ++++++++--------- cupsfilters/testpdf1.c | 7 +- 27 files changed, 291 insertions(+), 334 deletions(-) diff --git a/cupsfilters/bannertopdf.c b/cupsfilters/bannertopdf.c index bac711fc4..cb04952d9 100644 --- a/cupsfilters/bannertopdf.c +++ b/cupsfilters/bannertopdf.c @@ -51,7 +51,7 @@ typedef enum banner_info_e INFO_TIME_AT_PROCESSING = 1 << 17 // I - Time at processing } banner_info_t; -typedef struct banner_s //*** Banner data structure *** +typedef struct banner_s // Banner data structure { char *template_file; // I - Template file path char *header, *footer; // I - Header and footer text diff --git a/cupsfilters/driver.h b/cupsfilters/driver.h index ca5744278..18f6dcee0 100644 --- a/cupsfilters/driver.h +++ b/cupsfilters/driver.h @@ -61,27 +61,27 @@ extern "C" { // Types/structures for the various routines. // -typedef struct cf_lut_s // *** Lookup Table for Dithering *** +typedef struct cf_lut_s // Lookup Table for Dithering { short intensity; // Adjusted intensity short pixel; // Output pixel value int error; // Error from desired value } cf_lut_t; -typedef struct cf_dither_s // *** Dithering State *** +typedef struct cf_dither_s // Dithering State { int width; // Width of buffer int row; // Current row int errors[96]; // Error values } cf_dither_t; -typedef struct cf_sample_s // *** Color sample point *** +typedef struct cf_sample_s // Color sample point { unsigned char rgb[3]; // sRGB values unsigned char colors[CF_MAX_RGB]; // Color values } cf_sample_t; -typedef struct cf_rgb_s // *** Color separation lookup table *** +typedef struct cf_rgb_s // Color separation lookup table { int cube_size; // Size of color cube (2-N) on a side int num_channels; // Number of colors per sample @@ -93,7 +93,7 @@ typedef struct cf_rgb_s // *** Color separation lookup table *** unsigned char white[CF_MAX_RGB]; // Cached white (sRGB = 255,255,255) } cf_rgb_t; -typedef struct cf_cmyk_s // *** Simple CMYK lookup table *** +typedef struct cf_cmyk_s // Simple CMYK lookup table { unsigned char black_lut[256]; // Black generation LUT unsigned char color_lut[256]; // Color removal LUT diff --git a/cupsfilters/filter.c b/cupsfilters/filter.c index 6262928d6..956d1d77c 100644 --- a/cupsfilters/filter.c +++ b/cupsfilters/filter.c @@ -27,7 +27,7 @@ #include -extern char **environ; +extern char **environ; // Environment variables for filter functions // @@ -237,8 +237,11 @@ cfFilterDataRemoveExt(cf_filter_data_t *data, // I - Filter data record // -// 'cfFilterGetEnvVar()' - Get the value of an environment variable from the -// supplied environment list. +// 'cfFilterGetEnvVar()' - Auxiliary function for cfFilterExternal(), +// gets value of an environment variable in a +// list of environment variables as used by +// the execve() function. +// // char * // O - Value of variable, or NULL @@ -314,8 +317,20 @@ cfFilterAddEnvVar(char *name, // I - Name of environment variable to set // -// 'cfFilterTee()' - Copy input data to a file (for debugging) while -// passing it unchanged to the output. +// 'cfFilterTee()' - This filter function is mainly for debugging. it +// resembles the "tee" utility, passing through the +// data unfiltered and copying it to a file. The +// file name is simply given as parameter. This +// makes using the function easy (add it as item of +// a filter chain called via cfFilterChain()) and +// can even be used more than once in the same +// filter chain (using different file names). In +// case of write error to the copy file, copying is +// stopped but the rest of the job is passed on to +// the next filter. If NULL is supplied as file +// name, the data is simply passed through without +// getting copied. +// int // O - 0 on success, -1 on error cfFilterTee(int inputfd, // I - File descriptor input stream @@ -939,9 +954,14 @@ sanitize_device_uri(const char *uri, // I - Device URI // -// 'cfFilterExternal()' - Filter function that executes an ezternal CUPS filter -// or System V interface script, typically used when conversion -// to a native filter function is not possible. +// 'cfFilterExternal()' - Filter function which calls an external +// classic CUPS filter or System V interface +// script, for example a (proprietary) printer +// driver which cannot be converted to a filter +// function or if it is too awkward or risky to +// convert for example when the printer +// hardware is not available for testing. +// // int // O - 0 on success, -1 on error @@ -1583,10 +1603,18 @@ cfFilterExternal(int inputfd, // I - File descriptor input stream // -// 'cfFilterOpenBackAndSidePipes()' - Open the pipes for the back and side channels -// to allow communication between filter functions and a -// backend. Used when a CUPS backend runs with the same filter_data. -// +// 'cfFilterOpenBackAndSidePipes()' - Open the pipes for the back +// channel and the side channel, so +// that the filter functions can +// communicate with a backend. Only +// needed if a CUPS backend (either +// implemented as filter function +// or called via +// cfFilterExternal()) is called +// with the same filter_data record +// as the filters. Usually to be +// called when populating the +// filter_data record. // int // O - 0 on success, -1 on error diff --git a/cupsfilters/filter.h b/cupsfilters/filter.h index da17d8c6e..57afe0294 100644 --- a/cupsfilters/filter.h +++ b/cupsfilters/filter.h @@ -52,7 +52,7 @@ extern "C" { typedef int (*cf_filter_iscanceledfunc_t)(void *data); -typedef struct cf_filter_data_s // *** Data structure for filter functions *** +typedef struct cf_filter_data_s // Data structure for filter functions { char *printer; // Print queue name or NULL int job_id; // Job ID or 0 @@ -75,7 +75,7 @@ typedef struct cf_filter_data_s // *** Data structure for filter functions *** void *iscanceleddata; // User data for is-canceled function, can be NULL } cf_filter_data_t; -typedef struct cf_filter_data_ext_s // *** Extension data for cf_filter_data_t *** +typedef struct cf_filter_data_ext_s // Extension data for cf_filter_data_t { char *name; // Name of the extension data void *ext; // Pointer to the extension data @@ -85,7 +85,7 @@ typedef int (*cf_filter_function_t)(int inputfd, int outputfd, int inputseekable, cf_filter_data_t *data, void *parameters); -typedef enum cf_filter_out_format_e // *** Possible output formats for filter functions *** +typedef enum cf_filter_out_format_e // Possible output formats for filter functions { CF_FILTER_OUT_FORMAT_PDF, // PDF CF_FILTER_OUT_FORMAT_PDF_IMAGE, // Raster-only PDF @@ -96,14 +96,14 @@ typedef enum cf_filter_out_format_e // *** Possible output formats for filter CF_FILTER_OUT_FORMAT_PXL // PCL-XL } cf_filter_out_format_t; -typedef struct cf_filter_filter_in_chain_s // *** Filter entry for CUPS array to be supplied to cfFilterChain() filter function *** +typedef struct cf_filter_filter_in_chain_s // Filter entry for CUPS array to be supplied to cfFilterChain() filter function { cf_filter_function_t function; // Filter function to be called void *parameters; // Parameters for this filter function call char *name; // Name/comment, only for logging } cf_filter_filter_in_chain_t; -typedef struct cf_filter_external_s // *** Parameters for the cfFilterExternal() filter function *** +typedef struct cf_filter_external_s // Parameters for the cfFilterExternal() filter function { const char *filter; // Path/Name of the CUPS filter to be called by this filter function, required int exec_mode; // 0 if we call a CUPS filter, -1 if we call a System V interface script, 1 if we call a CUPS backend, 2 if we call a CUPS backend in device discovery mode @@ -112,7 +112,7 @@ typedef struct cf_filter_external_s // *** Parameters for the cfFilterExternal() char **envp; // Additional environment variables, the already defined ones stay valid but can be overwritten by these ones, NULL if none } cf_filter_external_t; -typedef struct cf_filter_texttopdf_parameter_s // *** parameters container of environemnt variables needed by texttopdf filter function *** +typedef struct cf_filter_texttopdf_parameter_s // parameters container of environemnt variables needed by texttopdf filter function { char *data_dir; // Data directory to be used for fonts and charsets, or NULL for default char *char_set; // Charset to be used for prettyprint, or NULL for default @@ -120,7 +120,7 @@ typedef struct cf_filter_texttopdf_parameter_s // *** parameters container of en char *classification; // Classification to be used for overprint/watermark, or NULL for default } cf_filter_texttopdf_parameter_t; -typedef struct cf_filter_universal_parameter_s // *** Contains input and output type to be supplied to the universal function, and also parameters for cfFilterTextToPDF() *** +typedef struct cf_filter_universal_parameter_s // Contains input and output type to be supplied to the universal function, and also parameters for cfFilterTextToPDF() { char *actual_output_type; // Output MIME type cf_filter_texttopdf_parameter_t texttopdf_params; // Parameters for cfFilterTextToPDF() filter function diff --git a/cupsfilters/gen-lorem-text.c b/cupsfilters/gen-lorem-text.c index 81a95915f..0f342eb9b 100644 --- a/cupsfilters/gen-lorem-text.c +++ b/cupsfilters/gen-lorem-text.c @@ -1,11 +1,11 @@ -/*Deterministically generate a long Lorem-Ipsum based text for tests. - * Usage: ./gen-lorem-text [repeats] > test_text_lorem.txt - * - * What This program does: - * - Uses a fixed publicly available Lorem paragraph. - * - Modifies some of the characters into special characters, i.e. "äöüßçáàñ...", based on fixed modification table. - * - Modified paragraph is repeated N times separated by blank lines. - */ +//Deterministically generate a long Lorem-Ipsum based text for tests. +// Usage: ./gen-lorem-text [repeats] > test_text_lorem.txt +// +// What This program does: +// - Uses a fixed publicly available Lorem paragraph. +// - Modifies some of the characters into special characters, i.e. "äöüßçáàñ...", based on fixed modification table. +// - Modified paragraph is repeated N times separated by blank lines. +// #include #include @@ -21,13 +21,14 @@ static const char *base_paragraph = "vehicula faucibus. Cras tincidunt, nibh quis aliquet tincidunt, " "lectus dolor iaculis nunc, id fermentum dui orci at urna."; -/* Deterministic modifications: we replace selected ASCII characters - * withspecial UTF-8 variants. The transformation depends on - * the character and the global position index so it's reproducible. - */ +// Deterministic modifications: we replace selected ASCII characters +// withspecial UTF-8 variants. The transformation depends on +// the character and the global position index so it's reproducible. +// + static const char *replace_char(unsigned char c, unsigned long pos) { - /* Replace only a subset of letters to keep readability. */ - /* Use pos to vary replacements deterministically. */ + // Replace only a subset of letters to keep readability. + // Use pos to vary replacements deterministically. switch (c) { case 'a': if ((pos % 5) == 0) return "ä"; @@ -56,13 +57,20 @@ static const char *replace_char(unsigned char c, unsigned long pos) { if ((pos % 31) == 0) return "í"; return "i"; default: - /* To emit the original byte */ + // To emit the original byte return NULL; } } -int main(int argc, char *argv[]) { - unsigned long repeats = 150; /* default: ~150 paragraphs -> multi-page */ +// +// 'main()' - Generate the Lorem-Ipsum text with modifications and repetitions. +// + +int // O - Exit status +main(int argc, // I - Number of command-line arguments + char *argv[]) // I - Command-line arguments + { + unsigned long repeats = 150; // default: ~150 paragraphs -> multi-page unsigned long i; unsigned long global_pos = 1; @@ -74,25 +82,25 @@ int main(int argc, char *argv[]) { printf("/* Generated by gen-lorem-text.c: repeats=%lu */\n\n", repeats); for (i = 0; i < repeats; ++i) { - /* iterate bytes of base_paragraph and print with replacements */ + // iterate bytes of base_paragraph and print with replacements const char *p = base_paragraph; while (*p) { unsigned char uc = (unsigned char)*p; const char *rep = replace_char(uc, global_pos); if (rep) { - fputs(rep, stdout); /* rep is UTF-8 literal */ + fputs(rep, stdout); // rep is UTF-8 literal } else { - /* print ASCII byte as-is */ + // print ASCII byte as-is fputc(uc, stdout); } ++p; ++global_pos; } - /* Paragraph separator: two newlines -> makes pages when converted */ + // Paragraph separator: two newlines -> makes pages when converted fputs("\n\n", stdout); } - /* trailing newline */ + // trailing newline fputs("\n", stdout); return 0; diff --git a/cupsfilters/ieee1284.c b/cupsfilters/ieee1284.c index 069fc94dc..25dad607e 100644 --- a/cupsfilters/ieee1284.c +++ b/cupsfilters/ieee1284.c @@ -633,50 +633,39 @@ move_right_part( // This function tries to undo the mistakes made by many printer manufacturers // to produce a clean make-and-model string we can use. // +// The 'make' parameter provides the manufacturer name as a hint for correct +// separation of 'make_and_model', or for adding the make. It can also point +// into the input string where the model name starts, or be NULL. It is ignored +// on device IDs with an "MFG" field or for NO_MAKE_MODEL. +// +// The 'extra_regex' parameter is a compiled regular expression used to +// determine where the extra information after the driver name starts. The +// driver name is marked with parentheses in the regular expression. +// +// The 'buffer' parameter is the string buffer that holds the normalized input +// string, plus, after the terminating zero, the driver name if an appropriate +// extra_regex is supplied. '*drvname' will point to it. +// +// '*model' points to where the model name starts in 'buffer', or NULL. +// +// '*extra' points to where extra information starts in 'buffer' after a comma, +// semicolon, parenthesis, or at the start of the extra_regex match, or NULL. +// +// '*drvname' points to the driver name string of the first matching parenthese +// expression in the extra_regex. +// -char * // O - Normalized make-and-model string or NULL on error +char * // O - Normalized make-and-model string or NULL on error cfIEEE1284NormalizeMakeModel( const char *make_and_model, // I - Original make-and-model string or device ID - const char *make, /* - * I - Manufacturer name as hint for correct separation of - * make_and_model or adding - * make, or pointer into input - * string where model name starts - * or NULL, - * ignored on device ID with "MFG" - * field or for NO_MAKE_MODEL - */ + const char *make, // I - Manufacturer name or model separation hint cf_ieee1284_normalize_modes_t mode, // I - Bit field to describe how to normalize - regex_t *extra_regex, /* - * I - Compiled regex to determine - * where the extra info after - * the driver name starts, also - * mark with parentheses which - * sub string should be the - * driver name - */ - char *buffer, /* - * O - String buffer, to hold the - * normalized input string, plus, - * after the terminating zero, the - * driver name if an appropriate - * extra_regex is supplied - * (*drvname will point to it) - */ + regex_t *extra_regex, // I - Bit field to describe how to normalize + char *buffer, // O - String buffer for normalized make-and-model string size_t bufsize, // O - Size of string buffer char **model, // O - Pointer to where model name starts in buffer or NULL - char **extra, /* - * O - Pointer to where extra info - * starts in buffer (after comma, - * semicolon, parenthese, or - * start of extra_regex - * match) or NULL - */ - char **drvname) /* - * O - Driver name, string of the first - * matching parenthese expression - * in the extra_regex - */ + char **extra, // O - Pointer to where extra info starts in buffer or NULL + char **drvname) // O - Driver name in buffer or NULL { int i; char *bufptr; // Pointer into buffer diff --git a/cupsfilters/ieee1284.h b/cupsfilters/ieee1284.h index c321f50b6..9852d2d33 100644 --- a/cupsfilters/ieee1284.h +++ b/cupsfilters/ieee1284.h @@ -74,29 +74,16 @@ enum cf_ieee1284_normalize_modes_e */ CF_IEEE1284_NORMALIZE_IPP = 0x02, // Only chars allowed in IPP keywords CF_IEEE1284_NORMALIZE_ENV = 0x04, // Environment variable format upparcase and underscore - CF_IEEE1284_NORMALIZE_HUMAN = 0x08, /* - * Human-readable, conserves - * spaces and special characters - * but does some clean-up - */ + CF_IEEE1284_NORMALIZE_HUMAN = 0x08, // Human-readable, conserves spaces and special characters but does some clean-up CF_IEEE1284_NORMALIZE_LOWERCASE = 0x10, // All letters lowercase CF_IEEE1284_NORMALIZE_UPPERCASE = 0x20, // All letters uppercase CF_IEEE1284_NORMALIZE_SEPARATOR_SPACE = 0x40,// Separator char is ' ' CF_IEEE1284_NORMALIZE_SEPARATOR_DASH = 0x80, // Separator char is '-' CF_IEEE1284_NORMALIZE_SEPARATOR_UNDERSCORE = 0x100,// Separator char is '_' CF_IEEE1284_NORMALIZE_PAD_NUMBERS = 0x200, // Zero-pad numbers in strings to get better list sorting results - CF_IEEE1284_NORMALIZE_SEPARATE_COMPONENTS = 0x400, /* - * In the output buffer put - * '\0' bytes between make, - * model, and extra, to use - * as separate strings - */ - CF_IEEE1284_NORMALIZE_NO_MAKE_MODEL = 0x800, /* - * No make/model/extra separation, - * do not try to identify, add, - * or clean up manufacturer - * name - */ + CF_IEEE1284_NORMALIZE_SEPARATE_COMPONENTS = 0x400, // In the output buffer put '\0' bytes between make, model, and extra, to use as separate strings + CF_IEEE1284_NORMALIZE_NO_MAKE_MODEL = 0x800, // No make/model/extra separation, do not try to identify, add, or clean up manufacturer name +}; typedef unsigned cf_ieee1284_normalize_modes_t; // diff --git a/cupsfilters/image-private.h b/cupsfilters/image-private.h index 461c8b6a6..2e469763f 100644 --- a/cupsfilters/image-private.h +++ b/cupsfilters/image-private.h @@ -83,7 +83,7 @@ // Types and structures... // -typedef enum cf_iztype_e // **** Image zoom type **** +typedef enum cf_iztype_e // Image zoom type { CF_IZOOM_FAST, // Use nearest-neighbor sampling CF_IZOOM_NORMAL, // Use bilinear interpolation @@ -92,7 +92,7 @@ typedef enum cf_iztype_e // **** Image zoom type **** struct cf_ic_s; -typedef struct cf_itile_s // **** Image tile **** +typedef struct cf_itile_s // Image tile { int dirty; // True if tile is dirty off_t pos; // Position of tile on disk (-1 if not @@ -100,7 +100,7 @@ typedef struct cf_itile_s // **** Image tile **** struct cf_ic_s *ic; // Pixel data } cf_itile_t; -typedef struct cf_ic_s // **** Image tile cache **** +typedef struct cf_ic_s // Image tile cache { struct cf_ic_s *prev, // Previous tile in cache *next; // Next tile in cache @@ -108,7 +108,7 @@ typedef struct cf_ic_s // **** Image tile cache **** cf_ib_t *pixels; // Pixel data } cf_ic_t; -struct cf_image_s // **** Image file data **** +struct cf_image_s // Image file data { cf_icspace_t colorspace; // Colorspace of image unsigned xsize, // Width of image in pixels @@ -124,7 +124,7 @@ struct cf_image_s // **** Image file data **** char cachename[256]; // Tile cache filename }; -struct cf_izoom_s // **** Image zoom data **** +struct cf_izoom_s // Image zoom data { cf_image_t *img; // Image to zoom cf_iztype_t type; // Type of zooming diff --git a/cupsfilters/image-zoom.c b/cupsfilters/image-zoom.c index 0f3890276..b8f1eba5c 100644 --- a/cupsfilters/image-zoom.c +++ b/cupsfilters/image-zoom.c @@ -81,8 +81,7 @@ _cfImageZoomNew( int yc1, // I - ... int xsize, // I - Final width of image int ysize, // I - Final height of image - int rotated, // I - Non-zero if image is rotated 90 - // degrees + int rotated, // I - Non-zero if image is rotated 90 degrees cf_iztype_t type) // I - Zoom type { cf_izoom_t *z; // New zoom record diff --git a/cupsfilters/image.h b/cupsfilters/image.h index cb558a782..e8423b3c3 100644 --- a/cupsfilters/image.h +++ b/cupsfilters/image.h @@ -29,7 +29,7 @@ extern "C" { // Constants... // -typedef enum cf_icspace_e // **** Image colorspaces **** +typedef enum cf_icspace_e // Image colorspaces { CF_IMAGE_CMYK = -4, // Cyan, magenta, yellow, and black CF_IMAGE_CMY = -3, // Cyan, magenta, and yellow @@ -44,13 +44,13 @@ typedef enum cf_icspace_e // **** Image colorspaces **** // Types and structures... // -typedef unsigned char cf_ib_t; // **** Image byte **** +typedef unsigned char cf_ib_t; // Image byte struct cf_image_s; -typedef struct cf_image_s cf_image_t; // **** Image file data **** +typedef struct cf_image_s cf_image_t; // Image file data struct cf_izoom_s; -typedef struct cf_izoom_s cf_izoom_t; // **** Image zoom data **** +typedef struct cf_izoom_s cf_izoom_t; // Image zoom data // diff --git a/cupsfilters/imagetopdf.c b/cupsfilters/imagetopdf.c index 0d9f75fd4..3937d9d14 100644 --- a/cupsfilters/imagetopdf.c +++ b/cupsfilters/imagetopdf.c @@ -35,12 +35,12 @@ // Types... // -struct pdfObject // **** PDF object information **** +struct pdfObject // PDF object information { int offset; // Offset of object in output file }; -typedef struct imagetopdf_doc_s // **** Document information **** +typedef struct imagetopdf_doc_s // Document information { int Flip, // Flip/mirror pages XPosition, // Horizontal position on page diff --git a/cupsfilters/imagetoraster.c b/cupsfilters/imagetoraster.c index b6b3c7f86..e0fbcb7f1 100644 --- a/cupsfilters/imagetoraster.c +++ b/cupsfilters/imagetoraster.c @@ -44,7 +44,7 @@ // Types... // -typedef struct // **** Document information ****¨ +typedef struct // **** Document information **** { int Flip, // Flip/mirror pages XPosition, // Horizontal position on page diff --git a/cupsfilters/ipp.c b/cupsfilters/ipp.c index d02f4473d..48709914e 100644 --- a/cupsfilters/ipp.c +++ b/cupsfilters/ipp.c @@ -34,7 +34,7 @@ #include -typedef struct cf_size_s // **** Media Size (cups_size_t of libcups2) **** +typedef struct cf_size_s // Media Size (cups_size_t of libcups2) { char media[128]; // Media name to use int width, // Width in hundredths of millimeters diff --git a/cupsfilters/ipp.h b/cupsfilters/ipp.h index 4ba8d9832..f84a930b1 100644 --- a/cupsfilters/ipp.h +++ b/cupsfilters/ipp.h @@ -76,7 +76,7 @@ typedef enum cf_backside_orient_e // Backside orientation for duplex printing // Data structure for resolution (X x Y dpi) -typedef struct cf_res_s // **** Resolution (X x Y dpi) **** +typedef struct cf_res_s // Resolution (X x Y dpi) { int x, y; // X and Y resolution in dpi } cf_res_t; diff --git a/cupsfilters/log.h b/cupsfilters/log.h index 5e050a582..22244097f 100644 --- a/cupsfilters/log.h +++ b/cupsfilters/log.h @@ -19,8 +19,8 @@ extern "C" { // Types... // -typedef enum cf_loglevel_e // Log levels, same as PAPPL, similar -{ // to CUPS +typedef enum cf_loglevel_e // Log levels, same as PAPPL, similar to CUPS +{ CF_LOGLEVEL_UNSPEC = -1, // Not specified CF_LOGLEVEL_DEBUG, // Debug message CF_LOGLEVEL_INFO, // Informational message diff --git a/cupsfilters/pclmtoraster.c b/cupsfilters/pclmtoraster.c index d1ca90149..17d91ab2a 100644 --- a/cupsfilters/pclmtoraster.c +++ b/cupsfilters/pclmtoraster.c @@ -36,13 +36,12 @@ typedef struct pclmtoraster_data_s int rowsize; // size of a row cups_page_header_t header; // CUPS page header char pageSizeRequested[64]; // Requested page size name - int bi_level; // flag for printing - // image swapping - int swap_image_x; - int swap_image_y; + int bi_level; // flag for printing image swapping + int swap_image_x; // image swapping + int swap_image_y; // image swapping // margin swapping - int swap_margin_x; - int swap_margin_y; + int swap_margin_x; // flag for printing margin swapping + int swap_margin_y; // flag for printing margin swapping unsigned int nplanes; // Number of colour planes unsigned int nbands; // Number of colour bands unsigned int bytesPerLine; // bytes per line in output @@ -55,7 +54,7 @@ typedef struct pclmtoraster_data_s // 'init_pclmtoraster_data_t()' - initialize the data structure with default values. // -void // O - void output +void init_pclmtoraster_data_t(pclmtoraster_data_t *data) // I - pclm data to initialize { data->outformat = CF_FILTER_OUT_FORMAT_PWG_RASTER; diff --git a/cupsfilters/pdf.h b/cupsfilters/pdf.h index f40410117..a66197cc0 100644 --- a/cupsfilters/pdf.h +++ b/cupsfilters/pdf.h @@ -36,7 +36,7 @@ struct _cf_opt cf_opt_t *next; }; -typedef struct iterate_data_s // *** Helper structure for PDF page iteration *** +typedef struct iterate_data_s // Helper structure for PDF page iteration { cf_pdf_t *pdf; // PDF document pdfio_dict_t *page_dict; // Current page dictionary diff --git a/cupsfilters/pdftopdf-private.h b/cupsfilters/pdftopdf-private.h index 70d58240e..009369c23 100644 --- a/cupsfilters/pdftopdf-private.h +++ b/cupsfilters/pdftopdf-private.h @@ -29,7 +29,7 @@ typedef enum { an_locked_contents = 1 << 9 // Locked contents } pdf_annotation_flag; -typedef struct // **** Document information **** +typedef struct // Document information { cf_logfunc_t logfunc; // Log function void *logdata; // Log data @@ -44,7 +44,7 @@ typedef struct { pdfio_obj_t *obj; // Track object pointers for cycle detection } VisitedObj; -typedef struct xform_document_s // *** Document information *** +typedef struct xform_document_s // Document information { const char *filename, // Document filename *format; // Document format @@ -56,7 +56,7 @@ typedef struct xform_document_s // *** Document information *** num_pages; // Number of pages to print in document } xform_document_t; -typedef struct xform_page_s // *** Output page *** +typedef struct xform_page_s // Output page { pdfio_file_t *pdf; // Output PDF file size_t layout; // Current layout cell @@ -68,7 +68,7 @@ typedef struct xform_page_s // *** Output page *** pdfio_stream_t *output; // Output page stream } xform_page_t; -typedef struct xform_page_ext_s // *** Output page *** +typedef struct xform_page_ext_s // Output page { pdfio_file_t *pdf; // Output PDF file pdfio_obj_t **input; // Input page objects @@ -80,7 +80,7 @@ typedef struct xform_page_ext_s // *** Output page *** } xform_page_ext_t; -typedef struct xform_prepare_s // *** Preparation data *** +typedef struct xform_prepare_s // Preparation data { cf_filter_options_t *options; // Print options cups_array_t *errors; // Error messages diff --git a/cupsfilters/pdftoraster.c b/cupsfilters/pdftoraster.c index 5d4c9432c..386f2f0fb 100644 --- a/cupsfilters/pdftoraster.c +++ b/cupsfilters/pdftoraster.c @@ -75,7 +75,7 @@ #define MAX_BYTES_PER_PIXEL 32 extern int errno; -typedef struct cms_profile_s // *** Color Management System profile structure *** +typedef struct cms_profile_s // Color Management System profile structure { // for color profiles cmsHPROFILE colorProfile; // color profile @@ -101,7 +101,7 @@ init_cms_profile_t(cms_profile_t *profile) // I - profile structure to init profile->cm_disabled = 0; } -typedef struct pdftoraster_doc_s // *** PDF to Raster Document Structure *** +typedef struct pdftoraster_doc_s // PDF to Raster Document Structure { char *input_filename; // Input PDF file name int pwgraster; // Whether to output PWG Raster (1) or CUPS Raster (0) @@ -144,7 +144,7 @@ typedef unsigned char *(*convert_line_func)(unsigned char *src, pdftoraster_doc_t* doc, convert_cspace_func convertCSpace); -typedef struct pdf_conversion_function_s // *** PDF Conversion Function Structure *** +typedef struct pdf_conversion_function_s // PDF Conversion Function Structure { convert_cspace_func convertCSpace; // Function for conversion of colorspaces convert_line_func convertLineOdd; // Function to modify raster data of a line @@ -789,7 +789,7 @@ line_swap_bit(unsigned char *src, return (dst); } -typedef struct func_table_s // *** Function Table for Special Edge Cases *** +typedef struct func_table_s // Function Table for Special Edge Cases { enum cups_cspace_e cspace; // Colour Space unsigned int bitsPerPixel; // Bits per Pixel diff --git a/cupsfilters/pwgtopdf.c b/cupsfilters/pwgtopdf.c index 13bc68652..4b2331b17 100644 --- a/cupsfilters/pwgtopdf.c +++ b/cupsfilters/pwgtopdf.c @@ -78,10 +78,10 @@ // Compression method for providing data to PCLm Streams. typedef enum compression_method_e { - DCT_DECODE = 0, - FLATE_DECODE, - RLE_DECODE -} compression_method_t; + DCT_DECODE = 0, // JPEG compression + FLATE_DECODE, // zlib compression + RLE_DECODE // Run Length Encoding compression +} compression_method_t; // Compression method for providing data to PCLm Streams. // Color conversion function typedef unsigned char *(*convert_function)(unsigned char *src, @@ -93,71 +93,63 @@ typedef unsigned char *(*bit_convert_function)(unsigned char *src, unsigned char *dst, unsigned int bytes); -typedef struct pwgtopdf_doc_s // **** Document information **** +typedef struct pwgtopdf_doc_s // Document information { - cmsHPROFILE colorProfile; // ICC Profile to be applied to - // PDF - int cm_disabled; // Flag raised if color - // management is disabled - convert_function conversion_function; // Raster color conversion - // function + cmsHPROFILE colorProfile; // ICC Profile to be applied to PDF + int cm_disabled; // Flag raised if color management is disabled + convert_function conversion_function; // Raster color conversion function bit_convert_function bit_function; // Raster bit function FILE *outputfp; // Temporary file, if any - cf_logfunc_t logfunc; // Logging function, NULL for no - // logging - void *logdata; // User data for logging - // function, can be NULL - cf_filter_iscanceledfunc_t iscanceledfunc; // Function returning 1 when - // job is canceled, NULL for not - // supporting stop on cancel - void *iscanceleddata; // User data for is-canceled - // function, can be NULL + cf_logfunc_t logfunc; // Logging function, NULL for no logging + void *logdata; // User data for logging function, can be NULL + cf_filter_iscanceledfunc_t iscanceledfunc; // Function returning 1 when job is canceled, NULL for not supporting stop on cancel + void *iscanceleddata; // User data for is-canceled function, can be NULL } pwgtopdf_doc_t; // PDF info structure struct pdf_info{ - pdfio_file_t *pdf; - pdfio_dict_t *page_dict; - pdfio_obj_t *page; - pdfio_stream_t *page_stream; - char *temp_filename; - - unsigned pagecount; - unsigned width; - unsigned height; - unsigned line_bytes; - unsigned bpp; - unsigned bpc; - - unsigned pclm_num_strips; - unsigned pclm_strip_height_preferred; + pdfio_file_t *pdf; // PDF file + pdfio_dict_t *page_dict; // Page dictionary for the current page + pdfio_obj_t *page; // Page object for the current page + pdfio_stream_t *page_stream; // Page content stream for the current page + char *temp_filename; // Temporary filename for the PDF file + + unsigned pagecount; // Number of pages in the PDF + unsigned width; // Width of the page in pixels + unsigned height; // Height of the page in pixels + unsigned line_bytes; // Number of bytes per line + unsigned bpp; // Bits per pixel + unsigned bpc; // Bits per component + + unsigned pclm_num_strips; // Number of strips in the PCLm raster data + unsigned pclm_strip_height_preferred; // Preferred strip height for PCLm raster data - unsigned *pclm_strip_height; - size_t pclm_strip_height_size; + unsigned *pclm_strip_height; // Array of strip heights for PCLm raster data + size_t pclm_strip_height_size; // Size of the pclm_strip_height array - unsigned *pclm_strip_height_supported; - size_t pclm_strip_height_supported_size; + unsigned *pclm_strip_height_supported; // Array of supported strip heights for PCLm raster data + size_t pclm_strip_height_supported_size; // Size of the pclm_strip_height_supported array - compression_method_t *pclm_compression_method_preferred; - size_t pclm_compression_method_preferred_size; + compression_method_t *pclm_compression_method_preferred; // Array of preferred compression methods for PCLm raster data + size_t pclm_compression_method_preferred_size; // Size of the pclm_compression_method_preferred array - char **pclm_source_resolution_supported; - size_t pclm_source_resolution_supported_size; + char **pclm_source_resolution_supported; // Array of supported source resolutions for PCLm raster data + size_t pclm_source_resolution_supported_size; // Size of the pclm_source_resolution_supported array - char *pclm_source_resolution_default; - char *pclm_raster_back_side; + char *pclm_source_resolution_default; // Default source resolution for PCLm raster data + char *pclm_raster_back_side; // Raster back side for PCLm raster data - char **pclm_strip_data; - size_t *pclm_strip_data_size; + char **pclm_strip_data; // Array of strip data for PCLm raster data + size_t *pclm_strip_data_size; // Array of sizes for each strip data in pclm_strip_data - char *render_intent; - cups_cspace_t color_space; + char *render_intent; // Rendering intent for the PDF + cups_cspace_t color_space; // Color space for the PDF - char *page_data; - size_t page_data_size; - double page_width; - double page_height; - cf_filter_out_format_t outformat; + char *page_data; // Page data for the current page + size_t page_data_size; // Size of the page data for the current page + double page_width; // Width of the page in points + double page_height; // Height of the page in points + cf_filter_out_format_t outformat; // Output format for the PDF }; // @@ -165,7 +157,7 @@ struct pdf_info{ // void -init_pdf_info(struct pdf_info *info) +init_pdf_info(struct pdf_info *info) // initialise pwgtopdf conversion doc { info->pdf = NULL; @@ -219,7 +211,7 @@ typedef void (*pdf_convert_function)(struct pdf_info *info, // 'free_pdf_info()' - Freeing the dynamically allocated memory // -void free_pdf_info(struct pdf_info *info) +void free_pdf_info(struct pdf_info *info) // Freeing the dynamically allocated memory { if (info->pclm_strip_height) { @@ -369,14 +361,11 @@ no_color_conversion(unsigned char *src, // 'split_strings()' - Split a string to a vector of strings given some // delimiters // -// O - std::vector of std::string after splitting -// I - input string to be split -// I - string containing delimiters -// -char** split_strings(const char *str, - const char *delimiters, - size_t *count) +char** // O - std::vector of std::string after splitting + split_strings(const char *str, // I - input string to be split + const char *delimiters, // I - string containing delimiters + size_t *count) // I - number of strings after splitting { *count = 0; if (!str || *str == '\0') @@ -493,14 +482,11 @@ num_digits(int n) // // 'int_to_fwstring()' - Convert a number to fixed width string by padding // with zeroes -// O - converted string -// I - the integee which needs to be converted to string -// I - width of string required // -char* -int_to_fwstring(int n, - int width) +char* // O - converted string +int_to_fwstring(int n, // I - the integee which needs to be converted to string + int width) // I - width of string required { int num_zeroes = width - num_digits(n); if (num_zeroes < 0) @@ -877,26 +863,17 @@ get_cal_gray_array(pdfio_file_t *pdf, // containing the stream data of the various strips // which make up a PCLm page. // -// O - std::vector of QPDFObjectHandle -// I - QPDF object -// I - number of strips per page -// I - std::vector of std::shared_ptr containing data for each strip -// I - strip width -// I - strip height -// I - color space -// I - bits per component -// I - document information -// -static pdfio_obj_t** -make_pclm_strips(pdfio_file_t *pdf, - unsigned num_strips, - char **strip_data, - size_t *strip_data_size, - compression_method_t *compression_methods, - unsigned width, unsigned *strip_height, - cups_cspace_t cs, - unsigned bpc, - pwgtopdf_doc_t *doc) + +static pdfio_obj_t** // O - std::vector of QPDFObjectHandle +make_pclm_strips(pdfio_file_t *pdf, // I - QPDF object + unsigned num_strips, // I - number of strips per page + char **strip_data, // I - std::vector of std::shared_ptr containing data for each strip + size_t *strip_data_size, // I - std::vector of sizes for each strip data in strip_data + compression_method_t *compression_methods, // I - std::vector of preferred compression methods for each strip + unsigned width, unsigned *strip_height, // I - strip width and height + cups_cspace_t cs, // I - color space + unsigned bpc, // I - bits per component + pwgtopdf_doc_t *doc) // I - document information { pdfio_obj_t **strips = (pdfio_obj_t **)malloc(num_strips * sizeof(pdfio_obj_t *)); @@ -1669,6 +1646,10 @@ set_profile(const char *path, return (1); } +// +// 'cfFilterPWGToPDF()' - Convert a PWG raster stream to PDF or PCLm. +// + int // O - Error status cfFilterPWGToPDF(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream diff --git a/cupsfilters/pwgtoraster.c b/cupsfilters/pwgtoraster.c index daaf0f50f..a941d2b05 100644 --- a/cupsfilters/pwgtoraster.c +++ b/cupsfilters/pwgtoraster.c @@ -67,7 +67,7 @@ #define MAX_BYTES_PER_PIXEL 32 -typedef struct cms_profile_s // *** for color management *** +typedef struct cms_profile_s // for color management { // for color profiles cmsHPROFILE colorProfile; // ICC profile @@ -79,7 +79,7 @@ typedef struct cms_profile_s // *** for color management *** cf_cm_calibration_t cm_calibrate; // Status of CUPS color management } cms_profile_t; -typedef struct pwgtoraster_doc_s // *** Document information *** +typedef struct pwgtoraster_doc_s // Document information { cf_filter_data_t *data; // Filter data bool page_size_requested; // Flag indicating if page size is requested @@ -117,7 +117,7 @@ typedef unsigned char *(*convert_line_func)(unsigned char *src, pwgtoraster_doc_t* doc, convert_cspace_func convertCSpace); -typedef struct conversion_function_s // *** Conversion function information *** +typedef struct conversion_function_s // Conversion function information { convert_cspace_func convertCSpace; // Function for conversion of colorspaces convert_line_func convertLineOdd; // Function to modify raster data of a line @@ -609,7 +609,7 @@ line_swap_bit(unsigned char *src, } -typedef struct func_table_s // *** Conversion function table for special cases *** +typedef struct func_table_s // Conversion function table for special cases { enum cups_cspace_e cspace; // CUPS colorspace unsigned int bitsPerPixel; // Bits per pixel diff --git a/cupsfilters/raster.c b/cupsfilters/raster.c index d331a6d01..70ff19862 100644 --- a/cupsfilters/raster.c +++ b/cupsfilters/raster.c @@ -154,7 +154,7 @@ cfRasterColorSpaceString(cups_cspace_t cspace) // I - cupsColorSpace value // -// 'cfRasterPrepareHeader() - This function creates a CUPS/PWG Raster +// 'cfRasterPrepareHeader()' - This function creates a CUPS/PWG Raster // header for Raster output based on the // printer and job properties supplied to // the calling filter functions, printer @@ -560,7 +560,7 @@ cfRasterPrepareHeader(cups_page_header_t *h, // I - Raster header // -// 'cfRasterSetColorSpace() - Update a given CUPS/PWG Raster header to +// 'cfRasterSetColorSpace()' - Update a given CUPS/PWG Raster header to // the desired color mode, color space, and // color depth. We supply one of the // printer IPP attributes urf-supported or diff --git a/cupsfilters/raster.h b/cupsfilters/raster.h index 91470b932..b9a832a2b 100644 --- a/cupsfilters/raster.h +++ b/cupsfilters/raster.h @@ -48,20 +48,8 @@ extern "C" { // // Prototypes... // -// -// 'cfRasterColorSpaceString()' - Return a human-readable -// name for the given raster color space. -// extern const char *cfRasterColorSpaceString(cups_cspace_t cspace); - -// -// 'cfRasterPrepareHeader()' - Prepare a CUPS/PWG raster page -// header based on job and printer data. -// -// Returns 0 on success, non-zero on error. -// - extern int cfRasterPrepareHeader(cups_page_header_t *h, cf_filter_data_t *data, cf_filter_out_format_t @@ -70,15 +58,6 @@ extern int cfRasterPrepareHeader(cups_page_header_t *h, header_outformat, int no_high_depth, cups_cspace_t *cspace); - -// -// 'cfRasterSetColorSpace()' - Update a raster header with the -// appropriate color space and color depth based on printer -// capabilities and job settings. -// -// Returns 0 on success, -1 on error. -// - extern int cfRasterSetColorSpace(cups_page_header_t *h, const char *available, const char *color_mode, diff --git a/cupsfilters/rastertopwg.c b/cupsfilters/rastertopwg.c index 4971a01a9..daeb745f3 100644 --- a/cupsfilters/rastertopwg.c +++ b/cupsfilters/rastertopwg.c @@ -28,11 +28,9 @@ int // O - Exit status cfFilterRasterToPWG(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream - int inputseekable, // I - Is input stream seekable? - // (unused) + int inputseekable, // I - Is input stream seekable?(unused) cf_filter_data_t *data, // I - Job and printer data - void *parameters) // I - Filter-specific parameters - // (unused) + void *parameters) // I - Filter-specific parameters(unused) { cups_raster_t *inras; // Input raster stream cups_raster_t *outras; // Output raster stream diff --git a/cupsfilters/test-pdftoraster-copy-height.c b/cupsfilters/test-pdftoraster-copy-height.c index 5b97b38dc..9d618d8d3 100644 --- a/cupsfilters/test-pdftoraster-copy-height.c +++ b/cupsfilters/test-pdftoraster-copy-height.c @@ -32,7 +32,11 @@ test_convert_line(unsigned char *src, unsigned char *dst, return dst; } -int +// +// 'main()' - Run the regression test. +// + +int // O - Exit status main(void) { const unsigned int copy_height = 4; diff --git a/cupsfilters/testfilters.c b/cupsfilters/testfilters.c index 4edfaef8c..a8ab7db3e 100644 --- a/cupsfilters/testfilters.c +++ b/cupsfilters/testfilters.c @@ -114,17 +114,17 @@ parse_filter_chain(const char *filter_chain_str, // I - Comma-separated list return chain; } -/* - * 'create_media_size_range()' - Create a ranged media-size value. - */ - -static ipp_t * /* O - media-col collection */ -create_media_size_range(int min_width, /* I - Minimum x-dimension in 2540ths */ - int max_width, /* I - Maximum x-dimension in 2540ths */ - int min_length, /* I - Minimum x-dimension in 2540ths */ - int max_length) /* I - Maximum y-dimension in 2540ths */ +// +// 'create_media_size_range()' - Create a ranged media-size value. +// + +static ipp_t * // O - media-col collection +create_media_size_range(int min_width, // I - Minimum x-dimension in 2540ths + int max_width, // I - Maximum x-dimension in 2540ths + int min_length, // I - Minimum x-dimension in 2540ths + int max_length) // I - Maximum y-dimension in 2540ths { - ipp_t *media_size = ippNew(); /* media-size value */ + ipp_t *media_size = ippNew(); // media-size value ippAddRange(media_size, IPP_TAG_ZERO, "x-dimension", min_width, max_width); @@ -134,19 +134,19 @@ create_media_size_range(int min_width, /* I - Minimum x-dimension in 2540ths */ } -static ipp_t * /* O - media-col collection */ -create_media_col(const char *media, /* I - Media name */ - const char *source, /* I - Media source, if any */ - const char *type, /* I - Media type, if any */ - ipp_t *media_size,/* I - media-size collection value */ - int bottom, /* I - Bottom margin in 2540ths */ - int left, /* I - Left margin in 2540ths */ - int right, /* I - Right margin in 2540ths */ - int top) /* I - Top margin in 2540ths */ +static ipp_t * // O - media-col collection +create_media_col(const char *media, // I - Media name + const char *source, // I - Media source, if any + const char *type, // I - Media type, if any + ipp_t *media_size,// I - media-size collection value + int bottom, // I - Bottom margin in 2540ths + int left, // I - Left margin in 2540ths + int right, // I - Right margin in 2540ths + int top) // I - Top margin in 2540ths { - ipp_t *media_col = ippNew(); /* media-col value */ - char media_key[256]; /* media-key value */ - const char *media_key_suffix = ""; /* media-key suffix */ + ipp_t *media_col = ippNew(); // media-col value + char media_key[256]; // media-key value + const char *media_key_suffix = ""; // media-key suffix if (bottom == 0 && left == 0 && right == 0 && top == 0) @@ -187,15 +187,15 @@ create_media_col(const char *media, /* I - Media name */ } -/* - * 'create_media_size()' - Create a media-size value. - */ +// +// 'create_media_size()' - Create a media-size value. +// -static ipp_t * /* O - media-col collection */ -create_media_size(int width, /* I - x-dimension in 2540ths */ - int length) /* I - y-dimension in 2540ths */ +static ipp_t * // O - media-col collection +create_media_size(int width, // I - x-dimension in 2540ths + int length) // I - y-dimension in 2540ths { - ipp_t *media_size = ippNew(); /* media-size value */ + ipp_t *media_size = ippNew(); // media-size value ippAddInteger(media_size, IPP_TAG_ZERO, IPP_TAG_INTEGER, "x-dimension", width); @@ -207,23 +207,6 @@ create_media_size(int width, /* I - x-dimension in 2540ths */ // // 'test_wrapper()' - Utilizes libcupsfilters API for running a particular test // -// - - -/* -int // O - Exit status -test_wrapper( - int num_clargs, // I - Number of command-line args - char *clargs[], // I - Command-line arguments - void *parameters, // I - Filter function parameters - int *JobCanceled, // I - Var set to 1 when job canceled - ipp_t* emulated_ipp, - char* inputMIME, - char* outputMIME, - char* inputFile, - char* outputFile) -{ -*/ int // O - Exit status test_wrapper( @@ -236,12 +219,11 @@ test_wrapper( char* outputMIME, // I - Output MIME type char* inputFile, // I - Input file name char* outputFile, // I - Output file name - cups_array_t *filter_chain) + cups_array_t *filter_chain) // I - Array of filters in the chain { int inputfd; // Print file descriptor int outputfd; // File Descriptor for Output File - int inputseekable = 0; // Is the input seekable (actual file - // not stdin)? + int inputseekable = 0; // Is the input seekable (actual file not stdin)? int num_options = 0; // Number of print options cups_option_t *options = NULL; // Print options cf_filter_data_t filter_data; @@ -382,35 +364,35 @@ test_wrapper( return retval; } -/* - * 'load_legacy_attributes()' - Load IPP attributes using the old ippserver - * options. - */ +// +// 'load_legacy_attributes()' - Load IPP attributes using the old ippserver +// options. +// -static ipp_t * /* O - IPP attributes or `NULL` on error */ +static ipp_t * // O - IPP attributes or `NULL` on error load_legacy_attributes( - const char *make, /* I - Manufacturer name */ - const char *model, /* I - Model name */ - int ppm, /* I - pages-per-minute */ - int ppm_color, /* I - pages-per-minute-color */ - int duplex, /* I - Duplex support? */ - cups_array_t *docformats) /* I - document-format-supported values */ + const char *make, // I - Manufacturer name + const char *model, // I - Model name + int ppm, // I - pages-per-minute + int ppm_color, // I - pages-per-minute-color + int duplex, // I - Duplex support? + cups_array_t *docformats) // I - document-format-supported values { - size_t i; /* Looping var */ - ipp_t *attrs, /* IPP attributes */ - *col; /* Collection value */ - ipp_attribute_t *attr; /* Current attribute */ - char device_id[1024],/* printer-device-id */ - *ptr, /* Pointer into device ID */ - make_model[128];/* printer-make-and-model */ - const char *format, /* Current document format */ - *prefix; /* Prefix for device ID */ - size_t num_media; /* Number of media */ - const char * const *media; /* List of media */ - size_t num_ready; /* Number of loaded media */ - const char * const *ready; /* List of loaded media */ - pwg_media_t *pwg; /* PWG media size information */ + size_t i; // Looping var + ipp_t *attrs, // IPP attributes + *col; // Collection value + ipp_attribute_t *attr; // Current attribute + char device_id[1024], // printer-device-id + *ptr, // Pointer into device ID + make_model[128];// printer-make-and-model + const char *format, // Current document format + *prefix; // Prefix for device ID + size_t num_media; // Number of media + const char * const *media; // List of media + size_t num_ready; // Number of loaded media + const char * const *ready; // List of loaded media + pwg_media_t *pwg; // PWG media size information static const char * const media_supported[] = { /* media-supported values */ "na_letter_8.5x11in", /* Letter */ diff --git a/cupsfilters/testpdf1.c b/cupsfilters/testpdf1.c index 9c54d5afc..dec27043a 100644 --- a/cupsfilters/testpdf1.c +++ b/cupsfilters/testpdf1.c @@ -9,7 +9,11 @@ #include "debug-internal.h" #include -int +// +// 'main()' - Run the regression test. +// + +int // O - Exit status main() { _cf_pdf_out_t *pdf; @@ -54,7 +58,6 @@ main() ">>\n" "endobj\n", obj, PageWidth, PageLength, cobj, font_obj); - // TODO: into pdf-> _cfPDFOutAddPage(pdf, obj); _cfPDFOutFinishPDF(pdf); From 4594e1497eb4e1413e0e9604a0201bd26461cf44 Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Sun, 13 Sep 2026 02:25:25 +0530 Subject: [PATCH 21/24] revert: testfilters.c to previous state --- cupsfilters/testfilters.c | 208 ++++++++++++++++++++------------------ 1 file changed, 107 insertions(+), 101 deletions(-) diff --git a/cupsfilters/testfilters.c b/cupsfilters/testfilters.c index a8ab7db3e..c25bd9876 100644 --- a/cupsfilters/testfilters.c +++ b/cupsfilters/testfilters.c @@ -18,15 +18,15 @@ # define cupsParseOptions(arg, end, num_options, options) cupsParseOptions(arg, num_options, options) #endif +/* + * 'remove_white_space()' - Remove white spaces from beginning and end of a string + */ typedef int (*cf_filter_func_t)(int input_fd, int output_fd, int input_seekable, cf_filter_data_t *data, void *parameters); -// -// 'remove_white_space()' - Remove white spaces from beginning and end of a string -// - -char* // O - Pointer to the modified string -remove_white_space(char* str) // I - Input string +char* +remove_white_space( + char* str) { char *end; while(isspace((unsigned char)*str)) str++; @@ -49,12 +49,8 @@ typedef struct { void *(*param_generator)(const char *output_mime); } FilterMapping; -// -// 'ghostscript_param_gen()' - Generate parameters for the ghostscript filter based on output MIME type. -// - -void // O - Pointer to parameters structure, or NULL on error -*ghostscript_param_gen(const char *output_mime) // I - Output MIME type +void +*ghostscript_param_gen(const char *output_mime) { cf_filter_out_format_t *out = malloc(sizeof(cf_filter_out_format_t)); if (strcasecmp(output_mime, "application/pdf") == 0) { @@ -82,13 +78,9 @@ FilterMapping filter_mappings[] = { { "texttopdf", cfFilterTextToPDF, NULL }, }; -// -// 'cfFilterFilterInChain()' - Call a filter function in the chain. -// - -cups_array_t* // O - Array of filters in the chain -parse_filter_chain(const char *filter_chain_str, // I - Comma-separated list of filter names - const char *output_mime) // I - Output MIME type +cups_array_t* +parse_filter_chain(const char *filter_chain_str, + const char *output_mime) { cups_array_t *chain = cupsArrayNew(NULL, NULL, NULL, 0, NULL, NULL); char *saveptr; @@ -114,17 +106,17 @@ parse_filter_chain(const char *filter_chain_str, // I - Comma-separated list return chain; } -// -// 'create_media_size_range()' - Create a ranged media-size value. -// +/* + * 'create_media_size_range()' - Create a ranged media-size value. + */ -static ipp_t * // O - media-col collection -create_media_size_range(int min_width, // I - Minimum x-dimension in 2540ths - int max_width, // I - Maximum x-dimension in 2540ths - int min_length, // I - Minimum x-dimension in 2540ths - int max_length) // I - Maximum y-dimension in 2540ths +static ipp_t * /* O - media-col collection */ +create_media_size_range(int min_width, /* I - Minimum x-dimension in 2540ths */ + int max_width, /* I - Maximum x-dimension in 2540ths */ + int min_length, /* I - Minimum x-dimension in 2540ths */ + int max_length) /* I - Maximum y-dimension in 2540ths */ { - ipp_t *media_size = ippNew(); // media-size value + ipp_t *media_size = ippNew(); /* media-size value */ ippAddRange(media_size, IPP_TAG_ZERO, "x-dimension", min_width, max_width); @@ -134,19 +126,19 @@ create_media_size_range(int min_width, // I - Minimum x-dimension in 2540ths } -static ipp_t * // O - media-col collection -create_media_col(const char *media, // I - Media name - const char *source, // I - Media source, if any - const char *type, // I - Media type, if any - ipp_t *media_size,// I - media-size collection value - int bottom, // I - Bottom margin in 2540ths - int left, // I - Left margin in 2540ths - int right, // I - Right margin in 2540ths - int top) // I - Top margin in 2540ths +static ipp_t * /* O - media-col collection */ +create_media_col(const char *media, /* I - Media name */ + const char *source, /* I - Media source, if any */ + const char *type, /* I - Media type, if any */ + ipp_t *media_size,/* I - media-size collection value */ + int bottom, /* I - Bottom margin in 2540ths */ + int left, /* I - Left margin in 2540ths */ + int right, /* I - Right margin in 2540ths */ + int top) /* I - Top margin in 2540ths */ { - ipp_t *media_col = ippNew(); // media-col value - char media_key[256]; // media-key value - const char *media_key_suffix = ""; // media-key suffix + ipp_t *media_col = ippNew(); /* media-col value */ + char media_key[256]; /* media-key value */ + const char *media_key_suffix = ""; /* media-key suffix */ if (bottom == 0 && left == 0 && right == 0 && top == 0) @@ -187,15 +179,15 @@ create_media_col(const char *media, // I - Media name } -// -// 'create_media_size()' - Create a media-size value. -// +/* + * 'create_media_size()' - Create a media-size value. + */ -static ipp_t * // O - media-col collection -create_media_size(int width, // I - x-dimension in 2540ths - int length) // I - y-dimension in 2540ths +static ipp_t * /* O - media-col collection */ +create_media_size(int width, /* I - x-dimension in 2540ths */ + int length) /* I - y-dimension in 2540ths */ { - ipp_t *media_size = ippNew(); // media-size value + ipp_t *media_size = ippNew(); /* media-size value */ ippAddInteger(media_size, IPP_TAG_ZERO, IPP_TAG_INTEGER, "x-dimension", width); @@ -204,26 +196,44 @@ create_media_size(int width, // I - x-dimension in 2540ths return (media_size); } -// -// 'test_wrapper()' - Utilizes libcupsfilters API for running a particular test -// +/* + * 'test_wrapper()' - Utilizes libcupsfilters API for running a particular test + * + */ -int // O - Exit status + +/* +int // O - Exit status test_wrapper( - int num_clargs, // I - Number of command-line args - char *clargs[], // I - Command-line arguments - void *parameters, // I - Filter function parameters - int *JobCanceled, // I - Var set to 1 when job canceled - ipp_t* emulated_ipp, // I - Emulated printer IPP attributes - char* inputMIME, // I - Input MIME type - char* outputMIME, // I - Output MIME type - char* inputFile, // I - Input file name - char* outputFile, // I - Output file name - cups_array_t *filter_chain) // I - Array of filters in the chain + int num_clargs, // I - Number of command-line args + char *clargs[], // I - Command-line arguments + void *parameters, // I - Filter function parameters + int *JobCanceled, // I - Var set to 1 when job canceled + ipp_t* emulated_ipp, + char* inputMIME, + char* outputMIME, + char* inputFile, + char* outputFile) +{ +*/ + +int +test_wrapper( + int num_clargs, + char *clargs[], + void *parameters, + int *JobCanceled, + ipp_t* emulated_ipp, + char* inputMIME, + char* outputMIME, + char* inputFile, + char* outputFile, + cups_array_t *filter_chain) { int inputfd; // Print file descriptor int outputfd; // File Descriptor for Output File - int inputseekable = 0; // Is the input seekable (actual file not stdin)? + int inputseekable = 0; // Is the input seekable (actual file + // not stdin)? int num_options = 0; // Number of print options cups_option_t *options = NULL; // Print options cf_filter_data_t filter_data; @@ -364,35 +374,35 @@ test_wrapper( return retval; } -// -// 'load_legacy_attributes()' - Load IPP attributes using the old ippserver -// options. -// +/* + * 'load_legacy_attributes()' - Load IPP attributes using the old ippserver + * options. + */ -static ipp_t * // O - IPP attributes or `NULL` on error +static ipp_t * /* O - IPP attributes or `NULL` on error */ load_legacy_attributes( - const char *make, // I - Manufacturer name - const char *model, // I - Model name - int ppm, // I - pages-per-minute - int ppm_color, // I - pages-per-minute-color - int duplex, // I - Duplex support? - cups_array_t *docformats) // I - document-format-supported values + const char *make, /* I - Manufacturer name */ + const char *model, /* I - Model name */ + int ppm, /* I - pages-per-minute */ + int ppm_color, /* I - pages-per-minute-color */ + int duplex, /* I - Duplex support? */ + cups_array_t *docformats) /* I - document-format-supported values */ { - size_t i; // Looping var - ipp_t *attrs, // IPP attributes - *col; // Collection value - ipp_attribute_t *attr; // Current attribute - char device_id[1024], // printer-device-id - *ptr, // Pointer into device ID - make_model[128];// printer-make-and-model - const char *format, // Current document format - *prefix; // Prefix for device ID - size_t num_media; // Number of media - const char * const *media; // List of media - size_t num_ready; // Number of loaded media - const char * const *ready; // List of loaded media - pwg_media_t *pwg; // PWG media size information + size_t i; /* Looping var */ + ipp_t *attrs, /* IPP attributes */ + *col; /* Collection value */ + ipp_attribute_t *attr; /* Current attribute */ + char device_id[1024],/* printer-device-id */ + *ptr, /* Pointer into device ID */ + make_model[128];/* printer-make-and-model */ + const char *format, /* Current document format */ + *prefix; /* Prefix for device ID */ + size_t num_media; /* Number of media */ + const char * const *media; /* List of media */ + size_t num_ready; /* Number of loaded media */ + const char * const *ready; /* List of loaded media */ + pwg_media_t *pwg; /* PWG media size information */ static const char * const media_supported[] = { /* media-supported values */ "na_letter_8.5x11in", /* Letter */ @@ -1100,14 +1110,15 @@ load_legacy_attributes( } -// -// 'run_test()' - Runs a particular test case -// +/* + * 'run_test()' - Runs a particular test case + * + */ -int // O - Exit status +int run_test( - char * test_case, // I - Test case string - char * currentFile) // I - Current file name + char * test_case, + char * currentFile) { cups_array_t *filter_chain = NULL; @@ -1256,13 +1267,8 @@ run_test( } -// -// 'main()' - Main entry point for the test filter program. -// - -int // O - Exit status - main(int argc, // I - Number of command-line args - char *argv[]) // I - Command-line arguments +int main(int argc, // I - Number of command-line args + char *argv[]) // I - Command-line arguments{ { char *file_name; // File Name of Input Test File FILE *fp; // File Pointer @@ -1329,4 +1335,4 @@ int // O - Exit status fclose(fp); return fail_cnt; -} +} \ No newline at end of file From 3645d69696fc88b3e33e5293563b711157cbb04b Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Sun, 13 Sep 2026 04:13:25 +0530 Subject: [PATCH 22/24] Improve Doc of testfilters.c --- cupsfilters/testfilters.c | 100 ++++++++++++++++++-------------------- 1 file changed, 47 insertions(+), 53 deletions(-) diff --git a/cupsfilters/testfilters.c b/cupsfilters/testfilters.c index c25bd9876..cd0c84ef1 100644 --- a/cupsfilters/testfilters.c +++ b/cupsfilters/testfilters.c @@ -18,15 +18,15 @@ # define cupsParseOptions(arg, end, num_options, options) cupsParseOptions(arg, num_options, options) #endif -/* - * 'remove_white_space()' - Remove white spaces from beginning and end of a string - */ +typedef int (*cf_filter_func_t)(int input_fd, int output_fd, int input_seekable, cf_filter_data_t *data, void *parameters); // Function pointer type for filter functions -typedef int (*cf_filter_func_t)(int input_fd, int output_fd, int input_seekable, cf_filter_data_t *data, void *parameters); +// +// 'remove_white_space()' - Remove white spaces from beginning and end of a string +// -char* +char* // O - Pointer to the modified string remove_white_space( - char* str) + char* str) // I - Input string { char *end; while(isspace((unsigned char)*str)) str++; @@ -49,8 +49,12 @@ typedef struct { void *(*param_generator)(const char *output_mime); } FilterMapping; -void -*ghostscript_param_gen(const char *output_mime) +// +// 'ghostscript_param_gen()' - Generate parameters for the ghostscript filter based on output MIME type. +// + +void // O - Pointer to parameters structure, or NULL on error +*ghostscript_param_gen(const char *output_mime) // I - Output MIME type { cf_filter_out_format_t *out = malloc(sizeof(cf_filter_out_format_t)); if (strcasecmp(output_mime, "application/pdf") == 0) { @@ -78,9 +82,13 @@ FilterMapping filter_mappings[] = { { "texttopdf", cfFilterTextToPDF, NULL }, }; -cups_array_t* -parse_filter_chain(const char *filter_chain_str, - const char *output_mime) +// +// 'parse_filter_chain()' - Parse a filter chain string into an array of filter functions and their parameters. +// + +cups_array_t* // O - Array of filter functions and their parameters +parse_filter_chain(const char *filter_chain_str, // I - Filter chain string (comma-separated) + const char *output_mime) // I - Output MIME type { cups_array_t *chain = cupsArrayNew(NULL, NULL, NULL, 0, NULL, NULL); char *saveptr; @@ -196,44 +204,26 @@ create_media_size(int width, /* I - x-dimension in 2540ths */ return (media_size); } -/* - * 'test_wrapper()' - Utilizes libcupsfilters API for running a particular test - * - */ - +// +// 'test_wrapper()' - Utilizes libcupsfilters API for running a particular test +// -/* -int // O - Exit status -test_wrapper( - int num_clargs, // I - Number of command-line args - char *clargs[], // I - Command-line arguments - void *parameters, // I - Filter function parameters - int *JobCanceled, // I - Var set to 1 when job canceled - ipp_t* emulated_ipp, - char* inputMIME, - char* outputMIME, - char* inputFile, - char* outputFile) -{ -*/ - -int +int // O - Exit status test_wrapper( - int num_clargs, - char *clargs[], - void *parameters, - int *JobCanceled, - ipp_t* emulated_ipp, - char* inputMIME, - char* outputMIME, - char* inputFile, - char* outputFile, - cups_array_t *filter_chain) + int num_clargs, // I - Number of command-line arguments + char *clargs[], // I - Command-line arguments + void *parameters, // I - Filter function parameters + int *JobCanceled, // I - Variable set to 1 when job is canceled + ipp_t* emulated_ipp, // I - Emulated IPP attributes + char* inputMIME, // I - Input MIME type + char* outputMIME, // I - Output MIME type + char* inputFile, // I - Input file name + char* outputFile, // I - Output file name + cups_array_t *filter_chain) // I - Array of filter functions and their parameters { int inputfd; // Print file descriptor int outputfd; // File Descriptor for Output File - int inputseekable = 0; // Is the input seekable (actual file - // not stdin)? + int inputseekable = 0; // Is the input seekable (actual file not stdin)? int num_options = 0; // Number of print options cups_option_t *options = NULL; // Print options cf_filter_data_t filter_data; @@ -1110,15 +1100,14 @@ load_legacy_attributes( } -/* - * 'run_test()' - Runs a particular test case - * - */ +// +// 'run_test()' - Runs a particular test case +// -int +int // O - Exit status run_test( - char * test_case, - char * currentFile) + char * test_case, // I - Test case string + char * currentFile) // I - Current file name { cups_array_t *filter_chain = NULL; @@ -1267,8 +1256,13 @@ run_test( } -int main(int argc, // I - Number of command-line args - char *argv[]) // I - Command-line arguments{ +// +// 'main()' - Main entry point for the test program +// + +int // O - Exit status + main(int argc, // I - Number of command-line args + char *argv[]) // I - Command-line arguments { char *file_name; // File Name of Input Test File FILE *fp; // File Pointer From e8b0e592729a360a4ec005965d2e447caf8afb96 Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Sat, 19 Sep 2026 12:57:14 +0530 Subject: [PATCH 23/24] fix: resolve CodeQL security issues in testfilters.c --- cupsfilters/testfilters.c | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/cupsfilters/testfilters.c b/cupsfilters/testfilters.c index cd0c84ef1..18cd28920 100644 --- a/cupsfilters/testfilters.c +++ b/cupsfilters/testfilters.c @@ -1139,7 +1139,8 @@ run_test( token = remove_white_space(token); //printf( "%s\n", token ); //printing each token - strcpy(inputFileName, token); + strncpy(inputFileName, token, sizeof(inputFileName) - 1); + inputFileName[sizeof(inputFileName) - 1] = '\0'; int token_index = 1; @@ -1277,6 +1278,11 @@ int // O - Exit status return EXIT_FAILURE; } file_name = argv[1]; + // Validate that file_name doesn't contain suspicious path traversal + if (strchr(file_name, '/') != NULL || strchr(file_name, '\\') != NULL) { + fprintf(stderr, "Invalid file path\n"); + return EXIT_FAILURE; + } fp = fopen(file_name, "r"); if (!fp) { From d0ff353fe599c018b3ad9f33b62584f81893a2f3 Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Sat, 19 Sep 2026 13:09:23 +0530 Subject: [PATCH 24/24] Revert "fix: resolve CodeQL security issues in testfilters.c" This reverts commit e8b0e592729a360a4ec005965d2e447caf8afb96. --- cupsfilters/testfilters.c | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/cupsfilters/testfilters.c b/cupsfilters/testfilters.c index 18cd28920..cd0c84ef1 100644 --- a/cupsfilters/testfilters.c +++ b/cupsfilters/testfilters.c @@ -1139,8 +1139,7 @@ run_test( token = remove_white_space(token); //printf( "%s\n", token ); //printing each token - strncpy(inputFileName, token, sizeof(inputFileName) - 1); - inputFileName[sizeof(inputFileName) - 1] = '\0'; + strcpy(inputFileName, token); int token_index = 1; @@ -1278,11 +1277,6 @@ int // O - Exit status return EXIT_FAILURE; } file_name = argv[1]; - // Validate that file_name doesn't contain suspicious path traversal - if (strchr(file_name, '/') != NULL || strchr(file_name, '\\') != NULL) { - fprintf(stderr, "Invalid file path\n"); - return EXIT_FAILURE; - } fp = fopen(file_name, "r"); if (!fp) {