Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: Files /
Chapter 2 - File Manager / File Manager Reference
Data Structures


Catalog Information Parameter Blocks

The low-level functions PBGetCatInfo, PBSetCatInfo, and PBCatSearch exchange information with your application using the catalog information parameter block, which is defined by the CInfoPBRec data type. There are two variants of this record, hFileInfo and dirInfo, which describe files and directories, respectively.

   TYPE CInfoPBRec   =  {catalog information parameter block}
   RECORD
      qLink:            QElemPtr;      {next queue entry}
      qType:            Integer;       {queue type}
      ioTrap:           Integer;       {routine trap}
      ioCmdAddr:        Ptr;           {routine address}
      ioCompletion:     ProcPtr;       {pointer to completion routine}
      ioResult:         OSErr;         {result code}
      ioNamePtr:        StringPtr;     {pointer to pathname}
      ioVRefNum:        Integer;       {volume specification}
      ioFRefNum:        Integer;       {file reference number}
      ioFVersNum:       SignedByte;    {version number}
      filler1:          SignedByte;    {reserved}
      ioFDirIndex:      Integer;       {directory index}
      ioFlAttrib:       SignedByte;    {file or directory attributes}
      ioACUser:         SignedByte;    {directory access rights}
   CASE CInfoType OF
   hFileInfo:
     (ioFlFndrInfo:     FInfo;         {information used by the Finder}
      ioDirID:          LongInt;       {directory ID or file ID}
      ioFlStBlk:        Integer;       {first alloc. blk. of data fork}
      ioFlLgLen:        LongInt;       {logical EOF of data fork}
      ioFlPyLen:        LongInt;       {physical EOF of data fork}
      ioFlRStBlk:       Integer;       {first alloc. blk. of resource fork}
      ioFlRLgLen:       LongInt;       {logical EOF of resource fork}
      ioFlRPyLen:       LongInt;       {physical EOF of resource fork}
      ioFlCrDat:        LongInt;       {date and time of creation}
      ioFlMdDat:        LongInt;       {date and time of last modification}
      ioFlBkDat:        LongInt;       {date and time of last backup}
      ioFlXFndrInfo:    FXInfo;        {additional Finder information}
      ioFlParID:        LongInt;       {file parent directory ID}
      ioFlClpSiz:       LongInt);      {file's clump size}
   dirInfo:
     (ioDrUsrWds:       DInfo;         {information used by the Finder}
      ioDrDirID:        LongInt;       {directory ID}
      ioDrNmFls:        Integer;       {number of files in directory}
      filler3:          ARRAY[1..9] OF Integer;
      ioDrCrDat:        LongInt;       {date and time of creation}
      ioDrMdDat:        LongInt;       {date and time of last modification}
      ioDrBkDat:        LongInt;       {date and time of last backup}
      ioDrFndrInfo:     DXInfo;        {additional Finder information}
      ioDrParID:        LongInt);      {directory's parent directory ID}
   END;
The first 14 fields are common to both variants. Each variant also includes its own unique fields.

Field descriptions common to both variants

qLink
A pointer to the next entry in the file I/O queue. (This field is used internally by the File Manager to keep track of asynchronous calls awaiting execution.)
qType
The queue type. (This field is used internally by the File Manager.)
ioTrap
The trap number of the routine that was called. (This field is used internally by the File Manager.)
ioCmdAddr
The address of the routine that was called. (This field is used internally by the File Manager.)
ioCompletion
A pointer to a completion routine to be executed at the end of an asynchronous call. It should be NIL for asynchronous calls with no completion routine and is automatically set to NIL for all synchronous calls. See "Completion Routines" on page 2-238 for information about completion routines.
ioResult
The result code of the function. For synchronous calls, this field is the same as the result code of the function call itself. To determine when an asynchronous call has actually been completed, your application can poll this field; it's set to a positive number when
the call is made and receives the actual result code when the call
is completed.
ioNamePtr
A pointer to a pathname. Whenever a routine description specifies that ioNamePtr is used--whether for input, output, or both--
it's very important that you set this field to point to storage for a Str255 value (if you're using a pathname) or to NIL (if you're not).
ioVRefNum
A volume specification. You can specify a volume using a volume reference number, a drive number, a working directory reference number, or 0 for the default drive.
ioFRefNum
The file reference number of an open file.
ioFVersNum
A file version number. This field is no longer used and you should always set it to 0.
filler1
Reserved.
ioFDirIndex
A file and directory index. If this field contains a positive number, PBGetCatInfo returns information about the file or directory having that directory index in the directory specified by the ioVRefNum field. (If ioVRefNum contains a volume reference number, the specified directory is that volume's root directory.)
If this field contains 0, PBGetCatInfo returns information about the file or directory whose name is specified in the ioNamePtr field and that is located in the directory specified by the ioVRefNum field. (Once again, if ioVRefNum contains a volume reference number, the specified directory is that volume's root directory.)
If this field contains a negative number, PBGetCatInfo ignores the ioNamePtr field and returns information about the directory specified in the ioDirID field. If both ioDirID and ioVRefNum are set to 0, PBGetCatInfo returns information about the current default directory.
ioFlAttrib
File or directory attributes. For files, the bits in this field have the following meanings:
 BitMeaning
 0Set if file is locked
 1Reserved
 2Set if resource fork is open
 3Set if data fork is open
 4Set if a directory
 5-6Reserved
 7Set if file (either fork) is open
For directories, the bits in this field have the following meanings:
 BitMeaning
 0Set if the directory is locked
 1Reserved
 2Set if the directory is within a shared area of the directory hierarchy
 3Set if the directory is a share point that is mounted by some user
 4Set if the item is a directory
 5Set if the directory is a share point
 6-7Reserved
ioACUser
The user's access rights for the specified directory. The bits in this field have the following meanings:
 BitMeaning
 0Set if user does not have See Folder privileges
 1Set if user does not have See Files privileges
 2Set if user does not have Make Changes privileges
 3-6Reserved; always set to 0
 7Set if user is not owner of the directory
For example, if you call PBGetCatInfo for a particular shared volume and ioACUser returns 0, you know that the user is the owner of the directory and has complete privileges to it.
Field descriptions for the hFileInfo variant

ioFlFndrInfo
Information used by the Finder.
ioDirID
A directory ID or file ID. On input to PBGetCatInfo, this field contains a directory ID (which is used only if the ioFDirIndex field is negative). On output, this field contains the file ID of the specified file.
ioFlStBlk
The first allocation block of the data fork. This field contains 0 if the file's data fork is empty.
ioFlLgLen
The logical end-of-file of the data fork.
ioFlPyLen
The physical end-of-file of the data fork.
ioFlRStBlk
The first allocation block of the resource fork.
ioFlRLgLen
The logical end-of-file of the resource fork.
ioFlRPyLen
The physical end-of-file of the resource fork.
ioFlCrDat
The date and time of the file's creation, specified in seconds since midnight, January 1, 1904.
ioFlMdDat
The date and time of the last modification to the file, specified in seconds since midnight, January 1, 1904.
ioFlBkDat
The date and time of the last backup to the file, specified in seconds since midnight, January 1, 1904.
ioFlXFndrInfo
Additional information used by the Finder. (See the chapter
"Finder Interface" in Inside Macintosh: Macintosh Toolbox Essentials for details.)
ioFlParID
The directory ID of the file's parent.
ioFlClpSiz
The clump size to be used when writing the file; if it's 0, the volume's clump size is used when the file is opened.
Field descriptions for the dirInfo variant

ioDrUsrWds
Information used by the Finder.
ioDrDirID
A directory ID. On input to PBGetCatInfo, this field contains a directory ID (which is used only if the value of the ioFDirIndex field is negative). On output, this field contains the directory ID of the specified directory.
ioDrNmFls
The number of files in the directory.
filler3
Reserved.
ioDrCrDat
The date and time of the directory's creation, specified in seconds since midnight, January 1, 1904.
ioDrMdDat
The date and time of the last modification to the directory, specified in seconds since midnight, January 1, 1904.
ioDrBkDat
The date and time of the last backup to the directory, specified in seconds since midnight, January 1, 1904.
ioDrFndrInfo
Additional information used by the Finder.
ioDrParID
The directory ID of the specified directory's parent.

Previous Book Contents Book Index Next

© Apple Computer, Inc.
2 JUL 1996