Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 5 - Collection Manager / Collection Manager Reference

Functions / Flattening and Unflattening a Collection

UnflattenCollection

You use the UnflattenCollection function to unflatten a collection that was flattened using the FlattenCollection or FlattenPartialCollection function.

OSErr UnflattenCollection (Collection target,
                           CollectionFlattenProc flattenProc,
                           void *refCon);

target

A reference to the collection object you want to create from the flattened data.

flattenProc

A pointer to a function to read in flattened data.

refCon

A reference constant that you want the Collection Manager to pass repeatedly to the callback function.

DESCRIPTION

The UnflattenCollection function unflattens a stream of bytes into the collection object you specify with the target parameter.

As this function unflattens the collection, it repeatedly calls the callback function you specify using the flattenProc parameter. Each time it calls this function, it provides the callback function with a pointer to a block of memory and a requested size. The callback function is responsible for reading the next set of bytes from the flattened byte stream and copying the data into the block of memory.

The Collection Manager continues to call your callback function, requesting more of the flattened stream of bytes each time, until it has unflattened the entire collection. Your callback function can read the flattened data from any source you choose: it could read the flattened data from a handle-based block of memory, it could read the flattened data from disk, and so on.

In the refCon parameter, you specify a value that the Collection Manager passes on to your callback function each time it calls your callback function. You can use this parameter as a pointer to a structure containing information your callback function needs when reading the blocks of flattened data.

This function can return any error returned by the callback function.

RESULT CODES

memFullErr	-108	Can't allocate memory.
collectionVersionErr	-5753	Unrecognized version/data may be corrupt.

SEE ALSO

For examples of this function, see "Flattening and Unflattening a Collection" beginning on page 5-37 and "Reading Collections From and Writing Collections to Disk" beginning on page 5-41.

For information about the callback function that you provide, see page 5-100.

To create a flattened collection that includes only those collection items whose attributes match a specified pattern, use the FlattenPartialCollection function, described in the previous section.

To create a flattened collection that includes every item in a collection, use the FlattenCollection function, described on page 5-88.