Resource Manager Reference (Not Recommended)

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

Callbacks

ResErrProcPtr

typedef void (*ResErrProcPtr) (
   OSErr thErr
);

If you name your function MyResErrProc, you would declare it like this:

void MyResErrProc (
   OSErr thErr
);

Availability
  • Available in OS X v10.0 and later.
Declared In
Resources.h

ResourceEndianFilterPtr

typedef OSErr (*ResourceEndianFilterPtr) (
   Handle theResource,
   Boolean currentlyNativeEndian
);

If you name your function MyResourceEndianFilter, you would declare it like this:

OSErr MyResourceEndianFilter (
   Handle theResource,
   Boolean currentlyNativeEndian
);

Availability
  • Available in OS X v10.0 and later.
Declared In
Resources.h

Data Types

ResAttributes

typedef short ResAttributes;
Availability
  • Available in OS X v10.0 and later.
Declared In
Resources.h

ResErrUPP

typedef ResErrProcPtr ResErrUPP;
Discussion

For more information, see the description of the ResErrProcPtr callback function.

Availability
  • Available in OS X v10.0 and later.
Declared In
Resources.h

ResFileAttributes

typedef short ResFileAttributes;
Availability
  • Available in OS X v10.0 and later.
Declared In
Resources.h

ResFileRefNum

typedef short ResFileRefNum;
Availability
  • Available in OS X v10.0 and later.
Declared In
Resources.h

ResID

Defines a unique identifier for a resource of a given type.

typedef short ResID;
Discussion

A resource is identified by its resource type and resource ID (or, optionally, its resource type and resource name). The IDs for resources used by the system software and those used by applications are assigned from separate ranges. By using these ranges correctly, you can avoid resource ID conflicts.

In general, system resources use IDs in the range –32767 through 127, and application resources must use IDs that fall between 128 and 32767. The IDs for some categories of resources, such as definition functions and font families, fall in different ranges or in ranges that are broken down for more specific purposes.

You can use a resource name instead of a resource ID to identify a resource of a given type. Like a resource ID, a resource name should be unique within each type. If you assign the same resource name to two resources of the same type, the second assignment of the name overrides the first, thereby making the first resource inaccessible by name. When comparing resource names, the Resource Manager ignores case (but does not ignore diacritical marks).

Availability
  • Available in OS X v10.0 and later.
Declared In
Resources.h

ResType

Defines a unique identifier for a type of resource.

typedef FourCharCode ResType;
Discussion

The Resource Manager uses the resource type along with the resource ID to identify a resource. A resource type can be any sequence of four alphanumeric characters, including the space character.

You can define your own resource types, but they must not conflict with any of the standard resource types. When identifying resource types, the Resource Manager distinguishes between uppercase letters and their lowercase counterparts. Apple reserves for its own use all resource types that consist of all lowercase letters, all spaces, or all international characters (characters greater than $7F).

Availability
  • Available in OS X v10.0 and later.
Declared In
IOMacOSTypes.h

Constants

Reference Number Constants

enum {
   kResFileNotOpened = -1,
   kSystemResFile = 0
};
Constants
kResFileNotOpened

Indicates the reference number returned as error when opening a resource file.

Available in OS X v10.0 and later.

Declared in Resources.h.

kSystemResFile

Indicates the default reference number to the system file.

Available in OS X v10.0 and later.

Declared in Resources.h.

Resource Attribute Bits

enum {
   resSysRefBit = 7,
   resSysHeapBit = 6,
   resPurgeableBit = 5,
   resLockedBit = 4,
   resProtectedBit = 3,
   resPreloadBit = 2,
   resChangedBit = 1,
};
Constants
resSysRefBit

If this attribute is set to 1, it is a system reference. If it is set to 0, it is a local reference.

Available in OS X v10.0 and later.

Declared in Resources.h.

resSysHeapBit

This attribute indicates whether the resource is read into the system heap (resSysHeapBit attribute is set to 1) or your application’s heap (resSysHeapBit attribute is set to 0).

If you are setting your resource’s attributes with SetResAttrs, you should set this bit to 0 for your application’s resources. Note that if you do set the resSysHeapBit attribute to 1 and the resource is too large for the system heap, the bit is cleared and the resource is read into the application heap.

Available in OS X v10.0 and later.

Declared in Resources.h.

resPurgeableBit

If this attribute is set to 1, the resource is purgeable if it’s 0, the resource is nonpurgeable. However, do not use SetResAttrs to make a purgeable resource nonpurgeable.

Because a locked resource is nonrelocatable and nonpurgeable, the resLockedBit attribute overrides the resPurgeableBit attribute.

Available in OS X v10.0 and later.

Declared in Resources.h.

resLockedBit

If this attribute is 1, the resource is nonpurgeable regardless of whether resPurgeableBit is set. If it’s 0, the resource is purgeable or nonpurgeable depending on the value of the resPurgeableBit attribute.

Available in OS X v10.0 and later.

Declared in Resources.h.

resProtectedBit

If this attribute is set to 1, your application can’t use Resource Manager functions to change the resource ID or resource name, modify the resource contents, or remove the resource from its resource fork. However, you can use the SetResAttrs function to remove this protection. Note that this attribute change takes effect immediately.

Available in OS X v10.0 and later.

Declared in Resources.h.

resPreloadBit

If this attribute is set to 1, the Resource Manager reads the resource’s resource data into memory immediately after opening its resource fork. You can use this setting to make multiple resources available for your application as soon as possible, rather than reading each one into memory individually. If both the resPreloadBit attribute and the resLockedBit attribute are set, the Resource Manager loads the resource as low in the heap as possible.

Available in OS X v10.0 and later.

Declared in Resources.h.

resChangedBit

If this attribute is set to 1, the resource has been changed. If it’s 0, the resource hasn’t been changed. This attribute is used only while the resource map is in memory. The resChangedBit attribute must be 0 in the resource fork on disk.

Do not use SetResAttrs to set the resChangedBit attribute. Be sure the attrs parameter passed to SetResAttrs doesn’t change the current setting of this attribute. To set the resChangedBit attribute, call the ChangedResource function.

Available in OS X v10.0 and later.

Declared in Resources.h.

Discussion

The SetResAttrs and GetResAttrs functions use these constants to refer to each attribute.

Resource Attribute Masks

enum {
   resSysHeap = 64,
   resPurgeable = 32,
   resLocked = 16,
   resProtected = 8,
   resPreload = 4,
   resChanged = 2,
};
Constants
resSysHeap

Use to set or test for the resSysHeapBit.

Available in OS X v10.0 and later.

Declared in Resources.h.

resPurgeable

Use to set or test for the resPurgeableBit.

Available in OS X v10.0 and later.

Declared in Resources.h.

resLocked

Use to set or test for the resLockedBit.

Available in OS X v10.0 and later.

Declared in Resources.h.

resProtected

Use to set or test for the resProtectedBit.

Available in OS X v10.0 and later.

Declared in Resources.h.

resPreload

Use to set or test for the resPreloadBit.

Available in OS X v10.0 and later.

Declared in Resources.h.

resChanged

Use to set or test for the resChangedBit.

Available in OS X v10.0 and later.

Declared in Resources.h.

Resource Chain Location

Specify the location of the resource chain.

typedef SInt16 RsrcChainLocation
enum {
   kRsrcChainBelowSystemMap = 0,
   kRsrcChainBelowApplicationMap = 1,
   kRsrcChainAboveApplicationMap = 2,
   kRsrcChainAboveAllMaps = 4
};
Constants
kRsrcChainBelowSystemMap

Indicates the resource chain is below the system's resource map.

Available in OS X v10.0 and later.

Declared in Resources.h.

kRsrcChainBelowApplicationMap

Indicates the resource chain is below the application's resource map.

Available in OS X v10.0 and later.

Declared in Resources.h.

kRsrcChainAboveApplicationMap

Indicates the resource chain is above the application's resource map.

Available in OS X v10.0 and later.

Declared in Resources.h.

kRsrcChainAboveAllMaps

Indicates the resource chain is above all resource maps.

Available in OS X v10.0 and later.

Declared in Resources.h.

Discussion

These constants and data type are for use with the Resource Manager chain manipulation routines under Carbon.

Resource Fork Attribute Bits

enum {
   mapReadOnlyBit = 7,
   mapCompactBit = 6,
   mapChangedBit = 5
};
Constants
mapReadOnlyBit

If this bit is set to 1, the Resource Manager doesn’t write anything to the resource fork on disk. It also doesn’t check whether the resource data can be written to disk when the resource map is modified. When this attribute is set to 1, the ChangedResource and WriteResource functions do nothing, but the function ResError returns the result code noErr.

If you set the mapReadOnlyBit attribute but later clear it, the resource data is written to disk even if there’s no room for it. This operation may destroy the resource fork.

Available in OS X v10.0 and later.

Declared in Resources.h.

mapCompactBit

If this bit is set to 1, the Resource Manager compacts the resource fork when it updates the file. The Resource Manager sets this attribute when a resource is removed or when a resource is made larger and thus must be written at the end of a resource fork. You may want to set the mapCompactBit attribute to force the Resource Manager to compact a resource fork when your changes have made resources smaller.

Available in OS X v10.0 and later.

Declared in Resources.h.

mapChangedBit

If this bit is set to 1, the Resource Manager writes the resource map to disk when the file is updated. For example, you can set mapChangedBit if you’ve changed resource attributes only and don’t want to call the ChangedResource function because you don’t want to write the resource data to disk.

Available in OS X v10.0 and later.

Declared in Resources.h.

Resource Fork Attribute Masks

enum{
   mapReadOnly = 128,
   mapCompact = 64,
   mapChanged = 32
};
Constants
mapReadOnly

Use to set or test for the mapReadOnlyBit.

Available in OS X v10.0 and later.

Declared in Resources.h.

mapCompact

Use to set or test for the mapCompactBit.

Available in OS X v10.0 and later.

Declared in Resources.h.

mapChanged

Use to set or test for the mapChangedBit.

Available in OS X v10.0 and later.

Declared in Resources.h.

Result Codes

The most common result codes returned by Resource Manager are listed in the table below. The Resource Manager may also return the following result codes: noErr (0), dirFulErr (-33), dskFulErr (-34), nsvErr (-35), ioErr (-36), bdNamErr (-37), eofErr (-39), tmfoErr (-42), fnfErr (-43), wPrErr (-44), fLckdErr (-45), vLckdErr (-46), dupFNErr (-48), opWrErr (-49), permErr (-54), extFSErr (-58), memFullErr (-108), dirNFErr (-120).

Result CodeValueDescription
badExtResource -185

The extended resource has a bad format.

Available in OS X v10.0 and later.

CantDecompress -186

Can’t decompress a compressed resource.

Available in OS X v10.0 and later.

resourceInMemory -188

The resource is already in memory.

Available in OS X v10.0 and later.

writingPastEnd -189

Writing past the end of file.

Available in OS X v10.0 and later.

inputOutOfBounds -190

The offset or count is out of bounds.

Available in OS X v10.0 and later.

resNotFound -192

The resource was not found.

Available in OS X v10.0 and later.

resFNotFound -193

The resource file was not found.

Available in OS X v10.0 and later.

addResFailed -194

The AddResource function failed.

Available in OS X v10.0 and later.

rmvResFailed -196

The RemoveResource function failed.

Available in OS X v10.0 and later.

resAttrErr -198

The attribute is inconsistent with the operation.

Available in OS X v10.0 and later.

mapReadErr -199

The map is inconsistent with the operation.

Available in OS X v10.0 and later.