Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 1 - Resource Manager / Resource Manager Reference

Resource Manager Routines / Reading Resources Into Memory

GetResource

You can use the GetResource function to get resource data for a resource specified by resource type and resource ID.

FUNCTION GetResource (theType: ResType; theID: Integer): Handle;

theType

A resource type.

theID

An integer that uniquely identifies a resource of the specified type.

DESCRIPTION

The GetResource function searches the resource maps in memory for the resource specified by the parameters theType and theID. The resource maps in memory, which represent all the open resource forks, are arranged as a linked list. When searching this list, GetResource starts with the current resource file and progresses through the list (that is, searching the resource maps in reverse order of opening) until it finds the resource's entry in one of the resource maps.

If the GetResource function finds the specified resource entry in one of the resource maps and the entry contains a valid handle, it returns that handle. If the entry contains a a handle whose value is NIL, and if you haven't called SetResLoad with the load parameter set to FALSE, GetResource attempts to read the resource into memory.

If GetResource can't find the resource data, it returns NIL, and ResError returns the result code resNotFound. The GetResource function also returns NIL if the resource data to be read into memory won't fit, in which case ResError returns an appropriate Memory Manager result code. If you call GetResource with a resource type that can't be found in any of the resource maps of the open resource forks, the function returns NIL, but ResError returns the result code noErr. You should always check that the value of the returned handle is not NIL.

You can change the resource map search order by calling the UseResFile procedure before GetResource.

SPECIAL CONSIDERATIONS

Calling GetResource 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 examples of the use of GetResource, see page 1-14 through page 1-18.

To include ROM-resident system resources in the Resource Manager's search of the resource maps of open resource forks, use the RGetResource function as described on page 1-73.

For information about the UseResFile and SetResLoad procedures, see page 1-65 and page 1-74, respectively.