Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 7 - Finder Interface / Finder Interface Reference

Routines / Finding Directories

FindFolder

To get the path information to gain access to the system-related directories, use the FindFolder function.

FUNCTION FindFolder (vRefNum: Integer; folderType: OSType; 
                     createFolder: Boolean; 
                     VAR foundVRefNum: Integer; 
                     VAR foundDirID: LongInt): OSErr;

vRefNum

The volume reference number (or the constant kOnSystemDisk for the startup disk) of the volume on which you want to locate a directory.

folderType

A four-character folder type, or a constant that represents the type, for the directory you want to find. The constants and the four-character folder types they represent are listed here:

            CONST
            kAppleMenuFolderType 
                                 = 'amnu';   {Apple Menu Items}
            kControlPanelFolderType
                                 = 'ctrl';   {Control Panels}
            kDesktopFolderType   = 'desk';   {Desktop Folder}
            kExtensionFolderType
                                 = 'extn';   {Extensions}
            kFontsFolderType     = 'font';   {Fonts folder}
            kPreferencesFolderType
                                 = 'pref';   {Preferences}
            kPrintMonitorDocsFolderType   
                                 = 'prnt';   {PrintMonitor  }
                                             { Documents}
            kStartupFolderType   = 'strt';   {Startup Items}
            kSystemFolderType    = 'macs';   {System Folder}
            kTemporaryFolderType
                                 = 'temp';   {Temporary Items}
            kTrashFolderType     = 'trsh';   {single-user Trash}
            kWhereToEmptyTrashFolderType  
                                 = 'empt';   {shared Trash on net}

createFolder

Pass the constant kCreateFolder in this parameter to create a directory if it does not already exist; otherwise, pass the constant kDontCreateFolder.

foundVRefNum

The volume reference number, returned by FindFolder, for the volume containing the directory you specify in the folderType parameter.

foundDirID

The directory ID number, returned by FindFolder, for the directory you specify in the folderType parameter.

DESCRIPTION

For the folder type on the particular volume (specified, respectively, in the folderType and vRefNum parameters), the FindFolder function returns the directory's volume reference number in the foundVRefNum parameter and its directory ID in the foundDirID parameter.

The specified folder used for a given volume might be located on a different volume in future versions of system software; therefore, do not assume the volume that you
specify in vRefNum and the volume returned in foundVRefNum will be the same.

Specify a volume reference number (or the constant kOnSystemDisk for the startup disk) in the vRefNum parameter.

Specify a four-character folder type--or the constant that represents it--in the folderType parameter. Use the kTrashFolderType constant to locate the current user's Trash directory for a given volume--even one located on a file server. On a file server, you can use the kWhereToEmptyTrashFolderType constant to locate the parent directory of all logged-on users' Trash subdirectories.

Use the constant kCreateFolder in the createFolder parameter to tell FindFolder to create a directory if it does not already exist; otherwise, use the constant kDontCreateFolder. Directories inside the System Folder are created only if the System Folder directory exists. The FindFolder function will not create a System Folder directory even if you specify the kCreateFolder constant in the createFolder parameter.

The FindFolder function returns a nonzero result code if the folder isn't found,
and it can also return other file system errors reported by the File Manager or
Memory Manager.

SPECIAL CONSIDERATIONS

The Finder identifies the subdirectories of the System Folder, and their folder types, in a resource of type 'fld#' located in the System file. Do not modify or rely on the contents of the 'fld#' resource in the System file; use only the FindFolder function to find the appropriate directories.

To determine the availability of the FindFolder function, use the Gestalt function with the Gestalt selector gestaltFindFolderAttr. Test the bit field indicated by the gestaltFindFolderPresent constant in the response parameter. If the bit is set, then the FindFolder function is present.

CONST gestaltFindFolderPresent = 0;    {if this bit is set, }
                                       { FindFolder is present}

RESULT CODES

noErr	0	No error
fnfErr	-43	Type not found in 'fld#' resource, or disk doesn't have System Folder support or System Folder in volume header, or disk does not have desktop database support for Desktop Folder--in all cases, folder not found
dupFNErr	-48	File found instead of folder

SEE ALSO

The system-related directories located by the FindFolder function are described in "Using the System Folder and Its Related Directories" beginning on page 7-39.