Hewlett-Packard Appliance Printing Development Kit

# Hewlett-Packard Appliance Printing Software Development Kit

#

# Sample Code

#

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.

# Sample Code

##

## Introduction

The Hewlett-Packard Appliance Printing Software Development Kit (SDK) presupposes a bi-directional connection with the printer and the use of defaults for all optional settings. It also presupposes that the graphical data is available at 300 d.p.i, and that rendering of text is done by the host. With these assumptions in place, the following are examples of API calls in sample code.

> Minimal Sequence

> Using ASCII Text

> User-Interface Calling Code Samples

> Additional Information

## Minimal Sequence

The following minimal sequence set of sample code presupposes a bi-directional connection with the printer and the use of defaults for all optional settings. It also presupposes that the graphical data is available at 300 d.p.i, and that rendering of text is done by the host system.

This minimal sequence is presented in the form of a routine that handles one print job, and returns an error-code to the caller. The number of pages and page height are given, as well as the graphical data. (For demonstration purposes, this is imagined as a giant array.) The commented numbers on the right correspond to notes about the code at the end of the code sequence.

DRIVER_ERROR PrintJob(unsigned int NumPages,

unsigned int PageHeight, // 1

unsigned int PageWidth, // 2

BYTE JobArray[NumPages][PageHeight][PageWidth*3] ) // 3

{

PlatformServices* pSys = new PlatformServices(); // 4

if (pSys==NULL)

return SYSTEM_ERROR; // 5

DRIVER_ERROR err = pSys->constructor_error; // 6

if (err != NO_ERROR)

return err;

PrintContext* pPC = new PrintContext(pSys, PageWidth); // 7

if (pPC == NULL)

{

delete pSys; // 8

return SYSTEM_ERROR;

}

err = pPC->constructor_error;

if (err != NO_ERROR)

{

delete pSys;

return err;

}

Job* pJob = new Job(pPC); // 9

if (pJob == NULL)

{

delete pPC;

delete pSys;

return SYSTEM_ERROR;

}

err = pJob->constructor_error;

if (err != NO_ERROR)

{

delete pPC;

delete pSys;

return SYSTEM_ERROR;

}

// JOB LOOP

for (int i=0; i < NumPages; i++)

{

// PAGE LOOP

for (int j=0; j < PageHeight; j++)

{

err = pJob->SendRasters( JobArray[i][j] ); // 10

if (err != NO_ERROR)

{

delete pJob;

delete pPC;

delete pSys;

return err;

}

}

err=pJob->NewPage(); // 11

if (err != NO_ERROR)

return err;

}

delete pJob;

delete pPC;

delete pSys;

return NO_ERROR;

}

### [Back to top]

###

### Notes on Minimal Sequence

1. PageHeight is given in pixel-rows. For a default page with a vertical printable area of 10 inches and effective resolution of 300 d.p.i., this value would be 3000.

2. PageWidth is given in pixels per row. Note that this value is constant across the Job; it must not exceed the maximum width for the target paper-size. (In this example using defaults, this would be assumed to be 2400 for LETTER size paper with 8 printable inches at 300 d.p.i.) All rows of data must be padded with white space (RGB value 0xFFFFFF).

3. The size of a row in the byte-array is given as PageWidth*3, because each pixel is represented as 3 bytes in the required RGB24 format.

4. Creation of a SystemServices object is the first time communication with the printer is attempted, and entry points required by the core code are mapped. The class SystemServices is abstract, so reference is made here to the derived class containing the implementation for this platform.

5. Check that operator new succeeded.

6. The code set presumes no throw/catch capability in the local compiler, so all errors in constructors are signaled by the value of constructor_error, which the caller must check.

7. The second step involves setting up the PrintContext for the job, which contains all the information about the print modes, paper type and size, etc. The constructor sets defaults for all necessary options, and defines the printer model being used based on information gathered by SystemServices constructor.

8. When exiting due to an error, this step cleans up all previously allocated objects.

9. The Job object handles one continuous sequence of rasters on successive pages. Data will be sent through this object.

10. All the data is sent here. Errors may include conditions such as printer out of paper, offline, etc.

11. This function causes the page to be ejected, and resets various internal counters.

12. This step cleans up all allocated objects.

[Back to top]

## Using ASCII Text

The availability of font types varies by printer model and print mode. Up to four font types are contained in the SDK code set: Courier, LetterGothic, CGTimes, and Univers. Once the printer model has been selected (implicitly or explicitly), and a print mode decided upon, use the PrintContext method PrinterFontsAvailable to determine whether ASCII support is available at all. If it is, use the method EnumFonts to iterate through the set of ReferenceFonts, querying each for desired properties such as fixed-pitch vs. proportional. Then obtain a Font object for use in TextOut calls, by means of the method RealizeFont. See the API document for details on the above methods.

The following example shows a minimal sequence in which default settings are used for all the properties including color, bold, underline, and italics. The first step is to determine whether printer fonts are available on the current printer, using the currently selected mode. (This example assumes nothing has been done about setting PrintModes yet.)

1) Fetch the mode that has been automatically set:

int ModeIndex = pPC->CurrentPrintMode();

2) Then query for font support:

BOOL fontsOK = pPC->PrinterFontsAvailable(ModeIndex);

3) If fontsOK is FALSE, cause the system to render the fonts into the graphics buffer. Otherwise, create a Font object to use for sending ASCII text.

// create Courier font at 12-point size

pFont = pPC->RealizeFont( COURIER_INDEX, 12);

err = pFont->constructor_error;

if (err != NO_ERROR)

// try again with different parameters, or bail out

Multiple fonts may of course be created for use on different portions of the text; it is up to the caller’s layout code, however, to determine sizes and locations on the page. Other Font methods such as GetTextExtent may also be used in the layout code. The text may be sent at any time while processing a page. Each string of characters using the same font and running continuously across a row should be sent in one call to Job:

err = pJob->TextOut( “Hello World”, strlen(“Hello World”), *pFont, x,y);

Errors may result from sending text that would run off the page, in addition to error conditions in the printer.

[Back to top]

## User-Interface Calling Code Samples

The following functions demonstrate how to relay information to the user about actual and potential printer models connected to the system, and about available print modes.

The three examples are presented as independent functions, and therefore each has the overhead of creating and deleting the SystemServices and PrintContext objects. In your code, these objects may already exist at the time this information is needed.

Note on strings: although basically in English, the strings used by these functions have been formulated so as to present minimal translation difficulties. Printer model names have the word "DeskJet" followed by numbers; print-mode names are things like "Best" and "Normal", which would ideally be translated, but probably are intelligible to most non-English-speaking computer users.

### Example 1: Show User What Printer Models Are Supported In The Current Build

This example is a function to return the number of supported model families and an array of their names. This functionality is only required when the connected printer cannot be identified directly through hardware, and thus the user must tell the system which model to target. This could occur because of a faulty printer cable, or in systems that direct output across a network or spooling system.

> DRIVER_ERROR AvailableModels(char* modelarray[], // 1

> unsigned int& count)

> {

> count=0;

> PlatformServices* pSys = new PlatformServices();

> if (pSys==NULL)

> return SYSTEM_ERROR;

> DRIVER_ERROR err=pSys->constructor_error;

> > if (err!=NO_ERROR)

> return err;

> PrintContext *pPC = new PrintContext(pSys);

> if (pPC==NULL)

> return SYSTEM_ERROR;

> err=pPC->constructor_error;

> if (err!=NO_ERROR)

> return err;

> unsigned int index=0;

> PRINTER_TYPE p = pPC->EnumDevices(index); // 2

> while (p != UNSUPPORTED)

> {

> modelarray[count++] = (char*)pPC->PrintertypeToString(p); // 3

> p = pPC->EnumDevices(index);

> }

> delete pPC;

> delete pSys;

> return NO_ERROR;

> }

### Notes on Available Models example

(For the "boilerplate" of SystemServices and PrintContext creation and deletion, see notes to PrintJob example.)

1. The caller of this routine will have allocated an array of size MAX_PRINTER_TYPE+1. MAX_PRINTER_TYPE is the index of the highest PRINTER_TYPE enum in a zero-based count.

2. EnumDevices is an iterative mechanism for listing each supported model in the build. It returns an enum representing the printer model family.

3. PrintertypeToString converts the enum to a string suitable for display to user.

### Example 2: Show User The Print-Mode Options Available For The Selected Printer

This function takes an enum representing a printer model, and returns the number and names of the print-modes available for the printer.

(Here again the "boilerplate" may be superfluous, since some work must already have been done to identify the target printer model, either implicitly or explicitly.)

DRIVER_ERROR ModeInfo(PRINTER_TYPE pt, unsigned int& count,

char names[6][12]) // 1

{

PlatformServices* pSys = new PlatformServices();

if (pSys==NULL)

return SYSTEM_ERROR;

DRIVER_ERROR err=pSys->constructor_error;

if (err!=NO_ERROR)

return err;

PrintContext *pPC = new PrintContext(pSys);

if (pPC==NULL)

return SYSTEM_ERROR;

err=pPC->constructor_error;

if (err!=NO_ERROR)

return err;

err=pPC->SelectDevice(pt); // 2

if (err!=NO_ERROR)

{

delete pPC;

delete pSys;

return SYSTEM_ERROR;

}

count = pPC->GetModeCount();

for (int i=0; i<count; i++)

{

err = pPC->SelectPrintMode(i);

if (err > 0) // 3

return err;

strcpy(names[i], pPC->GetModeName() ); // 4

}

delete pPC;

delete pSys;

return NO_ERROR;

}

### Notes on ModeInfo example

1. See previous note (1).

2. The device is selected explicitly here; as with the rest of the "boilerplate", this work may have already been done by the time this functionality is needed.

3. The test (err > 0) ignores warnings, whose values are less than zero. These can be generated by a mismatch between mode and hardware configuration (e.g. the engagement of a photo-tray, or the presence of a special type of ink cartridge), indicating that the result will be sub-optimal.

4. Copy the name stored with the print-mode, for relay to user.

###

### Example 3: Show user the specific model name of the connected printer

The model names and enums used in Example (1) above refer to printer-model families. These families share all important firmware and are treated as a single type from the perspective of the SDK code. But further differences are found within these families. For example the family that includes the 690 models has members with particular designations such as 692. This detailed information, matching the designation on the customer’s device and packaging, exists in the device memory, and can be obtained through the following method.

DRIVER_ERROR GetConnectedModel(PRINTER_TYPE& pt, const char* ModelID)

{

PlatformServices* pSys = new PlatformServices();

if (pSys==NULL)

return SYSTEM_ERROR;

DRIVER_ERROR err=pSys->constructor_error;

if (err!=NO_ERROR)

return err;

PrintContext *pPC = new PrintContext(pSys);

if (pPC==NULL)

return SYSTEM_ERROR;

err=pPC->constructor_error;

if (err!=NO_ERROR)

return err;

pt = pPC->SelectedDevice(); // 1

ModelID = pPC->PrinterModel(); // 2

delete pPC;

delete pSys;

return NO_ERROR;

}

### Notes on GetConnectedMode example

1. See previous note (2)

2. Fetches the string from printer memory.

## Additional Information

For more information on ASCII text, refer to the Device-Based Fonts document.

[Back to top]