prnt/hpijs/systemservices.h

   1 /*****************************************************************************\
   2   systemservices.h : Interface for the SystemServices class
   3
   4   Copyright (c) 1996 - 2001, Hewlett-Packard Co.
   5   All rights reserved.
   6
   7   Redistribution and use in source and binary forms, with or without
   8   modification, are permitted provided that the following conditions
   9   are met:
  10   1. Redistributions of source code must retain the above copyright
  11      notice, this list of conditions and the following disclaimer.
  12   2. Redistributions in binary form must reproduce the above copyright
  13      notice, this list of conditions and the following disclaimer in the
  14      documentation and/or other materials provided with the distribution.
  15   3. Neither the name of Hewlett-Packard nor the names of its
  16      contributors may be used to endorse or promote products derived
  17      from this software without specific prior written permission.
  18
  19   THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED
  20   WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  21   MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN
  22   NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  23   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
  24   TO, PATENT INFRINGEMENT; PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
  25   OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
  26   ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  28   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29 \*****************************************************************************/
  30
  31
  32 #ifndef APDK_SYSTEMSERVICES_H
  33 #define APDK_SYSTEMSERVICES_H
  34
  35 APDK_BEGIN_NAMESPACE
  36
  37 struct IO_MODE
  38 {
  39  //NO_FEEDBACK, STATUS_ONLY, BIDI, USB
  40     BOOL bDevID;
  41     BOOL bStatus;
  42     BOOL bUSB;
  43 }; //IO_MODE
  44
  45
  46 //forward declarations
  47 class DeviceRegistry;
  48 //class RasterSender;
  49 class Scripter;
  50
  51 const int DevIDBuffSize = 512;       //!< size of buffer used by SetDevInfo
  52
  53 //SystemServices
  54 //! Provides interface to host environment
  55 /*! \class SystemServices systemservices.h "hpprintapi.h"
  56 The SystemServices object is used to encapsulate memory-management, I/O,
  57 clock access, user notification and UI, and other utilities provided by the
  58 operating system or host system supporting the driver. It is an abstract base
  59 class, requiring implementation of the necessary routines by the host.
  60 Creation of SystemServices is the first step in the calling sequence for the
  61 driver, followed by creation of the PrintContext and the Job. The derived
  62 class constructor must include a call to the member function InitDeviceComm,
  63 which establishes communication with the printer if possible.
  64 The only reference to this object in API-calling code should be to its
  65 constructor and destructor, which must be invoked prior to and after all other
  66 driver calls.
  67 ******************************************************************************/
  68 class SystemServices
  69 {
  70 friend class PrintContext;
  71 friend class Printer;   // for saved device strings
  72 #ifdef APDK_APOLLO2XXX
  73 friend class Apollo2xxx;    // it needs to check the specific model string
  74 #endif
  75 friend class Tester;
  76 friend class AsciiScripter;
  77 friend class BinaryScripter;
  78 public:
  79     SystemServices();
  80     virtual ~SystemServices();
  81
  82     /*!
  83     Check this member variable for the validity of the constructed object.
  84     Calling code must check that the value of this variable is NO_ERROR before
  85     proceeding.
  86     \sa DRIVER_ERROR
  87     */
  88     DRIVER_ERROR constructor_error;
  89
  90     //! Must include in derived class constructor (if using bi-di)
  91     DRIVER_ERROR InitDeviceComm();
  92
  93     /////////////////////////////////////////////////////////////////////
  94     IO_MODE IOMode;
  95
  96     //! Passes a command to the I/O system to send all data to the printer immediately.
  97     /*!
  98     A typical I/O system either buffer data or send data immediatly.  If the I/O
  99     system is buffering data then typically store all data sent in a buffer until it
 100     has some amount of data (say 1, 2, or 4 Kbytes) then will send that block of data
 101     to the printer. In some cases, it may be necessary that data that has just been
 102     sent to the I/O system reach the printer ASAP, at which point the printer driver
 103     will check the status or deviceID string of the printer and continue. Often,
 104     USB implementations will favor the block-send mechanism because it is more
 105     efficient through the system's call stack. Simple and traditional centronics
 106     I/O is usually not buffered, but this is still a system-by-system I/O preference.
 107
 108     If the I/O system is buffering data into blocks before sending to the printer,
 109     this command should pass a command to the I/O system to stop waiting and send
 110     everything it has to the printer now. The base implimentation simply returns
 111     NO_ERROR and is appropriate for a system that does not buffer I/O.
 112
 113     \note  The appropriate way to handle a FlushIO on a buffered system is to call
 114     the USB class driver's I/O Control routine with a flush command.  If the USB
 115     class driver has no flush command then check to see if it has timed flush
 116     (it auto-flushes every n [milli]seconds).  If it does then the base FlushIO
 117     method will work okay.
 118
 119     \warning In the past some have implemented flush by sending 10K nulls to the USB
 120     driver.  Currently this does work and will cause data already in the buffer
 121     to be sent to the printer.  Current printers ignore the null, however, there
 122     may be printers in the future that cannot handle this behavior.
 123     */
 124     virtual DRIVER_ERROR FlushIO() { return NO_ERROR; }
 125
 126     //! Tells the I/O system that the print job has ended prematurely.
 127     /*!
 128     This routine instructs the I/O system that this print job has ended
 129     prematurely, that no further data will be sent and that any data being held
 130     in a "send" buffer can be thrown away. This command is optional and depends
 131     on the implementation of the I/O system.  In some error conditions, the
 132     printer is incapable of accepting more data. The printer driver will sense
 133     this error and stop sending data, but if the I/O system has buffered data
 134     it may continue to wait for the printer to accept this remaining data
 135     before unloading. This mechanism will allow for a more efficient clean up
 136     of the aborted job.
 137     */
 138     virtual DRIVER_ERROR AbortIO() { return NO_ERROR; }
 139
 140     /*!
 141     Uses message code to relay a message to the user. Must be implemented in
 142     derived class provided by developer. This routine will cause a corresponding
 143     text string (or graphic, or both) to be displayed to the user to inform them
 144     of printer status. This is how printer events such as out-of-paper will be
 145     communicated to the user.
 146     */
 147     virtual void DisplayPrinterStatus (DISPLAY_STATUS ePrinterStatus)=0;
 148
 149     /*!
 150     Must be implemented in derived class. Waits for the specified number of
 151     milliseconds before returning to the caller. Gives host system a chance to
 152     process asynchronous events.  Derived implimentation of BusyWait MUST allow
 153     the processing of asynchronous events such as user interface changes, response
 154     to dialogs or pop-ups.  The BusyWait method should return NO_ERROR if we should
 155     continue processing.  The APDK core code calls busy wait within loops (when
 156     the printer is out of paper, has no pen, etc...) and will continue when the
 157     user has fixed the problem.  If the user wants to cancel the job then the
 158     implemented version of BusyWait must return JOB_CANCELED so that the APDK
 159     stops retrying and cancels the job.
 160     */
 161     virtual DRIVER_ERROR BusyWait(DWORD msec)=0;
 162
 163     /*!
 164     Retrieves the device identifier string from the printer.
 165
 166     \param strID Pointer to buffer for storing string.
 167     \param iSize The size of buffer.
 168     \return IO_ERROR
 169     */
 170     virtual DRIVER_ERROR ReadDeviceID(BYTE* strID, int iSize)=0;
 171
 172     /*!
 173     This method will allocate a contiguous block of memory at least iMemSize bytes long.
 174
 175     \param iMemSize - size of block.
 176     \return Pointer to the memory block. Can also return NULL, if allocation failed.
 177     */
 178     virtual BYTE* AllocMem (int iMemSize)=0;
 179
 180     /*!
 181     Frees a given block of memory previously allocated with AllocMem.
 182
 183     \param pMem - pointer to the block of memory to be freed.
 184     */
 185     virtual void FreeMem (BYTE* pMem)=0;
 186
 187     virtual BOOL PrinterIsAlive();
 188
 189     /*!
 190     This method reads status register from printer. If the parallel status byte
 191     is returned, the function returns TRUE when it sets this value. Otherwise
 192     the function returns FALSE if this functionality is not supported.
 193
 194     \param bStatReg Pointer to a byte into which status register will be copied.
 195
 196     \return TRUE The value is set after returning the parallel status byte,
 197     FALSE if the functionality is not supported.
 198     */
 199     virtual BOOL GetStatusInfo(BYTE* bStatReg)=0;
 200
 201     /*!
 202     Sends bytes of data to the printer.
 203     \note This method decrements the dwCount parameter (*dwCount) by the number
 204     of bytes that were actually sent.
 205
 206     \param pBuffer pointer to buffer full of data.
 207     \param dwCount (in/out) Upon entry, this contains the number of bytes of
 208     data requested to send. Upon return from the method, dwCount is the number
 209     of bytes that were not sent, i.e. the remaining bytes.
 210     */
 211     virtual DRIVER_ERROR ToDevice(const BYTE* pBuffer, DWORD* dwCount)=0;
 212
 213     /*!
 214     Gets data from printer.
 215
 216     \param pReadBuff Pointer to buffer into which data is to be copied.
 217     \param wReadCount Output parameter (pointer to allocated DWORD) telling
 218     number of bytes copied.
 219     */
 220     virtual DRIVER_ERROR FromDevice(BYTE* pReadBuff, DWORD* wReadCount)=0;
 221
 222     virtual DRIVER_ERROR GetECPStatus(BYTE *pStatusString,int *pECPLength, int ECPChannel);
 223
 224     /*!
 225     This routine will query the system for the current tick count (time).
 226     Since it will be used primarily for retry time-outs in the driver, it only
 227     needs to provide a running count of elapsed time since the device was booted,
 228     for example.
 229
 230     \return DWORD Number of ticks for current tick count.
 231     */
 232     virtual DWORD GetSystemTickCount (void)=0;
 233
 234     virtual float power(float x, float y)=0;
 235
 236     /*!
 237     Returns the model portion of the firmware ID string from the printer.
 238     */
 239     const char* PrinterModel() { return strModel; }
 240
 241         /*!
 242         Returns the size of the send buffer.
 243         */
 244     unsigned int GetSendBufferSize() const { return iSendBufferSize; }
 245
 246 #if defined (APDK_DJ3320)
 247     /*!
 248     This method return the reads Crossbow/Spear vertical alignment value from printer.
 249         If the vertical alignment value is set by the user from host,
 250         the function returns TRUE. Otherwise the function returns FALSE if this functionality
 251         is not supported.
 252
 253     \param cVertAlignVal Pointer to a byte into which vertical alignment value will be copied.
 254
 255     \return TRUE The value is set after returning the vertical alignment value,
 256     FALSE if the functionality is not supported.
 257     */
 258     virtual BOOL GetVerticalAlignmentValue(BYTE* cVertAlignVal) { return FALSE; }
 259
 260     /*!
 261     This method reads Crossbow/Spear vertical alignment value from the device during
 262     printer instantiation. The value is saved for later calls by GetVerticalAlignmentValue.
 263
 264     \return TRUE valid value read,
 265     FALSE invalid value or not supported.
 266     */
 267
 268     virtual BOOL GetVertAlignFromDevice() { return FALSE; }
 269 #endif
 270
 271 // utilities ///////////////////////////////////////////////////////
 272
 273     // call FreeMem after checking for null ptr
 274     DRIVER_ERROR FreeMemory(void *ptr);
 275     DRIVER_ERROR GetDeviceID(BYTE* strID, int iSize, BOOL query);
 276
 277         /*!
 278         Return the VIP version of the firmware ID from the printer.
 279         */
 280     int    GetVIPVersion () { return VIPVersion; }
 281
 282 #if defined(APDK_CAPTURE)
 283     Scripter *pScripter;
 284     /*!
 285     Begin recording script for debugging.
 286     \param FileName Name of the output file which will hold the script.
 287     \param ascii If TRUE use ASCII implementation. Otherwise, use binary.
 288     */
 289     DRIVER_ERROR InitScript(const char* FileName, BOOL ascii, BOOL read=FALSE);
 290
 291         /*!
 292     Stop recording script for debugging.
 293         */
 294     DRIVER_ERROR EndScript();
 295
 296     BOOL Capturing;
 297     BOOL replay;
 298 #endif
 299 \r
 300     virtual int GetPJLHeaderBuffer (char **szPJLBuffer)\r
 301     {\r
 302         return 0;\r
 303     }\r
 304
 305 protected:
 306     virtual void AdjustIO(IO_MODE IM, const char* model = NULL);
 307
 308     BYTE strDevID[DevIDBuffSize]; // save whole DevID string
 309
 310     unsigned int iSendBufferSize;
 311
 312
 313     PORTID ePortID;
 314
 315     DeviceRegistry* DR;
 316
 317     char strModel[DevIDBuffSize]; // to contain the MODEL (MDL) from the DevID
 318     char strPens[132];   // to contain the VSTATUS penID from the DevID
 319     int  VIPVersion;    // VIP version from the DevID
 320
 321     // for internal use
 322     virtual BYTE* AllocMem (int iMemSize, BOOL trackmemory)
 323     { return AllocMem(iMemSize); }
 324
 325     virtual void FreeMem (BYTE* pMem, BOOL trackmemory)
 326     { FreeMem(pMem); }
 327
 328 }; //SystemServices
 329
 330 APDK_END_NAMESPACE
 331
 332
 333 #endif //APDK_SYSTEMSERVICES_H