Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Resource Manager Reference

Framework
CoreServices/CoreServices.h
Declared in
IOMacOSTypes.h
Resources.h

Overview

The Resource Manager allows applications to create, delete, open, read, modify, and write resources, get information about them, and alter the Resource Manager’s search path. A resource is data of any kind stored in a defined format in a resource file. The Resource Manager keeps track of resources in memory and provides functions for the proper management of the resource chain. In Mac OS X, you should store resources in the data fork of a resource file.

Carbon applications have used Resource Manager resources to store the descriptions for user interface elements such as menus, windows, dialogs, controls, and icons. In addition, applications have used resources to store variable settings, such as the location of a document window at the time the user closes the window. When the user opens the document again, the application reads the information in the appropriate resource and restores the window to its previous location.

Functions by Task

Checking for Errors

Closing Resource Forks

Counting and Listing Resource Types

Creating Resource Files and Forks

Disposing of Resources

Getting a Unique Resource ID

Getting and Setting Resource Fork Attributes

Getting and Setting Resource Information

Getting and Setting the Current Resource File

Getting Resource Sizes

Managing the Resource Chain

Modifying Resources

Opening Resource Forks

Reading and Writing Partial Resources

Reading Resources Into Memory

Writing to Resource Forks

Not Recommended

Functions

AddResource

Adds a resource to the current resource file’s resource map in memory.

void AddResource (
   Handle theData,
   ResType theType,
   ResID theID,
   ConstStr255Param name
);

Parameters
theData

A handle to data in memory to be added as a resource to the current resource file (not a handle to an existing resource). If the value of this parameter is an empty handle (that is, a handle whose master pointer is set to NULL), the Resource Manager writes zero-length resource data to disk when it updates the resource. If its value is either NULL or a handle to an existing resource, the function does nothing, and the ResError function returns the result code addResFailed. If the resource map becomes too large to fit in memory, the function does nothing, and ResError returns an appropriate result code. The same is true if the resource data in memory can’t be written to the resource fork (for example, because the disk is full).

theType

The resource type of the resource to be added.

theID

The resource ID of the resource to be added.

name

The name of the resource to be added.

Discussion

This function sets the resChanged attribute to 1 it does not set any of the resource’s other attributes—that is, all other attributes are set to 0. If the resChanged attribute of a resource has been set and your application calls the UpdateResFile function or quits, the Resource Manager writes both the resource map and the resource data for that resource to the resource fork of the corresponding file on disk. If the resChanged attribute for a resource has been set and your application calls the WriteResource function, the Resource Manager writes only the resource data for that resource to disk.

If you add a resource to the current resource file, the Resource Manager writes the entire resource map to disk when it updates the file. If you want any of your changes to the resource map or resource data to be temporary, you must restore the original information before the Resource Manager updates the file on disk.

The function doesn’t verify whether the resource ID you pass in the parameter theID is already assigned to another resource of the same type. You should call the UniqueID or Unique1ID function to get a unique resource ID before adding a resource with this function.

When your application calls this function, the Resource Manager attempts to reserve disk space for the new resource. If the new resource data can’t be written to the resource fork (for example, if there’s not enough room on disk), the resChanged attribute is not set to 1. If this is the case and you call UpdateResFile or WriteResource, the Resource Manager won’t know that resource data has been added. Thus, the function won’t write the new resource data to the resource fork and won’t return an error. For this reason, always make sure that the ResError function returns the result code noErr after a call to AddResource.

To copy an existing resource, get a handle to the resource you want to copy, call the DetachResource function, then call AddResource. To add the same resource data to several different resource forks, call the Memory Manager function HandToHand to duplicate the handle for each resource.

Availability
Declared In
Resources.h

ChangedResource

Sets a flag in the resource’s resource map entry in memory to show that you’ve made changes to a resource’s data or to an entry in a resource map. 

void ChangedResource (
   Handle theResource
);

Parameters
theResource

A handle to the resource whose data you’ve changed. The function sets the resChanged attribute for that resource in the resource map in memory. If the resChanged attribute for a resource has been set and your application calls the UpdateResFile function or quits, the Resource Manager writes the resource data for that resource (and for all other resources whose resChanged attribute is set) and the entire resource map to the resource fork of the corresponding file on disk. If the resChanged attribute for a resource has been set and your application calls the WriteResource function, the Resource Manager writes only the resource data for that resource to disk.

If the given handle isn’t a handle to a resource, if the modified resource data can’t be written to the resource fork, or if the resProtected attribute is set for the modified resource, the function does nothing. To find out whether any of these errors occurred, call the ResError function.

Discussion

If you change information in the resource map with a call to the SetResInfo or SetResAttrs function and then call ChangedResource and UpdateResFile, the Resource Manager still writes both the resource map and the resource data to disk. If you want any of your changes to the resource map or resource data to be temporary, you must restore the original information before the Resource Manager updates the resource fork on disk.

After writing a resource to disk, the Resource Manager clears the resource’s resChanged attribute in the appropriate entry of the resource map in memory.

When your application calls this function, the Resource Manager attempts to reserve enough disk space to contain the changed resource. The function reserves space every time you call it, but the resource is not actually written until you call WriteResource or UpdateResFile. Thus, if you call ChangedResource several times before the resource is actually written, the function reserves much more space than is needed. If the resource is large, you may unexpectedly run out of disk space. When the resource is actually written, the file’s end-of-file (EOF) is set correctly, and the next call to ChangedResource will work as expected.

If the modified resource data can’t be written to the resource fork (for example, if there’s not enough room on disk), the resChanged attribute is not set to 1. If this is the case and you call UpdateResFile or WriteResource, the Resource Manager won’t know that the resource data has been changed. Thus, the function won’t write the modified resource data to the resource fork and won’t return an error. For this reason, always make sure that the ResError function returns the result code noErr after a call to ChangedResource.

If your application frequently changes the contents of resources (especially large resources), you should call WriteResource or UpdateResFile immediately after calling ChangedResource.

If you need to make changes to a purgeable resource using functions that may cause the Memory Manager to purge the resource, you should make the resource temporarily not purgeable. To do so, use the Memory Manager functions HGetState, HNoPurge, and HSetState to make sure the resource data remains in memory while you change it and until the resource data is written to disk. (You can’t use the SetResAttrs function for this purpose, because the changes don’t take effect immediately.) First call HGetState and HNoPurge, then change the resource as necessary. To make a change to a resource permanent, use ChangedResource and UpdateResFile or WriteResource; then call HSetState when you’re finished. Or, instead of calling WriteResource to write the resource data immediately, you can call the SetResPurge function with the install parameter set to TRUE before making changes to purgeable resource data.

If your application doesn’t make its resources purgeable, or if the changes you are making to a purgeable resource don’t involve functions that may cause the resource to be purged, you don’t need to take these precautions

Availability
Declared In
Resources.h

CloseResFile

Closes a resource fork before your application terminates.

void CloseResFile (
   ResFileRefNum refNum
);

Parameters
refNum

The file reference number for the resource fork to close. If this parameter does not contain a file reference number for a file whose resource fork is open, the function does nothing, and the ResError function returns the result code resFNotFound. If the value of this parameter is 0, it represents the System file and is ignored. You cannot close the System file’s resource fork.

Discussion

This function performs four tasks. First, it updates the file by calling the UpdateResFile function. Second, it releases the memory occupied by each resource in the resource fork by calling the DisposeHandle function. Third, it releases the memory occupied by the resource map. The fourth task is to close the resource fork.

When your application terminates, the Resource Manager automatically closes every resource fork open to your application except the System file’s resource fork. You need to call this function only if you want to close a resource fork before your application terminates.

Availability
Declared In
Resources.h

Count1Resources

Returns the total number of resources of a given type in the current resource file.

ResourceCount Count1Resources (
   ResType theType
);

Parameters
theType

The resource type of the resources to count.

Return Value

The total number of resources of the given type in the current resource file.

Discussion

To check for errors, call the ResError function.

Availability
Declared In
Resources.h

Count1Types

Returns the number of resource types in the current resource file.

ResourceCount Count1Types (
   void
);

Return Value

The total number of unique resource types in the current resource file.

Discussion

To check for errors, call the ResError function.

Availability
Declared In
Resources.h

CountResources

Returns the total number of available resources of a given type.

ResourceCount CountResources (
   ResType theType
);

Parameters
theType

A resource type.

Return Value

The total number of resources of the given type in all resource forks open to your application.

Discussion

To check for errors, call the ResError function.

Availability
Declared In
Resources.h

CountTypes

Returns the number of resource types in all resource forks open to your application.

ResourceCount CountTypes (
   void
);

Return Value

The total number of unique resource types in all resource forks open to your application.

Discussion

To check for errors, call the ResError function.

Availability
Declared In
Resources.h

CurResFile

Gets the file reference number of the current resource file.

ResFileRefNum CurResFile (
   void
);

Return Value

The file reference number associated with the current resource file. You can call this function when your application starts up (before opening the resource fork of any other file) to get the file reference number of your application’s resource fork. If the current resource file is the System file, the function returns the actual file reference number. You can use this number or 0 with functions that take a file reference number for the System file. All Resource Manager functions recognize both 0 and the actual file reference number as referring to the System file.

Discussion

Most of the Resource Manager functions assume that the current resource file is the file on whose resource fork they should operate or, in the case of a search, the file where they should begin. In general, the current resource file is the last one whose resource fork your application opened unless you specify otherwise.

To check for errors, call the ResError function.

Availability
Declared In
Resources.h

DetachResource

Sets the value of a resource’s handle in the resource map in memory to NULL while keeping the resource data in memory.

void DetachResource (
   Handle theResource
);

Parameters
theResource

A handle to the resource which you wish to detach. If this parameter doesn’t contain a handle to a resource or if the resource’s resChanged attribute is set, the function does nothing. To determine whether either of these errors occurred, call the ResError function.

Discussion

After this call, the Resource Manager no longer recognizes the handle as a handle to a resource. However, this function does not release the memory used for the resource data, and the master pointer is still valid. Thus, you can access the resource data directly by using the handle.

If your application subsequently calls a Resource Manager function to get the released resource, the Resource Manager assigns a new handle. You can use DetachResource if you want to access the resource data directly without using Resource Manager functions. You can also use the DetachResource function to keep resource data in memory after closing a resource fork.

To copy a resource and install an entry for the duplicate in the resource map, call DetachResource, then call the AddResource function using a different resource ID.

Special Considerations

Do not use this function to detach a System resource that might be shared by several applications.

Availability
Declared In
Resources.h

DetachResourceFile

Removes a resource file from the resource chain.

OSErr DetachResourceFile (
   ResFileRefNum refNum
);

Return Value

A result code. See “Resource Manager Result Codes.”

Discussion

If the file is not currently in the resource chain, this returns resNotFound. Otherwise, the resource file is removed from the resource chain.

Availability
Declared In
Resources.h

DisposeResErrUPP

Disposes of the universal procedure pointer (UPP) to your callback function.

void DisposeResErrUPP (
   ResErrUPP userUPP
);

Availability
Declared In
Resources.h

FSCreateResFile

Creates a file with an empty resource fork.

void FSCreateResFile (
   const FSRef *parentRef,
   UniCharCount nameLength,
   const UniChar *name,
   FSCatalogInfoBitmap whichInfo,
   const FSCatalogInfo *catalogInfo,
   FSRef *newRef,
   FSSpec *newSpec
);

Discussion

This function is not recommended. You should use a file’s data fork instead of its resource fork to store resource data.

Availability
Declared In
Resources.h

FSCreateResourceFile

Creates a file with a named fork for storing resource data.

OSErr FSCreateResourceFile (
   const FSRef *parentRef,
   UniCharCount nameLength,
   const UniChar *name,
   FSCatalogInfoBitmap whichInfo,
   const FSCatalogInfo *catalogInfo,
   UniCharCount forkNameLength,
   const UniChar *forkName,
   FSRef *newRef,
   FSSpec *newSpec
);

Parameters
parentRef

A pointer to the directory in which the resource file is to be created.

nameLength

The number of Unicode characters in the file's name.

name

A pointer to the Unicode name of the new resource file.

whichInfo

The catalog information fields to set. See the File Manager documentation for a description of the FSCatalogInfoBitmap data type.

catalogInfo

A pointer to the values for the catalog information fields. This pointer may be set to NULL. See the File Manager documentation for a description of the FSCatalogInfo data type.

forkNameLength

The number of Unicode characters in the fork’s name.

forkName

A pointer to the Unicode name of the fork to initialize. If you pass NULL in this parameter, the data fork is used.

newRef

A pointer to a variable allocated by the caller, or NULL. On return, the new resource file.

newSpec

A pointer to a variable allocated by the caller, or NULL. On return, the new resource file.

Return Value

A result code. See “Resource Manager Result Codes.”

Discussion

This function creates a new file and initializes the specified fork for storing resource data. If you don’t specify the fork name, the data fork is used. This function makes it possible to store resources in the data fork of a file.

Availability
Declared In
Resources.h

FSCreateResourceFork

Creates a named fork for storing resource data.

OSErr FSCreateResourceFork (
   const FSRef *ref,
   UniCharCount forkNameLength,
   const UniChar *forkName,
   UInt32 flags
);

Parameters
ref

A pointer to the file to which to add the fork.

forkNameLength

The number of Unicode characters in the fork’s name.

forkName

A pointer to the Unicode name of the fork to initialize. If you pass NULL in this parameter, the data fork is used.

flags

A value of type UInt32. You should pass 0.

Return Value

A result code. See “Resource Manager Result Codes.”

Discussion

This function creates the specified fork in an existing file and initializes the fork for storing resources. If the named fork already exists, this function does nothing and returns errFSForkExists. If you don’t specify the fork name, the data fork is used. This function makes it possible to store resources in the data fork of a file.

Availability
Declared In
Resources.h

FSOpenOrphanResFile

Opens a resource file that is persistent across all contexts.

OSErr FSOpenOrphanResFile (
   const FSRef *ref,
   SignedByte permission,
   ResFileRefNum *refNum
);

Parameters
ref

A pointer to the resource file to open.

permission

A constant indicating the type of access with which to open the resource fork. For a description of the types of access you can request, see File Access Permission Constants in File Manager Reference.

refNum

A pointer to a variable allocated by the caller. On return, the reference number for accessing the open fork.

Return Value

A result code. See “Resource Manager Result Codes.”

Discussion

This function loads a map and all preloaded resources into the system context and detaches the specified file from the context in which it was opened. If the file is already in the resource chain and a new instance is not opened, this function returns paramErr. Use this function with care, as it may fail if the map is very large or many resources are preloaded.

Availability
Declared In
Resources.h

FSOpenResFile

Opens the resource fork in a file specified with an FSRef structure.

ResFileRefNum FSOpenResFile (
   const FSRef *ref,
   SInt8 permission
);

Discussion

This function is not recommended. You should use a file’s data fork instead of its resource fork to store resource data.

Availability
Declared In
Resources.h

FSOpenResourceFile

Opens a named fork in an existing resource file.

OSErr FSOpenResourceFile (
   const FSRef *ref,
   UniCharCount forkNameLength,
   const UniChar *forkName,
   SInt8 permissions,
   ResFileRefNum *refNum
);

Parameters
ref

A pointer to the file containing the fork to open.

forkNameLength

The number of Unicode characters in the fork’s name.

forkName

A pointer to the Unicode name of the fork to open. If you pass NULL in this parameter, the data fork is used.

permissions

A constant indicating the type of access with which to open the fork. For a description of the types of access you can request, see File Access Permission Constants in File Manager Reference.

refNum

A pointer to a variable allocated by the caller. On return, the reference number for accessing the open fork.

Return Value

A result code. See “Resource Manager Result Codes.”

Discussion

This function allows any named fork of a file to be used for storing resources. Passing in a null fork name will result in the data fork being used. You should use a file’s data fork to store resource data.

Availability
Declared In
Resources.h

FSResourceFileAlreadyOpen

Checks whether a resource file is open.

Boolean FSResourceFileAlreadyOpen (
   const FSRef *resourceFileRef,
   Boolean *inChain,
   ResFileRefNum *refNum
);

Parameters
resourceFileRef

The resource file to check.

inChain

A pointer to a variable allocated by the caller. On return, true if the resource file is in the resource chain, false otherwise.

refNum

A pointer to a variable allocated by the caller. On return, the reference number of the file if it is open.

Return Value

This function returns true if the resource file is already open and known by the Resource Manager—for example, it is either in the current resource chain or it is a detached resource file.

Availability
Declared In
Resources.h

Get1IndResource

Returns a handle to a resource of a given type in the current resource file.

Handle Get1IndResource (
   ResType theType,
   ResourceIndex index
);

Parameters
theType

A resource type.

index

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

Return Value

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. If you provide an index that is either 0 or negative, the function returns NULL, and the ResError function returns the result code resNotFound. If the given index is larger than the value returned by Count1Resources, Get1IndResource returns NULL, and ResError returns the result code resNotFound. If the resource to be read won’t fit into memory, the function returns NULL, and ResError returns the appropriate result code.

Discussion

The function reads the resource data into memory if it’s not already there, unless you’ve called the SetResLoad function with the load parameter set to FALSE. 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 NULL). 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, the function 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 function.

Availability
Declared In
Resources.h

Get1IndType

Gets a resource types available in the current resource file.

void Get1IndType (
   ResType *theType,
   ResourceIndex index
);

Parameters
theType

On return, the resource type with the specified index in the current resource file.

You can call this function repeatedly over the entire range of the index to get all the resource types available in the current resource file. If the given index isn’t in the range from 1 to the number of resource types as returned by Count1Types, this parameter contains four null characters (ASCII code 0).

index

An integer ranging from 1 to the number of resource types in the current resource file, as returned by the Count1Types function.

Discussion

To check for errors, call the ResError function.

Availability
Declared In
Resources.h

Get1NamedResource

Gets a named resource in the current resource file.

Handle Get1NamedResource (
   ResType theType,
   ConstStr255Param name
);

Parameters
theType

The resource type of the resource about which you wish to retrieve data.

name

A name that uniquely identifies the resource about which you wish to retrieve data.

Return Value

If the function finds an entry for the resource in the current resource file’s resource map and the entry contains a valid handle, the function returns that handle. If the entry contains a handle whose value is NULL, and if you haven’t called the SetResLoad function with the load parameter set to FALSE, Get1NamedResource attempts to read the resource into memory. If it can’t find the resource data, the function returns NULL, and the ResError function returns the result code resNotFound. The Get1NamedResource function also returns NULL 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 this function with a resource type that can’t be found in the resource map of the current resource file, the function returns NULL, but ResError returns the result code noErr. You should always check that the value of the returned handle is not NULL.

Discussion

The function searches the current resource file’s resource map in memory for the specified resource. You can change the search order by calling the UseResFile function before Get1NamedResource.

Availability
Declared In
Resources.h

Get1Resource

Gets resource data for a resource in the current resource file.

Handle Get1Resource (
   ResType theType,
   ResID theID
);

Parameters
theType

The resource type of the resource about which you wish to retrieve data.

theID

An integer that uniquely identifies the resource about which you wish to retrieve data.

Return Value

If the function finds an entry for the resource in the current resource file’s resource map and the entry contains a valid handle, it returns that handle. If the entry contains a handle whose value is NULL, and if you haven’t called the SetResLoad function with the load parameter set to FALSE, Get1Resource attempts to read the resource into memory.

If the function can’t find the resource data, it returns NULL, and ResError returns the result code resNotFound. The Get1Resource function also returns NULL 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 this function with a resource type that can’t be found in the resource map of the current resource file, the function returns NULL, but ResError returns the result code noErr. You should always check that the value of the returned handle is not NULL.

Discussion

The function searches the current resource file’s resource map in memory for the specified resource.

You can change the resource map search order by calling the UseResFile function before Get1Resource.

Availability
Declared In
Resources.h

GetIndResource

Returns a handle to a resource of a given type in resource forks open to your application.

Handle GetIndResource (
   ResType theType,
   ResourceIndex index
);

Parameters
theType

A resource type.

index

An integer ranging from 1 to the number of resources of a given type returned by the CountResources function, which is the number of resources of that type in all resource forks open to your application.

Return Value

A handle to a resource of the given type. If you call this function repeatedly over the entire range of the index, it returns handles to all resources of the given type in all resource forks open to your application. The function returns handles for all resources in the most recently opened resource fork first, and then for those in resource forks opened earlier in reverse chronological order. If you provide an index to that is either 0 or negative, the function returns NULL, and the ResError function returns the result code resNotFound. If the given index is larger than the value returned by CountResources, the function returns NULL, and ResError returns the result code resNotFound. If the resource to be read won’t fit into memory, the function returns NULL, and ResError returns the appropriate result code.

Discussion

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

If you’ve called SetResLoad with the load parameter set to FALSE and the data isn’t already in memory, the function returns an empty handle (a handle whose master pointer is set to NULL). 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 GetIndResource function, the function 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 function.

The UseResFile function affects which file the Resource Manager searches first when looking for a particular resource; this is not the case when you use GetIndResource to get an indexed resource.

If you want to find out how many resources of a given type are in a particular resource fork, set the current resource file to that resource fork, then call the Count1Resources function and use the Get1IndResource function to get handles to the resources of that type.

Availability
Declared In
Resources.h

GetIndType

Gets a resource type available in resource forks open to your application.

void GetIndType (
   ResType *theType,
   ResourceIndex index
);

Parameters
theType

On return, a pointer to the resource type for the specified index among all the resource forks open to your application.

You can call this function repeatedly over the entire range of the index to get all the resource types available in all resource forks open to your application. If the given index isn’t in the range from 1 to the number of resource types as returned by CountTypes, this parameter contains four null characters (ASCII code 0).

index

An integer ranging from 1 to the number of resource types in all resource forks open to your application, as returned by CountTypes function.

Discussion

To check for errors, call the ResError function.

Availability
Declared In
Resources.h

GetMaxResourceSize

Returns the approximate size of a resource. 

long GetMaxResourceSize (
   Handle theResource
);

Parameters
theResource

A handle to the resource whose size you wish to retrieve.

Return Value

The approximate size, in bytes, of the resource. Unlike the GetResourceSizeOnDisk function, this function does not check the resource on disk instead, it either checks the resource size in memory or, if the resource is not in memory, calculates its size on the basis of information in the resource map in memory. This gives you an approximate size for the resource that you can count on as the resource’s maximum size. It’s possible that the resource is actually smaller than the offsets in the resource map indicate because the file has not yet been compacted. If you want the exact size of a resource on disk, either call GetResourceSizeOnDisk or call the UpdateResFile function before calling GetMaxResourceSize. If the handle isn’t a handle to a valid resource, the function returns –1, and the ResError function returns the result code resNotFound.

Availability
Declared In
Resources.h

GetNamedResource

Gets a named resource.

Handle GetNamedResource (
   ResType theType,
   ConstStr255Param name
);

Parameters
theType

The resource type of the resource about which you wish to retrieve data.

name

A name that uniquely identifies the resource about which you wish to retrieve data. Strings passed in this parameter are case-sensitive.

Return Value

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

If the function can’t find the resource data, it returns NULL, and the ResError function returns the result code resNotFound. The function also returns NULL 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 GetNamedResource with a resource type that can’t be found in any of the resource maps of the open resource forks, the function returns NULL as well, but ResError returns the result code noErr. You should always check that the value of the returned handle is not NULL.

Discussion

The function searches the resource maps in memory for the specified resource. The resource maps in memory, which represent all the open resource forks, are arranged as a linked list. When the function searches this list, it starts with the current resource file and progresses through the list in order (that is, in reverse chronological order in which the resource forks were opened) until it finds the resource’s entry in one of the resource maps.

You can change the resource map search order by calling the UseResFile function before GetNamedResource.

Availability
Declared In
Resources.h

GetNextFOND

Gets the next FOND handle.

Handle GetNextFOND (
   Handle fondHandle
);

Availability
Declared In
Resources.h

GetNextResourceFile

Retrieves the next resource file in the resource chain.

OSErr GetNextResourceFile (
   ResFileRefNum curRefNum,
   ResFileRefNum *nextRefNum
);

Parameters
curRefNum

A value of type SInt16 representing the current reference number of a resource file.

nextRefNum

A pointer to a value of type SInt16. On return, this points to the next resource file in the resource chain.

Return Value

A result code. See “Resource Manager Result Codes.”

Discussion

GetNextResourceFile can be used to iterate over resource files in the resource chain. By passing a valid reference number in the curRefNum parameter, the function returns the reference number of the next file in the resource chain. If the resource file specified by the curRefNum parameter is not found in the resource chain, the GetNextResourceFile function returns the error code resFNotFound. When the end of the chain is reached GetNextResourceFile returns noErr and the value of the nextRefNum parameter is NIL.

Availability
Declared In
Resources.h

GetResAttrs

Gets a resource’s attributes.

ResAttributes GetResAttrs (
   Handle theResource
);

Parameters
theResource

A handle to the resource whose attributes you wish to retrieve. If the value of this parameter isn’t a handle to a valid resource, the function does nothing, and the ResError function returns the result code resNotFound.

Return Value

The resource’s attributes as recorded in its entry in the resource map in memory. The function returns the resource’s attributes in the low-order byte of the function result. Each attribute is identified by a specific bit in the low-order byte. If the bit corresponding to an attribute contains 1, then that attribute is set if the bit contains 0, then that attribute is not set.

Discussion

To change a resource’s attributes in the resource map in memory, use the SetResAttrs function.

Availability
Declared In
Resources.h

GetResFileAttrs

Gets the attributes of a resource fork.

ResFileAttributes GetResFileAttrs (
   ResFileRefNum refNum
);

Parameters
refNum

A file reference number for the resource fork whose attributes you want to get. Specify 0 in this parameter to get the attributes of the System file’s resource fork.

Return Value

The attributes of the file’s resource fork. If there’s no open resource fork for the given file reference number, the function does nothing, and the ResError function returns the result code resFNotFound. Like individual resources, resource forks have attributes that are specified by bits in the low-order byte of a word.

Discussion

The Resource Manager sets the mapChanged attribute for the resource fork when you call the ChangedResource, the AddResource, or the RemoveResource function.

Availability
Declared In
Resources.h

GetResInfo

Gets a resource’s resource ID, resource type, and resource name.

void GetResInfo (
   Handle theResource,
   ResID *theID,
   ResType *theType,
   Str255 name
);

Parameters
theResource

A handle to the resource for which you want to retrieve information. If the handle isn’t a valid handle to a resource, the function does nothing to determine whether this has occurred, call the ResError function.

theID

On return, a pointer to the resource ID of the specified resource.

theType

On return, a pointer to the resource type of the specified resource.

name

On return, the name of the specified resource.

Discussion

To set a resource’s ID, resource type, or resource name, use the SetResInfo function.

Availability
Declared In
Resources.h

GetResource

Gets resource data for a resource specified by resource type and resource ID.

Handle GetResource (
   ResType theType,
   ResID theID
);

Parameters
theType

The resource type of the resource about which you wish to retrieve data.

theID

An integer that uniquely identifies the resource about which you wish to retrieve data.

Return Value

If the 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 NULL, and if you haven’t called the SetResLoad function with the load parameter set to FALSE, GetResource attempts to read the resource into memory.

If the function can’t find the resource data, it returns NULL, and the ResError function returns the result code resNotFound. The GetResource function also returns NULL 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 NULL, but ResError returns the result code noErr. You should always check that the value of the returned handle is not NULL.

Discussion

The function searches the resource maps in memory for the specified resource. The resource maps in memory, which represent all the open resource forks, are arranged as a linked list. When searching this list, the function 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.

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.

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

Availability
Declared In
Resources.h

GetResourceSizeOnDisk

Returns the exact size of a resource. 

long GetResourceSizeOnDisk (
   Handle theResource
);

Parameters
theResource

A handle to the resource whose size you wish to retrieve.

Return Value

The exact size, in bytes, of the resource. If the handle isn’t a handle to a valid resource, the function returns –1, and the ResError function returns the result code resNotFound.

Discussion

This function checks the resource on disk, not in memory. You can call this function before reading a resource into memory to make sure there’s enough memory available to do so successfully.

The GetResourceSizeOnDisk function is also available as the SizeResource function.

Availability
Declared In
Resources.h

GetTopResourceFile

Retrieves the topmost resource file in the current resource chain.

OSErr GetTopResourceFile (
   ResFileRefNum *refNum
);

Parameters
refNum

A pointer to a value of type SInt16. On return, this points to the top most resource file in the current resource chain.

Return Value

A result code. See “Resource Manager Result Codes.” If the resource chain is empty, resFNotFound is returned.

Availability
Declared In
Resources.h

HomeResFile

Gets the file reference number associated with a particular resource.

ResFileRefNum HomeResFile (
   Handle theResource
);

Parameters
theResource

A handle to the resource for which you wish to get the associated file reference number.

Return Value

The file reference number for the resource fork containing the specified resource. If the given handle isn’t a handle to a resource, the function returns –1, and the ResError function returns the result code resNotFound. If HomeResFile returns 0, the resource is in the System file’s resource fork. If it returns 1, the resource is ROM-resident.

Availability
Declared In
Resources.h

InsertResourceFile

Inserts a resource file into the current resource chain at the specified location.

OSErr InsertResourceFile (
   ResFileRefNum refNum,
   RsrcChainLocation where
);

Parameters
refNum

A value of type SInt16 indicating the reference number of the resource file to insert into the resource chain.

where

A value of type RsrcChainLocation indicating where in the resource chain the resource file should be inserted. See the RsrcChainLocation data type.

Return Value

A result code. See “Resource Manager Result Codes.”

Discussion

If the file is already in the resource chain, it is removed and reinserted at the specified location. If the file has been detached, it is added to the resource chain at the specified location Returns resFNotFound if it's not currently open.

Availability
Declared In
Resources.h

InvokeResErrUPP

Calls your callback function.

void InvokeResErrUPP (
   OSErr thErr,
   ResErrUPP userUPP
);

Availability
Declared In
Resources.h

LoadResource

Gets resource data after you’ve called the SetResLoad function with the load parameter set to FALSE or when the resource is purgeable.

void LoadResource (
   Handle theResource
);

Parameters
theResource

A handle to a resource. Given this handle, the function reads the resource data into memory. If the resource is already in memory, or if the this parameter doesn’t contain a handle to a resource, then the function does nothing. To determine whether either of these situations occurred, call the ResError function. If the resource is already in memory, ResError returns noErr; if the handle is not a handle to a resource, ResError returns resNotFound.

Discussion

If you’ve changed the resource data for a purgeable resource and the resource is purged before being written to the file, the changes will be lost. In this case, this function rereads the original resource from the file’s resource fork. You should use the ChangedResource or SetResPurge function before calling LoadResource to ensure that changes made to purgeable resources are written to the resource fork.

Availability
Declared In
Resources.h

NewResErrUPP

Creates a new universal procedure pointer (UPP) to your callback function.

ResErrUPP NewResErrUPP (
   ResErrProcPtr userRoutine
);

Return Value

See ResErrUPP for more information.

Availability
Declared In
Resources.h

ReadPartialResource

Reads part of a resource into memory and work with a small subsection of a large resource.

void ReadPartialResource (
   Handle theResource,
   long offset,
   void *buffer,
   long count
);

Parameters
theResource

A handle to the resource you wish to read.

offset

The beginning of the resource subsection to be read, measured in bytes from the beginning of the resource.

buffer

A pointer to the buffer into which the partial resource is to be read. Your application is responsible for the buffer’s memory management. You cannot use the ReleaseResource function to release the memory the buffer occupies.

count

The length of the resource subsection.

Discussion

This function always tries to read resources from disk. If a resource is already in memory, the Resource Manager still reads it from disk, and the ResError function returns the result code resourceInMemory. If you try to read past the end of a resource or the value of the offset parameter is out of bounds, ResError returns the result code inputOutOfBounds. If the handle in the parameter theResource doesn’t refer to a resource in an open resource fork, ResError returns the result code resNotFound.

You may experience problems if you have a copy of a resource in memory when you are using the partial resource functions. If you have modified the copy in memory and then access the resource on disk using this function, the function reads the data on disk, not the data in memory, which is referenced through the resource’s handle.

When using partial resource functions, you should call the SetResLoad function, specifying FALSE for the load parameter, before you call GetResource. Using the SetResLoad function prevents the Resource Manager from reading the entire resource into memory. Be sure to restore the normal state by calling SetResLoad again, with the load parameter set to TRUE, immediately after you call the GetResource function. Then use ReadPartialResource to read a portion of the resource into a buffer.

If the entire resource is in memory and you want only part of its data, it’s faster to use the Memory Manager function BlockMove instead of the ReadPartialResource function. If you read a partial resource into memory and then change its size, you can use the SetResourceSize function to change the entire resource’s size on disk as necessary

Availability
Declared In
Resources.h

ReleaseResource

Releases the memory a resource occupies when you have finished using it.

void ReleaseResource (
   Handle theResource
);

Parameters
theResource

A handle to the resource which you wish to release. The function sets the master pointer of the resource’s handle in the resource map in memory to NULL. If your application previously obtained a handle to that resource, the handle is no longer valid. If your application subsequently calls the Resource Manager to get the released resource, the Resource Manager assigns a new handle.

If the given resource isn’t a handle to a resource, the function does nothing, and the ResError function returns the result code resNotFound. Be aware that ReleaseResource won’t release a resource whose resChanged attribute has been set, but ResError still returns the result code noErr.

Special Considerations

Do not use this function to release a System resource that might be shared by several applications.

Availability
Declared In
Resources.h

RemoveResource

Removes a resource’s entry from the current resource file’s resource map in memory. 

void RemoveResource (
   Handle theResource
);

Parameters
theResource

A handle to the resource which you wish to detac