Hewlett-Packard Appliance Printing Development Kit

# Hewlett-Packard Appliance Printing Software Development Kit

#

# Host System Interface

Version | Date | Comments
2.0.0 | 11.29.00 | Version 2.0.0 documentation reflects code changes from code Version 1.1.0. (Note: Documentation and code version numbers are designed to be independent of each other, and may not agree.)

Notice

The information contained in this document is subject to change without notice.

Hewlett-Packard makes no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Hewlett-Packard shall not be liable for errors contained herein or for incidental or consequential damages in connection with the furnishing, performance, or use of this material.

All SDK documentation included in this list, received with the Hewlett-Packard Appliance Printing Software Development Kit, or received at a later date as a result of communication with any Hewlett-Packard employee regarding the Hewlett-Packard Appliance Printing Software Development Kit, is Hewlett-Packard "confidential" information.

Licensee shall not export or re-export the Hewlett-Packard documentation, or copies or variations thereof. Licensee may use Hewlett-Packard documentation only to develop Licensee Printer Drivers for exclusive use only on Hewlett-Packard printers.

Licensee shall assure that all Hewlett-Packard Software and all documentation based on Hewlett-Packard Documentation include the following notice:

"Copyright © [year]

Hewlett-Packard Company.

All Rights Reserved."

Hewlett-Packard Documentation has been developed entirely at private expense and is provided as "Commercial Computer Software" or "restricted computer software." Use, duplication or disclosure by the US Government or a US Government subcontractor is subject to the restrictions set forth in subparagraph (c) (1) (ii) of the Rights in Technical Data and Computer Software clauses in DFARS 252.227-7013 or as set forth in subparagraph (c) (1) and (2) of the Commercial Computer Software-Restricted Rights clauses in FAR 52.227-19, as applicable. The Contractor is Hewlett-Packard Company, 3000 Hanover Street, Palo Alto, California 94304.

Copyright ã 2000

Hewlett-Packard Company.

All rights reserved.

# Host System Interface

##

## Introduction

The Hewlett-Packard Appliance Printing Software Development Kit (SDK) enables system developers to produce a minimal, yet flexible, user-interactive printer driver. Developers are free to create a minimum number of user-interactive commands, or create additional commands by migrating driver error/status codes into Graphic User Interfaces (GUIs) and messages.

The following sections enumerate the use of user commands and interfaces within the printer driver.

> User Interfaces & Guidelines

> Warnings and Errors

> DisplayPrinterStatus

> HTML Help System

> Memory Requirements

> Abstract Class "System Services" To Be Implemented By Host System Interface

> Parallel 1284 Versus USB

> Plug & Play Versus Uni-Directional

## User Interfaces & Guidelines

Drivers built from the SDK core code provide simple printing solutions that do not require extended responses from end users. Developers determine their own number and complexity of GUIs to be presented by their product to the user.

There are a few basic concepts that are necessary to understand in order to instantiate the user interface for a print solution. The simplest concept is to have only one print button (or GUI) allowing the user to initiate a print job. Developers have the option of increasing printer/user interaction by creating a second GUI for example, which the user could use to determine the CurrentMode or other print job options. These other options include:

- Print Area
- Margins
- Rendering and Formatting Options (e.g. eliminate solid backgrounds and invert font colors, send text only)
- Duplex Printing
- Output Tray Selection
- Printer Maintenance Functions (e.g. clean pen)

The following two lists are strongly recommended GUIs and optional GUIs. These lists are recommendations only, and should be modified to meet the needs of the host system and end user.

Strongly Recommended

- Error Dialogue

- Errors that occur at the printing level are reflected to the user in an easily understandable manner.
- Printing Progress
- The user visually sees the status of their print job.
- Printer-Model Selection (for Uni-di)
- In cases where Bi-directional communication is not available, the user should be prompted to select their printer from a supported printer list.
- Driver Version
- Allows the user to find out what Hewlett-Packard print driver version is being used.
- Printer Maintenance Functionality
- Some functionality for printer maintenance should be incorporated. Future maintenance functionality will continue to be added to future SDK releases.

Optional

- Printmode Selection

(including dialogue for mode mismatch) - Allows users to choose print modes such as print quality, grayscale, etc.
- Font Selection & Formatting
(e.g. for email) - Developers may want to give end users a minimal selection of fonts, or the ability to eliminate backgrounds or invert font colors when printing.
- Models Supported In Driver - Allows developers to show users which DeskJet models are supported by the particular print driver.
- Paper size -
Allows the user to choose the paper size (letter vs. legal).
- Margins -
Allows users to alter the margins for a print job.
- Retrieve Image Data At Higher Resolution
(to match capabilities of the printmode) - This feature is recommended for devices that may use low-resolution displays such as televisions.

[Back to top]

## Warnings & Errors, DisplayPrinterStatus, & HTML Help System:

The following three sections are all used to communicate with the end user to solve any problems that may be occurring:

##

### Warnings & Errors:

The SDK has a series of warning and error codes that are used to indicate success or failure of methods. For a complete list, refer to the API Appendix.

Warnings (represented by a value less than zero):

A warning is code that has completely executed, but is notifying the user that a print concern exists. Example: A user has chosen grayscale print mode, but a color pen is installed. A warning is issued to the user, telling them that this is an inefficient use of the pen, that the printed product will not look like they expect it to, but the printer will print with it anyway unless given further direction. At this point, a dialogue box can be sent to the user via a GUI button confirming that they really want to use this setting.

Errors (represented by a value greater than zero):

An error is code that has not completely executed, and is notifying the user that action must be taken. An error is a dialogue with the user that the process did not execute, and the user must take action. Example: When a paper jam occurs during printing, a GUI should be sent to the user indicating that action(s) must be taken before the print job can continue.

[Back to top]

##

### DisplayPrinterStatus:

The method DisplayPrinterStatus is used by the driver to communicate the printer state to the host system and ultimately the end user. The Driver uses DisplayPrinterStatus to inform the host of any error conditions, which the host environment then handles appropriately.

For example, if the printer has a mechanical error, the printer flags that an error has occurred. The driver stops sending data to the printer and calls DisplayPrinterStatus. The host then flashes a GUI conveying the error to the user. The DisplayPrinterStatus method is implemented in the derived host SystemServices class.

DisplayPrinterStatus values can either be recoverable or non-recoverable, and/or display the current status of the print job. The developer should keep this in mind when creating GUIs, and be sure to include a Cancel or OK button if necessary. Some display printer status values are conditions that the user can easily correct and allow the print job to continue.The following is an example of this:

A user submitting a print job incurs an error condition because there is no paper in the paper input tray.The hosting environment should be prompted with a display printer status value of DISPLAY_OUT_OF_PAPER and accordingly prompt the user with a GUI explaining the error condition, and how to resolve it.If the user puts paper into the input tray and hits the resume button on the printer, the display printer status value will be changed and the print job can continue normally.

For recoverable error conditions such as this, the hosting environment will need to continue looping around to check the display printer status value, giving the flexibility of the error condition being resolved on the printer.

The following list of printer statuses describes the condition, whether it’s recoverable or not, and where appropriate, sample text to use in the GUI.

DISPLAY_PRINTING | Condition: | Currently printing - this is a flag that says the job is currently printing.
| Recoverable: | N/A
| Example Text: | "Currently Printing."
DISPLAY_PRINTING_COMPLETE | Condition: | Printing complete.
| Recoverable: | N/A
| Example Text: | "Printing Complete."
DISPLAY_PRINTING_CANCELED | Condition: | Printing canceled.
| Recoverable: | N/A
| Example Text: | "Printing Canceled."
DISPLAY_OFFLINE | Condition: | Printing is currently offline; some Hewlett-Packard printers go offline to flag that an error has occurred.
| Recoverable: | N/A
| Example Text: | "Your printer has gone offline due to an error. Cancel the job, check the printer, and try again."
DISPLAY_BUSY | Condition: | Printer is busy.
| Recoverable: | N/A
| Example Text: | "Printer Busy."
DISPLAY_OUT_OF_PAPER | Condition: | Printer is out of paper.
| Recoverable: | Yes, depending on if the user cancels the job or loads more paper and presses the resume button.
| Example Text: | "The printer is out of paper. Insert paper into the paper tray, and push the resume button on the printer."
DISPLAY_TOP_COVER_OPEN | Condition: | Printer top cover is open.
| Recoverable: | Yes, depending on if the user cancels the job or loads more paper and presses the resume button.
| Example Text: | "The top cover of your printer is open. Close the top cover to resume printing."
DISPLAY_ERROR_TRAP | Condition: | Printer mechanism error, this is a non-recoverable error which usually requires intervention by the user.
| Recoverable: | No
| Example Text: | "The printer is in an error condition. Cancel the job, check your printer, and try to print again."
DISPLAY_NO_PRINTER_FOUND | Condition: | No printer found.
| Recoverable: | Yes, depending on if the user cancels the job. or if there is a printer attached, powers the printer on and presses the resume button.
| Example Text: | "No printer was found. Check to make sure your printer is connected properly and that the power is on. Then push the resume button on the printer to continue printing."
DISPLAY_NO_PEN_DJ400 | Condition: | No pen found in the Hewlett-Packard DJ400 series printer.
| Recoverable: | Yes, depending on if the user cancels the job, or inserts a pen and presses the resume button.
| Example Text: | "The print cartridge is either missing or installed incorrectly. Check the printer cartridge and push the resume button on the printer."
DISPLAY_NO_PEN_DJ600 | Condition: | No pen found in the Hewlett-Packard DJ600 series printer.
| Recoverable: | Yes, depending on if the user cancels the job, or inserts a pen and presses the resume button.
| Example Text: | "The print cartridge is either missing or installed incorrectly. Check the printer cartridge and push the resume button on the printer."
DISPLAY_NO_COLOR_PEN | Condition: | No color pen found on Hewlett-Packard DJ 2 pen products.
| Recoverable: | Yes, depending on if the user cancels the job, or inserts a pen and presses the resume button.
| Example Text: | "The color print cartridge is either missing or installed incorrectly. Check the printer cartridge and push the resume button on the printer."
DISPLAY_NO_BLACK_PEN | Condition: | No black pen found on Hewlett-Packard DJ 2 pen products.
| Recoverable: | Yes, depending on if the user cancels the job, or inserts a pen and presses the resume button.
| Example Text: | "The black print cartridge is either missing or installed incorrectly. Check the printer cartridge and push the resume button on the printer."
DISPLAY_NO_PENS | Condition: | Both pens are missing from Hewlett-Packard DJ 2 pen products.
| Recoverable: | Yes, depending on if the user cancels the job, or inserts a pen and presses the resume button.
| Example Text: | "The print cartridges are either missing or installed incorrectly. Check the printer cartridges and push the resume button on the printer."
DISPLAY_PHOTO_PEN_WARN | Condition: | Indicates photo pen in a printer that cannot make use of it.
| Recoverable: | No
| Example Text: | "Photo print cartridges are not supported. Cancel the print job and insert the correct print cartridges."
DISPLAY_PRINTER_NOT_SUPPORTED | Condition: | Printer not supported by driver
| Recoverable: | No
| Example Text: | "This printer is not supported."
DISPLAY_COMM_PROBLEM | Condition: | Communication problem with printer
| Recoverable: | No
| Example Text: | "Cannot communicate with the printer."
DISPLAY_CANT_ID_PRINTER | Condition: | Cannot id printer
| Recoverable: | No
| Example Text: | "Cannot properly identify the printer."

A second button may also be added to a GUI providing users access to an html help support system. Refer to the following HTML Help System for more information.

[Back to top]

### HTML Help System

Print Drivers derived from this SDK can further help end users solve printer related problems/issues through a html based help system provided over the web by HP. These html pages can describe in detail to a user how to resolve issues with there printing experience. The also provide answers to questions about printing in general on appliance type devices. Access to these pages is made via a URL call to a Perl script hosted on a HP server called "errorparse.cgi". Parameters are placed at the end of the URL in a format as shown below allowing the Perl script to decide which pages should be sent to the calling client.

Refer to the table in htmlerrtble.xls to determine which values correlate with what errors and Refspec.html located in the html help directory for more detailed information about the HTML help system.

http://www.hp.com/embed/hpapdk_help?errorcode=5&printermodel=5&language=en-US&systemID=0

In the URL above is an example of a device trying to print to a DJ690 that has an out of paper error condition. The page that would be returned by a call to this URL is an "out of paper error" web page in English for a DJ690 running under the generic systemID number that will provide text and graphics showing the user how to solve the error condition.

This URL should be built in the glue code of a hosting device, where access can be made to the errorcode and printermodel parameters. The values for the errorcode and printermodel parameters can be queried or passed up from the HP print driver. Developers do not have to worry about what combinations are being used because the hosting environment only needs to pass these values along with the language and systemID parameters.

The language parameter is a combination of the language code and country code separated by a dash as specified by ISO 639:1988, and ISO 3166-1. If the Perl script does not recognize the language code combination, it will be set by default to en-US.

The systemID parameter gives Hewlett-Packard the flexibility to provide different sets of html help pages to different print solutions in the future. Developers should set the systemID to 0 to properly access the html help system. These help pages are generic enough to be associated with most any supported Hewlett-Packard DeskJet printer printing from an appliance type device.

A combination of parameters not matching any of the combinations recognized by the Perl script will be redirected to the top index page of the html tree. This top-level index page provides entry points to all Hewlett-Packard DeskJet models supported by the help pages.

[Back to top]

## Abstract Class "System Services" To Be Implemented By Host System Interface

The SDK requires access to certain basic services that can only be provided by the hosting environment such as memory management and input/output. The SystemServices object is used to obtain and encapsulate these services and other utilities that the Printer Driver uses to process print jobs, such as InitDeviceComm, DisplayPrinterStatus, ReadDeviceID, and GetStatusInfo.

System Services: System Services is an abstract base class that requires implementation of various routines by the host environment in order to compile. In most cases, this implementation is straight-forward. For example, implementing the required AllocMem function should just require mapping it to "malloc" or some equivalent; however, the host system also has the opportunity to allocate all driver memory in a single block up front (in the constructor) and then use AllocMem calls to dole out pieces from this block.

Instantiation of a SystemServices object is the first step in the driver calling sequence, and must occur before either PrintContext or Job can be instantiated.

InitDeviceComm:

InitDeviceComm is a method included in the base class whose function is to ensure that communication can be established with the printer, and the printer can be identified. InitDeviceComm must be called from the derivative SystemServices constructor. All other system-specific initialization should be done in the derivative SystemServices constructor as well. An example would be setting the seed for random number generation (i.e. implementation of the GetRandomNumber method).

DisplayPrinterStatus:

DisplayPrinterStatus is a method implemented in the derivative class that allows communication of the driver status (errors, conditions requiring user intervention, etc.,) to user interfaces provided by the host. For more information, refer to DisplayPrinterStatus.

ReadDeviceID:

ReadDeviceID is a method implemented in the derivative class for retrieving the raw DeviceID string from the printer. ReadDeviceID is dependent on the type of communications protocol used, (1284, USB, or other methods.) If access to the printer's DeviceID is not possible due to I/O issues on the host system, have this function return BAD_DEVICE_ID to allow proper operation of the printer driver's error handling system.

GetStatusInfo:

GetStatusInfo is a method implemented in the derivative class for retrieving the centronics status byte from the printer. Since this "status byte" is a fundamental element of parallel I/O and is emulated in USB, this byte should be available in most systems. If this byte is not available, simply return FALSE from GetStatusInfo to ensure proper operation of the printer driver's error handling system.

##

## Parallel 1284 versus USB

If USB will be the print solution I/O method, the printer driver must be informed by setting the flag IOMode.bUSB to TRUE in the constructor of the derivative SystemServices class. The drivers produced by the Hewlett-Packard Print Driver SDK require this information due to I/O and error handling differences between USB and parallel/1284 connectivity..

[Back to top]

## Plug & Play versus Uni–Directional

Hewlett-Packard strongly recommends using bi-directional communication (bi-di) instead of uni-directional communication (uni-di) when implementing print solutions with this SDK. Bi-directional communication provides complete communication between the user and the printer, and enables plug and play capability, which provides seamless identification and use of Hewlett-Packard DeskJet printers without any input from the user.

If a uni-directional I/O method is the only option, the driver can still be used although the user will not have the advantage of the printer-to-host system communication for troubleshooting. In this situation, the host system will need to prompt the user to report the model they will be printing to before initiating a print job. The hosting system is responsible for storing this printer model to prevent further prompting from the user again.

In normal bi-directional communication, Initdevicecomm tries to establish contact with the printer when the SystemServices class is created. If successful, the model number is saved for later use. When the PrintContext is created, the pointer for the SystemServices class will be used to check if the model number has been previously saved. If it was, bi-directional communication has been achieved.

It is also possible for PrintContext to be created when no model has been saved. The host system should always call PrinterSelected( ) to see if a printer has been selected after the PrintContext is created. A return value of TRUE will occur if bi-di communication is operational and the printer's model has been established. If it appears that no device has been selected (FALSE), then the user should be prompted to enter the model number, and SelectDevice should be called in order to pass on the appropriate model number.

The first possibility is when no status can be read at all from the centronics port, such as in a spooling case. The developer knows that the solution will be a true uni-directional I/O and should leave out InitDeviceComm from the derived SystemServices class. The second possibility is when the hosting system would still have access to the centronics register. If the hosting environment has access to the centronics port, the register can be passed to GetStatusInfo, allowing the driver to process the status.

There are four different path in the communication model: (DevID indicates access to the printer's deviceID string, and Status indicates access to the centronics status byte.) No DevID/No Status, No DevID/Yes Status, Yes DevID/No Status, and Yes DevID/Yes Status. The InitDeviceComm method looks at the return values of ReadDeviceID and GetStatusInfo, and sets the error handling functionality appropriately.

[Back to top]