Hewlett-Packard Appliance Printing Software Development Kit

 

Debugging the Printer Driver

 


 

 

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.

 

Debugging the Printer Driver

 

Introduction

Hewlett-Packard has learned through experience that it can be very difficult to disentangle pieces of a printing system from other applications and operating system items such as user-interface, memory management, network access, rendering of images and document formatting. As a result, finding the cause of undesirable behavior or output often leads a developer through all these areas.

In contrast to this complexity, the core code delivered in the Hewlett-Packard Appliance Printing Software Development Kit (SDK) is functionally very simple: it can only take graphical (and in some cases text) data and relay it to a printer in the native format of that printer, reporting the status of this communication back to the calling code. This functional limitation does have an advantage in that the interface to the core code can be very well-defined and the internal behavior easily understood. 

Given a specific set of inputs to the API, Hewlett-Packard (HP) has created a script that can easily determine whether the behavior of the core code is as expected or not, and consequently whether any problems should be sought elsewhere. In addition, it is often possible to determine the mistake in the upstream code just by looking at the calling sequence or data.

The following topics describe how to use this script to debug and communicate with Hewlett-Packard.

Debugging A Driver With Scripts

Recording A Script

 

Debugging A Driver With Scripts

The SDK has been instrumented so that when a debug flag (build define “CAPTURE” is set, all API calls along with their data are recorded in what Hewlett-Packard calls a script. From this script, a large class of problems can be immediately found that would otherwise potentially take a very long time to debug.

[Back to top]

 

Recording a Script

Developers can utilize the script recording device in order to communicate with Hewlett-Packard when debugging, problem solving, or quality testing.

  1. The first step in producing a script is to decide on the mechanism for storing it, and the format to be used. The easiest way to produce a script is to write the data to a file on local storage using standard “fopen/fwrite” commands. If such storage is available, the code included in the SDK will be sufficient. The data can be written in either binary or ASCII form; the binary form will produce smaller files and run faster.

Hewlett-Packard has encountered some systems where a storage disk is not available and the only means of capturing data is to use printf commands that are sent to a terminal window. In this case the base-class scripting code has to be overridden (in the derivative SystemServices class). The code can be copied as is from the base-class routines, replacing every file-writing call (fwrite, fputc, etc.) with a display call (printf), and avoiding the fopen/fclose calls in the methods OpenDebugStreamR and CloseDebugStreamR. In order to capture the data from the terminal window, the ASCII format must be used. (This is why the ASCII option has been provided.) Thus the code that needs to be overridden is in the AsciiScripter subclass of Scripter, found in the file script.cpp.

  1. The second step is for the calling code to invoke the SystemServices methods InitScript and EndScript. InitScript, as usual, should be called after the SystemServices object is constructed and before any other API calls are made. InitScript takes two parameters: the name of the script file to be created on disk (ignored in the diskless implementation), and a flag that is TRUE if ASCII format is to be used. EndScript should be called after everything else has finished and been cleaned up, except of course for destruction of the SystemServices object. Both these calls should be conditionally compiled into the calling code, so that they only occur in debug builds. (See next paragraph.)

  2. The final step is to compile all the code with the symbol CAPTURE defined, and with the files in the “debug” subdirectory included in the build. Note that CAPTURE should not be defined in any production builds, as performance will be severely degraded.

  3. Run the test print-job and send the resulting file (one per job – managing the files as you see fit through passing in different filenames, or copying the result to a different filename after each run,) to Hewlett-Packard. See the emailing instructions in the Testing document.

[Back to top]