TweetFollow Us on Twitter

March 95 - Print Hints

PRINT HINTS

Writing QuickDraw GX Drivers With Custom I/O and Buffering

DAVE HERSEY

[IMAGE 073-077_Print_Hints_html1.GIF]


One of the great features of QuickDraw GX is that it provides the printer driver developer with default implementations of commonly used routines. For example, just by specifying a few parameters in your driver's 'comm' (gxDeviceCommunicationsType) resource, your printer driver can connect to a printer either serially or through the Printer Access Protocol (PAP). You don't need to write a single line of communications code!

Another powerful feature of QuickDraw GX is that you can ignore the default implementations of printer driver routines and write your own routines instead. This feature enables you to tailor your printer driver so that it can accommodate unique situations. The ability to modify bits and pieces of the printing system is especially useful when it comes to writing printer drivers with custom communications code or buffering routines.

In general, to create custom communications code, youconfigure your driver's 'iobm' (gxUniversalIOPrefsType)resource, create a "not connected" 'comm' resource, and then override certain QuickDraw GX messages. For SCSI printers, however, you don't need to create the "not connected" resource, because a SCSI format of the 'comm' resource is already defined. We'll talk more about when you would want to use custom communications code, and how to write it, later in this column.

Also covered is how to write custom buffering routines. You may want to use custom buffering if, for example, you already have code that you want to use or you want to increase printer performance by taking advantage of a hardware buffer that you have available.

On this issue's CD, you'll find a sample printer driver called CustomWriter that illustrates how to implement "not connected" custom I/O and buffering. In addition, there's a sample LaserWriter IISC printer driver that shows how to create custom I/O code for a SCSI printer.

CUSTOM I/O -- WHO NEEDS IT?
The default communications code in QuickDraw GX handles asynchronous communications for serial and PAP printers and QuickDraw GX shared printers. Even so, you may want to override this code in some cases, such as if your printer communicates using a protocol that QuickDraw GX doesn't support (like 200 Kbits/second serial), or if you have your own PAP code that you'd like to continue using.

QuickDraw GX also supports the special cases of "not connected" printers and SCSI printers. If you're writing a driver using either of these two types of connections, you'll need to write some custom I/O code. In fact, the "not connected" communications method is provided specifically for the developer writing a driver containing custom communications code. What does this type of communications method do? In the default implementation, nothing at all. In a minute, you'll see how to use this to your advantage.

The only SCSI support currently built into QuickDraw GX handles filling out the Chooser list with your devices' SCSI addresses and saving updated 'comm' resources for any desktop printers that are created. Otherwise, QuickDraw GX doesn't actually open connections or try to send commands, such as SCSIRead or SCSIWrite, to the printer. SCSI printers usually have unique command sets, and trying to provide a generic mechanism to support all of these devices is unrealistic. As a result, you must provide your own communications code if you're writing a SCSI driver.

Finally, if your device is connected through a hardware interface that QuickDraw GX doesn't provide default support for (such as a NuBusTM card), you'll need to provide all of the communications code for your driver.

HOW TO GET STARTED
The first step in writing a driver with custom communications code is to configure your driver's 'iobm' resource. This is a very easy (and very critical) exercise.

'iobm' stands for "Input/Output and Buffering preferences." So what does the "m" stand for? Great question. As it turns out, if you set up this resource incorrectly, it becomes an "I/O BooM" resource. (The system crashes.) The "m" is silent as long as the resource is set up correctly. *

The 'iobm' resource tells QuickDraw GX how your driver wants its communications and buffering environment set up. This resource has the following format:

type gxUniversalIOPrefsType {
    longint standardIO = 0x00000000,
            customIO = 0x00000001;
    longint;        // number of buffers to allocate,
                    // 0 = none
    longint;        // size of each buffer
    longint;        // number of IO requests that can
                    // be pending at any one time
    longint;        // open/close time-out in ticks
    longint;        // read/write time-out in ticks
};

The 'iobm' resource was described in thedevelop Issue 20 Print Hints column about QuickDraw GX buffering. Rather than reiterate that information here, we're going to briefly focus on the first three fields of the resource.

The first item in the 'iobm' resource (standardIO or customIO) tells QuickDraw GX whether you want to use its built-in communications code. You must specify customIO if you want to use your own custom I/O code. When customIO is specified, QuickDraw GX won't go through the overhead of initialization and data allocation for the internal communications routines; as a result, youmust override certain messages, as described in a following section. When you specify customIO, the last three longint fields of this resource are ignored.

The two fields in the 'iobm' resource that follow the I/O type field indicate the number and size of the buffers your driver would like QuickDraw GX to create. Note that you can use QuickDraw GX's built-in buffering even if you're writing your own communications code. If, however, you're creating and disposing of your own buffers, you should set the "number of buffers" field to 0, so that QuickDraw GX won't waste time and memory allocating buffers that are never used. For code that communicates synchronously, multiple buffers don't improve performance, so you should set this field to 1.

Later in this column we'll take a closer look at what's required to create and manage your own I/O buffers.

WHEN "NOT CONNECTED" MEANS "CONNECTED"
Unless you're writing custom I/O routines to support a SCSI printer, you'll want to create a "not connected" 'comm' resource for your driver. Below is the declaration of a 'comm' resource for the "not connected" case.

For the full description of a 'comm' resource, see Inside Macintosh: QuickDraw GX Printing Extensions and Drivers .*

type gxDeviceCommunicationsType {
    unsigned longint = 'nops';
};

There's not a whole lot to it, is there? When you specify customIO in your 'iobm' resource, QuickDraw GX never does anything with your desktop printer's 'comm' resources other than examine the first longint. So, all sorts of possibilities become apparent. As long as that first longint is 'nops', you can extend the definition of this resource to suit your needs. Whether to change the definition of the resource in the PrintingResTypes.r interface file or not is up to you. Instead, you could just resize the resource when you update it at desktop printer creation time, as we'll discuss momentarily.

CUSTOM I/O -- THE MESSAGES
When you supply your own I/O routines, there are several messages that you need to override. Some of these messages will always need to betotally overridden, meaning that your overrides for these messages should never forward the messages. Other messages should bepartially overridden, in which case the message is forwarded at some point in your override code.

Now we'll look at the messages you need to override. (Table 1 summarizes these messages and the ones to override for custom buffering.) If you want more information on writingmessage overrides, see Sam Weiss's article, "DevelopingQuickDraw GX Printing Extensions," in develop Issue 15, andInside Macintosh: QuickDraw GX Printing Extensions and Drivers .


Table 1. Overriding QuickDraw GX messages

When to OverrideCustom I/OCustom Buffering
Always override (partially)GXOpenConnectionGXOpenConnection
GXCloseConnectionGXCloseConnection
GXCleanupOpenConnectionGXCleanupOpenConnection
GXWriteData
Always override (totally)GXDumpBufferGXBufferData
GXWriteData
Usually override (partially)GXDefaultDesktopPrinter
GXChooserMessage
Sometimes override (totally)GXFreeBuffer

Always override (partially)

  • GXOpenConnection
  • GXCloseConnection
  • GXCleanupOpenConnection
  • GXWriteData

When you override these messages, you should first forward the message, then execute your added code. Your overrides for the first three messages should contain code to open and close a connection to your device.

GXCloseConnection is sent to close a connection if no errors occur during the device communications phase of printing; GXCleanupOpenConnection is sent if an error does occur during this time. The goal for both of these overrides is to "undo" any data allocation or initialization that occurred in the GXOpenConnection override. Often, your GXCleanupOpenConnection message override can simply execute the same code as your GXCloseConnection override.

The GXWriteData override should forward the message(with a nil pointer and a length of 0) to flush any data that's buffered, and then send the data to the printer.

Always override (totally)

  • GXDumpBuffer

Your override for this message should execute code that sends the indicated data to your printer. When this message is sent, a connection to your device will already have been established through the successful execution of your GXOpenConnection override. The GXDumpBuffer message is used to send data to the printer whenever an I/O buffer becomes full.

Usually override (partially)

  • GXDefaultDesktopPrinter
  • GXChooserMessage

When QuickDraw GX creates a desktop printer, it stores in it a 'comm' resource that specifies how to communicate with the printer. By default, this 'comm' resource is just a filled-in copy of one of your driver's 'comm' resources. Depending on the setting in the Chooser's "Connect via:" menu, the 'comm' resource is updated with information about the printer, such as the selected serial port, SCSI address, and network address for an AppleTalk printer. If your driver uses a "not connected" 'comm' resource (as described earlier), it will be copied verbatim, without updated information about the selected printer. As a result, you might need to step in and fill out the resource yourself.

To update the 'comm' resource, you need to override the GXDefaultDesktopPrinter message as shown in Listing 1. Here we forward the message so that QuickDraw GX completes creation of the desktop printer; then we retrieve the 'comm' resource from the desktop printer, update it, and replace the old version with the updated version.

When you update the 'comm' resource, you need to know which printer the user selected, as well as its addressing information and so forth. You can find this information by overriding GXChooserMessage, which is sent by the GXHandleChooserMessage API call. In this override, possibly with some help from your Chooser PACK's LDEF, you can determine the relevant information about the selected printer.

For example, you can store this information in a column of cells that's appended to the printer list. Or you can store it in the list record's userHandle or, by using PC-relative addressing, in a data storage area following your jump table. When you retrieve this data in your GXChooserMessage override, simply store it using one of QuickDraw GX's global data functions for printing. Finally, retrieve the information from your GXDefaultDesktopPrinter override and store it in the desktop printer's 'comm' resource.

It's important to note that you can't use any of the functions GetMessageHandlerInstanceContext, SetMessageHandlerInstanceContext, GXGetJobRefCon,GXSetJobRefCon, and NewMessageGlobals for the example in Listing 1, because the GXChooserMessage and GXDefaultDesktopPrinter messages are sent to two different message handler instances. Therefore, you should use GetMessageHandlerClassContext, SetMessageHandlerClassContext, or some other method that works across message handler instances.

Sometimes override (totally)

  • GXFreeBuffer

If your communications code runs asynchronously, you must override GXFreeBuffer so that QuickDraw GX can tell when operations on a buffer have completed. The GXFreeBuffer message is sent to make sure that all the data in the buffer has been processed before the buffer is used again. When GXFreeBuffer returns, the indicated buffer is ready to accept more data. An override for this message should loop (calling GXJobIdle) until I/O on the specified buffer is complete, and then return.


Listing 1. Updating a 'comm' resource when a desktop printer is created

OSErr MyDefaultDesktopPrinter (Str31 dtpName) {
    OSErr   anyErrors;
    Handle  theCommResource;
    
    // Forward the message so that the desktop printer is created.
    anyErrors = Forward_GXDefaultDesktopPrinter(dtpName);
    nrequire(anyErrors, Abort);
    
    // Load the data for the 'comm' resource that was stored in the
    // desktop printer.
    anyErrors = GXFetchDTPData(dtpName, gxDeviceCommunicationsType,
       gxDeviceCommunicationsID, &theCommResource);
    require_action(theCommResource != nil, Abort,
       anyErrors = resNotFound;);
    
    // Update the 'comm' data with info about the selected printer,
    // and store the updated copy 
    // back in the desktop printer.
    MyUpdateCommResource(theCommResource);
    anyErrors = GXWriteDTPData(dtpName, gxDeviceCommunicationsType,
       gxDeviceCommunicationsID, theCommResource);
    
    // Finally, dispose of the handle we received from
    // GXFetchDTPData. It's a detached resource
    // handle, so DON'T USE RELEASERESOURCE!!
    DisposeHandle(theCommResource);

Abort:
    return anyErrors;
}

USING YOUR OWN BUFFERING SCHEME
At this point, we've discussed everything that's needed to handle your own custom I/O code. Now we'll take a quick look at what's required if you want to create and maintain your own buffers, instead of using those that the default implementation provides.

First things first. Go back to your 'iobm' resource, and set the number of buffers to 0. This tells QuickDraw GX not to waste time and memory allocating buffers that you aren't going to use.

When you implement your own buffering scheme, you can use any sort of internal representation for your buffers that you want to. However, since some of the buffering messages take a pointer to a gxPrintingBuffer, you'll need to use that format for passing your buffers between certain messages. But as far as the actual buffer structures go, you can use a handle, a linked list, or any other configuration that's convenient or necessary to use.

To support custom buffering code, you'll need to override the following messages.

Always override (partially)

  • GXOpenConnection
  • GXCloseConnection
  • GXCleanupOpenConnection
The partial overrides for these messages should forward the messages and then allocate or dispose of your internal buffer structures. If you're using custom I/O, you already provide overrides of these messages. In that case, simply add this new code to the existing overrides.

Always override (totally)

  • GXBufferData
  • GXWriteData

Provide an override of GXBufferData that stores the passed data in your next available buffer. If a buffer becomes full, call Send_GXDumpBuffer. Before you attempt to add data to this buffer again, call Send_GXFreeBuffer to make sure that all of the buffer's data has been sent to the printer.

Your override for the GXWriteData message should flush all data from your buffers and then immediately send the passed data to the printer. To do this, call Send_GXDumpBuffer on all buffers, followed bySend_GXFreeBuffer on all buffers. If you're performingcustom I/O, just add this code to your existing override.

You may wonder why you don't need to override the GXDumpBuffer message when you perform custom buffering. Unlike the messages listed above, GXDumpBuffer takes a pointer to a gxPrintingBuffer. Whenever your code calls Send_GXDumpBuffer, you must pass data in a gxPrintingBuffer structure, regardless of the internal buffer representation that you're using. Since the buffered data is passed in the format that GXDumpBuffer already expects, there's no need to override the message.

DRIVE SAFELY
That's all there is to it. So, the next time someone asks, "Can you write QuickDraw GX printer drivers for my 200 Kbits/second serial typesetter, my SCSI copier/printer, and my NuBus-interfaced cutter plotter?" tell them, "Yoooooooou betcha!"

DAVE HERSEY (AppleLink HERSEY) left Apple's Developer Technical Support (DTS) group about six months ago to join the Print Shop software development group. He now fixes the QuickDraw GX bugs that he reported while in DTS, and works on QuickDraw GX 2.0 -- the "knock your socks off" release. *

Thanks to Tom Dowdy, David Hayward, and Nick Thompson for reviewing this column. *

 
AAPL
$106.95
Apple Inc.
-0.39
MSFT
$46.09
Microsoft Corpora
-0.54
GOOG
$550.68
Google Inc.
+1.35

MacTech Search:
Community Search:

Software Updates via MacUpdate

Cocktail 8.0.1 - General maintenance and...
Cocktail is a general purpose utility for OS X that lets you clean, repair and optimize your Mac. It is a powerful digital toolset that helps hundreds of thousands of Mac users around the world get... Read more
LibreOffice 4.3.3.2 - Free Open Source o...
LibreOffice is an office suite (word processor, spreadsheet, presentations, drawing tool) compatible with other major office suites. The Document Foundation is coordinating development and... Read more
VMware Fusion 7.0.1 - Run Windows apps a...
VMware Fusion allows you to create a Virtual Machine on your Mac and run Windows (including Windows 8.1) and Windows software on your Mac. Run your favorite Windows applications alongside Mac... Read more
OneNote 15.3.2 - Free digital notebook f...
OneNote is your very own digital notebook. With OneNote, you can capture that flash of genius, that moment of inspiration, or that list of errands that's too important to forget. Whether you're at... Read more
Audio Hijack Pro 2.11.4 - Record and enh...
Audio Hijack Pro drastically changes the way you use audio on your computer, giving you the freedom to listen to audio when you want and how you want. Record and enhance any audio with Audio Hijack... Read more
Iridient Developer 3.0.0 beta 3 - Powerf...
Iridient Developer (was RAW Developer) is a powerful image conversion application designed specifically for OS X. Iridient Developer gives advanced photographers total control over every aspect of... Read more
TextWrangler 4.5.11 - Free general purpo...
TextWrangler is the powerful general purpose text editor, and Unix and server administrator's tool. Oh, and also, like the best things in life, it's free. TextWrangler is the "little brother" to... Read more
NeoFinder 6.6 - Catalog your external me...
NeoFinder (formerly CDFinder) rapidly organizes your data, either on external or internal disks, or any other volumes. It catalogs all your data, so you stay in control of your data archive or disk... Read more
Chromium 38.0.2125.111 - Fast and stable...
Chromium is an open-source browser project that aims to build a safer, faster, and more stable way for all Internet users to experience the web. FreeSMUG-Free OpenSource Mac User Group build is... Read more
Default Folder X 4.6.11 - Enhances Open...
Default Folder X attaches a toolbar to the right side of the Open and Save dialogs in any OS X-native application. The toolbar gives you fast access to various folders and commands. You just click... Read more

Latest Forum Discussions

See All

SAS: Zombie Assault 4 Review
SAS: Zombie Assault 4 Review By Jennifer Allen on October 30th, 2014 Our Rating: :: FLAWED SHOOTERUniversal App - Designed for iPhone and iPad Shoot everything that moves in this fun, if flawed, twin-stick shooter.   | Read more »
Naailde the Witch Review
Naailde the Witch Review By Amy Solomon on October 30th, 2014 Our Rating: :: PITCH-PERFECT STORYTELLINGUniversal App - Designed for iPhone and iPad Marvelous storytelling, narration, and moving illustrations make this storybook... | Read more »
1st & Goal Review
1st & Goal Review By Andrew Fisher on October 30th, 2014 Our Rating: :: FOR THE D&D LOVING QBUniversal App - Designed for iPhone and iPad 1st & Goal is a board gamer’s football game, a football fan’s board game, and... | Read more »
French Developer Pated Unveils Seashine
French Developer Pated Unveils Seashine Posted by Ellis Spice on October 30th, 2014 [ permalink ] French one-man studio Pated has unveiled Seashine, “a poetic journey into the abyss.” Players take on the role of a jellyfish strugglin | Read more »
Agents of Storm: Tips, Tricks, and Strat...
Calling all agents: Would you like to see what we thought of this rather pretty base builder? Check out our Agents of Storm review! Have you downloaded Agents of Storm, been bowled over by the graphics, and aren’t quite sure what to do next? Never... | Read more »
Any.DO 2.0 Hopes to Help Manage Producti...
Any.DO 2.0 Hopes to Help Manage Productivity Posted by Ellis Spice on October 30th, 2014 [ permalink ] iPhone App - Designed for the iPhone, compatible with the iPad | Read more »
Base Busters Review
Base Busters Review By Jennifer Allen on October 30th, 2014 Our Rating: :: FUN BUT RESTRICTED MIXUniversal App - Designed for iPhone and iPad Mixing up two forms of tower defense gaming and collectible cards, Base Busters is a fun... | Read more »
Sumptus - Personal Expense Tracker in Yo...
Sumptus - Personal Expense Tracker in Your Pocket 1.0 Device: iOS iPhone Category: Finance Price: $3.99, Version: 1.0 (iTunes) Description: Sumptus - a personal finance assistant in your pocket. It’s an ultimate expense tracker... | Read more »
Meat Factory (Games)
Meat Factory 0.1 Device: iOS Universal Category: Games Price: $.99, Version: 0.1 (iTunes) Description: Meat factory harks back to the old days of the game and watch. Easy to pick up and play, but hard to score big. With cute visuals... | Read more »
Medford Asylum: Paranormal Case - Hidden...
Medford Asylum: Paranormal Case - Hidden Object Adventure (Full) 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Uncover the mystery of Medford City asylum! | Read more »

Price Scanner via MacPrices.net

Apple Regains Momentum As Windows Stutters An...
The latest smartphone sales data from Kantar Worldpanel ComTech, for the three months to March 2014, shows Apple performing strongly in the first quarter of the year, with sales bouncing back in... Read more
Worldwide Smartphone Shipments Increase 25.2%...
New smartphone releases and an increased emphasis on emerging markets drove global smartphone shipments above 300 million units for the second consecutive quarter, according to preliminary data from... Read more
Apple now offering refurbished 2014 15-inch M...
The Apple Store is now offering Apple Certified Refurbished 2014 15″ Retina MacBook Pros for up to $400 off the cost of new models. An Apple one-year warranty is included with each model, and... Read more
Apple drops prices on refurbished 2013 Retina...
The Apple Store has dropped prices on 2013 Apple Certified Refurbished 13″ and 15″ Retina MacBook Pros, with Retina models now available starting at $999. Apple’s one-year warranty is standard, and... Read more
New 2.8GHz Mac mini on sale for $949, save $5...
Abt Electronics has the new 2.8GHz Mac mini in stock and on sale for $949.05 including free shipping. Their price is $50 off MSRP, and it’s the lowest price available for this model from any reseller... Read more
Sale! 3.7GHz Quad Core Mac Pro available for...
 B&H Photo has the 3.7GHz Quad Core Mac Pro on sale for $2649 including free shipping plus NY sales tax only. Their price is $350 off MSRP, and it’s the lowest price for this model from any... Read more
Mujjo Steps Up The Game With Refined Touchscr...
Netherlands based Mujjo have just launched their Refined Touchscreen Gloves, stepping up their game. The gloves feature a updated elegant design that takes these knitted gloves to the next level. A... Read more
Sale! Preorder the new 27-inch 5K iMac for $2...
 Abt Electronics has the new 27″ 3.5GHz 5K iMac on sale and available for preorder for $2374.05 including free shipping. Their price is $125 off MSRP, and it’s the lowest price available for this... Read more
Simplex Solutions Inc. Brings Secure Web Surf...
New York based Simplex Solutions Inc. has announced the release and immediate availability of Private Browser 1.0, its revolutionary new secure web browser developed for iPhone, iPad and iPod touch... Read more
Save up to $180 off MSRP with an Apple refurb...
The Apple Store has Apple Certified Refurbished 2014 MacBook Airs available for up to $180 off the cost of new models. An Apple one-year warranty is included with each MacBook, and shipping is free.... Read more

Jobs Board

*Apple* Solutions Consultant (ASC) - Apple I...
…important role that the ASC serves is that of providing an excellent Apple Customer Experience. Responsibilities include: * Promoting Apple products and solutions Read more
*Apple* Solutions Consultant (ASC) - Apple I...
…important role that the ASC serves is that of providing an excellent Apple Customer Experience. Responsibilities include: * Promoting Apple products and solutions Read more
*Apple* Solutions Consultant (ASC) - Apple I...
…important role that the ASC serves is that of providing an excellent Apple Customer Experience. Responsibilities include: * Promoting Apple products and solutions Read more
*Apple* Solutions Consultant - Apple Inc. (U...
…important role that the ASC serves is that of providing an excellent Apple Customer Experience. Responsibilities include: * Promoting Apple products and solutions Read more
*Apple* Solutions Consultant - Apple Inc. (U...
…important role that the ASC serves is that of providing an excellent Apple Customer Experience. Responsibilities include: * Promoting Apple products and solutions Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.