PBHSetVolSync
PBHSetVol Select a default volume/directory (HFS only)
#include <Files.h> File Manager (PBxxx)
OSErr PBHSetVol(pb, async ); WDPBPtr pb ; address of a 52-byte WDPBRec structure Boolean async ; 0=await completion; 1=immediate return Apple does not recommend using PBHSetVol or HSetVol. See the notes below for details.
PBHSetVol is used to select both a default volume and a default working
directory. The File Manager will use these defaults in future calls in which
you specify no volume name and a volume reference number of 0. Unlike
SetVol and PBSetVol, PBHSetVol lets you specify the volume and the directory separately, using the ioVRefNum and the ioWDDirID fields.
pb is the address of a 52-byte WDPBRec structure. The following fields are relevant:
Out-In Name Type Size Offset Description
-> ioCompletion ProcPtr 4 12 Completion routine address (if async =TRUE) -> ioNamePtr StringPtr 4 18 Address of full or partial pathname (or NIL) -> ioVRefNum short 2 22 Volume reference number
-> ioWDDirID long 4 48 ID of desired default working directory
<- ioResult OSErr 2 16 Error Code (0=no error, 1=not done yet) async is a Boolean value. Use FALSE for normal (synchronous) operation or TRUE to enqueue the request and resume control immediately. See Async I/O.
noErr (0) No error
nsvErr (-35) No default volume
Notes: You can specify the new default by any of the following options:
• A full or partial pathname (ends in a colon). Put the address of the
pascal-style string in ioNamePtr
• A volume number or a working directory number in ioVRefNum. If you
use a working directory reference it will affect how PBGetVol works.
• A directory number in ioWDDirID (as obtained via PBOpenWD).
See SetVol for an example showing usage of various ways to set a default volume and open a file.
PBHSetVol lets you specify a WDRefNum for the ioVRefNum in addition to
a partial pathname in ioNamePtr. PBHSetVol will start at the specified
working directory and use the partial pathname to determine the final
directory. This directory might not correspond to an already existing
working directory, so the File Manager cannot refer to this directory with a
WDRefNum. Instead, it must use the actual volume refNum and the dirID
number (which is assigned when the directory is created, and does not
change). This all means that if you call PBHSetVol, the File Manager
stores the actual volume refNum as the default volume, and the default dirID
separately. This will happen on all calls to PBHSetVol. Subsequent calls to
GetVol or PBGetVol will return only the volume refNum in the ioVRefNum field of the parameter block. If any code tries to use the refNum
returned by GetVol, it will be accessing the root of the volume, and not the current default directory as expected. This can be disastrous for desk
accessories because they don't know that your code has called PBHSetVol
and they don't get what they expect if they call GetVol. Because of these problems, Apple does not recommend using PBHSetVol