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

GetTaggedCollectionItem

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

OSErr GetTaggedCollectionItem(Collection source,
                              CollectionTag tag,
                              long position,
                              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.

position

The tag list position associated with the specific item.

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 of 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 GetTaggedCollectionItem 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; you specify the item in that collection using the tag and position parameters. In the tag parameter you specify the collection tag of the desired item and in the position parameter you specify the tag list position of the desired item.

Remember that a tag list position is the sequential index that determines an item given a specific collection tag. For example:

• A tag list position of 1 indicates the first item with the specified tag.
• A tag list position of 2 indicates the second item with the specified tag.

By sequentially incrementing the position parameter, you can use this function to step through all of the items in a collection without knowing their collection IDs.

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 the constant 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

collectionIndexRangeErr

-5752

Index is out of range.

SEE ALSO

For information about collection items and their associated collection tags and variable-length data, see "Collection Items" beginning on page 5-8. For information about tag list positions, see "Methods of Identifying Collection Items" beginning on page 5-11.

For examples of 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 tag and ID, use the GetCollectionItem function, described on page 5-71.

To retrieve the data associated with a collection item given its collection index, use the GetIndexedCollectionItem function, described in the previous section.