This chapter provides an overview of printer driver processing, followed by a detailed analysis of an example printer driver. The required printer filter/driver options and the reserved and unreserved printer filter/driver options are also covered.
The following topics are discussed in this chapter:
 | Note: The PostScript interpreter, psrip, has been upgraded to an Adobe Level II Configurable PostScript Interpreter (CPSI). Adobe Systems, Inc. imposes strict limitations on the use of the Configurable PostScript Interpreter by developers. Please refer to Appendix H, “Using the Adobe Configurable PostScript Interpreter,” for details. |
A printer driver must perform the following tasks:
Receive and process an input file.
Send formatted data to the printer or to standard out. (The driver can use standard out when sending data to the generic drivers phandler and nethandler.)
Query the printer and receive status information. (This step is optional if phandler or nethandler is used.)
Read and write the printer object database (POD) files.
All printer drivers must read the POD files to determine printer-specific defaults and to maintain the active status file of the POD so that other clients can determine the printer's status. Chapter 5, “Printing Libraries,” describes libpod, the library that provides an API to the POD. Appendix C, “Printer Object Database (POD) File Formats,” defines the file formats for the printer configuration file, the printer status file, and the printer log file in the POD.
Figure 2-1 provides an overview of printer driver processing. Note that this is a simplified overview; the actual steps might be more complex.
Two example printer drivers are provided: laserjetPJL for HP LaserJet printers and phandler for generic parallel printers. The source code files for laserjetPJL are in the directory /usr/impressario/src/drivers/laserjetPJL and the source code files for phandler are in the directory /usr/impressario/src/drivers/phandler. Both drivers follow the steps shown in Figure 2-1, but the laserjetPJL driver is more complex because it also performs data compression. Because this added complexity is not necessary for the example, the focus is on the phandler driver in this chapter.
The example printer driver phandler checks the status of the parallel port while passing data through to the printer. It treats the input as a byte stream and updates the printer status file at various stages of processing.
Among the include files in this program is pod.h, which contains printer status error codes and other defined constants related to printing. The include file plp.h contains information related to the parallel port.
The command-line interface for phandler is
phandler -P printer_name [options] [filename] |
Arguments:
| -P printer_name | The name of the installed printer (required). | |
| filename | The name of the file to send to the printer. Data is read from standard input if no filename is given. |
options can be one or more of the following:
| -e | Exit immediately on error. (The default is not to exit on error.) | |
| -w | Suppress warning messages. | |
| -D | Enable debugging. -D is the lowest level of detail, -D -D is the second level, and -D -D -D is the highest level of detail. The debugging information is appended to the log file. | |
| -L filename | Use filename as the log file for debugging information and errors. The default is to use standard error, which the System V, Release 3 lp spooler redirects to the spooler log file. | |
| -R | Reset the parallel port before sending data. | |
| -K | Ignore interrupts. | |
| -I | Enable sensing of the EOI pin. The default is to ignore the EOI pin. | |
| -B int | Set the size of the internal transfer buffer to int bytes. The default is 1024. Larger buffers enable more page buffering, which may free upstream filters to do more processing while data is being sent to the printer. | |
| -s | Invoke phandler to update the printer's status. Check the parallel port's status unless -u is specified. Update the paper size if -S is specified. | |
| -u | Used only with -s. Don't check the parallel port's status. This allows the driver to ignore the parallel port while it is updating the POD status file. | |
| -S string | Set the paper size (for example, A, A4, Legal) to string and update the POD status file for the printer. | |
| -d | Send an ASCII Control-D (hexadecimal 0x4) at the end of the job. |
To invoke phandler to update the POD data base, enter this command:
/usr/lib/print/phandler -P printername -s -u -K -S A |
This use of phandler only updates the POD data base with the paper size. It ignores the parallel port status, and no information is sent to the parallel port. You normally use this command before invoking any filter that accesses the POD data base to insure that the filter gets the correct paper size.
After updating the POD data base with the paper size, you could send a file to the parallel port with phandler like this:
/usr/lib/print/text2ps -J printername textfile | \ /usr/lib/print/phandler -P printername -K -S A -d |
Here, text2ps is used to convert an ASCII text file to a PostScript file. text2ps uses printername to access the POD and get printer-specific information, such as paper size. Other filters operate similarly to text2ps by accessing the POD for printer-specific information. This is why you run phandler to update the POD status before using a filter.
The output of text2ps is piped to phandler, which sends it to the parallel port while monitoring the printer's status and updating the POD.
This section contains a detailed discussion of the phandler driver. A more detailed example driver is supplied in the /usr/impressario/src/drivers/laserjetPJL directory.
| Note: The Impressario guidelines strictly require drivers to retry errors. Error exits are to be avoided whenever possible so that print jobs do not disappear before the user has a chance to fix the error condition. |
Open the port. If there is an error and you requested exit on error when invoking phandler, then the program writes an error message and exits. Otherwise, when an error occurs, the program continues trying to open the port. It checks every n seconds (where n is the value of error_retry_wait) and writes an error message to the log file after each failed attempt to open the port.
If phandler successfully opens the port, it updates the current printer status to “Busy” in the printer active status file. If the command line contained the -s option (status only), then phandler exits after updating the status. (The kernel closes the port when it exits the program.)
Allocate and set up the buffer. If phandler cannot allocate the buffer, the program exits with an error message. (It exits only because memory allocation errors are very rarely recoverable.)
Begin reading from the input and begin sending data to the parallel port.
Your driver will probably need to process the input data into an appropriate printable format before sending the data to the printer.
If an unrecoverable error occurs while writing to the parallel port, write an error message to the log file, write the faulted state to the printer status configuration file, and exit.
If the input file is empty or unreadable, write an error message to the log file, update the status file, and exit.
The driver uses signal handling to ensure that it is not interrupted in “critical regions,” during which an interrupt could destroy vital files or the printer state.
The command-line options listed in this section must be implemented as specified for any printing filter or driver to be compatible with Impressario. Switch letters have been chosen to maximize the intuitive correlation with function. Additional functionality beyond that listed here must use unreserved switch settings. Please note the following points:
All switches are case sensitive. That is, -P does not have the same meaning as -p.
Printer drivers must accept and ignore all reserved options that are not supported.
Printer drivers must conform to getopts conventions. (See getopts(2) for more information.)
Multiple options on a single line have right-to-left precedence. For example:
-n 1 -n 2
has the same effect as
-n 2
The STIFF file passed to a printer driver may have command-line options embedded in it by psrip, a program that converts PostScript files to STIFF files. Drivers that accept input from psrip must accept and parse these command-line options. A good example is a PostScript file that contains a PostScript command to print 5 copies. psrip parses that PostScript command and embeds -n5 in the STIFF file header. This header file information tells the printer driver to print 5 copies. The laserjetPJL example driver demonstrates how to parse command-line options embedded in a STIFF file. Appendix A, “Stream TIFF Data Format,” details the STIFF header format.
These switches must be supported by all drivers:
| -e | Exit immediately on fault without waiting for faults to clear. The default behavior is to wait indefinitely for faults to clear, polling the device at the error-retry intervals specified in the POD configuration file. This option is used when only a quick query should be done. | ||
| -s | Update the status file. Exit only after successfully doing so. This switch has the highest precedence. If the -e switch is given, exit after one try at reading status. | ||
| -w | Do not report warnings in the status file. Report errors only. | ||
| -D | Enable debugging information. Optionally, more -D switches increase the level of debugging detail. For example, entering
| ||
enables a second level of debugging detail. At least one level of debugging must be supported. | |||
| -P string | The value of string defines the printer name. The printer name is used to find the POD. The printer name is the name given to the printer at installation time. See the libpod(3) reference page for more information. This option is also a required option whenever the driver is invoked. |
Impressario printer drivers must read the libpod printer object database to
determine defaults
maintain the active status portion of the POD database
enable other clients to determine printer status
The following options are reserved and are to be implemented by drivers whose hardware supports them, or by inline filters that process the options before the driver is invoked. You need not implement all options, but every driver must accept or ignore any unimplemented options on this list.
Raster-specific options include the following:
| -f | Flip the image, as if in a mirror. The image is rotated horizontally about the y-axis. Useful for transparencies or decals. | |||||||||
| -p int | Scale the image as if it were being printed on a device with the designated resolution specified in int pixels per inch. This is a convenience switch, since the same effect can be obtained by computing the appropriate scale factor for the image size and destination resolution. | |||||||||
| -r int | Rotate the image counter-clockwise by an angle specified in int degrees. Values outside the range 0-359 should be accepted and modulo converted to a value between 0-359. | |||||||||
| -z float | Zoom the image using proportional scaling, where the floating-point argument is nonnegative. Some values are given below:
|
Engine-specific options include the following:
Output-specific options include the following:
| -L filename | Log errors to filename instead of standard error. The file specified should be opened in append mode. If the file cannot be opened, errors should be reported to standard error instead. | |
| -O filename | Output data to filename instead of the device port or standard output. The file specified should be opened. If the file cannot be opened, data should instead be written to the device or standard output, as appropriate. If this option is used, all status reporting is disabled, because the printer driver is not communicating with the actual device. |