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.
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.
![]() |
|||
![]() |
|||
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.
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.
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.
Function
Name |
Description |
Return Type |
Parameters |
Returns a string identifying components and features of the driver build. |
char * |
BOOL bCompress |
Member
Name |
Description |
Data
/ Return Type |
Parameters |
The following items are provided in the
base class |
|||
constructor |
N/A |
Void |
|
destructor |
N/A |
N/A |
|
Calling code must check that the value of this variable is NO_ERROR before proceeding. |
DRIVER_ERROR |
N/A |
|
Mandatory call to be inserted in derived constructor. |
DRIVER_ERROR |
Void |
|
Tests communication with printer. |
BOOL |
Void |
|
The following items are to be implemented for the host system |
|||
Uses message code to relay a message to the user. |
Void |
DISPLAY_STATUS |
|
Waits for the specified number of milliseconds before returning to the caller. |
DRIVER_ERROR |
DWORD msec |
|
Retrieves the device identifier string from the printer. |
DRIVER_ERROR |
BYTE* strID, int iSize |
|
Allocates a block of memory. |
BYTE* |
int iMemSize |
|
Frees a given block of memory. |
Void |
BYTE* pMem |
|
Reads status register from printer. |
BOOL |
BYTE* bStatReg |
|
Sends bytes of data to the printer. |
DRIVER_ERROR |
const BYTE* pBuffer, DWORD* dwCount |
|
Gets data from printer. |
DRIVER_ERROR |
char* pReadBuff, WORD* wReadCount |
|
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 |
|
Gives host system a chance to process asynchronous events |
BOOL |
Void |
|
Get random number from system. |
BYTE |
Void |
|
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 |
|||
Pointer to the script-debugging handler. |
Scripter* |
N/A |
|
Begin recording script for debugging. |
DRIVER_ERROR |
const char* FileName, BOOL ascii, BOOL read |
|
Stop recording script for debugging. |
DRIVER_ERROR |
Void |
Member Name |
Description |
Data
/ Return Type |
Parameters
|
constructor |
N/A |
pSysServ, InputPixelsPerRow, OutputPixelsPerRow, ps, |
|
destructor |
N/A |
N/A |
|
Calling code must check that the value of this variable is NO_ERROR before proceeding. |
DRIVER_ERROR |
N/A |
|
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 |
|
Returns the currently selected device. |
PRINTER_TYPE |
Void |
|
Returns number of supported print modes for the select printer model. |
unsigned int |
Void |
|
Returns the identifying string for the currently selected print mode. |
char* |
Void |
|
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 |
Retrieves an index of the currently selected print mode. |
unsigned int |
Void |
|
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 |
|
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 |
|
Returns the enum for the next supported model. Used when bi-directional communication is missing. |
PRINTER_TYPE |
unsigned int& currIDX |
|
Used outside the context of a Job, to perform functions such as pen cleaning. |
DRIVER_ERROR |
PRINTER_FUNC eFunc |
|
Sets or changes the target paper size for a print job. |
DRIVER_ERROR |
PAPER_SIZE ps |
|
Sets the width of all rows on the page. |
DRIVER_ERROR |
unsigned int PixelsPerRow |
|
Returns TRUE if printer has been selected. |
BOOL |
Void |
|
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 |
Retrieves information about the physical width of the currently selected paper size. |
float |
Void |
|
Retrieves information about the physical height of the currently selected paper size. |
float |
Void |
|
Returns the left margin or distance from the top edge of the page. |
float |
Void |
|
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 |
|||
Flushes data in the printer's input buffer to prepare for new data stream. |
int |
Void |
|
For use when pre-formatted data is available from an external source. |
DRIVER_ERROR |
BYTE* stream, unsigned int size |
Function
Name |
Description |
Data
/ Return Type |
Parameters |
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 |
|
Destructor |
N/A |
N/A |
|
The following are for use in determining general properties of the font family, prior to instantiating a concrete font. |
|||
Returns the typeface name. |
char* |
Void |
|
Tells whether text bolding is available. |
BOOL |
Void |
|
Tells whether text italicizing is available. |
BOOL |
Void |
|
Tells whether text underlining is available. |
BOOL |
Void |
|
Tells whether text coloring is available. |
BOOL |
Void |
|
Tells whether this font is proportionally spaced, as opposed to fixed. |
BOOL |
Void |
|
Tells whether this typeface has serifs. |
BOOL |
Void |
|
The following items refer to a concrete
font already created by RealizeFont. |
|||
Calculates width and height of a string using current settings. |
DRIVER_ERROR |
const char* pTextSTring, const int iLenString, int& iHeight, int& iWidth |
|
For fixed fonts, returns the pitch for given point-size. (Returns zero for proportional fonts.) |
BYTE |
const BYTE pointsize |
|
Variable holds currently selected point size. |
int |
N/A |
|
Tells whether bold is currently selected. |
BOOL |
N/A |
|
Tells whether italic is currently selected. |
BOOL |
N/A |
|
Tells whether underline is currently selected. |
BOOL |
N/A |
|
Variable holds currently selected color. |
BOOL |
N/A |
|
Variable holds currently selected color. |
BOOL |
N/A |
|
Index of point-size from available list for this font. |
int |
Void |
Function
Name |
Description |
Data
/ Return Type |
Parameters |
constructor |
N/A |
PrintContext* pPC |
|
destructor |
N/A |
N/A |
|
Calling code must check that the value of this variable is NO_ERROR
before proceeding. |
DRIVER_ERROR |
N/A |
|
This is the fundamental method for the driver, by
means of which graphics data is sent to the printer |
DRIVER_ERROR |
BYTE* ImageData |
|
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 |
|
Resets counters, flushes buffers, and sends a
form feed to the printer |
DRIVER_ERROR |
Void |
char* Version (BOOL beCompressed) ;
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.
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.
String as described above
N/A
SystemServices (WORD unsigned int) ;
This method constructs a SystemServices object. This is the first step in the calling sequence.
ToDevice
FromDevice
N/A
N/A see constructor_error
~SystemServices () ;
This method is a destructor, called when the instance of SystemServices is deleted or goes out of scope.
N/A
N/A
N/A
DRIVER_ERROR constructor_error;
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.
DRIVER_ERROR InitDeviceComm () ;
This method tries to establish communications with printer and identify it. This base-class routine must be called by the derived SystemServices constructor.
Void
DRIVER_ERROR
CANCELLED
BOOL PrinterIsAlive () ;
This method
tests communication with printer.
NOTE:
This implementation is appropriate for Parallel bus only.
Void
TRUE if communication with printer is working.
N/A
BYTE DisplayPrinterStatus (DISPLAY_STATUS ePrinterStatus)
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.
EPrinterStatus code for status condition see Display Statuses in Appendix.
Void
N/A
DRIVER_ERROR BusyWait (DWORD msec);
This method waits for the specified number of milliseconds before returning to the caller.
msec milliseconds to wait
Void
DRIVER_ERROR
DRIVER_ERROR ReadDeviceID(BYTE* strID, int iSize);
This method retrieves the device identifier string from the printer.
strID - pointer to buffer for storing string.
iSize The size of buffer.
DRIVER_ERROR
IO_ERROR
BYTE* AllocMem (int iMemSize);
This method will allocate a contiguous block of memory at least iMemSize bytes long.
iMemSize - size of block.
Returns a pointer to the memory block. Can also return NULL, if allocation failed.
N/A
void FreeMem (BYTE* pMem);
This method frees a given block of memory.
pMem pointer to the block of memory to be freed.
Void
N/A
BOOL GetStatusInfo (BYTE* bStatReg)
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.
bStatReg pointer to a byte into which status register will be copied.
TRUE - when the value is set after returning the parallel status byte.
FALSE - if the functionality is not supported.
N/A
DRIVER_ERROR ToDevice (const BYTE* pBuffer, DWORD* d wCount)
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.
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.
DRIVER_ERROR
Varies per implementation.
DRIVER_ERROR FromDevice (char* pReadBuff, WORD* wReadCount);
This method gets data from the printer.
pReadBuff pointer to buffer into which data is to be copied.
wReadCount output parameter (pointer to allocated WORD) telling number of bytes copied.
DRIVER_ERROR
Varies per implementation
DRIVER_ERROR GetECPStatus (Byte *pStatusString, int *pECPLength, int ECPChannel)
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.
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.
PStatusString now contains the set of status bytes retrieved from the ECP channel.
DRIVER_ERROR
BYTE YieldToSystem (void)-0;
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.
Void
BOOL
N/A
BYTE GetRandomNumber ();
This method gets random number from system. Any seeding of random number generator needs to be done in constructor.
Void
Returns an 8-bit, pseudo-random number.
N/A
DWORD GetSystemTickCount (void);
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.
Void
DWORD number of ticks for current tick count.
N/A
DRIVER_ERROR FlushIO ();
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.
N/A
DRIVER_ERROR
N/A
DRIVER_ERROR AbortIO ();
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.
N/A
DRIVER_ERROR.
N/A
Scripter *pScripter;
This member variable is a pointer to the script-debugging handler.
DRIVER_ERROR InitScript (const char* FileName, BOOL ascii) ;
This member variable begins recording script for debugging.
FileName name of the output file which will hold the script.
ascii If TRUE use ASCII implementation. Otherwise, use binary.
DRIVER_ERROR
SYSTEM_ERROR - if file cant be opened.
DRIVER_ERROR EndScript () ;
This member variable stops recording script for debugging.
Void
DRIVER_ERROR
SYSTEM_ERROR - if called out of sequence.
PrintContext
(SystemServices * pSysServ,
unsigned int InputPixelsPerRow,
unsigned int OutputPixelsPerRow,
PAPER_SIZE ps);
This method constructs a PrintContext object
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.
N/A
constructor_error must be NO_ERROR, else object is invalid.
~PrintContext ();
This method is a destructor, called when object is deleted or goes out of scope.
N/A
N/A
N/A
DRIVER_ERROR SelectDevice (const PRINTER_TYPE Model)
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.
Model The model of printer as mapped to the enumeration PRINTER_TYPE.
Calling the host with this method returns an error code of type DRIVER_ERROR.
NO_ERROR Success
UNSUPPORTED_PRINTER This printer type is unavailable.
UNSUPPORTED_PEN This pen type is unavailable.
PRINTER_TYPE
SelectedDevice () ;
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
Void
PRINTER_TYPE - returns UNSUPPORTED if no Printer has been selected, either implicitly or explicitly.
N/A
Unsigned int GetModeCount ();
This method is used to determine the number of supported print modes for this device.
Void
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
N/A
Unsigned int GetModeName ();
This method returns the identifying string for the currently selected print mode. Returns NULL if no printer selected.
Void
This method returns char* , the identifying string for the currently selected print mode.
N/A
DRIVER_ERROR SelectPrintMode (const unsigned int index) ;
This method is used to select the print mode for the current print job.
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
DRIVER_ERROR.
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.
const char* PrinterModel (void) ;
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.
Void
strModel - the model portion of the firmware ID string from SystemServices, or NULL if no printer is selected or the connection is uni-di.
N/A
const char* PrintertypeToString (PRINTER_TYPE pt) ;
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.
PRINTER_TYPE enum representing one of the supported printer model families.
Returns a string version of the enum.
N/A
unsigned int CurrentPrintMode () ;
This method is used to determine the current print mode.
Void
Returns the index value for the currently used print mode.
N/A
The
following two methods are only available in builds that support printer
fonts see the Version
function.
ReferenceFont* EnumFont (int& iCurrIdx) ;
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.
ICurrIdx Caller starts at zero; reference variable is incremented automatically for next call.
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.
N/A
Font* RealizeFont (const int index, const BYTE bSize,
const TEXTCOLOR eColor=BLACK,
const BOOL bBold=FALSE, const BOOL bItalic=FALSE,
const BOOL bUnderline=FALSE);
This method is the means of creating a Font object with the desired properties, for use in Job::TextOut calls.
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
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.
None
PRINTER_TYPE EnumDevices (int& currIdx) const;
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.
currIdx Caller starts at zero; reference variable is incremented automatically for next call.
A value matching an element of the enum PRINTER_TYPE, which can then be passed to other methods such as SelectDevice.
N/A
DRIVER_ERROR PerformPrinterFunction (PRINTER_FUNC eFunc) ;
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.
eFunc The action which the host has requested the printer to perform.
An error value of type DRIVER_ERROR.
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.
DRIVER_ERROR SetPaperSize (PAPER_SIZE ps) ;
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.
ps The desired paper size.
An error value of type DRIVER_ERROR.
NO_ERROR Success
NO_PRINTER_SELECTED - Failure
DRIVER_ERROR SetPixelsPerRow (unsigned int PixelsPerRow,
unsigned int OutputPixelsPerRow=0) ;
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.
PixelsPerRow The number of pixels to be printed for every row in this Job.
An error value of type DRIVER_ERROR
NO_ERROR Success
ILLEGAL_COORDS If pixels per row exceeds the printable region of this printer and paper type.
BOOL PrinterSelected () ;
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.
Void
TRUE if a printer object exists
FALSE if a printer object does not exist. This indicates a printer model must be specified (via SelectDevice).
N/A
BOOL PrinterFontsAvailable (unsigned int PrintModeIndex) ;
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.
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
N/A
NO_ERROR Success.
SYSTEM_ERROR No printer selected yet.
int InputPixelsPerRow () ;
This method queries the number of pixels per row of the printed image.
Void
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.
N/A
unsigned int OutputPixelsPerRow () ;
This method returns the current setting for output width.
Void
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.
N/A
PAPER_SIZE GetPaperSize () ;
This routine queries for the currently set paper size.
Void
Calling GetMediaSize returns a value from the PAPER_SIZE enum corresponding to the current paper size to be printed on.
N/A
float PhysicalPageSizeX () ;
This method is used to get the physical width of the currently selected paper size.
Void
The page width is returned in inches. 0 is returned if a printer object has not been created yet.
N/A
float PhysicalPageSizeY () ;
This method is used to get the physical height of the currently selected paper size.
Void
The page height is returned in inches. 0 is returned if a printer object has not been created yet.
N/A
unsigned int PrintableStartX () ;
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.
Void
Calling PrintableStartX returns a float description in inches. Returns a value of 0 if a printer object has not been created yet.
N/A
unsigned int PrintableStartY () ;
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.
Void
Calling PrintableStartY returns a float description in inches. Returns a value of 0 if a printer object has not been created yet..
N/A
float PrintableWidth () ;
This method returns the height of printable region in inches.
Void
N/A
N/A
float PrintableHeight () ;
This method returns the height of printable region in inches.
Void
N/A
N/A
voidFlush (int FlushSize);
This method flushes data in the printer's input buffer to prepare for a new data stream.
FlushSize - how many bytes to send to flush the printer buffer.
None
None
HELP_TYPE GetHelpType ()
This method returns a HELP_TYPE value corresponding to the selected printer class, for use in composing the URL for HTML Help.
Void
HELP_TYPE
None
<Help Section>
unsigned int EffectiveResoltuionX ()
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.)
Void
Returns the horizontal printer resolution.
None
unsigned int EffectiveResoltuionY ()
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.)
Void
Returns the vertical printer resolution.
None
DRIVER_ERROR SetInputResolution (unsigned int Res)
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.)
unsigned int Res - resolution of input data
DRIVER_ERROR
error: Res exceeded the effective resolution in one or both dimensions.
unsigned int InputResolution ()
This method returns the value set by SetInputResolution (or the default value of 300).
Void
Returns the value set by SetInputResolution.
None
DRIVER_ERROR SendPrinterReadyData (Byte* stream, unsigned int size);
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.
stream - pointer to the byte stream.
size - size of the buffer.
DRIVER_ERROR
I/O_ERROR
JOB_CANCELLED
Pass Through Mode Document
~Font () ;
This method is a deconstructor invoked by deleting Font or object going out of scope.
N/A
N/A
N/A
const char* GetName ();
This method returns the typeface name.
Void
Calling GetName returns a pointer to the typeface name. This pointer is constant and cannot be changed.
N/A
BOOL IsboldAllowed ();
This method tells whether text bolding is available.
Void
TRUE, if bold is allowed.
N/A
BOOL IsItalicAllowed () ;
This method tells whether text italicizing is available.
Void
Returns TRUE, if italics is allowed.
N/A
BOOL IsUnderlinedAllowed () ;
This method tells whether text underlining is available.
Void
Returns TRUE, if underline is allowed.
N/A
BOOL IsColorAllowed () ;
This method tells whether text coloring is available.
Void
Returns TRUE, if color is allowed.
N/A
BOOL IsProportional () ;
This method tells whether this font is proportionally spaced, as opposed to fixed.
Void
Returns TRUE, if this font is proportional.
N/A
BOOL HasSerif () ;
This method tells whether this typeface has serifs.
Void
HasSerif returns TRUE if the typeface has serifs.
N/A
DRIVER_ERROR
GetTextExtent (const char* pTextString, const int iLenString,
int& IHeight, int& iWidth) ;
This function will calculate & return the width and height (in printer units) for the given text string based on the font supplied
pTextString
string
used to calculate sizeiLenString
length of the string.
IHeight
- result
calculated for height (output).
iWidth
- result
calculated for width (output).
DRIVER_ERROR
Output parameters iWidth,iHeight
SYSTEM_ERROR
BYTE GetPitch (const BYTE pointsize) ;
This method, for fixed fonts, returns the pitch for given point-size. (Returns zero for proportional fonts.)
pointsize size in traditional typesetting unit.
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.
N/A
int iPointsize;
This variable holds currently selected point size.
BOOL bBold;
This variable tells whether bold is currently selected.
BOOL bItalic;
This variable tells whether italic is currently selected.
BOOL bUnderline;
This variable tells whether underline is currently selected.
TEXTCOLOR eColor;
This variable holds currently selected color.
int iPitch;
This variable holds currently selected pitch.
int Index ()
This method is an index of point-size from available list for this font.
Void
Calling Index returns an integer
N/A
Job (PrintContext* pPC) ;
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.
pPC pointer to previously created, valid PrintContext.
N/A
must check constructor_error for valid construction.
~Job () ;
This destructor is invoked by delete, or object going out of scope.
N/A
N/A
N/A
DRIVER_ERROR SendRasters (BYTE* ImageData=(BYTE*) NULL) ;
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.
ImageData=(BYTE*) NULL Pointer to graphics data, 24 bits per pixel. If NULL, causes the printer to skip a row.
DRIVER_ERROR
IO_ERROR, SYSTEM_ERROR
The
following method is available only in builds which include text support (see
Version function.)
DRIVER_ERROR
TextOut (const char* pTextString, int iLenString,
const Font& font, int iAbsX, int iAbsY ) ;
This method is used to send ASCII data to the printer, which it will render as determined by the Font object.
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.
DRIVER_ERROR
IO_ERROR, SYSTEM_ERROR, ILLEGAL_COORDS
DRIVER_ERROR NewPage () ;
This method resets counters, flushes buffers, and sends a form feed to the printer.
Void
DRIVER_ERROR
JOB_CANCELLED
IO_ERROR
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)
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.
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.
US Letter
US Legal
A4
WHITE_TEXT
CYAN_TEXT
MAGENTA_TEXT
BLUE_TEXT
YELLOW_TEXT
GREEN_TEXT
RED_TEXT
BLACK_TEXT
CLEAN_PEN
Note: This list will be expanding in the future.
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.