Legacy Document

Inside Macintosh: Files /

Chapter 2 - File Manager / File Manager Reference

Low-Level Volume Access Routines / Obtaining Volume Information

PBHGetVolParms

You can use the PBHGetVolParms function to determine the characteristics of a volume.

FUNCTION PBHGetVolParms (paramBlock: HParmBlkPtr; async: Boolean):  
                        OSErr;

paramBlock

A pointer to a basic HFS parameter block.

async

A Boolean value that specifies asynchronous (TRUE) or synchronous (FALSE) execution.

-->	ioCompletion	ProcPtr	A pointer to a completion routine.
<--	ioResult	OSErr	The result code of the function.
-->	ioNamePtr	StringPtr	A pointer to the volume's name.
-->	ioVRefNum	Integer	A volume specification.
-->	ioBuffer	Ptr	A pointer to a GetVolParmsInfoBuffer record.
-->	ioReqCount	LongInt	The size of the buffer area.
<--	ioActCount	LongInt	The size of the data actually returned.

DESCRIPTION

The PBHGetVolParms function returns information about the characteristics of a volume. You specify a volume (either by name or by volume reference number) and a buffer size, and PBHGetVolParms fills in the volume attributes buffer, as described in this section.

You can use a name (pointed to by the ioNamePtr field) or a volume specification (contained in the ioVRefNum field) to specify the volume. A volume specification can be a volume reference number, drive number, or working directory reference number. If you use a volume specification to specify the volume, you should set the ioNamePtr field to NIL.

You must allocate memory to hold the returned attributes and put a pointer to the buffer in the ioBuffer field. Specify the size of the buffer in the ioReqCount field. The PBHGetVolParms function places the attributes information in the buffer pointed to by the ioBuffer field and specifies the actual length of the data in the ioActCount field.

The PBHGetVolParms function returns the bulk of its volume description in the vMAttrib field of the attributes buffer. The vMAttrib field contains 32 bits of
attribute information about the volume. Bits 0-3 and 21-24 are reserved; all volumes should return these bits clear. The bits currently used are defined by these constants:

CONST
   bHasBlankAccessPrivileges
                  =  4;    {volume supports inherited privileges}
   bHasBTreeMgr   =  5;    {reserved}
   bHasFileIDs    =  6;    {volume supports file ID functions}
   bHasCatSearch  =  7;    {volume supports PBCatSearch}
   bHasUserGroupList
                  =  8;    {volume supports AFP privileges}
   bHasPersonalAccessPrivileges
                  =  9;    {local file sharing is enabled}
   bHasFolderLock =  10;   {volume supports locking of folders}
   bHasShortName  =  11;   {volume supports AFP short names}
   bHasDesktopMgr =  12;   {volume supports Desktop Manager}
   bHasMoveRename =  13;   {volume supports _MoveRename}
   bHasCopyFile   =  14;   {volume supports _CopyFile}
   bHasOpenDeny   =  15;   {volume supports shared access modes}
   bHasExtFSVol   =  16;   {volume is external file system volume}
   bNoSysDir      =  17;   {volume has no system directory}
   bAccessCntl    =  18;   {volume supports AFP access control}
   bNoBootBlks    =  19;   {volume is not a startup volume}
   bNoDeskItems   =  20;   {do not place objects on the desktop}
   bNoSwitchTo    =  25;   {do not switch launch to applications}
   bTrshOffLine   =  26;   {zoom volume when it is unmounted}
   bNoLclSync     =  27;   {don't let Finder change mod. date}
   bNoVNEdit      =  28;   {lock volume name}
   bNoMiniFndr    =  29;   {reserved; always 1}
   bLocalWList    =  30;   {use shared volume handle for window }
                           { list}
   bLimitFCBs     =  31;   {limit file control blocks}

These constants have the following meanings if set:

Constant descriptions

bHasBlankAccessPrivileges

This volume supports inherited access privileges for folders.

bHasBTreeMgr

Reserved for internal use.

bHasFileIDs

This volume supports the file ID functions, including the PBExchangeFiles function.

bHasCatSearch

This volume supports the PBCatSearch function.

bHasUserGroupList

This volume supports the Users and Groups file and thus the AFP privilege functions.

bHasPersonalAccessPrivileges

This volume has local file sharing enabled.

bHasFolderLock

Folders on the volume can be locked, and so they cannot be deleted or renamed.

bHasShortName

This volume supports AFP short names.

bHasDesktopMgr

This volume supports all of the desktop functions (described in
the chapter "Desktop Manager" in Inside Macintosh: More
Macintosh Toolbox).

bHasMoveRename

This volume supports the PBHMoveRename function.

bHasCopyFile

This volume supports the PBHCopyFile function, which is used in copy and duplicate operations if both source and destination volumes have the same server address.

bHasOpenDeny

This volume supports the PBHOpenDeny and PBHOpenRFDeny functions.

bHasExtFSVol

This volume is an external file system volume.

bNoSysDir

This volume doesn't support a system directory. Do not switch launch to this volume.

bAccessCntl

This volume supports AppleTalk AFP access-control interfaces. The PBHGetLoginInfo, PBHGetDirAccess, PBHSetDirAccess, PBHMapID, and PBHMapName functions are supported. Special folder icons are used. The Access Privileges menu command is enabled for disk and folder items. The ioFlAttrib field of PBGetCatInfo calls is assumed to be valid.

bNoBootBlks

This volume is not a startup volume. The Startup menu item is disabled. Boot blocks are not copied during copy operations.

bNoDeskItems

Don't place objects in this volume on the Finder desktop.

bNoSwitchTo

The Finder will not switch launch to any application on this volume.

bTrshOffLine

Any time this volume goes offline, it is zoomed to the Trash
and unmounted.

bNoLclSync

Don't let the Finder change the modification date.

bNoVNEdit

This volume's name cannot be edited.

bNoMiniFndr

Reserved; always set to 1.

bLocalWList

The Finder uses the returned shared volume handle for its local window list.

bLimitFCBs

The Finder limits the number of file control blocks used during copying to 8 instead of 16.

SPECIAL CONSIDERATIONS

A volume's characteristics can change when the user enables and disables file sharing. You might have to make repeated calls to PBHGetVolParms to ensure that you have the current status of a volume.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for PBHGetVolParms are

Trap macro	Selector
_HFSDispatch	$0030

RESULT CODES

noErr	0	No error
nsvErr	-35	Volume not found
paramErr	-50	Volume doesn't support the function