Desktop Stuffing
Volume Number: 14
Issue Number: 5
Column Tag: Powerplant
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;
// 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
CStuffItArchive::BrowseNext(archiveObject &outObject)
if (!mIteratorInitialized) {
Reset();
if (mBrowseStack) {
delete mBrowseStack;
mBrowseStack = 0L;
}
}
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)
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/.