Legacy Document

Inside Macintosh: Files /

Chapter 2 - File Manager / Using the File Manager

Determining the Features of the File Manager

Some of the capabilities provided by the File Manager depend on the version of system software that is running, and some others depend on the characteristics of the target volume. For example, the routines that accept FSSpec records as file or directory specifications were introduced in system software version 7.0 and are unavailable in earlier system software versions--unless your software development system provides "glue" that allows you to call those routines when running in earlier system software versions (or unless some system extension provides those routines). Similarly, some volumes support features that other volumes do not; a volume that has local file
sharing enabled, for instance, allows you to lock byte ranges in any files on a volume
that is sharable.

Before using any of the File Manager features that are not universally available in all system software versions and on all volumes, you should check for that feature's availability by calling either the Gestalt function or the PBHGetVolParms function, according to whether the feature's presence depends on the system software or the characteristics of the volume.

You can use Gestalt to determine whether or not you can call the functions that accept and support FSSpec records. Call Gestalt with the gestaltFSAttr selector to check for File Manager features. The response parameter currently has two relevant bits:

CONST
   gestaltFullExtFSDispatching   =  0;    {exports HFSDispatch traps}
   gestaltHasFSSpecCalls         =  1;    {supports FSSpec records}

Constant descriptions

gestaltFullExtFSDispatching

If set, all of the routines selected through the _HFSDispatch trap are available to external file systems. If this bit is clear, the File Manager checks the selector passed to _HFSDispatch and ensures that it is valid; if the selector is invalid, the result code paramErr is returned to the caller. If this bit is set, no such validity checking is performed.

gestaltHasFSSpecCalls

If set, the operating environment provides the file system specification versions of the basic file-manipulation functions, plus the FSMakeFSSpec function.

The chapter "Introduction to File Management" in this book illustrates how to use the Gestalt function to determine whether the operating environment supports the routines that accept FSSpec records. For a complete description of the Gestalt function, see the chapter "Gestalt Manager" in Inside Macintosh: Operating System Utilities.

To test for the availability of the features that depend on the volume, you can call the low-level function PBHGetVolParms. Listing 2-1 illustrates how you can determine whether the PBCatSearch function is available before using it to search a volume's catalog. Note that the SupportsCatSearch function defined in Listing 2-1 first calls Gestalt to determine whether the File Manager supports PBCatSearch. If it does, the SupportsCatSearch function calls PBHGetVolParms to see if the indicated volume also supports PBCatSearch.

Listing 2-1 Testing for PBCatSearch

FUNCTION SupportsCatSearch (vRefNum: Integer): Boolean;
VAR
   myHPB:         HParamBlockRec;
   infoBuffer:    GetVolParmsInfoBuffer;
   attrib:        LongInt;
BEGIN
   SupportsCatSearch := FALSE;   {assume no PBCatSearch support}
   IF gHasGestalt THEN           {set this somewhere else}
      IF Gestalt(gestaltFSAttr, attrib) = noErr THEN
         IF BTst(attrib, gestaltFullExtFSDispatching) THEN

            BEGIN                {this File Mgr has PBCatSearch}
               WITH myHPB DO
                  BEGIN
                     ioNamePtr := NIL;
                     ioVRefNum := vRefNum;
                     ioBuffer := @infoBuffer;
                     ioReqCount := SIZEOF(infoBuffer);
                  END;
               IF PBHGetVolParms(@myHPB, FALSE) = noErr THEN
                  IF BTST(infoBuffer.vMAttrib, bHasCatSearch) THEN
                     SupportsCatSearch := TRUE;
            END;
END;

The SupportsCatSearch function calls PBHGetVolParms for the volume whose reference number is passed as a parameter to SupportsCatSearch. The PBHGetVolParms function returns information about a volume in a record of type GetVolParmsInfoBuffer. The vMAttrib field of that record contains a number of bits that encode information about the capabilities of the target volume. In particular, the bit bHasCatSearch is set if the specified volume supports the PBCatSearch function.

Note

Some features of volumes might change dynamically during the execution of your application. For example, the user can turn File Sharing on and off, thereby changing the capabilities of volumes. See "Locking and Unlocking File Ranges" on page 2-50 for more details.