Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 1 - Resource Manager / Resource Manager Reference

Resource Manager Routines

Reading Resources Into Memory

The routines described in this section allow your application to read resource data into memory. The GetResource and Get1Resource functions get a resource specified by a resource type and a resource ID. The GetNamedResource and Get1NamedResource functions get a resource specified by name. The RGetResource function searches the ROM-resident resources as well as the open resource forks.

The SetResLoad procedure enables and disables automatic loading of resource data into memory for routines that return handles to resources, and the LoadResource procedure reads resource data into memory for a purged resource or after you've called SetResLoad with the load parameter set to FALSE.

When your application requests a resource, the Resource Manager normally looks in the current resource file's resource map in memory. If it can't find an entry for the specified resource, the Resource Manager searches the resource maps for each open resource fork in the reverse order that the resource forks were opened. If it can't find an entry for the specified resource in any of these resource maps, the Resource Manager searches your application's resource map. If it can't find an entry for the specified resource in
your application's resource map, the Resource Manager searches the resource map for the System file.

The Resource Manager determines whether or not to load the specified resource into memory according to the entry for that resource in the resource map. If the resource's resource map entry contains a valid handle, the Resource Manager returns that handle. If the value of the handle is NIL, the Resource Manager reads the resource data into memory.

Before reading the resource data into memory, the Resource Manager calls the Memory Manager to allocate a relocatable block for the resource data. The Memory Manager allocates the block, assigns a master pointer to the block, and returns to the Resource Manager a pointer to the master pointer. The Resource Manager then installs this handle in the resource map and also returns a handle to the resource.

If the resource's resource map entry contains an empty handle (a handle whose master pointer is set to NIL) and the value of the system global variable ResLoad is TRUE, the Resource Manager routines that get resources reallocate the resource's handle and read the resource data from disk back into memory.

IMPORTANT

In certain situations, a Resource Manager routine can return an empty handle (a handle whose master pointer is set to NIL). For instance, if you've called SetResLoad with the load parameter set to FALSE and the resource data isn't already in memory, and then you call the GetResource function (or any of the other Resource Manager routines that get a resource), the Resource Manager routine returns an empty handle (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, when you call GetResource (or other routines that get a resource), the Resource Manager 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.

---

Subtopics

GetResource

Get1Resource

GetNamedResource

Get1NamedResource

RGetResource

SetResLoad

LoadResource