Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 1 - Resource Manager / Resource Manager Reference

Resource Manager Routines / Counting and Listing Resource Types

Get1IndResource

You can use the Get1IndResource function repeatedly to get handles to all resources of a given type in the current resource file.

FUNCTION Get1IndResource (theType: ResType; 
                          index: Integer): Handle;

theType

A resource type.

index

An integer ranging from 1 to the number of resources of a given type returned by Count1Resources, which is the number of resource types in the current resource file.

DESCRIPTION

Given an index ranging from 1 to the number of resources of a given type returned by Count1Resources (that is, the number of resources of that type in the current resource file), the Get1IndResource function returns a handle to a resource of the given type. If you call Get1IndResource repeatedly over the entire range of the index, it returns handles to all resources of the given type in the current resource file.

The function reads the resource data into memory if it's not already there, unless you've called SetResLoad with the load parameter set to FALSE.

IMPORTANT

If you've called SetResLoad with the load parameter set to FALSE and the data isn't already in memory, Get1IndResource returns an empty handle (that is, a handle whose master pointer is set to NIL). This can also happen if you read resource data for a purgeable resource into memory and then call SetResLoad with the load parameter set to FALSE. If the resource data is later purged and you call the Get1IndResource function, Get1IndResource returns an empty handle. You should test for an empty handle in these situations. To make the handle a valid handle to resource data in memory, you can call the LoadResource procedure.

If you provide an index to Get1IndResource that's either 0 or negative, Get1IndResource returns NIL, and the ResError function returns the result code resNotFound. If the given index is larger than the value returned by Count1Resources, Get1IndResource returns NIL, and ResError returns the result code resNotFound. If the resource to be read won't fit into memory, Get1IndResource returns NIL, and ResError returns the appropriate result code.

SPECIAL CONSIDERATIONS

The Get1IndResource function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.

RESULT CODES

noErr	0	No error
resNotFound	-192	Resource not found

SEE ALSO

To check for errors, call the ResError function as described on page 1-47.

For an example of the use of the Get1IndResource function, see Listing 1-10 on page 1-28.

For a description of the Count1Resources function, see page 1-93. For a description of the UseResFile procedure, see page 1-65. For descriptions of the SetResLoad and LoadResource procedures, see page 1-74 and page 1-75, respectively.