TweetFollow Us on Twitter

Desktop Printing Revealed

Volume Number: 13 (1997)
Issue Number: 8
Column Tag: develop

Desktop Printing Revealed

by Dave Polaschek

With the introduction of System 6 and MultiFinder in 1989, Apple introduced background printing. For the first time, a user could regain control of the Macintosh almost immediately after printing a document, while the printer driver processed the document in the background. Classic background printing has been far more robust than anyone may have imagined, and it's still the basis of much of today's printing technology, including desktop printing. Unfortunately for developers interested in supporting desktop printing, the interfaces to background printing have remained largely undocumented.

In 1994 the desktop printing architecture was introduced with the StyleWriter 1200 driver and LaserWriter 8.3. From its initial release to the present, desktop printing has existed as a collection of extensions and invisible applications. While this has not created a clear and simple picture for developers interested in supporting desktop printing, this technology shows every sign of thriving for a long time to come, so understanding its architecture is more vital than ever.

While the complete story is far from written, and things will certainly change again with the introduction of Rhapsody, this article will cover background printing for all pre-Rhapsody versions of the MacOS. This includes the significant changes that will make Desktop Printing accessible to third party developers. If you've currently got a printer driver, this article describes everything you need to add support for desktop printing.

Classic Background Printing

The way early background printing worked was that printer drivers would save each page as a QuickDraw picture in the data fork of a temporary file (a spool file) in a special folder (the Spool Folder) within the System Folder. There was also information stored in the resource fork describing the page format, document name, and other job information, as well as offsets to the beginning of the data for each page. A special application (Backgrounder) launched by MultiFinder at startup time (in System 7, Backgrounder was incorporated into Finder) would see the document created by the printer driver and would launch PrintMonitor, which would run in the background, feeding the spool file to the printer driver.

PrintMonitor performs its magic by calling the printer driver in much the same way as an application would, except rather than your driver's 'PDEF' 0 resource getting called, its 'PDEF' 126 resource -- which has the same format as the 'PDEF' 0 resource -- is called. A special PrGeneral call is sent just after PrOpen has been called (before PrOpenDoc has been called), to provide the printer driver with the pointers to notification functions it will need to call. PrintMonitor then prints each page by replaying the stored page data to the driver. This method of background printing is still used by the Printing Manager today in two cases: when desktop printing isn't installed (or has been disabled) and when the Finder isn't running (usually because At Ease is running instead).

Getting to know classic background printing means you need to know the structure of its spool file. The resource fork of the spool file contains the following resources (note that all structures mentioned in this document have 68k alignment):

*  'PREC' 3 -- the print record
*  'alis' -8192 -- an alias to the driver that created the spool file
*  'ics#' 131 -- the small icon to display for the spool file in the PrintMonitor window
*  'PREC' 124 -- the printer name
*  'PREC' 126 -- the job information
typedef {
  short    version;    // always 0
  short   flags;       // always 0
  short   numPages;    // total number of pages in the spool file
  short    numCopies;  // total number of copies for the spool file
  OSType  crtr;        // the creator type of the driver used to 
                       // create the spool file
  Str31    appName;    // the application name used to print the 
                       // spool file
} PREC236Record, **PREC126Handle;
*  'STR ' -8192 -- the filename of the printer driver
*  'STR ' -8189 -- the document name (always padded to 80 bytes)
The data fork of the spool file begins with a SpoolHeader structure, followed by the pages.
typedef struct {
  short    version;     // should always be 1
  long    fileLen;      // length of file including header
  long    fileFlags;    // should always be 0
  short    numPages;
  TPrint  printRecord;  // used only if PREC 3 can't be read
} SpoolHeader, *SpoolHeaderPtr, **SpoolHeaderHdle;

typedef struct {
  long    pictFlags;    // should always be 0
  Picture  thePict;     // variable length
  long    pageOffset;   // offset to the beginning of this page's  
                        // PICT
} Page;

The spool file is created by the driver in the Spool Folder or PrintMonitor Documents folder within the System Folder (or in the current default desktop printer folder if MacOS 8 desktop printing is active -- you can find the correct folder with FindFolder and the kPrintMonitorDocsFolderType selector). The spool file has the name of the document being printed. If you're putting the file directly into the desktop printer folder, you'll need to append "(print)" to the filename (which means you may need to shorten the document name). Spool files that are being written have a type of '?job' and a creator of 'prmt'. Once the file is completely written, the driver changes the type to 'pjob'. When the version of Desktop Printing that supports third-party drivers is available, your driver also needs to send an Apple event to the Finder telling it that a new spool file was created (more on this below).

When PrintMonitor (or Desktop PrintMonitor) prints a job, it calls the driver's PrOpen routine and then calls PrGeneral with the structure shown below (see the DTPNotification.h header file, available on MacTech's web site at, for specifics). PrintMonitor then calls PrOpenDoc with a pIdleProc that the driver needs to call periodically. PrOpenPage and PrClosePage will get called for each page of the document, and the page will be printed to the driver.

// Function prototypes
typedef pascal void (*AsynchErrorNotificationProcPtr) 
  (StringHandle string);
typedef pascal void (*EndNotificationProcPtr) ();
typedef pascal Boolean (*InForegroundProcPtr) ();
typedef pascal void (*StatusMessageProcPtr) (StringHandle string);

const short kPrintMonitorPrGeneral = -3;

typedef struct {
  short            iOpCode;     // kPrintMonitorPrGeneral
  short            iError;
  long            iReserved;   // 0 = PrintMonitor,
                               // 1 = Desktop PrintMonitor
  THPrint          hPrint;
  short            noProcs;
  long            iReserved2;
  // UPP to put up a notification
  ErrorNotificationUPP  pASyncNotificationProc;

  // UPP to take down the notification
  EndNotificationUPP  pASyncUnnotifyProc;

  // UPP to see if we are in the foreground
  InForegroundUPP    pInForegroundProc;

  // UPP to update the status message
  // (available only with desktop printing that supports third parties)
  StatusMessageUPP    pStatusMessageProc;

} TDesktopPrintingData;

When printing with background printing, both PrintMonitor and Desktop PrintMonitor will put a DialogPtr into the low-memory global ApplScratch just before calling PrOpenDoc. The driver should put status messages into the first item in that dialog using GetDialogItem and SetDialogItemText.

If the PrGeneral call says that printing is occurring from Desktop PrintMonitor (which is a faceless background application), no dialogs or alerts should be displayed. The one exception is that Desktop PrintMonitor patches StopAlert and ParamText. If you call ParamText and then StopAlert, the Finder will display an alert for you with the text you've set. However, the filter proc passed into StopAlert will not be called.

Desktop Printing Today

Desktop printing was introduced with the LaserWriter 8.3 and the StyleWriter 1200 printer drivers, and it uses much the same approach as classic background printing. Currently, desktop printing only supports Apple print drivers, but the additions described in this section are things you will need to incorporate into your drivers in order to work with desktop printing in the future. The additional resources a driver needs to add to support desktop printing are the icons for the desktop printers. As a driver developer you'll need to supply a full 'BNDL' resource with your driver's creator. Beyond the types and icons you've probably already got in your driver (for the driver itself and any preferences file), you'll need to add icons for the types 'dpnn', 'dpcn', and 'dpna', which correspond to a "normal" desktop printer, a default desktop printer (with the heavy line around it), and an inactive (or unavailable) desktop printer. LaserWriter 8 has a slightly different scheme for setting the icons for desktop printers, in that it retrieves them from the PostScript printer description (PPD) file for a given printer.

The StyleWriter 2500 Bundle and Icons

When an Apple driver creates a spool file for desktop printing, it places the file in the same folder used by classic background printing. The Desktop Printing Extension will take care of moving the file to the desktop printer and beginning the process of actually printing the document. The resources defined immediately following are those added to the spool file when desktop printing is active:

*  'PINX' -8200 -- the page index resource
*  'jobi' 1 -- the print job information
typedef struct {
  short  count;
  long  pageoffset[1];  // The offset from the beginning of the file to
                        // the pageRecord (i.e., for the first page, it
                        // would be sizeof(SpoolHeader))
} PageIndex, *PageIndexPtr, **PageIndexHdl;

// Print priorities
#define  kPrintJobUrgent    0x00000001
#define  kPrintJobAtTime    0x00000002
#define  kPrintJobNormal    0x00000003
#define  kPrintJobHolding   0x00001003

typedef struct {
  short        firstPageToPrint;  // first page in the spool file to print
  short        priority;          // print priority
  short        numCopies;         // total number of copies
  short        numPages;          // total number of pages in the spool file
  unsigned long  timeToPrint;     // (when priority is kPrintJobAtTime)
  Str31        documentName;      // name of the document
  Str31        applicationName;   // the name of the application
  Str32        printerName;       // should match PREC 124
} PrintJobInfo, **PrintJobInfoHandle;

Another addition is a new way to change the default desktop printer. An application or driver can send an Apple event to the Finder as shown below. (Note that SendAEToFinder just sends the event to the Finder with an eventID of kFinderExtension.)

#define kDesktopPrinting  'dtpx'
#define kFinderExtension  'fext'

typedef struct {
  OSType  pfeCreator;
  OSType  extensionType;
  Str31    dtpName;
} SetDTPEvent;

OSErr SetDefaultDTP(StringPtr dtpName)
  OSErr      err=noErr;
  SetDTPEvent  myEvent;

  myEvent.pfeCreator = kDesktopPrinting;
  myEvent.extensionType = 'pfpr';
  pStrCpy(myEvent.dtpName, dtpName);
  err = SendAEToFinder((Ptr) &myEvent, sizeof(SetDTPEvent));
  return (err);

Desktop Printing Tomorrow

With the introduction of MacOS 8, desktop printing will no longer be a separate extension. It will be integrated into the Finder and therefore available in most cases. A user can still disable desktop printing by disabling the Desktop PrintMonitor and Desktop Printer Spooler in Extensions Manager, though. In a future version changes will be made to make it possible for third parties to integrate support. These changes are also being made to the previous versions of desktop printing so third parties (that's you!) can use desktop printing on systems which have not been upgraded to MacOS 8. For details on licensing the Desktop Printing software, contact Apple's Software Licensing department, at (512) 919-2645 or

Desktop printing installs a Gestalt selector to tell you if third-party drivers can be supported. If desktop printing is available, but this selector does not report that third-party drivers are supported by desktop printing, you will need to use the methods described in the "Classic Background Printing" section above.

#define kGestaltPFEFeatures  'dtpf'
#define kThirdPartySupport    0x00000004

Boolean ThirdPartyDriverSupported(void)
  long  response;
  Boolean  result = false;
  OSErr  err = Gestalt(kGestaltPFEFeatures, &response);
  if (err == noErr)
    result = !!(response & kThirdPartySupport);
  return result;

When non-Apple drivers are supported by desktop printing, your driver needs to write your spool files directly to the desktop printer folder with the type of '?job'. When you are done spooling, you need to change the file's type to 'pjob'. The driver can determine the current default desktop printer folder, and many other things, by calling the Gestalt routine with the desktop printing extension selector. The selector is 'dtpx', and the information is returned to you in a handle. When you're done with the handle, do not call DisposeHandle on theDTPList and the GestaltPFEInfoHdle.

typedef struct {
  short    vRefNum;      // vRefNum of the desktop printer folder
  long    dirID;         // Directory ID of the desktop printer
  Str31    dtpName;      // Name of the desktop printer folder
  OSType  driverType;    // Driver's creator
  Boolean  isDefault;    // Is this the default desktop printer?
  Str32    printerName;  // Network name of the printer (only for
                         // LaserWriter 8.4 desktop printers)
  Str32    zoneName;     // Zone of the printer (only for LaserWriter 
                         // 8.4 desktop printers)
} DTPInfo, *DTPInfoPtr;

typedef struct
  long     structversion;  // Version of this structure
  short    numDTPs;        // Number of desktop printers in the list
  Handle  theDTPList;
} GestaltPFEInfo, **GestaltPFEInfoHdle;

When you're done writing the spool file, you need to send a Core Apple event to the Finder with the following direct object key:

typedef struct {
  OSType    pfeCreator;    // Set this to 'dtpx'
  OSType    pfeEventType;  // Set this to 'pfsc'
  FSSpec    dtpSpec;       // The file spec of the desktop printer where 
                           // the new spool file was added
} SyncDTPEventData;

There are also added calls for this version of desktop printing. Specifically, there are three new PrGeneral selectors that a driver needs to support: kIsSamePrinterInfo, kGetPrinterInfo, and kSetDefaultPrinterInfo. These selectors enable the desktop printing extension to decide which of the driver's desktop printers is the current default printer, to determine whether it needs to create a new desktop printer, and to inform the driver that a desktop printer has been selected as the default. The structures you'll need to use to support these selectors are shown below.

// DTP printer types
enum { kSerial, kAppleTalk, kTCPIP, kUnknown };
enum { kPrinterPort, kModemPort };
enum {
  kGetPrinterInfo = 23,
  kIsSamePrinterInfo = 24,
  kSetDefaultPrinterInfo = 25

typedef struct {
  short    port;          // kPrinterPort or kModemPort
} SerialPrinterInfo;

typedef struct {
  Str32    nbpName;
  Str32    nbpZone;
  Str32    nbpType;
} AppleTalkPrinterInfo;

typedef struct {
  Str255  TCPIPAddress;
} TCPIPPrinterInfo;

typedef struct {
  Str31    dtpDefaultName;  // Default name to be used for the desktop
                            // printer. The desktop printing extension
                            // will add a suffix if there's a conflict 
                            // with other desktop printers.
  short    printerType;

  // Info specific to each class of printers
  union {
    SerialPrinterInfo    serialInfo;
    AppleTalkPrinterInfo  appleTalkInfo;
    TCPIPPrinterInfo    TCPIPInfo;
  } u;
  // Optional driver-specific information can be appended here.
} DTPPrinterInfo, **DTPPrinterInfoHandle;

typedef struct {
  short            iOpCode;
  short            iError;
  long            iCommand;
  DTPPrinterInfoHandle  printerInfo;
} TPrinterInfoPrGeneralData;

When your driver is selected in the Chooser, desktop printing will call your driver via a series of PrGeneral calls. First, you'll get called with the kIsSamePrinterInfo selector for each of the desktop printers created by your driver in order to determine which is the currently selected printer. Your driver responds by filling in the iError field of the TPrinterInfoPrGeneralData record. If the printer that your driver thinks is current matches the information passed in with the kIsSamePrinterInfo selector, the driver responds by setting the iError field to noErr. If it's not a match, the driver sets the iError field to -1.

If the printer selected in the Chooser is not among the desktop printers owned by your driver, desktop printing will create a new desktop printer and call PrGeneral with the kGetPrinterInfo selector to get the information for the selected printer. At this point, your driver should resize the printerInfo handle and fill in the printer information. You need to fill in the dtpDefaultName field with the name you'd like to see a desktop printer created with. Also note that your driver can append as much (or as little) extra printer information as you'd like. Once you've returned the information, the desktop printing extension will save this information into the desktop printer.

If a user selects one of your desktop printers via the Set Default Printer menu item in the Printing menu (which appears in the Finder when you've clicked on a desktop printer), your driver will get a PrGeneral call with the kSetDefaultPrinterInfo selector. When you receive this call, you should change any internal settings your driver maintains so that the printer pointed to by the DTPPrinterInfo you received is now the currently selected printer for your driver.

The Future Is Now

If you've currently got a driver that supports classic background printing, your best bet for future compatibility is to add support for desktop printing. However, if you're just starting to tackle background printing now, while you could implement support for MacOS 8 desktop printing only, we strongly recommend that you support the current desktop printing architecture and classic background printing, as well. That way your users will have a more consistent experience when printing, regardless of which version of the MacOS they're running.

Thanks to reviewers Alan Beck, Rich Blanchard, Paul Danbold, Hueii Huang, Ingrid Kelly, and Donna Lee. And thanks to Jimmy Buffett for the soundtrack.

Dave Polaschek (, doesn't work for Apple anymore, but he still finds himself writing these articles. Most summer evenings will find Dave watching the St. Paul Saints from his season-ticket seat five rows behind the umpire, who often seems to show a surprising lack of knowledge as to where the strike zone really is. Fear not; Dave makes sure the umpire gets properly educated over the course of the season.


Community Search:
MacTech Search:

Software Updates via MacUpdate

OmniPlan 3.0 - Robust project management...
With OmniPlan, you can create logical, manageable project plans with Gantt charts, schedules, summaries, milestones, and critical paths. Break down the tasks needed to make your project a success,... Read more
Yummy FTP 1.11 - FTP/SFTP/FTPS client fo...
Yummy FTP is an FTP + SFTP + FTPS file transfer client which focuses on speed, reliability and productivity. Whether you need to transfer a few files or a few thousand, schedule automatic backups, or... Read more
Tweetbot 2.1 - Popular Twitter client. (...
Tweetbot is a full-featured OS X Twitter client with a lot of personality. Whether it's the meticulously-crafted interface, sounds and animation, or features like multiple timelines and column views... Read more
MacPilot 8.0 - Enable over 1,200 hidden...
MacPilot gives you the power of UNIX and the simplicity of Macintosh, which means a phenomenal amount of untapped power in your hands! Use MacPilot to unlock over 1,200 features, and access them all... Read more
Typinator 6.7 - Speedy and reliable text...
Typinator turbo-charges your typing productivity. Type a little. Typinator does the rest. We've all faced projects that require repetitive typing tasks. With Typinator, you can store commonly used... Read more
Adobe Lightroom 6.2 - Import, develop, a...
Adobe Lightroom is available as part of Adobe Creative Cloud for as little as $9.99/month bundled with Photoshop CC as part of the photography package. Lightroom 6 is also available for purchase as a... Read more
ForeverSave 2.1.4 - Universal auto-save...
ForeverSave auto-saves all documents you're working on while simultaneously doing backup versioning in the background. Lost data can be quickly restored at any time. Losing data, caused by... Read more
VueScan 9.5.27 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more
AirPort Utility 6.3.6 - Set up and manag...
Note: Most recent release available only within OS X 10.11 El Capitan update. Use AirPort Utility to set up and manage your Wi-Fi network and AirPort base stations, including AirPort Express, AirPort... Read more
Quicksilver 1.3.1 - Application launcher...
Quicksilver is a light, fast and free Mac application that gives you the power to control your Mac with keystrokes alone. Quicksilver allows you to find what you need quickly and easily, then act... Read more

Super Sharp (Games)
Super Sharp 1.1 Device: iOS Universal Category: Games Price: $1.99, Version: 1.1 (iTunes) Description: Your finger has never been so sharp! Cut with skill to complete the 120 ingenious physics levels of Super Sharp and become a cut... | Read more »
Assembly - Graphic design for everyone...
Assembly - Graphic design for everyone 1.0 Device: iOS Universal Category: Photography Price: $2.99, Version: 1.0 (iTunes) Description: Assembly is the easiest most powerful design tool on the App Store. Create anything you can... | Read more »
YAMGUN (Games)
YAMGUN 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: The invasion has begun! Protect the walls of the citadel against waves of enemies! But watch out, you will soon run out of ammo...... | Read more »
Royal Bounty HD (Games)
Royal Bounty HD 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: New World Computing Approved "Hi Guys! looks good so far! keep up the good work. I worked on HoMM 3 and 4 creating all of the... | Read more »
Swords & Crossbones: An Epic Pirate...
Swords & Crossbones: An Epic Pirate Story 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: | Read more »
Camel Up (Games)
Camel Up 1.0.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.0 (iTunes) Description: | Read more »
The Martian: Bring Him Home (Games)
The Martian: Bring Him Home 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Based on the best selling novel and critically acclaimed film, THE MARTIAN tells the story of Astronaut Mark... | Read more »
This Week at 148Apps: September 21-30, 2...
Leap Into Fall With 148Apps How do you know what apps are worth your time and money? Just look to the review team at 148Apps. We sort through the chaos and find the apps you're looking for. The ones we love become Editor’s Choice, standing out above... | Read more »
Tweetbot 4 for Twitter (Social Networki...
Tweetbot 4 for Twitter 4.0 Device: iOS Universal Category: Social Networking Price: $4.99, Version: 4.0 (iTunes) Description: *** 50% off for a limited time. *** | Read more »
Mori (Games)
Mori 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Stop, rewind and unwind with Mori. Time is always running, take a moment to take control. Mori is an action puzzle game about infinitely... | Read more »

Price Scanner via

Save up to $350 with Apple refurbished iMacs
Apple has Certified Refurbished iMacs available for up to $350 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 27″ 3.5GHz 5K iMac – $1949 $350 off MSRP - 27... Read more
Mac Pros on sale for up to $300 off MSRP
B&H Photo has Mac Pros on sale for up to $300 off MSRP. Shipping is free, and B&H charges sales tax in NY only: - 3.7GHz 4-core Mac Pro: $2818.99, $181 off MSRP - 3.5GHz 6-core Mac Pro: $3699... Read more
5K iMacs on sale for up to $150 off MSRP, fre...
B&H Photo has the 27″ 3.3GHz 5K iMac on sale for $1899.99 including free shipping plus NY tax only. Their price is $100 off MSRP. They have the 27″ 3.5GHz 5K iMac on sale for $2149, $150 off MSRP... Read more
Twelve South Redesigns BookArc For Today’s Sm...
Twelve South has announced a redesigned version of their very first product, BookArc for MacBook. Tailored specifically for the newest generation of MacBooks, BookArc holds the new, smaller Apple... Read more
Phone 6s Tips & Tricks – Tips Book For iP...
Poole, United Kingdom based Tap Guides Ltd. has announced the release and immediate availability of iPhone 6s Tips & Tricks, an in-depth eBook available in the iBookstore that’s priced just $2.99... Read more
13-inch 2.5GHz MacBook Pro on sale for $994,...
Best Buy has the 13″ 2.5GHz MacBook Pro available for $994.99 on their online store. Choose free shipping or free instant local store pickup (if available). Their price is $105 off MSRP. Price valid... Read more
Is The iPad Pro Really A Serious Laptop Repla...
Probably not, at least for productive professionals and other power users. Steve Jobs declared that we’d entered the “post-PC Era” with the advent of the original iPad in 2010, a phrase we don’t hear... Read more
Wednesday Deal: 13-inch Retina MacBook Pros f...
Adorama has 13″ Retina MacBook Pros on sale for up to $130 off MSRP. Shipping is free, and Adorama charges sales tax for NY & NJ residents only: - 13″ 2.7GHz/128GB Retina MacBook Pro: $1199.99 $... Read more
uBar 3.0 for Mac OS X – Custom Dock Replaceme...
Brawer Software has announced the release of uBar 3.0, an important update to their popular app and window manager for Mac OS X. uBar allows users to position it whichever side of the screen they... Read more
13-inch 2.5GHz MacBook Pro (refurbished) avai...
Apple has Certified Refurbished 13″ 2.5GHz MacBook Pros available for $829, or $270 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 13″ 2.5GHz MacBook Pros... Read more

Jobs Board

*Apple* Retail - Multiple Customer Support P...
Job Description:Customer SupportSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the Read more
Software Engineer, *Apple* Watch - Apple (U...
…the team that is revolutionizing the watch! As a software engineer on the Apple Watch team, you will be responsible for building world-class applications and frameworks Read more
*Apple* Online Store UAT Lead - Apple (Unite...
**Job Summary** The Apple Online Store is a fast paced and ever evolving business environment. The User Acceptance Testing (UAT) lead in this organization is able to Read more
Hardware Systems Integration Engineer - *App...
**Job Summary** We are seeking an enthusiastic electrical engineer for the Apple Watch team. This is a design engineering position that entails working with Read more
Touch Validation Design (EE) - *Apple* Watc...
**Job Summary** Help launch next-generation Touch Technologies in Apple products. The Touch Technology team develops cutting-edge Touch solutions and technologies that Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.