Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 5 - Collection Manager / Using the Collection Manager

Reading Collections From and Writing Collections to Disk

The Collection Manager provides a number of methods for storing collections on disk:

• You can store the collection's contents as a collection ('cltn') resource and read the information into a collection object using the GetNewCollection function. For more information about the 'cltn' resource, see "The Collection Resource" beginning on page 5-102, and for more information about the GetNewCollection function, see the description of that function on page 5-99. For an example of reading a collection object from a collection resource, see the next section, "Reading a Collection From a Collection Resource."
• You can flatten a collection using the FlattenCollection function and provide a callback function that writes the blocks of flattened data to a file. You can unflatten this collection using the UnflattenCollection function, providing a callback function that reads blocks of data from the file. For more information about these functions, see "Flattening and Unflattening a Collection" beginning on page 5-37 and the description of the FlattenCollection function on page 5-88 and the description of the UnflattenCollection function on page 5-90.
• You can flatten a collection to a handle using the FlattenCollectionToHdl function and write the contents of the handle to the resource fork of a file (using the Macintosh function AddResource) or to the data fork of a file (using the Macintosh function FSWrite). You can then read the contents of this file into a handle (using the Macintosh functions GetResource or FSRead) and unflatten the result using the UnflattenCollectionFromHdl function.

IMPORTANT

Although you may create a resource containing a flattened collection using the FlattenCollectionToHdl and AddResource functions, you cannot recreate the collection from this resource using the GetNewCollection function. The resource format created by the FlattenCollectionToHdl and AddResource functions is incompatible with the resource format expected by the GetNewCollection function.

Listing 5-22 shows how to flatten a collection to a handle and then write the contents of the handle to the resource fork of a disk file.

Listing 5-22 Flattening a collection to a disk file as a resource

OSErr anErr;
Handle flattened;

/* write the collection out as a resource */

flattened = NewHandle(0);
anErr = FlattenCollectionToHdl(myCollection, flattened);

if (anErr == noErr) {
   AddResource(flattened, myType, myID, myName);
   anErr = ResError();
}

Listing 5-23 shows how to flatten a collection to a handle and then write the contents of the handle to the data fork of a disk file.

Listing 5-23 Flattening a collection to a data fork of a disk file

OSErr anErr;
Handle flattened;
long theSize;

/* write the collection out to the data fork */

flattened = NewHandle(0);
anErr = FlattenCollectionToHdl(myCollection, flattened);

if (anErr == noErr) {
   theSize = GetHandleSize(flattened);
   anErr = FSWrite(refNum, theSize, *flattened);
}

Listing 5-24 shows how to read a flattened collection from the resource fork of a disk file into a block of memory referenced by a Macintosh Memory Manager handle and then unflatten the information in that block of memory into a collection object.

Listing 5-24 Unflattening a collection from a disk file as a resource

Handle flattened;
Collection myCollection;

if (myCollection = NewCollection()) {

   /* read the collection in as a resource */

   flattened = GetResource(myType, myID);

   if ((anErr = ResError()) == noErr) {
   anErr = UnflattenCollectionFromHdl(myCollection, flattened);
   ReleaseResource(flattened);
   if (anErr == noErr)
      anErr = ResError();
   }
}

Listing 5-25 shows how to read a flattened collection from the data fork of a disk file into a block of memory referenced by a Macintosh Memory Manager handle and then unflatten the information in that block of memory into a collection object.

Listing 5-25 Unflattening a collection from the data fork of a disk file

OSErr anErr;
Handle flattened;
Collection myCollection;

if (myCollection = NewCollection()) {

   /* read the collection in from the data fork */

   flattened = NewHandle(theSize);

   if ((anErr = MemError()) == noErr) {
      if ((anErr = FSRead(refNum, theSize, *flattened)) == noErr)
         anErr = UnflattenCollectionFromHdl(myCollection,
                                            flattened);
      DisposHandle(flattened);

   }
}

To unflatten a collection using Listing 5-25, you must know the size of the collection before you can unflatten it. If you don't know the size of the collection, you unflatten a collection using the callback function mechanism described in "Flattening and Unflattening a Collection" beginning on page 5-37.

For more information about the FlattenCollectionToHdl function and the UnflattenCollectionFromHdl function, see "Flattening and Unflattening a Collection" beginning on page 5-37 as well as the descriptions of these functions starting on page 5-97.

For information about the Macintosh functions AddResource and GetResource, see the chapter "Resource Manager" in Inside Macintosh: More Macintosh Toolbox. For information about the Macintosh functions FSRead and FSWrite, see the chapter "File Manager" in Inside Macintosh: Files.