Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 5 - Collection Manager / Collection Manager Reference

Functions / Working With Macintosh Memory Manager Handles

GetCollectionItemHdl

You can use the GetCollectionItemHdl function to obtain a copy of the variable-length data associated with a collection item given the item's collection tag and collection ID. You must provide a valid Macintosh Memory Manager handle for this function to copy the data into.

OSErr GetCollectionItemHdl(Collection source,
                           CollectionTag tag,
                           long id,
                           Handle itemData);

source

A reference to the collection object containing the item whose data you want to retrieve.

tag

The collection tag associated with the item whose data you want to retrieve.

id

The collection ID associated with the item whose data you want to retrieve.

itemData

A handle to a block of memory to contain the item's data. On return, this memory contains a copy of the data associated with the specified item. You may specify the constant dontWantData for this parameter if you do not want a copy of the item's data.

DESCRIPTION

The GetCollectionItemHdl function allows you to obtain a copy of the variable-length data associated with a specific collection item. You specify a collection object using the source parameter and you specify an item in that collection using the tag and id parameters. If you provide a valid Macintosh Memory Manager handle in the itemData parameter, the function uses this parameter to return a copy of the variable-length data associated with the specified collection item.

RESULT CODES

memFullErr	-108	Can't allocate memory.
collectionItemNotFoundErr	-5751	Can't locate item.

SEE ALSO

For information about collection items and their associated collection tags, collection IDs, and variable-length data, see "Collection Items" beginning on page 5-8.

For examples using this function, see "Retrieving the Variable-Length Data From an Item" beginning on page 5-33.

To retrieve the data associated with a collection item into a block of memory referenced by a pointer (rather than a handle), use the GetCollectionItem function, described on page 5-71.