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
$97.03
Apple Inc.
-0.16
MSFT
$44.40
Microsoft Corpora
-0.47
GOOG
$593.35
Google Inc.
-2.63

MacTech Search:
Community Search:

Software Updates via MacUpdate

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
Airfoil 4.8.7 - Send audio from any app...
Airfoil allows you to send any audio to AirPort Express units, Apple TVs, and even other Macs and PCs, all in sync! It's your audio - everywhere. With Airfoil you can take audio from any... Read more
Microsoft Remote Desktop 8.0.8 - Connect...
With Microsoft Remote Desktop, you can connect to a remote PC and your work resources from almost anywhere. Experience the power of Windows with RemoteFX in a Remote Desktop client designed to help... Read more
xACT 2.30 - Audio compression toolkit. (...
xACT stands for X Aaudio Compression Toolkit, an application that encodes and decodes FLAC, SHN, Monkey’s Audio, TTA, Wavpack, and Apple Lossless files. It also can encode these formats to MP3, AAC... Read more
Firefox 31.0 - Fast, safe Web browser. (...
Firefox for Mac offers a fast, safe Web browsing experience. Browse quickly, securely, and effortlessly. With its industry-leading features, Firefox is the choice of Web development professionals... Read more
Little Snitch 3.3.3 - Alerts you to outg...
Little Snitch gives you control over your private outgoing data. Track background activityAs soon as your computer connects to the Internet, applications often have permission to send any... Read more
Thunderbird 31.0 - Email client from Moz...
As of July 2012, Thunderbird has transitioned to a new governance model, with new features being developed by the broader free software and open source community, and security fixes and improvements... Read more
Together 3.2 - Store and organize all of...
Together helps you organize your Mac, giving you the ability to store, edit and preview your files in a single clean, uncluttered interface. Smart storage. With simple drag-and-drop functionality,... Read more
Cyberduck 4.5 - FTP and SFTP browser. (F...
Cyberduck is a robust FTP/FTP-TLS/SFTP browser for the Mac whose lack of visual clutter and cleverly intuitive features make it easy to use. Support for external editors and system technologies such... Read more

Latest Forum Discussions

See All

LEX Goes Free For One Day In Honor of Ne...
LEX Goes Free For One Day In Honor of New Update Posted by Jennifer Allen on July 24th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Thomas Was Alone Goes Universal, Slashes...
Thomas Was Alone Goes Universal, Slashes Price to $3.99 Posted by Ellis Spice on July 24th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Meerkatz Challenge Review
Meerkatz Challenge Review By Jennifer Allen on July 24th, 2014 Our Rating: :: FONDLY PUZZLINGUniversal App - Designed for iPhone and iPad Cute and challenging, Meerkatz Challenge is a fun puzzle game, particularly for fans of... | Read more »
Book Your Appointment with F.E.A.R. this...
Book Your Appointment with F.E.A.R. | Read more »
It Came From Canada: Epic Skater
For all the hate that it gets for being a pastime for slackers, skateboarding really does require a lot of skill. All those flips and spins take real athleticism, and there’s all the jargon to memorize. Fortunately for us less extreme individuals,... | Read more »
Cultures Review
Cultures Review By Jennifer Allen on July 24th, 2014 Our Rating: :: SLOW-PACED EMPIRE BUILDINGiPad Only App - Designed for the iPad Cute it might seem, but Cultures is a bit too slow paced when it comes to those pesky timers to... | Read more »
More Paintings Have Been Added to Paint...
More Paintings Have Been Added to Paint it Back! Posted by Jessica Fisher on July 24th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
The Order of Souls Review
The Order of Souls Review By Campbell Bird on July 24th, 2014 Our Rating: :: STORY GRINDUniversal App - Designed for iPhone and iPad The Order of Souls is a free-to-play, turn-based RPG with a genre-mixing art style, interesting... | Read more »
Revolution 60 Review
Revolution 60 Review By Jordan Minor on July 24th, 2014 Our Rating: :: LASS EFFECTUniversal App - Designed for iPhone and iPad Revolution 60 is a bold, cinematic action game with ambition to spare.   | Read more »
Matter (Photography)
Matter 1.0.1 Device: iOS Universal Category: Photography Price: $1.99, Version: 1.0.1 (iTunes) Description: Add stunning 3D effects to your photos with real-time shadows and reflections. Export your creations as photos or video loops... | Read more »

Price Scanner via MacPrices.net

Save on 5th generation refurbished iPod touch...
The Apple Store has Apple Certified Refurbished 5th generation iPod touches available starting at $149. Apple’s one-year warranty is included with each model, and shipping is free. Many, but not all... Read more
What Should Apple’s Next MacBook Priority Be;...
Stabley Times’ Phil Moore says that after expanding its iMac lineup with a new low end model, Apple’s next Mac hardware decision will be how it wants to approach expanding its MacBook lineup as well... Read more
ArtRage For iPhone Painting App Free During C...
ArtRage for iPhone is currently being offered for free (regularly $1.99) during Comic-Con San Diego #SDCC, July 24-27, in celebration of the upcoming ArtRage 4.5 and other 64-bit versions of the... Read more
With The Apple/IBM Alliance, Is The iPad Now...
Almost since the iPad was rolled out in 2010, and especially after Apple made a 128 GB storage configuration available in 2012, there’s been debate over whether the iPad is a serious tool for... Read more
MacBook Airs on sale starting at $799, free s...
B&H Photo has the new 2014 MacBook Airs on sale for up to $100 off MSRP for a limited time. Shipping is free, and B&H charges NY sales tax only. They also include free copies of Parallels... Read more
Apple 27″ Thunderbolt Display (refurbished) a...
The Apple Store has Apple Certified Refurbished 27″ Thunderbolt Displays available for $799 including free shipping. That’s $200 off the cost of new models. Read more
WaterField Designs Unveils Cycling Ride Pouch...
High end computer case and bag maker WaterField Designs of San Francisco now enters the cycling market with the introduction of the Cycling Ride Pouch – an upscale toolkit with a scratch-free iPhone... Read more
Kingston Digital Ships Large Capacity Near 1T...
Kingston Digital, Inc., the Flash memory affiliate of Kingston Technology Company, Inc.,has announced its latest addition to the SSDNow V300 series, the V310. The Kingston SSDNow V310 solid-state... Read more
Apple’s Fiscal Third Quarter Results; Record...
Apple has announced financial results for its fiscal 2014 third quarter ended June 28, 2014, racking up quarterly revenue of $37.4 billion and quarterly net profit of $7.7 billion, or $1.28 per... Read more
15-inch 2.0GHz MacBook Pro Retina on sale for...
B&H Photo has the 15″ 2.0GHz Retina MacBook Pro on sale for $1829 including free shipping plus NY sales tax only. Their price is $170 off MSRP. B&H will also include free copies of Parallels... 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
Senior Interaction Designer, *Apple* Online...
**Job Summary** Apple is looking for a hands on Senior…will be a key player in designing for the Apple Online Store. The ideal designer will have a Read more
*Apple* Sales Chat Rep - Apple (United State...
…is looking for motivated, outgoing, and tech savvy individuals who want to offer Apple Customers an unparalleled customer experience over chat. At Apple , we believe Read more
Mac Expert - *Apple* Online Store Mexico -...
…MUST be fluent in English and Spanish to be considered for this position At Apple , we believe that hard work, a fun environment, creativity and innovation fuel the Read more
*Apple* Industrial Design CAD Sculptor - App...
**Job Summary** The Apple Industrial Design team is looking for a CAD sculptor/Digital 3D modeler to create high quality CAD models used in the industrial design process Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.