Printer messages
================

 Author: Philip Colmer
Version: 0.03
History: 0.01  04-Jun-91  Created
         0.02  12-Jun-91  PrintBusy changed to PrintError and expanded
                          PrintFile message contents changed
         0.03  18-Jun-91  PS messages added

This document specifies the Wimp messages understood and used by !Printers.
The basic protocol is:

 * Application issues DataSave (user has dropped file onto printer icon) or
   PrintSave (user has initiated an application print option).

 * !Printers replies with PrintError if there is an error or PrintFile.

 * Application does one of the following:
   * ignores PrintFile, in which case !Printers will respond with
     DataSaveAck, to which the application should reply with a DataLoad.
   * replies with WillPrint and then proceeds to print the file
   * converts the file, stores the output in <Printer$Temp> and replies with
     DataLoad.

 * Upon receipt of a DataLoad, the file gets queued and the application is
   sent a DataLoadAck.

IMPORTANT! With the introduction of true queueing, the use of the PrintFile
protocol is now deprecated. Applications should rely on the PrintTypeOdd
protocol instead. Receipt of a PrintFile message should be IGNORED!

PrintFile (80140)
-----------------
 This messsage is broadcast as a recorded delivery upon receipt of a
DataSave or PrintSave message. The reason for having this message is
two-fold:

 * the application doing the DataSave might need to know that, in effect,
   the user is wanting to print.
 * it allows applications to try and improve on !Printer-provided services
   such as text printing.

 The format of the message is:

 +12: your_ref
 +16: &80140
 +20
 ...  from DataSave/PrintSave block
 +44

 This allows any application to try and do better than !Printers can do with
the default actions available. Such an application has three choices:

1) It can ignore the message, in which case if no-one else claims it,
   !Printers will resort to the normal processes (ie issue a DataSaveAck).

2) It can respond with WillPrint, in which case !Printers takes no further
   action.

3) It can convert the file into another format and store in the file
   specified by <Printer$Temp>. It should then reply with a DataLoad with
   the filetype reflecting the new type.

WillPrint (80141)
-----------------
 This message is sent by an application in response to a PrintFile
broadcast. The application should then proceed to print the file.

PrintSave (80142)
-----------------
 The format of this message is:

 +12: 0
 +16: &80142
 +20
 ...  as for DataSave
 +44

 It allows applications to send files to the printer manager for printing
without having to know the task handle, etc since the message is broadcast.
The message simply needs to be broadcast as a recorded delivery, at which
point the printer manager will enter the PrintFile dialogue. If the message
bounces, the application should complain as the printer manager is not
loaded.

PrintInit (80143)
-----------------
 This is broadcast when a printer manager is starting up. Any active printer
managers should quit quietly upon receipt of this message to avoid a clash
occurring.

PrintError (80144)
------------------
 This was sent by release 2 printer managers in response to a PrintSave if
they were already printing (since they could only queue one file at a time).
With !Printers, it will be sent if an error occurs as a result of one of the
other messages being used. The format of the block will be:

 +12: your_ref
 +16: &80140
 +20: error number
 +24: error message (NULL terminated)

 To maintain compatibility with release 2 printer managers, if the message
is the original PrintBusy, the size (in +0) will be 20.

 Error numbers (and english messages) to date are:

1: Can only print from applications when a printer has been selected
   This is sent in reply to a PrintSave when there isn't a selected printer.

PrintTypeOdd (80145)
--------------------
 This message is broadcast if the filetype is not considered known by
!Printers. "Known" is qualified as being the current printer type (eg FF5
for PostScript), text, obey or command files. The format of the message is:

 +12: 0 (zero)
 +16: &80145
 +40: file type of data
 +44: zero terminated filename

 If an application can print this filetype directly, it should respond with
PrintTypeKnown. The application can either print the file directly to
printer:, or it can output it to <Printer$Temp> in which case this MUST be
done before replying with PrintTypeKnown.

PrintTypeKnown (80146)
----------------------
 This message is sent by an application in response to a PrintTypeOdd.

SetPrinter (80147)
------------------
 This message is broadcast by !Printers when the printer settings or
selection has changed.

PrintInit2 (80148)
SelectTemporaryPrinter (80149)
SelectPermanentPrinter (8014A)
SelectPrinterOK (8014B)
------------------------------
 These messages are not used. They were defined for release 3 printer
drivers and are no longer necessary. For clarity sakes, they have not been
reassigned.

PSPrinterQuery (8014C)
----------------------
 This message is sent as a recorded delivery by !FontPrint to !Printers when
!FontPrint either starts up or when it receives SetPrinter. The layout of
the block is:

 +12: 0
 +16: &8014C
 +20: buffer address (or zero)
 +24: buffer size

 If the buffer address is non-zero, !Printers places the following
information into the buffer (all NULL terminated):

 * current printer name
 * current printer type
 * pathname to printer font file

 Regardless of the buffer address, !Printers places the real buffer size
into the block and replies with:

PSPrinterAck (8014D)
--------------------
 This is sent by !Printers to !FontPrint in response to PSPrinterQuery. If
!FontPrint does not receive this message, it should raise an error to advise
the user (eg !Printers is required to allow use of !FontPrint).

PSPrinterModified (8014E)
-------------------------
 This is sent by !FontPrint to !Printers when the user clicks on the Save
button. !Printers then re-reads the font file and resets the printer's font
list.

PSPrinterDefaults (8014F)
-------------------------
 This is sent by !FontPrint to !Printers when the user clicks on the Default
button. !Printers then resets the font file, resets the printer's font list
and replies with:

PSPrinterDefaulted (80150)
--------------------------
 This is sent by !Printers to !FontPrint when the font file has been reset.

PSPrinterNotPS (80151)
----------------------
 This is sent by !Printers upon receipt of PSPrinterQuery if the currently
selected printer is not a PostScript printer.

ResetPrinter (80152)
--------------------
 This can be sent to !Printers to ensure that the printer settings are
correct for the currently selected printer.

PSIsFontPrintRunning (80153)
----------------------------
 If !FontPrint receives this message, it will acknowledge it.
