Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 5 - Collection Manager / Collection Manager Reference

Functions / Flattening and Unflattening a Collection

FlattenPartialCollection

You can use the FlattenPartialCollection function to convert a collection object into a stream format suitable for storage and unflattening. With this function, you can include in the flattened collection only those items whose attributes match a specified pattern.

OSErr FlattenPartialCollection(Collection source,
                               CollectionFlattenProc flattenProc,
                               void *refCon,
                               long whichAttributes,
                               long matchingAttributes)

source

The collection that you want to flatten.

flattenProc

A pointer to a function to write data.

refCon

A reference constant that you want the Collection Manager to pass repeatedly to the flatten procedure.

whichAttributes

A mask indicating which attributes you want to test.

matchingAttributes

A long word containing the attribute values you want to match.

DESCRIPTION

The FlattenPartialCollection function flattens into a stream of bytes the collection you specify with the source parameter. It includes only the collection items whose attributes specified by the whichAttributes parameter match the values specified by the matchingAttributes parameter.

As this function flattens 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 containing flattened data. It continues to call this function until it has flattened the entire collection. Your callback function can process the flattened data in a number of ways: it could copy the flattened data into a handle-based block of memory, it could write the flattened data to 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 to process the blocks of flattened data.

When flattening the source collection, this function includes only the collection items whose persistence attribute is set, regardless of the values you provide in the whichAttributes and matchingAttributes parameters.

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

SEE ALSO

For information about matching collection item attributes, see "Collection Items" beginning on page 5-8.

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

To create a flattened collection that includes every item in a collection, use the FlattenCollection function, described in the previous section.

To unflatten a flattened collection, use the UnflattenCollection function, described in the next section.