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

GetIndexedCollectionItem

You can use the GetIndexedCollectionItem function to obtain a copy of the variable-length data associated with a collection item given the item's collection index.

OSErr GetIndexedCollectionItem(Collection source,
                               long index,
                               long *itemSize,
                               void *itemData);

source

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

index

The collection index 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 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 GetIndexedCollectionItem 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 index parameter.

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 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 variable-length data, see "Collection Items" beginning on page 5-8. For information about collection indexes, see "Methods of Identifying Collection Items" beginning on page 5-11.

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