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/.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Sibelius 2020.6 - Music notation solutio...
Sibelius is the world's best-selling music notation software for Mac. It is as intuitive to use as a pen, yet so powerful that it does most things in less than the blink of an eye. The demo includes... Read more
Bookends 13.4.2 - Reference management a...
Bookends is a full-featured bibliography/reference and information-management system for students and professionals. Bookends uses the cloud to sync reference libraries on all the Macs you use.... Read more
OmniGraffle Pro 7.16 - Create diagrams,...
OmniGraffle Pro helps you draw beautiful diagrams, family trees, flow charts, org charts, layouts, and (mathematically speaking) any other directed or non-directed graphs. We've had people use... Read more
Drive Genius 6.1.0 - $79.00
Drive Genius features a comprehensive Malware Scan. Automate your malware protection. Protect your investment from any threat. The Malware Scan is part of the automated DrivePulse utility. DrivePulse... Read more
Tor Browser 9.5 - Anonymize Web browsing...
The Tor Browser Bundle is an easy-to-use portable package of Tor, Vidalia, Torbutton, and a Firefox fork preconfigured to work together out of the box. It contains a modified copy of Firefox that... Read more
VueScan 9.7.28 - 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
OmniGraffle 7.16 - Create diagrams, flow...
OmniGraffle helps you draw beautiful diagrams, family trees, flow charts, org charts, layouts, and (mathematically speaking) any other directed or non-directed graphs. We've had people use Graffle to... Read more
WALTR 2 2.6.26 - $39.95
WALTR 2 helps you wirelessly drag-and-drop any music, ringtones, videos, PDF, and ePub files onto your iPhone, iPad, or iPod without iTunes. It is the second major version of Softorino's critically-... Read more
Airmail 4.1 - Powerful, minimal email cl...
Airmail is an mail client with fast performance and intuitive interaction. Support for iCloud, MS Exchange, Gmail, Google Apps, IMAP, POP3, Yahoo!, AOL, Outlook.com, Live.com. Airmail was designed... Read more
Iridient Developer 3.3.12 - Powerful ima...
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

Latest Forum Discussions

See All

Willy Jetman: Astromonkey's Revenge...
Barcelona-based developer Last Chicken Games are set to bring their game Willy Jetman: Astromonkey's Revenge to both iOS and Android on 9th July. The Metroidvania is already available on the likes of PS4, Switch and PC but now mobile folk will be... | Read more »
The 5 Best Mobile Real Time Strategy Gam...
Real-time strategy games feel like they’d be a perfect fit for mobile, but they’re trickier to pull off that you might think. The traditional mold of base-building and micro management can work on touch screens, but needs to be carefully honed so... | Read more »
Using your phone in a protest
I can't write about games today. There is a struggle happening in the streets right now and it needs everyone's attention. Here's some good info on how you can use your iOS device safely amidst a protest. | Read more »
Dungonian is a card-based dungeon crawle...
Dungonian is a card-based dungeon crawler from developer SandFish Games that only recently launched as a free-to-play title. It offers an extensive roster of playable heroes to collect and enemies to take down, and it's available right now for iOS... | Read more »
Steam Link Spotlight - Signs of the Sojo...
Steam Link Spotlight is a feature where we look at PC games that play exceptionally well using the Steam Link app. Our last entry was XCOM: Chimera Squad. Read about how it plays using Steam Link's new mouse and keyboard support over here. | Read more »
Steampunk Tower 2, DreamGate's sequ...
Steampunk Tower 2 is a DreamGate's follow up to their previous tower defence game. It's available now for both iOS and Android as a free-to-play title and will see players defending their lone base by kitting it out with a variety of turrets. [... | Read more »
Clash Royale: The Road to Legendary Aren...
Supercell recently celebrated its 10th anniversary and their best title, Clash Royale, is as good as it's ever been. Even for lapsed players, returning to the game is as easy as can be. If you want to join us in picking the game back up, we've put... | Read more »
Pokemon Go Fest 2020 will be a virtual e...
Niantic has announced that Pokemon Go Fest will still take place this year although understandably it won't be a physical event. Instead, it will become a virtual celebration and is set to be held on 25th and 26th July. [Read more] | Read more »
Marvel Future Fight's major May upd...
Marvel Future Fight's latest update has now landed, and it sounds like a big one. The focus this time around is on Marvel's Guardians of the Galaxy, and it introduces all-new characters, quests, and uniforms for players to collect. [Read more] | Read more »
SINoALICE, Yoko Taro and Pokelabo's...
Yoko Taro and developer Pokelabo's SINoALICE has now opened for pre-registration over on the App Store. It's already amassed 1.5 million Android pre-registrations, and it's currently slated to launch on July 1st. [Read more] | Read more »

Price Scanner via MacPrices.net

Apple restocks 27″ iMacs, Certified Refurbish...
Apple has restocked Certified Refurbished 2019 27″ iMacs starting at $1529 and up to $350 off the cost of new models. Apple’s one-year warranty is standard, shipping is free, and each iMac features a... Read more
Apple’s new 2020 13″ 4-Core MacBook Airs on s...
B&H Photo has Apple’s new 2020 13″ 4-Core MacBook Airs on sale today for $100 off Apple’s MSRP, only $1199. Expedited shipping is free to many addresses in the US. The MacBook Airs are the same... Read more
New Verizon promo: $150 off any Apple Watch w...
Verizon is offering $150 off any Apple Watch when purchased alongside an iPhone through June 10, 2020. They’re also offering up to $100 on any Apple Watch trade-in. Here are the details: “Get $150... Read more
Last year’s 13″ 2.4GHz MacBook Pros are avail...
Apple has Certified Refurbished 2019 13″ 2.4GHz/256GB 4-Core Touch Bar MacBook Pros available for $1359, $440 off original MSRP. Apple’s one-year warranty is included, shipping is free, and each... Read more
Apple’s new 2020 13″ MacBook Pros on sale for...
Apple reseller Abt Electronics has new 2020 13″ MacBook Pros on sale today for up to $140 off MSRP, starting at $1208. Shipping is free, and most configurations are in stock today. Note that Abt’s... Read more
Apple CEO Reacts To Nationwide Protests Over...
NEWS: 06.03.20 – With the recent death of a black man in the custody of a white police officer igniting outrage among Americans from all walks of life, which resulted in protests and civil unrest... Read more
At up to $420 off MSRP, these Certified Refur...
Apple has Certified Refurbished 2019 16″ MacBook Pros available for up to $420 off the cost of new models, starting at $2039. Each model features a new outer case, shipping is free, and an Apple 1-... Read more
Apple restocks refurbished 3rd generation 12....
Apple restocked select 3rd generation 12.9″ WiFi iPad Pros starting at only $699 and up to $330 off original MSRP. Each iPad comes with a standard Apple one-year warranty, outer cases are new, and... Read more
These wireless carriers are offering Apple’s...
Looking for a deal on Apple’s new iPhone SE? Apple itself offers the unlocked 64GB iPhone SE for $399 or $16.62/month. If you’re willing to try a new carrier, two of Apple’s wireless carriers are... Read more
Save $80 on the 64GB 10.5″ iPad Air with this...
Apple has 10.5″ 64GB WiFi iPad Airs models available for $80 off MSRP, Certified Refurbished. Each iPad comes with Apple’s standard one-year warranty and includes a new outer case. Shipping is free... Read more

Jobs Board

*Apple* Architect - SAIC (United States)
**Description** We are currently seeking a motivated, career and customer oriented Apple Architect to join our team in Washington, DC to begin an exciting and Read more
*Apple* Support Engineer - SAIC (United Stat...
**Description** We are currently seeking a motivated, career and customer oriented Apple Support Engineer to join our team in Washington, DC to begin an exciting and Read more
Perioperative RN - ( *Apple* Hill Surgical C...
Perioperative RN - ( Apple Hill Surgical Center) Tracking Code 60593 Job Description Monday - Friday - Full Time Days Possible Saturdays General Summary: Under the Read more
Senior Practice Manager - *Apple* Hill Eye...
Senior Practice Manager - Apple Hill Eye Center Tracking Code 61713 Job Description Apple Hill Medical Center General Summary: Under general supervision, manages Read more
*Apple* Mac Desktop Support - Global Dimensi...
…Operate and support an Active Directory (AD) server-client environment for all Apple devices operating on the BUMED network + Leverage necessary industry enterprise Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.