Legacy Document

Inside Macintosh: Files /

Chapter 2 - File Manager / About the File Manager

Volume Manipulation

The File Manager provides a number of routines that allow you to manipulate volumes. For example, you can obtain information about a mounted volume, update the information on a volume, unmount a mounted volume or place it offline, and so forth. Most applications don't need explicit access to volumes. The Standard File Package and the Finder handle most events related to the insertion and ejection of disks.

When the Event Manager function WaitNextEvent (or GetNextEvent) receives a disk-inserted event, it calls the Desk Manager function SystemEvent. The Desk Manager in turn calls the File Manager function PBMountVol, which attempts to mount the volume on the disk. The result of the PBMountVol call is put into the high-order word of the event message, and the drive number is put into its low-order word. If the result code indicates that an error occurred, you need to call the Disk Initialization Manager routine DIBadMount to allow the user to initialize or eject the volume. For details, see the chapter "Disk Initialization Manager" in this book.

After a volume has been mounted, your application can call GetVInfo, which returns the name, the amount of unused space, and the volume reference number. Given a file reference number, you can get the volume reference number of the volume containing that file by calling either GetVRefNum or GetFCBInfo.

You can unmount or place offline any volumes that aren't currently being used. To unmount a volume, call UnmountVol, which flushes a volume (by calling FlushVol) and releases all of the memory it uses. To place a volume offline, call PBOffLine, which flushes a volume and releases all of the memory used for it except for the volume control block. The File Manager places offline volumes online as needed, but your application must remount any unmounted volumes it wants to access. The File Manager itself may place volumes offline during its normal operation.

Note

If you make a call to an offline volume, the File Manager displays the disk switch dialog box and waits for the user to reinsert the disk containing the volume. When the user inserts the required disk, the File Manager mounts the volume and then reissues your original call. To avoid presenting the user with numerous disk switch dialog boxes, you might need to check that a volume is online before attempting to access data on it.

To protect against data loss due to power interruption or unexpected disk ejection, you should periodically call FlushVol (probably after each time you close a file), which writes the contents of the volume buffer and all access path buffers (if any) to the volume and updates the descriptive information contained on the volume.

Whenever your application is finished with a disk, or when the user chooses Eject from a menu, call the Eject function. This function calls FlushVol, places the volume offline, and then physically ejects the volume from its drive.

If you would like all File Manager calls to apply to a particular volume, specify it as the default volume. You can use the HGetVol (or GetVol) function to determine the name and volume reference number of the default volume, and the SetVol function to make any mounted volume the default.

Normally, volume initialization and naming are handled by the Disk Initialization Manager. If you want to initialize a volume explicitly or erase all files from a volume, you can call the Disk Initialization Manager directly. When you want to change the name of a volume, call the HRename function.

Table 2-6 summarizes the volume-manipulation routines. Most of these routines require you to specify a volume either by name or by volume reference number.

Table 2-6 Routines for operating on volumes

High-Level	Low-Level	Description
	PBMountVol	Mount a volume.
UnmountVol	PBUnmountVol	Unmount a volume.
Eject	PBEject	Eject a volume.
	PBOffLine	Place a volume offline.
FlushVol	PBFlushVol	Update a volume.
GetVol	PBGetVol	Get the default volume.
HGetVol	PBHGetVol	Get the default volume.
SetVol	PBSetVol	Set the default volume.
HSetVol	PBHSetVol	Set the default volume.
GetVInfo	PBHGetVInfo	Get information about a volume.
	PBSetVInfo	Set information about a volume.
	PBHGetVolParms	Determine capabilities of a volume.
	PBCatSearch	Search a volume for files or directories satisfying certain criteria.