The Printer protocol
--- ------- --------

   The printer protocol is used to ensure a uniform procedure by which an
application may print files of any type, allowing for the files to be
printed immediately or queued by other software for printing later. The
printer manager Printers, supplied with RISC OS 3, uses this protocol. The
description below will assume that the dialogue is being conducted between
an application and Printers, to avoid referring repeatedly to "the
destination of the printer protocol."

   The protocol for printing a file is:

         1 The application issues either:

            (a) DataSave    (user dropped file onto Printers icon)
            (b) PrintSave   (user initiated an application 'Print' option)

         2 If Printers is loaded, it replies with PrintError if there is an
      error (the protocol is now over), or PrintFile. (This stage is present
      for compatibility with RISC OS 2 applications.) If Printers is not
      loaded, the message bounces. In this case, the application should do
      one of two things: if it was graphics printing, go ahead and try to
      print anyway; if it was text printing, complain that the printer
      manager is required.

         3 The application does one of the following:

               ignores PrintFile (this is the normal behaviour under RISC
            OS 3);

               replies with WillPrint and prints the file (this is the RISC
            OS 2 behaviour, now deprecated - the application has "jumped the
            queue);

               converts the file, stores the output in Printer$Temp, and
            replies with DataLoad.

      In the first case, the protocol continues as described below.

         4 Printers responds in one of two ways, depending on whether the
      destination printer is in use or not, by issuing either:

            PrintTypeOdd (requesting the application to print the file
                  itself immediately);

            DataSaveAck (requesting the application to send the file to
                  Printers for queuing).

      In the first case, this PrintTypeOdd is NOT broadcast, and does NOT
      contain valid file type or file name fields. These must not be relied
      on.

         5 In the first case, the application may be able to print the file
      itself immediately, in which case it replies with PrintTypeKnown and
      prints the file (the protocol is now over); or it may not, in which
      case it ignores the PrintTypeOdd, and Printers responds with a
      DataSaveAck, so that it can take a copy of the file. 

         6 Either way, the application has received a DataSaveAck from
      Printers. It should save the data it wants printed to the file
      whose name was supplied in the DataSaveAck message, and reply with
      DataLoad.

         7 Printers will respond with DataLoadAck. The file is in the print
      queue.

   At some future time, the file will rise to the top of the queue (unless
the user has removed it manually), and Printers will broadcast a PrintType-
Odd to find an application willing to print the file. (This might be the
same application as the one that queued the file, or a different one.) If
the PrintTypeOdd is not replied to, Printers will issue the SWI

      sprintf (s, "@PrintType_%3.3X %s", file_type, file_name);
      _swi (Wimp_StartTask, _IN (0), s);

This should be a command that will cause the application to print the file
immediately.

   In response to the PrintSave, the printer manager may reply with
PrintError (0x80144). If the size of this message is 20, this means you are
talking to an old printer manager and it is busy. If the size of the message
is not 20, there is an error number at offset 20 and null terminated error
text at offset 24.

   If the application is doing graphics printing, it should print the file
WITHOUT CALLING Wimp_Poll. Wimp_Poll must NOT be called when using
Printers because when Printers regains control it assumes that the current
file has been printed and moves on to the next entry in the queue.

   The protocol as decribed above is the one implemented by Printers. Future
versions of printer managing software may take the copy by RAM transfer from
applications that support it: to be ready for this, the application should
be prepared for a RAMFetch to be sent in the place of the DataSaveAck
described above. (By ignoring this RAMFetch, they will revert to the
file-based protocol.)
