Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 5 - Collection Manager / Collection Manager Reference

Functions / Retrieving the Variable-Length Data From an Item

GetCollectionItem

You can use the GetCollectionItem function to obtain a copy of the variable-length data associated with a collection item given the item's collection tag and collection ID.

OSErr GetCollectionItem(Collection source,
                        CollectionTag tag,
                        long id,
                        long *itemSize,
                        void *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.

itemSize

A pointer to a long value indicating the number of bytes of data you want returned in the itemData parameter. On return, this value indicates the size in bytes of the variable-length data associated with the specified item. You may specify the constant dontWantSize for this parameter to indicate that you want to copy all the specified item's variable-length data and you do not want to determine the size of this data.

itemData

A pointer 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 GetCollectionItem 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.

You use the itemSize parameter to specify how many bytes of data to return in the itemData parameter. You may specify the constant dontWantSize for this parameter to indicate that you want to copy all of the variable-length data from the specified item into the itemData parameter. You may specify a value for the itemSize parameter that is greater than the actual number of bytes in the specified item's variable-length data; however, this function never returns in the itemData parameter more data than contained in the specified item's variable-length data.

This function returns information in the itemSize and itemData parameters:

• If you provide a pointer in the itemSize parameter, the function uses this parameter to return the size in bytes of the variable-length data associated with the specified collection item.
• If you provide a pointer in the itemData parameter, the function uses this parameter to return a copy of the variable-length data associated with the specified collection item.

If you don't know the size of the item you want to retrieve, you typically call this function twice. The first time you provide a pointer in the itemSize parameter to determine the size of the specified item's data and you specify dontWantData for the itemData parameter. Then you allocate a memory block large enough to hold a copy of the item's data. Then you call the function a second time. This time you specify the constant dontWantSize for the itemSize parameter and provide a pointer to the allocated memory block for the itemData parameter. The function then copies the data into the allocated block of memory.

RESULT CODES

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 given its collection index (rather than its collection tag and ID), use the GetIndexedCollectionItem function, described in the next section.