Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 5 - Collection Manager / Using the Collection Manager

Retrieving the Variable-Length Data From an Item

The Collection Manager provides three functions that return a copy of the information in an item's variable-length data. These three functions differ in how they allow you to specify which item you want information about:

• The GetCollectionItem function requires that you specify the collection tag and collection ID of the desired item.
• The GetIndexedCollectionItem function requires that you specify the collection index of the desired item.
• The GetTaggedCollectionItem function requires that you specify the collection tag and tag list position of the desired item.

Note

The Collection Manager also provides the utility function GetCollectionItemHdl, which returns a copy of the item's data in a block of memory referenced by a Macintosh Memory Manager handle, rather than a pointer. See page 5-94 for more information about this function.

These functions each return two pieces of information about the specified item--the size of its variable-length data and a copy of the data itself. You can specify that you want to determine either the size or the data or both (or neither, actually, although that doesn't prove to be very useful).

Typically, you call these functions twice:

• once to determine the size of the data (if you don't already know the size)
• once (after allocating enough memory) to obtain a copy of the data.

Listing 5-15 shows how to use the GetCollectionItem function to retrieve the variable-length data from an item. This sample code uses the pointsAndQuotes collection defined in "Adding Items to a Collection" beginning on page 5-17.

Listing 5-15 Retrieving the variable-length data from an item

long theSize;
char *theData;
.
.
.
anErr = GetCollectionItem(pointsAndQuotes,
                          'QUOT', 0, /* tag and id */
                          &theSize,
                          dontWantData);
                       
theData = (char *) NewPtr(theSize);

anErr = GetCollectionItem(pointsAndQuotes,
                          'QUOT', 0,
                          dontWantSize,
                          theData);

If you specify a non-NIL value for the size parameter, the GetCollectionItem function returns in the size parameter the actual number of bytes of the item's data.

If you specify non-NIL values for both the size and data parameters, the number of bytes returned in the data parameter is either the value specified by the size parameter or the actual number of bytes of the specified item's data, whichever is lower.

You can also use the GetIndexedCollectionItem function to retrieve an item's data, given the item's collection index rather than its collection tag and collection ID, as shown in Listing 5-16.

Listing 5-16 Retrieving the variable-length data from an item using the item's index

long index;
long theSize;
char *theData;
.
.
.
/* get the index and data size */
anErr = GetCollectionItemInfo(pointsAndQuotes, 
                              'QUOT', 0, /* tag and id */
                              &index, 
                              &theSize, 
                              dontWantAttributes;
.
.
.
theData = (char *) NewPtr(theSize);

anErr = GetIndexedCollectionItem(pointsAndQuotes,
                                 index,
                                 dontWantSize,
                                 theData);

Similarly, you can use the GetTaggedCollectionItem function to retrieve an item's data, given the item's collection tag and tag list position, as shown in Listing 5-17.

Listing 5-17 Retrieving the variable-length data from an item using the tag and tag list position

long index;
long theSize;
char *theData;
.
.
.
anErr = GetTaggedCollectionItem(pointsAndQuotes,
                                'QUOT',
                                1, /* first of the 'QUOT' items */
                                &theSize,
                                dontWantData);
                       
theData = (char *) NewPtr(theSize);

anErr = GetTaggedCollectionItem(pointsAndQuotes,
                                'QUOT',
                                1, /* first of the 'QUOT' items */
                                dontWantSize,
                                (void *) theData);

For more information about identifying collection items, see "Methods of Identifying Collection Items" on page 5-11.

For more information about the GetCollectionItem, GetIndexedCollectionItem, and GetTaggedCollectionItem functions, see "Retrieving the Variable-Length Data From an Item" beginning on page 5-70.