Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 1 - Resource Manager / Resource Manager Reference

Resource Manager Routines / Getting and Setting Resource Information

SetResInfo

You can use the SetResInfo procedure to change the name and resource ID of a resource.

PROCEDURE SetResInfo (theResource: Handle; theID: Integer; 
                      name: Str255);

theResource

A handle to a resource.

theID

The new resource ID.

name

The new name or an empty string to preserve the resource name.

DESCRIPTION

Given a handle to a resource, SetResInfo changes the resource ID and the resource name of the specified resource to the values given in theID and name. If you pass an empty string for the name parameter, the resource name is not changed. The SetResInfo procedure changes the information in the resource map in memory, not in the resource file itself.

WARNING

Do not change a system resource's resource ID or name. Other applications may already access the resource and may not work properly if you change the resource ID, resource name, or both.

If the parameter theResource doesn't contain a handle to an existing resource, SetResInfo does nothing, and ResError returns the result code resNotFound. If
the resource map becomes too large to fit in memory (for example, after an unnamed resource is given a name), SetResInfo does nothing, and ResError returns an appropriate Memory Manager 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). If the resProtected attribute is set for the resource, SetResInfo does nothing, and ResError returns the result code resAttrErr.

If you want to write changes to the resource map on disk after updating the resource map in memory, call the ChangedResource procedure for the same resource after you call SetResInfo.

IMPORTANT

Even if you don't call ChangedResource after using SetResInfo to change the name and resource ID of a resource, the change may be written to disk when the Resource Manager updates the resource fork. If you call ChangedResource for any resource in the same resource fork, or if you add or remove a resource, the Resource Manager writes the entire resource map to disk after a call to UpdateResFile or when your application terminates. In these cases, all changes to resource information in the resource map become permanent. If you want any of the changes to be temporary, you should restore the original information before the resource is updated.

SPECIAL CONSIDERATIONS

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

RESULT CODES

noErr	0	No error
resNotFound	-192	Resource not found
resAttrErr	-198	Attribute does not permit operation

SEE ALSO

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

For a description of the ChangedResource and UpdateResFile procedures, see page 1-83 and page 1-87, respectively.