Hewlett-Packard Appliance Printing Development Kit

# Hewlett-Packard Appliance Printing Software Development Kit

#

# A P I

#

#

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.

#

# Introduction

The Hewlett-Packard Appliance Printing Software Development Kit (SDK) API reflects the lean footprint and memory usage required for the driver. It is not immense, and should not take long to become familiar with.

The API is broken into three sections. First, the API gives a brief description of the four public classes used to run the driver: SystemServices, PrintContext, Job, Font, and Scaler. (Not each of these classes will be used for every driver.) After the descriptions are tables with class members, a one or two-sentence description, and any return type(s) or parameter(s), if applicable. Following the tables are detailed paragraphs for each member, with parameters, return values, and error codes.

An Appendix is located at the very end of the document detailing the Enums and Data Types, and printer driver codes containing information on driver errors, display statuses, media information and text colors.

Be sure to utilize the several hyperlinks throughout the document (reflected with blue, underlined text.) These are designed to transport the user to additional information related to the underlined item.

#

# Global Functions

There is one Global Function in the printer driver code, used to determine properties of the current version. All other API calls are made through one of five C++ objects.

# Object Classes

There are four object classes. Not all of these classes will be used in every host system.

· SystemServices This object encapsulates functionality which must be supplied by the host system, including memory management and I/O, clock access, user notification, etc. The abstract base class must be instantiated in a host-specific derived class, where the system code is hooked up to the required driver entry points. The only reference to this object in API-calling code should be to its constructor and destructor, which must be invoked prior to and after all other driver calls.

· PrintContext This object serves two purposes. First, it encapsulates knowledge about all devices supported in available driver components. It can be queried at runtime to determine capabilities of the attached device. Second, it allows for setting optional parameters of a print job, such as media size and margins, use of color and data-resolution, etc.

· Job This object receives processes and transmits data to be printed by one device on successive pages. The PrintContext and Job together form the core of the driver proper.

· Font This object is used to control printer fonts when sending ASCII data. (For systems that lack a reasonable font engine or for some reason can benefit from using printer fonts.)

· Subclass ReferenceFont (EnumFont) is used to query available font properties prior to instantiating the font. Whereas Font objects created upon request are to be deleted by caller, ReferenceFonts live with the core structures and cannot be deleted.

# Auxiliary Objects

> Scripter For debugging purposes only. This object provides script-recording and playback functionality. (See the SystemServices functions InitScript and EndScript.) It comes in two flavors, Ascii and Binary. A platform that lacks a file system can add an additional subclass using terminal-emulation captures, or whatever means is available.

[Back to top]

# Global Functions

Function Name | Description | Return Type | Parameters
Version | Returns a string identifying components and features of the driver build. | char * | BOOL bCompress

[Back to top]

# SystemServices

Member Name | Description | Data / Return Type | Parameters
The following items are provided in the base class
SystemServices | constructor | N/A | Void
~SystemServices | destructor | N/A | N/A
constructor_error | Calling code must check that the value of this variable is NO_ERROR before proceeding. | DRIVER_ERROR | N/A
InitDeviceComm | Mandatory call to be inserted in derived constructor. | DRIVER_ERROR | Void
PrinterIsAlive | Tests communication with printer. NOTE: This implementation is appropriate for Parallel bus only. | BOOL | Void
The following items are to be implemented for the host system
DisplayPrinterStatus | Uses message code to relay a message to the user. | Void | DISPLAY_STATUS ePrinterStatus
BusyWait | Waits for the specified number of milliseconds before returning to the caller. | DRIVER_ERROR | DWORD msec
ReadDeviceID | Retrieves the device identifier string from the printer. | DRIVER_ERROR | BYTE* strID, int iSize
AllocMem | Allocates a block of memory. | BYTE* | int iMemSize
FreeMem | Frees a given block of memory. | Void | BYTE* pMem
GetStatusInfo | Reads status register from printer. | BOOL | BYTE* bStatReg
ToDevice | Sends bytes of data to the printer. | DRIVER_ERROR | const BYTE* pBuffer, DWORD* dwCount
FromDevice | Gets data from printer. | DRIVER_ERROR | char* pReadBuff, WORD* wReadCount
GetECPStatus | Opens an ECP I/O channel to the printer and retrieves a given number of bytes. Required only for the DeskJet 4xx Series. | DRIVER_ERROR | BYTE *pStatusString, int *pECPLength, int ECPChannel
YieldToSystem | Gives host system a chance to process asynchronous events | BOOL | Void
GetRandomNumber | Get random number from system. | BYTE | Void
GetSystemTickCount | Read system clock. | DWORD | Void
FlushIO | Passes a command to the I/O system to send all data to the printer immediately. | DRIVER_ERROR | Void
AbortIO | Tells the I/O system that the print job has ended prematurely, and to throw away that any data being held in a "send" buffer. | DRIVER_ERROR | Void
The following are debugging members present only in debug build
pScripter | Pointer to the script-debugging handler. | Scripter* | N/A
InitScript | Begin recording script for debugging. | DRIVER_ERROR | const char* FileName, BOOL ascii, BOOL read
EndScript | Stop recording script for debugging. | DRIVER_ERROR | Void

[Back to top]

# PrintContext

Member Name | Description | Data / Return Type | Parameters
PrintContext | constructor | N/A | pSysServ, InputPixelsPerRow, OutputPixelsPerRow, ps,
~PrintContext | destructor | N/A | N/A
constructor_error | Calling code must check that the value of this variable is NO_ERROR before proceeding. | DRIVER_ERROR | N/A
SelectDevice | Used to explicitly select a printer model when bi-directional communication is lacking, or when the constructor could not instantiate the printer. | DRIVER_ERROR | const PRINTER_TYPE Model
SelectedDevice | Returns the currently selected device. | PRINTER_TYPE | Void
GetModeCount | Returns number of supported print modes for the select printer model. | unsigned int | Void
GetModeName | Returns the identifying string for the currently selected print mode. | char* | Void
SelectPrintMode | Chooses amongst available print modes. Index of zero implies grayscale, index of 1 implies default mode. | DRIVER_ERROR | const unsigned int index
PrinterModel | Returns the model portion of the firmware ID string from SystemServices. | strModel or NULL | Void
PrintertypeToString | Returns a string representing the printer model family signified by the parameter. | str | PRINTER_TYPE
CurrentPrintMode | Retrieves an index of the currently selected print mode. | unsigned int | Void
EnumFont | Returns a Font object for the selected printer based on index, in order for host to query font properties prior to selection. | ReferenceFont* or NULL | int& iCurrIdx
RealizeFont | The means of creating a Font object with the desired properties, for use in Job::TextOut calls. | Font* or NULL | const int index, const BYTE bSize, const TEXTCOLOR eColor, const BOOL bBold, const BOOL bItalic, const BOOL bUnderline
EnumDevices | Returns the enum for the next supported model. Used when bi-directional communication is missing. | PRINTER_TYPE | unsigned int& currIDX
PerformPrinterFunction | Used outside the context of a Job, to perform functions such as pen cleaning. | DRIVER_ERROR | PRINTER_FUNC eFunc
SetPaperSize | Sets or changes the target paper size for a print job. | DRIVER_ERROR | PAPER_SIZE ps
SetInputPixelsPerRow | Sets the width of all rows on the page. | DRIVER_ERROR | unsigned int PixelsPerRow
PrinterSelected | Returns TRUE if printer has been selected. | BOOL | Void
PrinterFontsAvailable | Returns TRUE if the selected printer (and the current build) provides font support. | DRIVER_ERROR | BOOL& answer
InputPixelsPerRow | Returns the width as set by SetPixelsPerRow. | unsigned int | Void
OutputPixelsPerRow | Returns the current setting for output width | unsigned int | Void
GetPaperSize | Returns the currently set paper size. | PAPER_SIZE | Void
PhysicalPageSizeX | Retrieves information about the physical width of the currently selected paper size. | float | Void
PysicalPageSizeY | Retrieves information about the physical height of the currently selected paper size. | float | Void
PrintableStartX | Returns the left margin or distance from the top edge of the page. | float | Void
PrintableStartY | Returns the top margin or distance from the top edge of the page. | float | Void
PrintableWidth | Returns width of printable region in inches | float | Void
PrintableHeight | Returns height of printable region in inches | float | Void
GetHelpType | Returns a HELP_TYPE value corresponding to a selected print class. | HELP_TYPE | Void
EffectiveResolutionX | Returns the horizontal printer resolution to be used for currently selected print mode. | unsigned int | Void
EffectiveResolutionY | Returns the vertical printer resolution to be used for currently selected print mode. | unsigned int | Void
SetInputResolution | Tells the code not to scale up image data in resolution. | DRIVER_ERROR | Res
InputResolution | Returns the value set by SetInputResolution | unsigned int | Void
Special method used outside the context of a Job
voidFlush | Flushes data in the printer's input buffer to prepare for new data stream. | int | Void
SendPrinterReadyData | For use when pre-formatted data is available from an external source. | DRIVER_ERROR | BYTE* stream, unsigned int size

[Back to top]

# Font

Function Name | Description | Data / Return Type | Parameters
PrintContext::RealizeFont | No public constructor with standard syntax use PrintContext::RealizeFont. | Font* | const int index, const BYTE bSize, const TEXTCOLOR eColor, const BOOL bBold, const BOOL bItalic, const BOOL bUnderline
~Font | Destructor | N/A | N/A
The following are for use in determining general properties of the font family, prior to instantiating a concrete font.
GetName | Returns the typeface name. | char* | Void
IsBoldAllowed | Tells whether text bolding is available. | BOOL | Void
IsItalicAllowed | Tells whether text italicizing is available. | BOOL | Void
IsUnderlineAllowed | Tells whether text underlining is available. | BOOL | Void
IsColorAllowed | Tells whether text coloring is available. | BOOL | Void
IsProportional | Tells whether this font is proportionally spaced, as opposed to fixed. | BOOL | Void
HasSerif | Tells whether this typeface has serifs. | BOOL | Void
The following items refer to a concrete font already created by RealizeFont.
GetTextExtent | Calculates width and height of a string using current settings. | DRIVER_ERROR | const char* pTextSTring, const int iLenString, int& iHeight, int& iWidth
GetPitch | For fixed fonts, returns the pitch for given point-size. (Returns zero for proportional fonts.) | BYTE | const BYTE pointsize
iPointsize | Variable holds currently selected point size. | int | N/A
bBold | Tells whether bold is currently selected. | BOOL | N/A
bItalic | Tells whether italic is currently selected. | BOOL | N/A
bUnderline | Tells whether underline is currently selected. | BOOL | N/A
eColor | Variable holds currently selected color. | BOOL | N/A
iPitch | Variable holds currently selected color. | BOOL | N/A
Index | Index of point-size from available list for this font. | int | Void

[Back to top]

# Job

Function Name | Description | Data / Return Type | Parameters
Job | constructor | N/A | PrintContext* pPC
~Job | destructor | N/A | N/A
constructor_error | Calling code must check that the value of this variable is NO_ERROR before proceeding. | DRIVER_ERROR | N/A
SendRasters | This is the fundamental method for the driver, by means of which graphics data is sent to the printer . | DRIVER_ERROR | BYTE* ImageData
TextOut | This method is used to send ASCII data to the printer, which it will render as determined by the Font object . | DRIVER_ERROR | const char* pTextSTring, int iLenSTring, const Font& font, int iAbsX, int iAbsY
NewPage | Resets counters, flushes buffers, and sends a form feed to the printer. | DRIVER_ERROR | Void

# [Back to top]

# Global Functions

## Version

##### SYNOPSIS

char* Version (BOOL beCompressed) ;

##### DESCRIPTION

This function returns a string identifying components and features of the driver build, such as which printer-models are supported, whether font and scaling support is included, and other information intended to help solve customer problems.

##### PARAMETERS

compressed If true, the information is packed into a decimal number that must be decoded by VCD. Otherwise, the string consists of human-readable indicators.

##### RETURN VALUE

String as described above

##### ERROR CODES

N/A

##### SEE ALSO

[Back to top]

# class System Services

## SystemServices

##### SYNOPSIS

SystemServices (WORD unsigned int) ;

##### DESCRIPTION

This method constructs a SystemServices object. This is the first step in the calling sequence.

##### PARAMETERS

ToDevice
FromDevice

##### RETURN VALUE

N/A

##### ERROR CODES

N/A see constructor_error

##### SEE ALSO

## ~SystemServices

##### SYNOPSIS

~SystemServices () ;

##### DESCRIPTION

This method is a destructor, called when the instance of SystemServices is deleted or goes out of scope.

##### PARAMETERS

N/A

##### RETURN VALUE

N/A

##### ERROR CODES

N/A

##### SEE ALSO

## constructor_error

##### SYNOPSIS

DRIVER_ERROR constructor_error;

##### DESCRIPTION

This member variable checks for the validity of the constructed object. Calling code must check that the value of this variable is NO_ERROR before proceeding.

##### SEE ALSO

[Back to top]

## InitDeviceComm

##### SYNOPSIS

DRIVER_ERROR InitDeviceComm () ;

##### DESCRIPTION

This method tries to establish communications with printer and identify it. This base-class routine must be called by the derived SystemServices constructor.

##### PARAMETERS

Void

##### RETURN VALUE

DRIVER_ERROR

##### ERROR CODES

CANCELLED

##### SEE ALSO

## PrinterIsAlive

##### SYNOPSIS

BOOL PrinterIsAlive () ;

##### DESCRIPTION

This method tests communication with printer.
NOTE: This implementation is appropriate for Parallel bus only.

##### PARAMETERS

Void

##### RETURN VALUE

TRUE if communication with printer is working.

##### ERROR CODES

N/A

##### SEE ALSO

## DisplayPrinterStatus

##### SYNOPSIS

BYTE DisplayPrinterStatus (DISPLAY_STATUS ePrinterStatus)

##### DESCRIPTION

This routine will cause a corresponding text string (or graphic, or both) to be displayed to the user to inform them of printer status. This is how printer events such as out-of-paper will be communicated to the user.

##### PARAMETERS

EPrinterStatus code for status condition see Display Statuses in Appendix.

##### RETURN VALUE

Void

##### ERROR CODES

N/A

##### SEE ALSO

[Back to top]

## BusyWait

##### SYNOPSIS

DRIVER_ERROR BusyWait (DWORD msec);

##### DESCRIPTION

This method waits for the specified number of milliseconds before returning to the caller.

##### PARAMETERS

msec milliseconds to wait

##### RETURN VALUE

Void

##### ERROR CODES

DRIVER_ERROR

##### SEE ALSO

## ReadDeviceID

##### SYNOPSIS

DRIVER_ERROR ReadDeviceID(BYTE* strID, int iSize);

##### DESCRIPTION

This method retrieves the device identifier string from the printer.

##### PARAMETERS

strID - pointer to buffer for storing string.

iSize The size of buffer.

##### RETURN VALUE

DRIVER_ERROR

##### ERROR CODES

IO_ERROR

##### SEE ALSO

## AllocMem

##### SYNOPSIS

BYTE* AllocMem (int iMemSize);

##### DESCRIPTION

This method will allocate a contiguous block of memory at least iMemSize bytes long.

##### PARAMETERS

iMemSize - size of block.

##### RETURN VALUE

Returns a pointer to the memory block. Can also return NULL, if allocation failed.

##### ERROR CODES

N/A

##### SEE ALSO

[Back to top]

## FreeMem

##### SYNOPSIS

void FreeMem (BYTE* pMem);

##### DESCRIPTION

This method frees a given block of memory.

##### PARAMETERS

pMem pointer to the block of memory to be freed.

##### RETURN VALUE

Void

##### ERROR CODES

N/A

##### SEE ALSO

## GetStatusInfo

##### SYNOPSIS

BOOL GetStatusInfo (BYTE* bStatReg)

##### DESCRIPTION

This method reads status register from printer. If the parallel status byte is returned, the function returns TRUE when it sets this value. Otherwise the function returns FALSE if this functionality is not supported.

##### PARAMETERS

bStatReg pointer to a byte into which status register will be copied.

##### RETURN VALUE

TRUE - when the value is set after returning the parallel status byte.

FALSE - if the functionality is not supported.

##### ERROR CODES

N/A

##### SEE ALSO

## ToDevice

##### SYNOPSIS

DRIVER_ERROR ToDevice (const BYTE* pBuffer, DWORD* d wCount)

##### DESCRIPTION

This method sends bytes of data to the printer.
Note: This method decrements the dwCount parameter (*dwCount) by the number of bytes that were actually sent.

##### PARAMETERS

pBuffer pointer to buffer full of data.

dwCount - (in/out) Upon entry, this contains the number of bytes of data requested to send. Upon return from the method, dwCount is the number of bytes that were not sent, i.e. the remaining bytes.

##### RETURN VALUE

DRIVER_ERROR

##### ERROR CODES

Varies per implementation.

##### SEE ALSO

[Back to top]

## FromDevice

##### SYNOPSIS

DRIVER_ERROR FromDevice (char* pReadBuff, WORD* wReadCount);

##### DESCRIPTION

This method gets data from the printer.

##### PARAMETERS

pReadBuff pointer to buffer into which data is to be copied.

wReadCount output parameter (pointer to allocated WORD) telling number of bytes copied.

##### RETURN VALUE

DRIVER_ERROR

##### ERROR CODES

Varies per implementation

##### SEE ALSO

## GetECPStatus

##### SYNOPSIS

DRIVER_ERROR GetECPStatus (Byte *pStatusString, int *pECPLength, int ECPChannel)

##### DESCRIPTION

This function will open an ECP I/O channel to the printer and retrieve a given number of bytes from it. Because ECP is a 1284 protocol, this function is only relevant for 1284 compliant parallel I/O connectivity. Currently, only the DeskJet 4xx Series of printers requires implementation of this function.

Because of the non-standard nature of this function, it is expected that the sample code supplied in ECPSample.cpp will be heavily leveraged during implementation of this function in the derived SystemServices class.

##### PARAMETERS

pStatusString the destination of the set of retrieved status bytes.

pECPLength the number of retrieved bytes.

ECPChannel the ECP channel number to be opened and read.

##### RETURN VALUE

PStatusString now contains the set of status bytes retrieved from the ECP channel.

##### ERROR CODES

DRIVER_ERROR

##### SEE ALSO

## YieldToSystem

##### SYNOPSIS

BYTE YieldToSystem (void)-0;

##### DESCRIPTION

The printer driver will call this routine from time to time in the course of processing the data. This gives other parts of the system a chance to run. For example, if the printer driver is blocked due to some error condition on the printer (buffer full, out-of-paper, etc.), the driver will call this routine inside its retry loop. This will allow the rest of the system to process events such as a job cancel, etc. If the driver is processing large blocks of data, it will call this routine to ensure adequate system responsiveness. It is the systems responsibility to ensure that the driver is not re-entered during a call to this routine.

##### PARAMETERS

Void

##### RETURN VALUE

BOOL

##### ERROR CODES

N/A

##### SEE ALSO

[Back to top]

## GetRandomNumber

##### SYNOPSIS

BYTE GetRandomNumber ();

##### DESCRIPTION

This method gets random number from system. Any seeding of random number generator needs to be done in constructor.

##### PARAMETERS

Void

##### RETURN VALUE

Returns an 8-bit, pseudo-random number.

##### ERROR CODES

N/A

##### SEE ALSO

## GetSystemTickCount

##### SYNOPSIS

DWORD GetSystemTickCount (void);

##### DESCRIPTION

This routine will query the system for the current tick count (time). Since it will be used primarily for retry time-outs in the driver, it only needs to provide a running count of elapsed time since the device was booted, for example.

##### PARAMETERS

Void

##### RETURN VALUE

DWORD number of ticks for current tick count.

##### ERROR CODES

N/A

##### SEE ALSO

## FlushIO

##### SYNOPSIS

DRIVER_ERROR FlushIO ();

##### DESCRIPTION

If the I/O system is buffering data into blocks before sending to the printer, this command should pass a command to the I/O system to stop waiting and send everything it has to the printer now. If the I/O system does not buffer data into blocks, this command may simply be stubbed out to return NO_ERROR.

A typical I/O system mechanism may be to wait until an I/O buffer has reached a threshold before sending that block of data to the printer. In some rare cases, it may be necessary that data which has just been sent to the I/O system reach the printer ASAP, at which point the printer driver will check the status or deviceID string of the printer and continue. Often, USB implementations will favor the block-send mechanism because it is more efficient through the system's call stack. Simple and traditional centronics I/O is usually not buffered, but this is still a system-by-system I/O preference.

##### PARAMETERS

N/A

##### RETURN VALUE

DRIVER_ERROR

##### ERROR CODES

N/A

##### SEE ALSO

AbortIO

## AbortIO

##### SYNOPSIS

DRIVER_ERROR AbortIO ();

##### DESCRIPTION

This routine instructs the I/O system that this print job has ended prematurely, that no further data will be sent and that any data being held in a "send" buffer can be thrown away. This command is optional and depends on the implementation of the I/O system.

In some error conditions, the printer is incapable of accepting more data. The printer driver will sense this error and stop sending data, but if the I/O system has buffered data it may continue to wait for the printer to accept this remaining data before unloading. This mechanism will allow for a more efficient clean-up of the aborted job.

##### PARAMETERS

N/A

##### RETURN VALUE

DRIVER_ERROR.

##### ERROR CODES

N/A

##### SEE ALSO

FlushIO

## pScripter

##### SYNOPSIS

Scripter *pScripter;

##### DESCRIPTION

This member variable is a pointer to the script-debugging handler.

##### SEE ALSO

[Back to top]

## InitScript

##### SYNOPSIS

DRIVER_ERROR InitScript (const char* FileName, BOOL ascii) ;

##### DESCRIPTION

This member variable begins recording script for debugging.

##### PARAMETERS

FileName name of the output file which will hold the script.

ascii If TRUE use ASCII implementation. Otherwise, use binary.

##### RETURN VALUE

DRIVER_ERROR

##### ERROR CODES

SYSTEM_ERROR - if file cant be opened.

##### SEE ALSO

## EndScript

##### SYNOPSIS

DRIVER_ERROR EndScript () ;

##### DESCRIPTION

This member variable stops recording script for debugging.

##### PARAMETERS

Void

##### RETURN VALUE

DRIVER_ERROR

##### ERROR CODES

SYSTEM_ERROR - if called out of sequence.

##### SEE ALSO

[Back to top]

# class PrintContext

## PrintContext

##### SYNOPSIS

PrintContext (SystemServices * pSysServ,
unsigned int InputPixelsPerRow,
unsigned int OutputPixelsPerRow,
PAPER_SIZE ps);

##### DESCRIPTION

This method constructs a PrintContext object

##### PARAMETERS

pSysServ A pointer to a SystemServices object which has already been instantiated and whose constructor_error==NO_ERROR.

InputPixelsPerRow The size of the input raster in pixels. If the default value of 0 is used, the raster is assumed to match the number of pixels in the printable width of the page.

OutputPixelsPerRow The width of a raster on the page. Implicitly sets the scaling factor, equal to OutputPixelsPerRow/InputPixelsPerRow. This must take account of the printer resolution for the PrintMode in use. If the default value of zero is used, the code will scale up to fit the printable width of the page.

ps This enumerated value of type PAPER_SIZE corresponds to the size of paper media to be printed on.
Note: The paper size is set for the duration of the print job, not on a page by page basis.

##### RETURN VALUE

N/A

##### ERROR CODES

constructor_error must be NO_ERROR, else object is invalid.

##### SEE ALSO

## ~PrintContext

##### SYNOPSIS

~PrintContext ();

##### DESCRIPTION

This method is a destructor, called when object is deleted or goes out of scope.

##### PARAMETERS

N/A

##### RETURN VALUE

N/A

##### ERROR CODES

N/A

##### SEE ALSO

Print Context

## SelectDevice

##### SYNOPSIS

DRIVER_ERROR SelectDevice (const PRINTER_TYPE Model)

##### DESCRIPTION

This method is used to explicitly select a printer model when bi-directional communication is lacking, or when the constructor could not instantiate the printer. Presumably, the Model and Pen values were pre-set internally, or else mapped from a set of host-controlled dialog box elements.

##### PARAMETERS

Model The model of printer as mapped to the enumeration PRINTER_TYPE.

##### RETURN VALUE

Calling the host with this method returns an error code of type DRIVER_ERROR.

##### ERROR CODES

NO_ERROR Success

UNSUPPORTED_PRINTER This printer type is unavailable.

UNSUPPORTED_PEN This pen type is unavailable.

##### SEE ALSO

PrinterSelected

[Back to top]

## SelectedDevice

##### SYNOPSIS

PRINTER_TYPE SelectedDevice () ;

##### DESCRIPTION

This method returns the currently selected device. A device is selected implicitly in the constructor if bi-directional communication is working. SelectDevice() is used with unidirectional communication, or to override the implicit selection

##### PARAMETERS

Void

##### RETURN VALUE

PRINTER_TYPE - returns UNSUPPORTED if no Printer has been selected, either implicitly or explicitly.

##### ERROR CODES

N/A

##### SEE ALSO

SelectDevice

## GetModeCount

##### SYNOPSIS

Unsigned int GetModeCount ();

##### DESCRIPTION

This method is used to determine the number of supported print modes for this device.

##### PARAMETERS

Void

##### RETURN VALUE

This method will return the number of print modes. The device must support (and should return a value of) at least two print modes, gray and normal. The general convention for interpretation of the indices is:

0 = GrayMode rendering for black pen

1 = the basic mode for this printer, usually targeting plain paper and normal quality

2,3... = special modes that may be available for this printer

##### ERROR CODES

N/A

##### SEE ALSO

SelectPrintMode

CurrentPrintMode

## GetModeName

##### SYNOPSIS

Unsigned int GetModeName ();

##### DESCRIPTION

This method returns the identifying string for the currently selected print mode. Returns NULL if no printer selected.

##### PARAMETERS

Void

##### RETURN VALUE

This method returns char* , the identifying string for the currently selected print mode.

##### ERROR CODES

N/A

##### SEE ALSO

## SelectPrintMode

##### SYNOPSIS

DRIVER_ERROR SelectPrintMode (const unsigned int index) ;

##### DESCRIPTION

This method is used to select the print mode for the current print job.

##### PARAMETERS

index The index value corresponding to the desired print mode.

This method will return the number of print modes. The device must support (and should return a value of) at least two print modes, gray and normal. The general convention for interpretation of the indices is:

0 = GrayMode rendering for black pen

1 = the basic mode for this printer, usually targeting plain paper and normal quality

2,3... = special modes that may be available for this printer

##### RETURN VALUE

DRIVER_ERROR.

##### ERROR CODES

NO_ERROR Success

NO_PRINTER_SELECTED A printer object must exist (SelectDevice) before the print mode can be selected.

INDEX_OUT_OF_RANGE Not an available mode value.

##### SEE ALSO

GetModeCount

CurrentPrintMode

[Back to top]

## PrinterModel

##### SYNOPSIS

const char* PrinterModel (void) ;

##### DESCRIPTION

This method returns the model portion of the firmware ID string from SystemServices, or NULL if no printer is selected or the connection is uni-di.

##### PARAMETERS

Void

##### RETURN VALUE

strModel - the model portion of the firmware ID string from SystemServices, or NULL if no printer is selected or the connection is uni-di.

##### ERROR CODES

N/A

##### SEE ALSO

[Back to top]

## PrintertypeToString

##### SYNOPSIS

const char* PrintertypeToString (PRINTER_TYPE pt) ;

##### DESCRIPTION

This method returns a string representing the printer model family signified by the parameter. This string is intended for use in a dialogue with the user when explicit printer model selection is required.

##### PARAMETERS

PRINTER_TYPE enum representing one of the supported printer model families.

##### RETURN VALUE

Returns a string version of the enum.

##### ERROR CODES

N/A

##### SEE ALSO

[Back to top]

## CurrentPrintMode

##### SYNOPSIS

unsigned int CurrentPrintMode () ;

##### DESCRIPTION

This method is used to determine the current print mode.

##### PARAMETERS

Void

##### RETURN VALUE

Returns the index value for the currently used print mode.

##### ERROR CODES

N/A

##### SEE ALSO

GetModeCount

SelectPrintMode

The following two methods are only available in builds that support printer fonts see the Version function.

## EnumFont

##### SYNOPSIS

ReferenceFont* EnumFont (int& iCurrIdx) ;

##### DESCRIPTION

This returns a ReferenceFont object for the selected printer based on index, in order for host to query font properties prior to selection. If index is out of range returns NULL.

##### PARAMETERS

ICurrIdx Caller starts at zero; reference variable is incremented automatically for next call.

##### RETURN VALUE

Pointer to a reference font of the specified family, which can be queried regarding its properties and allowable settings. This object cannot be deleted by caller.

If index is out of range, returns NULL.

##### ERROR CODES

N/A

##### SEE ALSO

## RealizeFont

##### SYNOPSIS

Font* RealizeFont (const int index, const BYTE bSize,
const TEXTCOLOR eColor=BLACK,
const BOOL bBold=FALSE, const BOOL bItalic=FALSE,
const BOOL bUnderline=FALSE);

##### DESCRIPTION

This method is the means of creating a Font object with the desired properties, for use in Job::TextOut calls.

##### PARAMETERS

index index of desired font as returned by EnumFont
bSize - point size
eColor=BLACK - color to use to print this font
bBold=FALSE - TRUE to use bold
bItalic=FALSE - TRUE to use italics
bUnderline=FALSE - TRUE to use underlining

##### RETURN VALUE

Pointer to font object with desired properties. If index is out of range or fonts are unsupported, returns NULL.

NOTE: Caller has the responsibility for deleting the resulting Font object when done.

##### ERROR CODES

None

##### SEE ALSO

[Back to top]

## EnumDevices

##### SYNOPSIS

PRINTER_TYPE EnumDevices (int& currIdx) const;

##### DESCRIPTION

Returns the enum for the next supported model. This method is used when bi-directional communication is missing, or for dynamic querying of the properties of a given build. This method is presumably called within a loop, which will exit when the return value equals UNSUPPORTED. Passing this return value to SelectDevice will instantiate this printer object and therefore allow further querying of the printers capabilities through other methods in PrintContext.

##### PARAMETERS

currIdx Caller starts at zero; reference variable is incremented automatically for next call.

##### RETURN VALUE

A value matching an element of the enum PRINTER_TYPE, which can then be passed to other methods such as SelectDevice.

##### ERROR CODES

N/A

##### SEE ALSO

SelectDevice

## PerformPrinterFunction

##### SYNOPSIS

DRIVER_ERROR PerformPrinterFunction (PRINTER_FUNC eFunc) ;

##### DESCRIPTION

This method is used outside the context of a Job, to perform the specified function such as pen cleaning. Care should be taken to ensure that this routine is NOT called in the middle of a normal print job.

##### PARAMETERS

eFunc The action which the host has requested the printer to perform.

##### RETURN VALUE

An error value of type DRIVER_ERROR.

##### ERROR CODES

NO_ERROR Success

NO_PRINTER_SELECTED A printer object must be created (SelectDevice) before the function can be performed.

UNSUPPORTED_FUNCTION This is not a recognized function.

##### SEE ALSO

## SetPaperSize

##### SYNOPSIS

DRIVER_ERROR SetPaperSize (PAPER_SIZE ps) ;

##### DESCRIPTION

This method sets the target paper size to be used by the print job. This would have already been set during PrintContext construction, but may be reset using this function as long as the job object itself has not yet been created.

##### PARAMETERS

ps The desired paper size.

##### RETURN VALUE

An error value of type DRIVER_ERROR.

##### ERROR CODES

NO_ERROR Success

NO_PRINTER_SELECTED - Failure

##### SEE ALSO

[Back to top]

## SetInputPixelsPerRow

##### SYNOPSIS

DRIVER_ERROR SetPixelsPerRow (unsigned int PixelsPerRow,
unsigned int OutputPixelsPerRow=0) ;

##### DESCRIPTION

This method sets the number of pixels per row to be printed for every call to SendRaster for the current Job. This value would have been set in the PrintContext constructor, but may be reset as long as the intended Job has not been created yet.

##### PARAMETERS

PixelsPerRow The number of pixels to be printed for every row in this Job.

##### RETURN VALUE

An error value of type DRIVER_ERROR

##### ERROR CODES

NO_ERROR Success

ILLEGAL_COORDS If pixels per row exceeds the printable region of this printer and paper type.

##### SEE ALSO

Job::SendRasters
PrintContex

## PrinterSelected

##### SYNOPSIS

BOOL PrinterSelected () ;

##### DESCRIPTION

This routine is used to determine whether a printer object has been created, and returns TRUE if printer has been selected. This routine is a common prelude to calling SelectDevice. For instance, if the creation of the SystemServices object successfully established bi-directional communication, PrintContext would have used the printer information to create a printer object. However, if bi-directional failed, PrintContext would not have created a printer object.

##### PARAMETERS

Void

##### RETURN VALUE

TRUE if a printer object exists

FALSE if a printer object does not exist. This indicates a printer model must be specified (via SelectDevice).

##### ERROR CODES

N/A

##### SEE ALSO

SelectDevice

## PrinterFontsAvailable

##### SYNOPSIS

BOOL PrinterFontsAvailable (unsigned int PrintModeIndex) ;

##### DESCRIPTION

This routine determines whether device-based text support is available in the currently instantiated printer. Returns TRUE if the selected printer (and the current build) provides font support for the given print mode.

##### PARAMETERS

answer This pass-by reference value will contain the results of the query following a successful (NO_ERROR) return from this method. TRUE indicates the printer is capable of using device-based text. FALSE indicates the printer is not capable of supporting this feature.

PrintModeIndex - the index of the Print Mode

##### RETURN VALUE

N/A

##### ERROR CODES

NO_ERROR Success.

SYSTEM_ERROR No printer selected yet.

##### SEE ALSO

[Back to top]

## InputPixelsPerRow

##### SYNOPSIS

int InputPixelsPerRow () ;

##### DESCRIPTION

This method queries the number of pixels per row of the printed image.

##### PARAMETERS

Void

##### RETURN VALUE

Calling PixelsPerRow returns an integer indicating the raster width for this printer. This number also corresponds to the expected number of 24-bit RGB pixels received by Job::SendRasters in each call.

##### ERROR CODES

N/A

##### SEE ALSO

## OutputPixelsPerRow ()

##### SYNOPSIS

unsigned int OutputPixelsPerRow () ;

##### DESCRIPTION

This method returns the current setting for output width.

##### PARAMETERS

Void

##### RETURN VALUE

Calling PixelsPerRow returns an integer indicating the raster width for this printer. This number also corresponds to the expected number of 24-bit RGB pixels received by Job::SendRasters in each call.

##### ERROR CODES

N/A

##### SEE ALSO

## GetPaperSize

##### SYNOPSIS

PAPER_SIZE GetPaperSize () ;

##### DESCRIPTION

This routine queries for the currently set paper size.

##### PARAMETERS

Void

##### RETURN VALUE

Calling GetMediaSize returns a value from the PAPER_SIZE enum corresponding to the current paper size to be printed on.

##### ERROR CODES

N/A

##### SEE ALSO

Paper Sizes

## PhysicalPageSizeX

##### SYNOPSIS

float PhysicalPageSizeX () ;

##### DESCRIPTION

This method is used to get the physical width of the currently selected paper size.

##### PARAMETERS

Void

##### RETURN VALUE

The page width is returned in inches. 0 is returned if a printer object has not been created yet.

##### ERROR CODES

N/A

##### SEE ALSO

[Back to top]

## PhysicalPageSizeY

##### SYNOPSIS

float PhysicalPageSizeY () ;

##### DESCRIPTION

This method is used to get the physical height of the currently selected paper size.

##### PARAMETERS

Void

##### RETURN VALUE

The page height is returned in inches. 0 is returned if a printer object has not been created yet.

##### ERROR CODES

N/A

##### SEE ALSO

## PrintableStartX

##### SYNOPSIS

unsigned int PrintableStartX () ;

##### DESCRIPTION

This method is used to return the left margin or distance from the edge of the page to where the printed raster actually begins. By default, the left margin has been calculated to center the printable region on the physical page. Hence, the left and right margins are identical.

##### PARAMETERS

Void

##### RETURN VALUE

Calling PrintableStartX returns a float description in inches. Returns a value of 0 if a printer object has not been created yet.

##### ERROR CODES

N/A

##### SEE ALSO

## PrintableStartY

##### SYNOPSIS

unsigned int PrintableStartY () ;

##### DESCRIPTION

This method is used to return the top margin or distance from the top edge of the page to where the first raster is actually printed.

##### PARAMETERS

Void

##### RETURN VALUE

Calling PrintableStartY returns a float description in inches. Returns a value of 0 if a printer object has not been created yet..

##### ERROR CODES

N/A

##### SEE ALSO

## PrintableWidth

##### SYNOPSIS

float PrintableWidth () ;

##### DESCRIPTION

This method returns the height of printable region in inches.

##### PARAMETERS

Void

##### RETURN VALUE

N/A

##### ERROR CODES

N/A

##### SEE ALSO

## PrintableHeight

##### SYNOPSIS

float PrintableHeight () ;

##### DESCRIPTION

This method returns the height of printable region in inches.

##### PARAMETERS

Void

##### RETURN VALUE

N/A

##### ERROR CODES

N/A

##### SEE ALSO

[Back to top]

## voidFlush

##### SYNOPSIS

voidFlush (int FlushSize);

##### DESCRIPTION

This method flushes data in the printer's input buffer to prepare for a new data stream.

##### PARAMETERS

FlushSize - how many bytes to send to flush the printer buffer.

##### RETURN VALUE

None

##### ERROR CODES

None

##### SEE ALSO

## GetHelpType ()

##### SYNOPSIS

HELP_TYPE GetHelpType ()

##### DESCRIPTION

This method returns a HELP_TYPE value corresponding to the selected printer class, for use in composing the URL for HTML Help.

##### PARAMETERS

Void

##### RETURN VALUE

HELP_TYPE

##### ERROR CODES

None

##### SEE ALSO

<Help Section>

## EffectiveResolutionX

##### SYNOPSIS

unsigned int EffectiveResoltuionX ()

##### DESCRIPTION

This method returns the horizontal printer resolution to be used for the currently selected print mode. (Returns zero if there is no current print mode.)

##### PARAMETERS

Void

##### RETURN VALUE

Returns the horizontal printer resolution.

##### ERROR CODES

None

##### SEE ALSO

## EffectiveResolutionY

##### SYNOPSIS

unsigned int EffectiveResoltuionY ()

##### DESCRIPTION

This method returns the vertical printer resolution to be used for the currently selected print mode. (Returns zero if there is no current print mode.)

##### PARAMETERS

Void

##### RETURN VALUE

Returns the vertical printer resolution.

##### ERROR CODES

None

##### SEE ALSO

## SetInputResolution

##### SYNOPSIS

DRIVER_ERROR SetInputResolution (unsigned int Res)

##### DESCRIPTION

This method is used to tell the code that the image data should be considered as already at a higher resolution and thus not to be scaled up. In the current version there is no print mode with resolution less than 300 or greater than 600, so 600 is the only useful parameter here, 300 being the default resolution assumed for input data.(Note that the value used here is assumed to be "square", that is, the same for both horizontal and vertical dimensions; thus it cannot exceed the lower of the two values EffectiveResolutionX, EffectiveResolutionY.)

##### PARAMETERS

unsigned int Res - resolution of input data

##### RETURN VALUE

DRIVER_ERROR

##### ERROR CODES

error: Res exceeded the effective resolution in one or both dimensions.

##### SEE ALSO

## InputResolution

##### SYNOPSIS

unsigned int InputResolution ()

##### DESCRIPTION

This method returns the value set by SetInputResolution (or the default value of 300).

##### PARAMETERS

Void

##### RETURN VALUE

Returns the value set by SetInputResolution.

##### ERROR CODES

None

##### SEE ALSO

## SendPrinterReadyData

##### SYNOPSIS

DRIVER_ERROR SendPrinterReadyData (Byte* stream, unsigned int size);

##### DESCRIPTION

This method is used when data that has been formatted in the target printer language is available from an external source. Not to be combined with the normal Job functions such as SendRaster. You do not even need to create a Job when using this function, in fact no Job should exist when it is being used.

##### PARAMETERS

stream - pointer to the byte stream.

size - size of the buffer.

##### RETURN VALUE

DRIVER_ERROR

##### ERROR CODES

I/O_ERROR

JOB_CANCELLED

##### SEE ALSO

Pass Through Mode Document

[Back to top]

# class Font

#### NOTE: ALL methods and member variables within the Font class are used only if _COURIER, _CGTIMES,_LTRGOTHIC, or _UNIVERS not #defined.

## ~Font

##### SYNOPSIS

~Font () ;

##### DESCRIPTION

This method is a deconstructor invoked by deleting Font or object going out of scope.

##### PARAMETERS

N/A

##### RETURN VALUE

N/A

##### ERROR CODES

N/A

##### SEE ALSO

## GetName

##### SYNOPSIS

const char* GetName ();

##### DESCRIPTION

This method returns the typeface name.

##### PARAMETERS

Void

##### RETURN VALUE

Calling GetName returns a pointer to the typeface name. This pointer is constant and cannot be changed.

##### ERROR CODES

N/A

##### SEE ALSO

## IsBoldAllowed

##### SYNOPSIS

BOOL IsboldAllowed ();

##### DESCRIPTION

This method tells whether text bolding is available.

##### PARAMETERS

Void

##### RETURN VALUE

TRUE, if bold is allowed.

##### ERROR CODES

N/A

##### SEE ALSO

[Back to top]

## IsItalicAllowed

##### SYNOPSIS

BOOL IsItalicAllowed () ;

##### DESCRIPTION

This method tells whether text italicizing is available.

##### PARAMETERS

Void

##### RETURN VALUE

Returns TRUE, if italics is allowed.

##### ERROR CODES

N/A

##### SEE ALSO

## IsUnderlineAllowed

##### SYNOPSIS

BOOL IsUnderlinedAllowed () ;

##### DESCRIPTION

This method tells whether text underlining is available.

##### PARAMETERS

Void

##### RETURN VALUE

Returns TRUE, if underline is allowed.

##### ERROR CODES

N/A

##### SEE ALSO

## IsColorAllowed

##### SYNOPSIS

BOOL IsColorAllowed () ;

##### DESCRIPTION

This method tells whether text coloring is available.

##### PARAMETERS

Void

##### RETURN VALUE

Returns TRUE, if color is allowed.

##### ERROR CODES

N/A

##### SEE ALSO

[Back to top]

## IsProportional

##### SYNOPSIS

BOOL IsProportional () ;

##### DESCRIPTION

This method tells whether this font is proportionally spaced, as opposed to fixed.

##### PARAMETERS

Void

##### RETURN VALUE

Returns TRUE, if this font is proportional.

##### ERROR CODES

N/A

##### SEE ALSO

## HasSerif

##### SYNOPSIS

BOOL HasSerif () ;

##### DESCRIPTION

This method tells whether this typeface has serifs.

##### PARAMETERS

Void

##### RETURN VALUE

HasSerif returns TRUE if the typeface has serifs.

##### ERROR CODES

N/A

##### SEE ALSO

## GetTextExtent

##### SYNOPSIS

DRIVER_ERROR GetTextExtent (const char* pTextString, const int iLenString,
int& IHeight, int& iWidth) ;

##### DESCRIPTION

This function will calculate & return the width and height (in printer units) for the given text string based on the font supplied

##### PARAMETERS

pTextString string used to calculate sizeiLenString length of the string.
IHeight - result calculated for height (output).
iWidth - result calculated for width (output).

##### RETURN VALUE

DRIVER_ERROR

Output parameters iWidth,iHeight

##### ERROR CODES

SYSTEM_ERROR

##### SEE ALSO

[Back to top]

## GetPitch

##### SYNOPSIS

BYTE GetPitch (const BYTE pointsize) ;

##### DESCRIPTION

This method, for fixed fonts, returns the pitch for given point-size. (Returns zero for proportional fonts.)

##### PARAMETERS

pointsize size in traditional typesetting unit.

##### RETURN VALUE

The pitch, which is defined in terms of characters per inch. A pitch of 10 (or 10-pitch) means that 10 characters (at the specified point size) will cover 1 inch across the page.

##### ERROR CODES

N/A

##### SEE ALSO

## iPointsize

##### SYNOPSIS

int iPointsize;

##### DESCRIPTION

This variable holds currently selected point size.

##### SEE ALSO

[Back to top]

## bBold

##### SYNOPSIS

BOOL bBold;

##### DESCRIPTION

This variable tells whether bold is currently selected.

##### SEE ALSO

## bItalic

##### SYNOPSIS

BOOL bItalic;

##### DESCRIPTION

This variable tells whether italic is currently selected.

##### SEE ALSO

## bUnderline

##### SYNOPSIS

BOOL bUnderline;

##### DESCRIPTION

This variable tells whether underline is currently selected.

##### SEE ALSO

[Back to top]

## eColor

##### SYNOPSIS

TEXTCOLOR eColor;

##### DESCRIPTION

This variable holds currently selected color.

##### SEE ALSO

## iPitch

##### SYNOPSIS

int iPitch;

##### DESCRIPTION

This variable holds currently selected pitch.

##### SEE ALSO

## Index

##### SYNOPSIS

int Index ()

##### DESCRIPTION

This method is an index of point-size from available list for this font.

##### PARAMETERS

Void

##### RETURN VALUE

Calling Index returns an integer

##### ERROR CODES

N/A

##### SEE ALSO

[Back to top]

# class Job

## Job

##### SYNOPSIS

Job (PrintContext* pPC) ;

##### DESCRIPTION

This constructor should only be invoked after valid SystemServices and PrintContext objects have been created, and all settings pertinent to this Job have been established in the PrintContext. No future changes in PrintContext will affect this Job.

##### PARAMETERS

pPC pointer to previously created, valid PrintContext.

##### RETURN VALUE

N/A

##### ERROR CODES

must check constructor_error for valid construction.

##### SEE ALSO

## ~Job

##### SYNOPSIS

~Job () ;

##### DESCRIPTION

This destructor is invoked by delete, or object going out of scope.

##### PARAMETERS

N/A

##### RETURN VALUE

N/A

##### ERROR CODES

N/A

##### SEE ALSO

## SendRasters

##### SYNOPSIS

DRIVER_ERROR SendRasters (BYTE* ImageData=(BYTE*) NULL) ;

##### DESCRIPTION

This is the fundamental method for the driver, by means of which graphics data is sent to the printer. The data must be of the width previously specified in the PrintContext. Its format is RGB24, that is, eight bits each of red, green and blue per pixel. It should be called once for every row on the page from start until NewPage is called, using the default (NULL) parameter for blank rows.

##### PARAMETERS

ImageData=(BYTE*) NULL Pointer to graphics data, 24 bits per pixel. If NULL, causes the printer to skip a row.

##### RETURN VALUE

DRIVER_ERROR

##### ERROR CODES

IO_ERROR, SYSTEM_ERROR

##### SEE ALSO

[Back to top]

The following method is available only in builds which include text support (see Version function.)

## TextOut

##### SYNOPSIS

DRIVER_ERROR TextOut (const char* pTextString, int iLenString,
const Font& font, int iAbsX, int iAbsY ) ;

##### DESCRIPTION

This method is used to send ASCII data to the printer, which it will render as determined by the Font object.

##### PARAMETERS

pTextString Pointer to a buffer containing the ASCII data.
iLenString Length of string to be printed.
font the font object encapsulating settings to be used.
iAbsX specifies horizontal location on page.
iAbsY specifies vertical location on page.

##### RETURN VALUE

DRIVER_ERROR

##### ERROR CODES

IO_ERROR, SYSTEM_ERROR, ILLEGAL_COORDS

##### SEE ALSO

## NewPage

##### SYNOPSIS

DRIVER_ERROR NewPage () ;

##### DESCRIPTION

This method resets counters, flushes buffers, and sends a form feed to the printer.

##### PARAMETERS

Void

##### RETURN VALUE

DRIVER_ERROR

##### ERROR CODES

JOB_CANCELLED

IO_ERROR

##### SEE ALSO

[Back to top]

# Appendix

#

# Enums and Data Types

BOOL TRUE or FALSE

BYTE unsigned char

DISPLAY_STATUS user-interface code

For more information on the following, see the Display Statuses section under Printer Driver codes.

DRIVER_ERROR error code

PAPER_SIZE size of target medium

PRINTER_FUNC auxiliary function

PRINTER_TYPE printer model family (DJ400, DJ540, DJ600, DJ6xx, DJ6xxPhoto, DJ8xx, DJ9xx, DJ9xxVIP, DJ630)

TEXTCOLOR color used for a font
HELP_TYPE index into HTML Help pages (dj400, dj540, dj600, dj6xx, dj6xxPhoto, dj8xx, dj9xx, dj9xxVIP, dj630, eprinter)

# Printer Driver Codes

## Driver Errors

Errors in the SDK code set are represented by integers with a value greater than zero.

ALLOCMEM_ERROR Failed to allocate memory.

BAD_DEVICE_ID Couldnt get intelligible device identifier string.

GRAPHICS_UNSUPPORTED Graphics output is unsupported in the build.

ILLEGAL COORDS Bad (x,y) passed to TextOut.

ILLEGAL_PAPERSIZE - Paper size illegal for given hardware.

ILLEGAL_RESOLUTION Tried to set resolutions at unacceptable values.

INDEX_OUT_OF_RANGE The index is out of range. Illegal value for a function that takes an index, e.g. index of PrintMode.

IO_ERROR Failed communications with printer.

JOB_CANCELLED CANCEL chosen by user.

The symbol NO_ERROR is defined as zero.

NO_ERROR Everything is okay.

NO_PRINTER_SELECTED No printer has been selected (either implicitly, or explicitly in the case of one-way communications,) prior to making a call that pre-supposes printer selection.

NULL_POINTER - The supplied pointer was null.

SYSTEM_ERROR Something bad has happened that should not have happened.

TEXT_UNSUPPORTED Printer fonts are unsupported in the build.

UNSUPPORTED_FONT The selected font is unsupported in the build. This also may just indicate a bad index from the client code.

UNSUPPORTED FUNCTION [0x16] Bad selection for PerformPrinterFunction.

UNSUPPORTED_PEN The selected pen-type is unsupported in the build. This also may just indicate a bad index from the client code.

UNSPPORTED_PRINTER The selected printer-type is unsupported in the build. This also may just indicate a bad index from the client code.

Warnings in the SDK code set are represented by a value less than zero.

WARN_MODE_MISMATCH The printmode selection is incompatible with the pen, tray, etc.

WARN_DUPLEX The duplexer is installed; the Hewlett-Packard driver can't use it in this version.

[Back to top]

## Display Statuses

DISPLAY_PRINTING Status Message

DISPLAY_PRINTING_CANCELED Status Message.

DISPLAY_PRINTING_COMPLETE Status Message.

DISPLAY_BUSY Mismatch between checkbox and cartridge installed, or cartridge is incorrect or missing.

DISPLAY_CANT_ID_PRINTER - There is a printer connected but none is selected in the Printer Setup.

DISPLAY_COMM_PROBLEM Incorrect connection between the printer and the switch box. Or, Printer in error state (e.g. out of paper,) and the power button is pressed.

DISPLAY_ERROR_TRAP Carriage stall.

DISPLAY_NO_PRINTER_FOUND There is no printer connected, or the printer is turned off.

DISPLAY_NO_PEN_DJ400 No cartridge is installed for the DJ400 or the print cartridge button was not pressed after the cartridge was installed.

DISPLAY_NO_PEN_DJ600 No cartridge is installed for the DJ600 or the print cartridge button was not pressed after the cartridge was installed.

DISPLAY_NO_COLOR_PEN No cartridge is installed in the color cartridge cradle.

DISPLAY_NO_BLACK_PEN No cartridge is installed in the black cartridge cradle.

DISPLAY_NO_PENS No cartridges were installed in any two-pen printer, or the print cartridge button was not pressed after the cartridges were installed.

DISPLAY_OFFLINE Incorrect print cartridge installation, or print cartridge is missing.

DISPLAY_OUT_OF_PAPER Out of Paper.

DISPLAY_PHOTO_PEN_WARN Reminds user that the photo cartridge is not supported, and expensive to use.

DISPLAY_PRINTER_NOT_SUPPORTED Printer is a Hewlett-Packard printer that is not supported. May print anyway, but output may not be recognizable.

DISPLAY_TOP_COVER_OPEN Top cover open.

[Back to top]

## Paper Sizes

US Letter

US Legal

A4

## Text Colors

WHITE_TEXT

CYAN_TEXT

MAGENTA_TEXT

BLUE_TEXT

YELLOW_TEXT

GREEN_TEXT

RED_TEXT

BLACK_TEXT

##

## Printer Func

CLEAN_PEN

Note: This list will be expanding in the future.

##

## Printer Type

DJ600

DJ630

DJ6xx

DJ6xxPhoto

DJ8xx

DJ9xx

DJ9xxVIP

Note: This list of printers is only for API Version 2.0, and may be changed for future versions.

[Back to top]