Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: More Macintosh Toolbox /: Chapter 1 - Resource Manager

Summary of the Resource Manager

Pascal Summary

Constants

CONST
   gestaltResourceMgrAttr           = 'rsrc';   {Gestalt selector ResMgr}
   gestaltPartialRsrcs              = 0;        {check this bit in the }
                                                { response parameter}
   {resource attributes}
   resSysHeap                       = 64;       {set if read into system }
                                                { heap}
   resPurgeable                     = 32;       {set if purgeable}
   resLocked                        = 16;       {set if locked}
   resProtected                     = 8;        {set if protected}
   resPreload                       = 4;        {set if to be preloaded}
   resChanged                       = 2;        {set if to be written to }
                                                { resource fork}
   {resource file attributes}
   mapReadOnly                      = 128;      {set to make file read-only}
   mapCompact                       = 64;       {set to compact file on }
                                                { update}
   mapChanged                       = 32;       {set to write map on update}

   {values for setting the RomMapInsert and TmpResLoad global variables}
   mapTrue                          = $FFFF;    {insert ROM map w/ }
                                                { TmpResLoad = TRUE}
   mapFalse                         = $FF00;    {insert ROM map w/ }
                                                { TmpResLoad = FALSE}

   {system icon definition IDs}
   genericDocumentIconResource      = -4000;    {default document icon}
   genericFolderIconResource        = -3999;    {default folder icon}
   floppyIconResource               = -3998;    {default disk icon}
   openFolderIconResource           = -3997;    {open folder icon}
   genericApplicationIconResource   = -3996;    {default application }
                                                { icon}
   genericHardDiskIconResource      = -3995;    {hard disk icon}
   privateFolderIconResource        = -3994;    {folder without privileges }
                                                { for this user icon}
   trashIconResource                = -3993;    {default empty Trash icon}
   desktopIconResource              = -3992;    {desktop icon}
   genericDeskAccessoryIconResource = -3991;    {default desk accessory icon}
   genericEditionFileIconResource   = -3989;    {default edition icon}
   genericStationeryIconResource    = -3985;    {default stationery icon}
   systemFolderIconResource         = -3983;    {System Folder icon}
   appleMenuFolderIconResource      = -3982;    {Apple Menu Items }
                                                { folder icon}
   genericFileServerIconResource    = -3972;    {file server icon}
   genericPreferencesIconResource   = -3971;    {default preferences }
                                                { file icon}
   genericSuitcaseIconResource      = -3970;    {default suitcase icon}
   genericMoverObjectIconResource   = -3969;    {System file object icon}
   genericQueryDocumentIconResource = -16506;   {default query }
                                                { document icon}
   genericExtensionIconResource     = -16415;   {default extensions icon}

   fullTrashIconResource            = -3984;    {default full Trash icon}
   startupFolderIconResource        = -3981;    {Startup Items folder icon}
   ownedFolderIconResource          = -3980;    {owned folder icon}
   dropFolderIconResource           = -3979;    {drop folder icon}
   sharedFolderIconResource         = -3978;    {shared folder icon}
   mountedFolderIconResource        = -3977;    {mounted folder icon}
   controlPanelFolderIconResource   = -3976;    {Control Panels folder icon}
   printMonitorFolderIconResource   = -3975;    {PrintMonitor }
                                                { Documents folder icon}
   preferencesFolderIconResource    = -3974;    {Preferences folder icon}
   extensionsFolderIconResource     = -3973;    {Extensions folder icon}
   fontsFolderIconResource          = -3968;    {Fonts folder icon}

Data Type

TYPE ResType = PACKED ARRAY[1..4] OF Char;

Routines

Initializing the Resource Manager

FUNCTION InitResources: Integer;
PROCEDURE RsrcZoneInit;

Checking for Errors

FUNCTION ResError: Integer;

Creating an Empty Resource Fork

PROCEDURE FSpCreateResFile   (spec: FSSpec; creator: OSType;
                              fileType: OSType; scriptTag: ScriptCode);
PROCEDURE HCreateResFile     (vRefNum: Integer; dirID: LongInt; 
                              fileName: Str255);
PROCEDURE CreateResFile      (fileName: Str255);

Opening Resource Forks

FUNCTION FSpOpenResFile      (spec: FSSpec; permission: SignedByte): Integer;
FUNCTION HOpenResFile        (vRefNum: Integer; dirID: LongInt; 
                              fileName: Str255; 
                              permission: SignedByte): Integer;
FUNCTION OpenRFPerm          (fileName: Str255; vRefNum: Integer; 
                              permission: SignedByte): Integer;
FUNCTION OpenResFile         (fileName: Str255): Integer;

Getting and Setting the Current Resource File

FUNCTION CurResFile: Integer;
PROCEDURE UseResFile (refNum: Integer);
FUNCTION HomeResFile (theResource: Handle): Integer;

Reading Resources Into Memory

FUNCTION GetResource         (theType: ResType; theID: Integer): Handle;
FUNCTION Get1Resource        (theType: ResType; theID: Integer): Handle;
FUNCTION GetNamedResource    (theType: ResType; name: Str255): Handle;
FUNCTION Get1NamedResource   (theType: ResType; name: Str255): Handle;
FUNCTION RGetResource        (theType: ResType; theID: Integer): Handle;
PROCEDURE SetResLoad         (load: Boolean);
PROCEDURE LoadResource       (theResource: Handle);

Getting and Setting Resource Information

PROCEDURE GetResInfo   (theResource: Handle; VAR theID: Integer; 
                        VAR theType: ResType; VAR name: Str255);
PROCEDURE SetResInfo   (theResource: Handle; theID: Integer; 
                        name: Str255);
FUNCTION GetResAttrs   (theResource: Handle): Integer;
PROCEDURE SetResAttrs  (theResource: Handle; attrs: Integer);

Modifying Resources

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

Writing to Resource Forks

PROCEDURE UpdateResFile (refNum: Integer);
PROCEDURE WriteResource (theResource: Handle);
PROCEDURE SetResPurge   (install: Boolean);

Getting a Unique Resource ID

FUNCTION UniqueID  (theType: ResType): Integer;
FUNCTION Unique1ID (theType: ResType): Integer;

Counting and Listing Resource Types

FUNCTION CountResources     (theType: ResType): Integer;
FUNCTION Count1Resources    (theType: ResType): Integer;
FUNCTION GetIndResource     (theType: ResType; index: Integer): Handle;
FUNCTION Get1IndResource    (theType: ResType; index: Integer): Handle;
FUNCTION CountTypes:        Integer;
FUNCTION Count1Types:       Integer;
PROCEDURE GetIndType        (VAR theType: ResType; index: Integer);
PROCEDURE Get1IndType       (VAR theType: ResType; index: Integer);

Getting Resource Sizes

{these routines also available as SizeResource and MaxSizeRsrc, respectively}
FUNCTION GetResourceSizeOnDisk 
                     (theResource: Handle): LongInt;
FUNCTION GetMaxResourceSize 
                     (theResource: Handle): LongInt;

Disposing of Resources

PROCEDURE ReleaseResource   (theResource: Handle);
PROCEDURE DetachResource    (theResource: Handle);
{The RemoveResource procedure is also available as RmveResource}
PROCEDURE RemoveResource    (theResource: Handle);

Closing Resource Forks

PROCEDURE CloseResFile (refNum: Integer);

Reading and Writing Partial Resources

PROCEDURE ReadPartialResource
                           (theResource: Handle; 
                            offset: LongInt; buffer: UNIV Ptr;
                            count: LongInt);
PROCEDURE WritePartialResource
                           (theResource: Handle; 
                            offset: LongInt; buffer: UNIV Ptr;
                            count: LongInt);
PROCEDURE SetResourceSize  (theResource: Handle; newSize: LongInt);

Getting and Setting Resource Fork Attributes

FUNCTION GetResFileAttrs   (refNum: Integer): Integer;
PROCEDURE SetResFileAttrs  (refNum: Integer; attrs: Integer);

Accessing Resource Entries in a Resource Map

FUNCTION RsrcMapEntry (theResource: Handle): LongInt;

C Summary

Constants

enum {
#define gestaltResourceMgrAttr       'rsrc'  /*Gestalt selector ResMgr*/
#define gestaltPartialRsrcs         = 0      /*check this bit in the */
                                             /* response parameter*/
};
enum {
   /*resource attributes*/
   resSysHeap                       = 64,    /*set if read into system heap*/
   resPurgeable                     = 32,    /*set if purgeable*/
   resLocked                        = 16,    /*set if locked*/
   resProtected                     = 8,     /*set if protected*/
   resPreload                       = 4,     /*set if to be preloaded*/
   resChanged                       = 2,     /*set if to be written */
                                             /* to resource fork*/
   /*resource fork attributes*/
   mapReadOnly                      = 128,   /*set to make file */
                                             /* read-only*/
   mapCompact                       = 64,    /*set to compact file */
                                             /* on update*/
   mapChanged                       = 32,    /*set to write map */
                                             /* on update*/
   /*values for setting the RomMapInsert and TmpResLoad global variables*/
   mapTrue                          = 0xFFFF,/*insert ROM map w/ */
                                             /* TmpResLoad = TRUE*/
   mapFalse                         = 0xFF00 /*insert ROM map w/ */
                                             /* TmpResLoad = FALSE*/
};
enum { 
   /*system icon definition IDs*/
   genericDocumentIconResource      = -4000,    /*default document icon*/
   genericStationeryIconResource    = -3985,    /*default stationery icon*/
   genericEditionFileIconResource   = -3989,    /*default edition icon*/
   genericApplicationIconResource   = -3996,    /*default application icon*/
   genericDeskAccessoryIconResource = -3991,    /*default desk accessory */
                                                /* icon*/
   genericFolderIconResource        = -3999,    /*default folder icon*/
   privateFolderIconResource        = -3994,    /*folder without privileges*/
                                                /* for this user icon*/
   floppyIconResource               = -3998,    /*default disk icon*/
   trashIconResource                = -3993,    /*default empty Trash icon*/
   desktopIconResource              = -3992,    /*desktop icon*/
   openFolderIconResource           = -3997,    /*open folder icon*/
   genericHardDiskIconResource      = -3995,    /*hard disk icon*/
   genericFileServerIconResource    = -3972,    /*file server icon*/
   genericSuitcaseIconResource      = -3970,    /*default suitcase icon*/
   genericMoverObjectIconResource   = -3969,    /*System file object icon*/
   genericPreferencesIconResource   = -3971,    /*default preferences */
                                                /* file icon*/
   genericQueryDocumentIconResource = -16506,   /*default query doc icon*/
   genericExtensionIconResource     = -16415,   /*default extension icon*/
   systemFolderIconResource         = -3983,    /*System Folder icon*/
   appleMenuFolderIconResource      = -3982,    /*Apple Menu Items */
                                                /* folder icon*/
};

enum {
   startupFolderIconResource        = -3981,    /*Startup Items folder icon*/
   ownedFolderIconResource          = -3980,    /*owned folder icon*/
   dropFolderIconResource           = -3979,    /*drop folder icon*/
   sharedFolderIconResource         = -3978,    /*shared folder icon*/
   mountedFolderIconResource        = -3977,    /*mounted folder icon*/
   controlPanelFolderIconResource   = -3976,    /*Control Panels folder */
                                                /* icon*/

   printMonitorFolderIconResource   = -3975,    /*PrintMonitor */
                                                /* Documents folder icon*/
   preferencesFolderIconResource    = -3974,    /*Preferences folder icon*/
   extensionsFolderIconResource     = -3973,    /*Extensions folder icon*/
   fontsFolderIconResource          = -3968,    /*Fonts folder icon*/
   fullTrashIconResource            = -3984     /*default full Trash icon*/
};

Data Type

typedef unsigned long ResType;

Routines

Initializing the Resource Manager

pascal short InitResources (void);
pascal void RsrcZoneInit   (void);

Checking for Errors

pascal short ResError  (void);

Creating an Empty Resource Fork

pascal void FSpCreateResFile
                            (const FSSpec *spec, OSType creator, 
                             OSType fileType, ScriptCode scriptTag);
pascal void HCreateResFile  (short vRefNum, long dirID, 
                             ConstStr255Param fileName);
pascal void CreateResFile   (ConstStr255Param fileName);

Opening Resource Forks

pascal short FSpOpenResFile 
                            (const FSSpec *spec, SignedByte permission);
pascal short HOpenResFile   (short vRefNum, long dirID, 
                             ConstStr255Param fileName, 
                             char permission);
pascal short OpenRFPerm     (ConstStr255Param fileName, short vRefNum,
                             char permission);
pascal short OpenResFile    (ConstStr255Param fileName);

Getting and Setting the Current Resource File

pascal short CurResFile  (void);
pascal void UseResFile   (short refNum);
pascal short HomeResFile (Handle theResource);

Reading Resources Into Memory

pascal Handle GetResource    (ResType theType, short theID);
pascal Handle Get1Resource   (ResType theType, short theID);
pascal Handle GetNamedResource
                             (ResType theType, ConstStr255Param name);
pascal Handle Get1NamedResource
                             (ResType theType, ConstStr255Param name);
pascal Handle RGetResource   (ResType theType, short theID);
pascal void SetResLoad       (Boolean load);
pascal void LoadResource     (Handle theResource);

Getting and Setting Resource Information

pascal void GetResInfo       (Handle theResource, short *theID, 
                              ResType *theType, Str255 name);
pascal void SetResInfo       (Handle theResource, short theID, 
                              ConstStr255Param name);
pascal short GetResAttrs     (Handle theResource);
pascal void SetResAttrs      (Handle theResource, short attrs);

Modifying Resources

pascal void ChangedResource 
                             (Handle theResource);
pascal void AddResource      (Handle theData, ResType theType, 
                              short theID, ConstStr255Param name);

Writing to Resource Forks

pascal void UpdateResFile    (short refNum);
pascal void WriteResource    (Handle theResource);
pascal void SetResPurge      (Boolean install);

Getting a Unique Resource ID

pascal short UniqueID        (ResType theType);
pascal short Unique1ID       (ResType theType);

Counting and Listing Resource Types

pascal short CountResources 
                             (ResType theType);
pascal short Count1Resources
                             (ResType theType);
pascal Handle GetIndResource
                             (ResType theType, short index);
pascal Handle Get1IndResource
                             (ResType theType, short index);
pascal short CountTypes      (void);
pascal short Count1Types     (void);
pascal void GetIndType       (ResType *theType, short index);
pascal void Get1IndType      (ResType *theType, short index);

Getting Resource Sizes

/*the GetResourceSizeOnDisk routine is also available as SizeResource*/
pascal long GetResourceSizeOnDisk 
                             (Handle theResource);
/*the GetMaxResourceSize routine is also available as MaxSizeRsrc*/
pascal long GetMaxResourceSize 
                             (Handle theResource);

Disposing of Resources

pascal void ReleaseResource 
                             (Handle theResource);
pascal void DetachResource   (Handle theResource);
/*the RemoveResource routine is also available as RvmeResource*/
pascal void RemoveResource   (Handle theResource);

Closing Resource Forks

pascal void CloseResFile     (short refNum);

Reading and Writing Partial Resources

pascal void ReadPartialResource
                             (Handle theResource, long offset, 
                              void *buffer, long count);
pascal void WritePartialResource
                             (Handle theResource, long offset, 
                              const void *buffer, long count);
pascal void SetResourceSize
                             (Handle theResource, long newSize);

Getting and Setting Resource Fork Attributes

pascal short GetResFileAttrs
                             (short refNum);
pascal void SetResFileAttrs
                             (short refNum, short attrs);

Accessing Resource Entries in a Resource Map

pascal long RsrcMapEntry (Handle theResource);

Assembly-Language Summary

Trap Macros

Trap Macros Requiring Routine Selectors

_ResourceDispatch

Selector	Routine
$7001	ReadPartialResource
$7002	WritePartialResource
$7003	SetResourceSize

_HighLevelFSDispatch

Selector	Routine
$0000	FSpOpenResFile
$000E	FSpCreateResFile

Global Variables
TopMapHndl long Handle to resource map of most recently opened resource fork
SysMapHndl long Handle to System file's resource fork
SysMap word File reference number of System file's resource fork
CurMap word File reference number of current resource file
ResLoad word Current `SetResLoad` state
ResErr word Current value of `ResError`
ResErrProc long Address of resource error procedure
SysResName length byte followed by up to 19 characters Name of System file's resource fork
RomMapInsert byte Flag for whether to insert ROM resource map
TmpResLoad byte Temporary `SetResLoad` state for calls using `RomMapInsert`

Result Codes
noErr 0 No error
dirFulErr -33 Directory full
dskFulErr -34 Disk full
nsvErr -35 No such volume
ioErr -36 I/O error
bdNamErr -37 Bad filename or volume name (perhaps zero length)
eofErr -39 End of file
tmfoErr -42 Too many files open
fnfErr -43 File not found
wPrErr -44 Disk is write-protected
fLckdErr -45 File is locked
vLckdErr -46 Volume is locked
dupFNErr -48 Duplicate filename (rename)
opWrErr -49 File already open with write permission
permErr -54 Permissions error (on file open)
extFSErr -58 Volume belongs to an external file system
memFullErr -108 Not enough room in heap zone
dirNFErr -120 Directory not found
resourceInMemory -188 Resource already in memory
writingPastEnd -189 Writing past end of file
inputOutOfBounds -190 Offset or count out of bounds
resNotFound -192 Resource not found
resFNotFound -193 Resource file not found
addResFailed -194 `AddResource` procedure failed
rmvResFailed -196 `RemoveResource` procedure failed
resAttrErr -198 Attribute inconsistent with operation
mapReadErr -199 Map inconsistent with operation

TopMapHndl	long	Handle to resource map of most recently opened resource fork
SysMapHndl	long	Handle to System file's resource fork
SysMap	word	File reference number of System file's resource fork
CurMap	word	File reference number of current resource file
ResLoad	word	Current `SetResLoad` state
ResErr	word	Current value of `ResError`
ResErrProc	long	Address of resource error procedure
SysResName	length byte followed by up to 19 characters	Name of System file's resource fork
RomMapInsert	byte	Flag for whether to insert ROM resource map
TmpResLoad	byte	Temporary `SetResLoad` state for calls using `RomMapInsert`

noErr	0	No error
dirFulErr	-33	Directory full
dskFulErr	-34	Disk full
nsvErr	-35	No such volume
ioErr	-36	I/O error
bdNamErr	-37	Bad filename or volume name (perhaps zero length)
eofErr	-39	End of file
tmfoErr	-42	Too many files open
fnfErr	-43	File not found
wPrErr	-44	Disk is write-protected
fLckdErr	-45	File is locked
vLckdErr	-46	Volume is locked
dupFNErr	-48	Duplicate filename (rename)
opWrErr	-49	File already open with write permission
permErr	-54	Permissions error (on file open)
extFSErr	-58	Volume belongs to an external file system
memFullErr	-108	Not enough room in heap zone
dirNFErr	-120	Directory not found
resourceInMemory	-188	Resource already in memory
writingPastEnd	-189	Writing past end of file
inputOutOfBounds	-190	Offset or count out of bounds
resNotFound	-192	Resource not found
resFNotFound	-193	Resource file not found
addResFailed	-194	`AddResource` procedure failed
rmvResFailed	-196	`RemoveResource` procedure failed
resAttrErr	-198	Attribute inconsistent with operation
mapReadErr	-199	Map inconsistent with operation