TweetFollow Us on Twitter

Desktop Stuffing

Volume Number: 14 (1998)
Issue Number: 5
Column Tag: Powerplant

Desktop Stuffing

by David Catmull

Using Aladdin Systems' StuffIt Engine

Gentlemen, Stuff Your Engines

Aladdin Systems' StuffIt has been the standard for compression on the Macintosh for quite some time now. Rather than keep it all to themselves, however, they chose to make the StuffIt features available to developers through a little file called the StuffIt Engine. Aladdin's own utilities use it to perform most of their compression operations, and they have published the API so outside developers can contribute to the StuffIt standard.

The StuffIt Engine API is organized into two parts: the general calls for Stuffing and UnStuffing, working with file segments, etc., and the "low-level" calls that let you poke around inside StuffIt archives to add and extract files individually. There are still some things that even the low-level calls don't let you do, such as deleting and re-ordering items in the archives, but unless you're writing your own StuffIt Deluxe you won't need to go that far.

The Basics

In order to use the StuffIt Engine, you must include two files from the SDK in your project: the StuffItEngineLib .rsrc resource file, and one of the CodeWarrior libraries: StuffItEngineLib, StuffItEngine LibPPC, or StuffItEngineLibA4.

If you want to have the StuffIt Engine built into your application, rather than depending on the user having it installed, you can pick and choose which parts of the engine you want to include -- Stuffing, UnStuffing, segmenting calls, and the various decoding parts (such as BinHex) can be added to your project as individual resource files.

Whether you use the engine externally or internally, you will need to obtain a license from Aladdin Systems since at the very least you will be linking their library into your program. For more details on licensing terms and fees, contact Aladdin Systems dev.sales@aladdinsys.com.

To access the StuffIt Engine in your program, you must first open it with the OpenSITEngine() call, which returns a "magic cookie" to be passed back in subsequent calls to the engine. When you are finished, use CloseSITEngine() to close your connection.

Each of the other calls to the StuffIt Engine has three types of parameters: the magic cookie obtained from OpenSITEngine(), the relevant FSSpec structures (source, destination, and result), and a set of options which can be specified using constants from StuffItEngineLib.h. These options tell the StuffIt Engine such things as whether to prompt the user for a destination, whether to delete the original items after Stuffing or UnStuffing them, what to do about linefeeds in text files, and so on.

Stuffing with PowerPlant

Metrowerks has been working on a set of classes that simplify the interface to the StuffIt Engine. PowerPlant users may have discovered the "StuffIt Classes" folder that was recently added to PowerPlant's "_In Progress" folder. The folder contains two pairs of header and source files: UStuffItSupport and LStuffItArchive. These two correspond to the two categories of calls in the StuffIt Engine (high-level and low-level). There are more than two classes, though:

  • UStuffItSupport: This class performs all the basic operations: opening and closing your connection to the StuffIt Engine, keeping track of the magic cookie, and simple Stuffing and UnStuffing operations.
  • LStuffItFileList: This is a wrapper class for the FSSpecArrayHandle type that is used for Stuffing multiple files into a single archive. In the StuffIt API, even if you're just Stuffing one file, you must still create a list with a single item; conveniently, UStuffItSupport has a call for Stuffing single files.
  • LStuffItArchive: This class is for working with the contents of an archive, covering the low-level API calls.
  • LStuffItArcObjectList: The complement to LStuffItFileList, this class wraps around StuffIt's arcObjectArrayHandle type and refers to multiple objects inside an archive.
  • StOpenStuffIt: A stack-based class which simplifies opening and closing the engine.

Their Example

The StuffIt Engine SDK includes a sample application called StuffIt Scrapbook which uses a neat trick to store its pictures in compressed resources. Since StuffIt only works with files, StuffIt Scrapbook gets around this by writing new pictures to a temporary file which is then Stuffed. The resulting archive is read in, and its data is stored as a 'Psit' resource in the scrapbook file. To display a stored picture, it goes through the reverse process.

Our Example

StuffIt Scrapbook covers the basics of using the general-purpose Stuffing and UnStuffing calls, so for this article we'll focus on the lower level. The example application is based on the Drag & Drop File Filter application from Metrowerks' PowerPlant samples. Our program accepts StuffIt archives dropped onto it, and extracts any text files that the archive contains, placing the files in the same folder as the archive.

Since the example application class FrDropApp provides a good enough framework for processing files dropped on the application, we only override the OpenDocument method, which is called for each file:

TextractorApp::OpenDocument
Search the given file for text files to extract
void
TextractorApp::OpenDocument(FSSpec *inMacFSSpec)
{
   StOpenStuffIt openEngine;
   CStuffItArchive archive(*inMacFSSpec);
   LStuffItArcObjectList list;
   archiveObject object;
   archive.mPromptForDestination = kDontPromptForDestination;
   
   Try_ {
      // Assemble a list of text files in the archive
      archive.Reset();
      while (archive.BrowseNext(object))
         if (object.fileType == 'TEXT')
            list.Append(object);
   
      // Extract the files, if there were any
      if (list.Count() > 0)
         archive.UnStuffFromArchive(list);
   }
   Catch_(caughtErr) {
      DoQuit();
   }
}

One of the various options for the StuffIt calls is whether to prompt the user for a destination. LStuffItArchive stores the values for these options in publicly accessible data members, so the first thing we do is turn the prompt option off. This is the first step in getting the extracted files to automatically appear in the same folder as the archive.

Notice the use of our subclass CStuffItArchive instead of LStuffItArchive. The subclass was added because we needed a couple of things that LStuffItArchive doesn't provide.

First of all, there's no simple way provided to iterate through the hierarchy of an archive. LStuffItArchive gives you Next(), Up(), and Down(), but if you want to just cruise through all the items in the archive, you have to figure out for yourself when to use what. Here's how it's done:

CStuffItArchive::BrowseNext
Return the next item in the archive, going straight ahead, up, or down
Boolean
CStuffItArchive::BrowseNext(archiveObject &outObject)
{
   Open();

   if (!mIteratorInitialized) {
      Reset();
      if (mBrowseStack) {
         delete mBrowseStack;
         mBrowseStack = 0L;
      }
   }
   
   if (mIteratorAtHead) {
      mIteratorAtHead = false;
      outObject = mCurrentObject;
      return true;
   }
   
   // Reset the stack if necessary
   if (!mBrowseStack)
      mBrowseStack = new LArray(sizeof(archiveObject));
   // If it's a folder, then browse into it (unless it's empty)
   // Otherwise, try to advance to the next object at this level
   // If it's not there, pop back up a level
   archiveObject tempObject,oldObject = mCurrentObject;
   if (mCurrentObject.objectIsFolder && Down(tempObject)) {
      outObject = mCurrentObject;
      mBrowseStack->AddItem(&oldObject,sizeof(oldObject));
      return true;
   }
   else if (Next(outObject))
      return true;
   else {
      if (mBrowseStack->GetCount() > 1) {
         mBrowseStack->FetchItemAt(LArray::index_Last,&outObject);
         mBrowseStack->RemoveItemsAt(1,LArray::index_Last);
         return true;
      }
      else
         return false;
   }
}

The first couple of lines in this method are similar to the beginnings of LStuffItArchive's Next(), Up(), and Down(), with the addition of initializing the browsing stack. Then we come to the fork in the road: if the current item is a folder, we can browse into it. If it's not a folder, then just move along. If there are no more files in this folder, we're done with the current folder and it's time to pop back up a level. An array of folder objects is used to keep track of where we need to pop up to, and when it runs out, that means the entire archive has been traversed.

The second addition that CStuffItArchive gives us is an alternate version of UnStuffFromArchive(). After turning off the user prompt option, this is the second step in making the extracted files appear in the same folder as the source archive. Unlike LStuffItArchive::UnStuffFromArchive(), this function takes no destination parameter, and passes a null value for the destination to StuffIt Engine's ExpandFromArchive().

CStuffItArchive:UnStuffFromArchive
Alternate version of the LStuffItArchive call with no destination
parameter void
CStuffItArchive::UnStuffFromArchive(LStuffItArcObjectList& inObjectList, unsigned char * inPassword)
{
   Open();

   StOpenStuffIt engineOpen;
   FSSpec resultSpec;

   OSErr err = ExpandFromArchive (
            UStuffItSupport::sCookie,
            &mArchiveInfo, 
            inObjectList, 
            0L, // Null destination means expand to the archive's folder
            &resultSpec,
            mPromptForDestination, 
            mCreateFolder, 
            mStopOnAbort,
            mConflictAction, 
            mConvertTextFiles, 
            inPassword,
            mShowNoProgress, 
            mAlertCBUPP,
            mStatusCBUPP, 
            mPeriodicCBUPP);

   ThrowIfOSErr_(err);
}

Beyond the Documentation

Here is a collection of tips and notes that I have collected, some of which are not mentioned in the StuffIt SDK documentation:

You can convert archives to and from self-extracting format using ConvertSITtoSEA() and ConvertSEAtoSIT(), but the Engine doesn't tell you what the name of the resulting file is. This is usually not a problem, especially if you don't care what the result is, but if you do and there is a naming conflict, it could cause confusion. The way it seems to work is this: If the file has the appropriate .sit or .sea extension, it attempts to substitute the other extension. If this causes a name conflict, or if the original file didn't have the right extension, then the name is not changed.

Although, by means of the ExpandFSSpec() call, the StuffIt Engine can decode and decompress a variety of non-StuffIt formats, the only encoding available is BinHex. Again, the HQXEncodeFSSpec call doesn't tell you what the resulting file is, so you have to guess. This call, in the case of a naming conflict, appends a number to the file name: "file.hqx.1"

The segmenting functions, SegmentFSSpec() and JoinFSSpec(), will prompt the user for a destination if you do not supply one. So if you don't want any Standard File dialogs popping up, be sure to specify your destination. And the destination must be a file, not the folder you want the file to go in.

There are certain resources you must include in your program for the StuffIt Engine to use, supplied in StuffItEngineLib.rsrc. If the file containing these resources is not open when you open the Engine, you will get the StuffIt registration dialog. This will normally not be a problem for applications, but for other projects such as contextual menu plug-ins you need to watch for it.

This is pointed out in the StuffIt Scrapbook notes: every time you perform an operation with an unregistered copy of StuffIt Engine (except for opening it), the registration dialog will appear. However, there are times when you don't want that to happen, such as a Drag Manager drag receive handler. Fortunately, there is an IsSITEngineRegistered() call to help you avoid embarrassing crashes and unwanted dialog boxes.

Conclusion

If you want your application to have file compression features, the StuffIt Engine SDK provides easy access to the StuffIt standard. While it does have its shortcomings, such as not always informing you of how it resolves a naming conflict, these problems are minor and in most cases not an issue. Overall, the StuffIt Engine SDK, especially with PowerPlant's additions, is easy to use and even fun.

The StuffIt Engine SDK is available from Aladdin Systems' web site at http://www.aladdinsys.com/dev/engine/enginesdk.html.


David Catmull is a shareware programmer living in Berkeley, California. He earned a degree in Computer Science from the California State University at Hayward, and is currently studying computer animation at the Academy of Art College in San Francisco. His shareware offerings include StuffCM, a contextual menu plug-in that uses the StuffIt Engine; and CCMArea, a set of classes for adding contextual menus to PowerPlant applications. These and others are available at http://www.kagi.com/dathorc/.

 
AAPL
$99.02
Apple Inc.
+1.35
MSFT
$43.97
Microsoft Corpora
-0.53
GOOG
$590.60
Google Inc.
+1.58

MacTech Search:
Community Search:

Software Updates via MacUpdate

OS X Yosemite Wallpaper 1.0 - Desktop im...
OS X Yosemite Wallpaper is the gorgeous new background image for Apple's upcoming OS X 10.10 Yosemite. This wallpaper is available for all screen resolutions with a source file that measures 5,418... Read more
Acorn 4.4 - Bitmap image editor. (Demo)
Acorn is a new image editor built with one goal in mind - simplicity. Fast, easy, and fluid, Acorn provides the options you'll need without any overhead. Acorn feels right, and won't drain your bank... Read more
Bartender 1.2.20 - Organize your menu ba...
Bartender lets you organize your menu bar apps. Features: Lets you tidy your menu bar apps how you want. See your menu bar apps when you want. Hide the apps you need to run, but do not need to... Read more
TotalFinder 1.6.2 - Adds tabs, hotkeys,...
TotalFinder is a universally acclaimed navigational companion for your Mac. Enhance your Mac's Finder with features so smart and convenient, you won't believe you ever lived without them. Tab-based... Read more
Vienna 3.0.0 RC 2 :be5265e: - RSS and At...
Vienna is a freeware and Open-Source RSS/Atom newsreader with article storage and management via a SQLite database, written in Objective-C and Cocoa, for the OS X operating system. It provides... Read more
VLC Media Player 2.1.5 - Popular multime...
VLC Media Player is a highly portable multimedia player for various audio and video formats (MPEG-1, MPEG-2, MPEG-4, DivX, MP3, OGG, ...) as well as DVDs, VCDs, and various streaming protocols. It... Read more
Default Folder X 4.6.7 - Enhances Open a...
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
TinkerTool 5.3 - Expanded preference set...
TinkerTool is an application that gives you access to additional preference settings Apple has built into Mac OS X. This allows to activate hidden features in the operating system and in some of the... Read more
Audio Hijack Pro 2.11.0 - 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
Intermission 1.1.1 - Pause and rewind li...
Intermission allows you to pause and rewind live audio from any application on your Mac. Intermission will buffer up to 3 hours of audio, allowing users to skip through any assortment of audio... Read more

Latest Forum Discussions

See All

Traps n’ Gemstones Review
Traps n’ Gemstones Review By Campbell Bird on July 28th, 2014 Our Rating: :: CASTLEVANIA JONESUniversal App - Designed for iPhone and iPad Fight mummies, dig tunnels, and ride a runaway minecart to discover ancient secrets in this... | Read more »
The Phantom PI Mission Apparition Review
The Phantom PI Mission Apparition Review By Jordan Minor on July 28th, 2014 Our Rating: :: GHOSTS BUSTEDUniversal App - Designed for iPhone and iPad The Phantom PI is an exceedingly clever and well-crafted adventure game.   | Read more »
More Stubies Are Coming Your Way in a Ne...
More Stubies Are Coming Your Way in a New Update Posted by Jessica Fisher on July 28th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
The Great Prank War Review
The Great Prank War Review By Nadia Oxford on July 28th, 2014 Our Rating: :: PRANKING IS SERIOUS BUSINESSUniversal App - Designed for iPhone and iPad Though short, The Great Prank War offers an interesting and fun mix of action and... | Read more »
Marvel Contest of Champions Announced at...
Marvel Contest of Champions Announced at Comic-Con Posted by Jennifer Allen on July 28th, 2014 [ permalink ] Announced over the weekend at San Diego Comic-Con was the fairly exciting looking Marvel Contest of Champions. | Read more »
Teenage Mutant Ninja Turtles Review
Teenage Mutant Ninja Turtles Review By Jennifer Allen on July 28th, 2014 Our Rating: :: DULL SWIPINGUniversal App - Designed for iPhone and iPad The pizza power is weak when it comes to this Teenage Mutant Ninja Turtles game.   | Read more »
Exploration Focused Puzzle Game Beatbudd...
Exploration Focused Puzzle Game Beatbuddy Set to Make Transition from PC to iOS this September Posted by Jennifer Allen on July 28th, 2014 [ permalink ] | Read more »
PlanetHD
PlanetHD By Nadia Oxford on July 28th, 2014 Our Rating: :: SPACE MADNESSUniversal App - Designed for iPhone and iPad PlanetHD will keep players busy for a while, though its unpredictable physics are a handful to deal with.   | Read more »
This Week at 148Apps: July 21-25, 2014
Another Week of Expert App Reviews   At 148Apps, we help you sort through the great ocean of apps to find the ones we think you’ll like and the ones you’ll need. Our top picks become Editor’s Choice, our stamp of approval for apps with that little... | Read more »
Reddme for iPhone - The Reddit Client (...
Reddme for iPhone - The Reddit Client 1.0 Device: iOS iPhone Category: News Price: $.99, Version: 1.0 (iTunes) Description: Reddme for iPhone is an iOS 7-optimized Reddit client that offers a refreshing new way to experience Reddit... | Read more »

Price Scanner via MacPrices.net

13-inch 2.5GHz MacBook Pro on sale for $1099,...
Best Buy has the 13″ 2.5GHz MacBook Pro available for $1099.99 on their online store. Choose free shipping or free instant local store pickup (if available). Their price is $100 off MSRP. Price is... Read more
Roundup of Apple refurbished MacBook Pros, th...
The Apple Store has Apple Certified Refurbished 13″ and 15″ MacBook Pros available for up to $400 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free. Their prices... Read more
Record Mac Shipments In Q2/14 Confound Analys...
A Seeking Alpha Trefis commentary notes that Apple’s fiscal Q3 2014 results released July 22, beat market predictions on earnings, although revenues were slightly lower than anticipated. Apple’s Mac’... Read more
Intel To Launch Core M Silicon For Use In Not...
Digitimes’ Monica Chen and Joseph Tsai, report that Intel will launch 14nm-based Core M series processors specifically for use in fanless notebook/tablet 2-in-1 models in Q4 2014, with many models to... Read more
Apple’s 2014 Back to School promotion: $100 g...
 Apple’s 2014 Back to School promotion includes a free $100 App Store Gift Card with the purchase of any new Mac (Mac mini excluded), or a $50 Gift Card with the purchase of an iPad or iPhone,... Read more
iMacs on sale for $150 off MSRP, $250 off for...
Best Buy has iMacs on sale for up to $160 off MSRP for a limited time. Choose free home shipping or free instant local store pickup (if available). Prices are valid for online orders only, in-store... Read more
Mac minis on sale for $100 off MSRP, starting...
Best Buy has Mac minis on sale for $100 off MSRP. Choose free shipping or free instant local store pickup. Prices are for online orders only, in-store prices may vary: 2.5GHz Mac mini: $499.99 2.3GHz... Read more
Global Tablet Market Grows 11% in Q2/14 Notwi...
Worldwide tablet sales grew 11.0 percent year over year in the second quarter of 2014, with shipments reaching 49.3 million units according to preliminary data from the International Data Corporation... Read more
New iPhone 6 Models to Have Staggered Release...
Digitimes’ Cage Chao and Steve Shen report that according to unnamed sources in Apple’s upstream iPhone supply chain, the new 5.5-inch iPhone will be released several months later than the new 4.7-... Read more
New iOS App Helps People Feel Good About thei...
Mobile shoppers looking for big savings at their favorite stores can turn to the Goodshop app, a new iOS app with the latest coupons and deals at more than 5,000 online stores. In addition to being a... Read more

Jobs Board

Sr Software Lead Engineer, *Apple* Online S...
Sr Software Lead Engineer, Apple Online Store Publishing Systems Keywords: Company: Apple Job Code: E3PCAK8MgYYkw Location (City or ZIP): Santa Clara Status: Full Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Sr. Product Leader, *Apple* Store Apps - Ap...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.