Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 1 - Resource Manager / Resource Manager Reference

Resource Manager Routines / Modifying Resources

AddResource

You can use the AddResource procedure to add a resource to the current resource file.

PROCEDURE AddResource (theData: Handle; theType: ResType; 
                       theID: Integer; name: Str255);

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).

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.

DESCRIPTION

Given a handle to any type of data in memory (but not a handle to an existing resource), AddResource adds the given handle, resource type, resource ID, and resource name to the current resource file's resource map in memory. The AddResource procedure 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.

WARNING

The AddResource procedure 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 AddResource.

If the resChanged attribute of a resource has been set and your application calls UpdateResFile 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 WriteResource, 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.

If the value of the parameter theData is an empty handle (that is, a handle whose master pointer is set to NIL), the Resource Manager writes zero-length resource data to disk when it updates the resource. If the value of theData is either NIL or a handle to an existing resource, AddResource does nothing, and the ResError function returns the result code addResFailed. If the resource map becomes too large to fit in memory, AddResource 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).

When your application calls AddResource, 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 routine 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 procedure, 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.

RESULT CODES

noErr	0	No error
addResFailed	-194	AddResource procedure failed

SEE ALSO

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

For examples of the use of the AddResource procedure, see Listing 1-4 on page 1-18 and Listing 1-11 on page 1-32.

For descriptions of the UpdateResFile and WriteResource procedures, see page 1-87 and page 1-88, respectively. For descriptions of the UniqueID and Unique1ID functions, see page 1-91. For a description of the DetachResource procedure, see page 1-102.

For information about using the Memory Manager procedure HandToHand, see Inside Macintosh: Memory.