Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 1 - Resource Manager / Resource Manager Reference

Resource Manager Routines / Opening Resource Forks

HOpenResFile

If the FSpOpenResFile function is not available, you can use HOpenResFile to open a file's resource fork.

FUNCTION HOpenResFile (vRefNum: Integer; dirID: LongInt;
                       fileName: Str255; 
                       permission: SignedByte): Integer;

vRefNum

The volume reference number of the volume on which the file is located.

dirID

The directory ID of the directory where the file is located.

fileName

The name of the file whose resource fork is to be opened.

permission

A constant for one of the read/write permission combinations.

DESCRIPTION

The HOpenResFile function opens the resource fork of the file with the name specified by the fileName parameter in the directory specified by the vRefNum and dirID parameters. It also makes this file the current resource file.

You can specify the access path permission for the resource fork by setting the permission parameter to one of these constants:

CONST
   fsCurPerm    = 0; {whatever is currently allowed}
   fsRdPerm     = 1; {read-only permission}
   fsWrPerm     = 2; {write permission}
   fsRdWrPerm   = 3; {exclusive read/write permission}
   fsRdWrShPerm = 4; {shared read/write permission}

See page 1-55 for information about specifying access path permission with FSpOpenResFile. The same information applies to HOpenResFile.

The Resource Manager reads the resource map from the resource fork of the specified file into memory. It also reads into memory every resource whose resPreload attribute is set.

The HOpenResFile function returns a file reference number for the file. You can use this file reference number to refer to the file in other Resource Manager routines. If the file's resource fork is already open, HOpenResFile returns the file reference number but does not make that file the current resource file.

If the HOpenResFile function fails to open the specified file's resource fork (because there's no file with the specified name or because there are permission problems), it returns -1 as the file reference number. Use the ResError function to determine what kind of error occurred.

You don't have to call HOpenResFile to open the System file's resource fork or an application file's resource fork. These files are opened automatically when the system and the application start up, respectively. To get the file reference number for your application, call the CurResFile function after the application starts up and before you open the resource forks for any other files.

The HOpenResFile function checks that the information in the resource map is internally consistent. If it isn't, ResError returns the result code mapReadErr.

To open a resource fork just for block-level operations, such as copying files without reading the resource map into memory, use the File Manager function OpenRF.

SPECIAL CONSIDERATIONS

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

It's possible to create multiple, unique, read-only access paths to a resource fork using HOpenResFile; however, you should avoid doing so. See page 1-56 for discussion of this issue in relation to FSpOpenResFile. The HOpenResFile function works the same way.

Versions of system software before System 7 do not allow you to use HOpenResFile to open a second access path, with write access, to a resource fork. In this case, HOpenResFile returns the reference number already assigned to the file.

If you want to open the resource fork for another application (or any resource fork other than your application's that includes 'CODE' resources), you must bracket your calls to HOpenResFile with calls to SetResLoad with the load parameter set to FALSE and then to TRUE. You must also avoid making intersegment calls while the other application's resource fork is open. The discussion of this issue in relation to FSpOpenResFile (page 1-56) also applies to HOpenResFile.

ASSEMBLY-LANGUAGE INFORMATION

A handle to the resource map for the most recently opened resource fork is stored in the global variable TopMapHndl.

RESULT CODES

noErr	0	No error
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
opWrErr	-49	File already open with write permission
permErr	-54	Attempt to open locked file for writing
extFSErr	-58	Volume belongs to an external file system
memFullErr	-108	Not enough room in heap zone
dirNFErr	-120	Directory not found
mapReadErr	-199	Map inconsistent with operation

SEE ALSO

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

For more information about permission parameter constants and the OpenRF function, see Inside Macintosh: Files.