Source/MoreFilesX.h

   1 /*
   2         File:           MoreFilesX.h
   3
   4         Contains:       A collection of useful high-level File Manager routines
   5                                 which use the HFS Plus APIs wherever possible.
   6
   7         Version:        MoreFilesX 1.0.1
   8
   9         Copyright:      © 1992-2002 by Apple Computer, Inc., all rights reserved.
  10
  11         Disclaimer:     IMPORTANT:  This Apple software is supplied to you by Apple Computer, Inc.
  12                                 ("Apple") in consideration of your agreement to the following terms, and your
  13                                 use, installation, modification or redistribution of this Apple software
  14                                 constitutes acceptance of these terms.  If you do not agree with these terms,
  15                                 please do not use, install, modify or redistribute this Apple software.
  16
  17                                 In consideration of your agreement to abide by the following terms, and subject
  18                                 to these terms, Apple grants you a personal, non-exclusive license, under AppleÕs
  19                                 copyrights in this original Apple software (the "Apple Software"), to use,
  20                                 reproduce, modify and redistribute the Apple Software, with or without
  21                                 modifications, in source and/or binary forms; provided that if you redistribute
  22                                 the Apple Software in its entirety and without modifications, you must retain
  23                                 this notice and the following text and disclaimers in all such redistributions of
  24                                 the Apple Software.  Neither the name, trademarks, service marks or logos of
  25                                 Apple Computer, Inc. may be used to endorse or promote products derived from the
  26                                 Apple Software without specific prior written permission from Apple.  Except as
  27                                 expressly stated in this notice, no other rights or licenses, express or implied,
  28                                 are granted by Apple herein, including but not limited to any patent rights that
  29                                 may be infringed by your derivative works or by other works in which the Apple
  30                                 Software may be incorporated.
  31
  32                                 The Apple Software is provided by Apple on an "AS IS" basis.  APPLE MAKES NO
  33                                 WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED
  34                                 WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  35                                 PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR IN
  36                                 COMBINATION WITH YOUR PRODUCTS.
  37
  38                                 IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR
  39                                 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  40                                 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  41                                 ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION
  42                                 OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, TORT
  43                                 (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN
  44                                 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  45
  46         File Ownership:
  47
  48                 DRI:                            Apple Macintosh Developer Technical Support
  49
  50                 Other Contact:          For bug reports, consult the following page on
  51                                                         the World Wide Web:
  52                                                                 http://developer.apple.com/bugreporter/
  53
  54                 Technology:                     DTS Sample Code
  55
  56         Writers:
  57
  58                 (JL)    Jim Luther
  59
  60         Change History (most recent first):
  61
  62                  <3>     4/19/02        JL              [2853905]  Fixed #if test around header includes.
  63                  <2>     4/19/02        JL              [2853901]  Updated standard disclaimer.
  64                  <1>     1/25/02        JL              MoreFilesX 1.0
  65
  66         Notes:
  67                 What do those arrows in the documentation for each routine mean?
  68
  69                         --> The parameter is an input
  70
  71                         <-- The parameter is an output. The pointer to the variable
  72                                 where the output will be returned (must not be NULL).
  73
  74                         <** The parameter is an optional output. If it is not a
  75                                 NULL pointer, it points to the variable where the output
  76                                 will be returned. If it is a NULL pointer, the output will
  77                                 not be returned and will possibly let the routine and the
  78                                 File Manager do less work. If you don't need an optional output,
  79                                 don't ask for it.
  80                         **> The parameter is an optional input. If it is not a
  81                                 NULL pointer, it points to the variable containing the
  82                                 input data. If it is a NULL pointer, the input is not used
  83                                 and will possibly let the routine and the File Manager
  84                                 do less work.
  85 */
  86
  87 #ifndef __MOREFILESX__
  88 #define __MOREFILESX__
  89
  90 #ifndef __CARBON__
  91         #if defined(__MACH__)
  92                 #include <Carbon/Carbon.h>
  93         #else
  94                 #include <Carbon.h>
  95         #endif
  96 #endif
  97
  98 #if PRAGMA_ONCE
  99 #pragma once
 100 #endif
 101
 102 #ifdef __cplusplus
 103 extern "C" {
 104 #endif
 105
 106 #if PRAGMA_IMPORT
 107 #pragma import on
 108 #endif
 109
 110 #if PRAGMA_STRUCT_ALIGN
 111         #pragma options align=mac68k
 112 #elif PRAGMA_STRUCT_PACKPUSH
 113         #pragma pack(push, 2)
 114 #elif PRAGMA_STRUCT_PACK
 115         #pragma pack(2)
 116 #endif
 117
 118 /*****************************************************************************/
 119
 120 #ifndef WIN32
 121 #pragma mark ----- FinderInfo and ExtendedFinderInfo -----
 122 #endif
 123
 124 /*
 125  *      FSGetFinderInfo and FSSetFinderInfo use these unions for Finder information.
 126  */
 127
 128 union FinderInfo
 129 {
 130   FileInfo                              file;
 131   FolderInfo                    folder;
 132 };
 133 typedef union FinderInfo FinderInfo;
 134
 135 union ExtendedFinderInfo
 136 {
 137   ExtendedFileInfo              file;
 138   ExtendedFolderInfo    folder;
 139 };
 140 typedef union ExtendedFinderInfo ExtendedFinderInfo;
 141
 142 /*****************************************************************************/
 143
 144 #pragma mark ----- GetVolParmsInfoBuffer Macros -----
 145
 146 /*
 147  *      Macros to get information out of GetVolParmsInfoBuffer.
 148  */
 149
 150 /* version 1 field getters */
 151 #define GetVolParmsInfoVersion(volParms) \
 152                 ((volParms)->vMVersion)
 153 #define GetVolParmsInfoAttrib(volParms) \
 154                 ((volParms)->vMAttrib)
 155 #define GetVolParmsInfoLocalHand(volParms) \
 156                 ((volParms)->vMLocalHand)
 157 #define GetVolParmsInfoServerAdr(volParms) \
 158                 ((volParms)->vMServerAdr)
 159
 160 /* version 2 field getters (assume zero result if version < 2) */
 161 #define GetVolParmsInfoVolumeGrade(volParms) \
 162                 (((volParms)->vMVersion >= 2) ? (volParms)->vMVolumeGrade : 0)
 163 #define GetVolParmsInfoForeignPrivID(volParms) \
 164                 (((volParms)->vMVersion >= 2) ? (volParms)->vMForeignPrivID : 0)
 165
 166 /* version 3 field getters (assume zero result if version < 3) */
 167 #define GetVolParmsInfoExtendedAttributes(volParms) \
 168                 (((volParms)->vMVersion >= 3) ? (volParms)->vMExtendedAttributes : 0)
 169
 170 /* attribute bits supported by all versions of GetVolParmsInfoBuffer */
 171 #define VolIsNetworkVolume(volParms) \
 172                 ((volParms)->vMServerAdr != 0)
 173 #define VolHasLimitFCBs(volParms) \
 174                 (((volParms)->vMAttrib & (1L << bLimitFCBs)) != 0)
 175 #define VolHasLocalWList(volParms) \
 176                 (((volParms)->vMAttrib & (1L << bLocalWList)) != 0)
 177 #define VolHasNoMiniFndr(volParms) \
 178                 (((volParms)->vMAttrib & (1L << bNoMiniFndr)) != 0)
 179 #define VolHasNoVNEdit(volParms) \
 180                 (((volParms)->vMAttrib & (1L << bNoVNEdit)) != 0)
 181 #define VolHasNoLclSync(volParms) \
 182                 (((volParms)->vMAttrib & (1L << bNoLclSync)) != 0)
 183 #define VolHasTrshOffLine(volParms) \
 184                 (((volParms)->vMAttrib & (1L << bTrshOffLine)) != 0)
 185 #define VolHasNoSwitchTo(volParms) \
 186                 (((volParms)->vMAttrib & (1L << bNoSwitchTo)) != 0)
 187 #define VolHasNoDeskItems(volParms) \
 188                 (((volParms)->vMAttrib & (1L << bNoDeskItems)) != 0)
 189 #define VolHasNoBootBlks(volParms) \
 190                 (((volParms)->vMAttrib & (1L << bNoBootBlks)) != 0)
 191 #define VolHasAccessCntl(volParms) \
 192                 (((volParms)->vMAttrib & (1L << bAccessCntl)) != 0)
 193 #define VolHasNoSysDir(volParms) \
 194                 (((volParms)->vMAttrib & (1L << bNoSysDir)) != 0)
 195 #define VolHasExtFSVol(volParms) \
 196                 (((volParms)->vMAttrib & (1L << bHasExtFSVol)) != 0)
 197 #define VolHasOpenDeny(volParms) \
 198                 (((volParms)->vMAttrib & (1L << bHasOpenDeny)) != 0)
 199 #define VolHasCopyFile(volParms) \
 200                 (((volParms)->vMAttrib & (1L << bHasCopyFile)) != 0)
 201 #define VolHasMoveRename(volParms) \
 202                 (((volParms)->vMAttrib & (1L << bHasMoveRename)) != 0)
 203 #define VolHasDesktopMgr(volParms) \
 204                 (((volParms)->vMAttrib & (1L << bHasDesktopMgr)) != 0)
 205 #define VolHasShortName(volParms) \
 206                 (((volParms)->vMAttrib & (1L << bHasShortName)) != 0)
 207 #define VolHasFolderLock(volParms) \
 208                 (((volParms)->vMAttrib & (1L << bHasFolderLock)) != 0)
 209 #define VolHasPersonalAccessPrivileges(volParms) \
 210                 (((volParms)->vMAttrib & (1L << bHasPersonalAccessPrivileges)) != 0)
 211 #define VolHasUserGroupList(volParms) \
 212                 (((volParms)->vMAttrib & (1L << bHasUserGroupList)) != 0)
 213 #define VolHasCatSearch(volParms) \
 214                 (((volParms)->vMAttrib & (1L << bHasCatSearch)) != 0)
 215 #define VolHasFileIDs(volParms) \
 216                 (((volParms)->vMAttrib & (1L << bHasFileIDs)) != 0)
 217 #define VolHasBTreeMgr(volParms) \
 218                 (((volParms)->vMAttrib & (1L << bHasBTreeMgr)) != 0)
 219 #define VolHasBlankAccessPrivileges(volParms) \
 220                 (((volParms)->vMAttrib & (1L << bHasBlankAccessPrivileges)) != 0)
 221 #define VolSupportsAsyncRequests(volParms) \
 222                 (((volParms)->vMAttrib & (1L << bSupportsAsyncRequests)) != 0)
 223 #define VolSupportsTrashVolumeCache(volParms) \
 224                 (((volParms)->vMAttrib & (1L << bSupportsTrashVolumeCache)) != 0)
 225
 226 /* attribute bits supported by version 3 and greater versions of GetVolParmsInfoBuffer */
 227 #define VolIsEjectable(volParms) \
 228                 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bIsEjectable)) != 0)
 229 #define VolSupportsHFSPlusAPIs(volParms) \
 230                 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsHFSPlusAPIs)) != 0)
 231 #define VolSupportsFSCatalogSearch(volParms) \
 232                 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsFSCatalogSearch)) != 0)
 233 #define VolSupportsFSExchangeObjects(volParms) \
 234                 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsFSExchangeObjects)) != 0)
 235 #define VolSupports2TBFiles(volParms) \
 236                 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupports2TBFiles)) != 0)
 237 #define VolSupportsLongNames(volParms) \
 238                 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsLongNames)) != 0)
 239 #define VolSupportsMultiScriptNames(volParms) \
 240                 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsMultiScriptNames)) != 0)
 241 #define VolSupportsNamedForks(volParms) \
 242                 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsNamedForks)) != 0)
 243 #define VolSupportsSubtreeIterators(volParms) \
 244                 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsSubtreeIterators)) != 0)
 245 #define VolL2PCanMapFileBlocks(volParms) \
 246                 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bL2PCanMapFileBlocks)) != 0)
 247 #define VolParentModDateChanges(volParms) \
 248                 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bParentModDateChanges)) != 0)
 249 #define VolAncestorModDateChanges(volParms) \
 250                 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bAncestorModDateChanges)) != 0)
 251 #define VolSupportsSymbolicLinks(volParms) \
 252                 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsSymbolicLinks)) != 0)
 253 #define VolIsAutoMounted(volParms) \
 254                 ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bIsAutoMounted)) != 0)
 255
 256 /*****************************************************************************/
 257
 258 #pragma mark ----- userPrivileges Bit Masks and Macros -----
 259
 260 /*
 261  *      Bit masks and macros to get common information out of userPrivileges byte
 262  *      returned by FSGetCatalogInfo.
 263  *
 264  *      Note:   The userPrivileges byte is the same as the ioACUser byte returned
 265  *                      by PBGetCatInfo, and is the 1's complement of the user's privileges
 266  *                      byte returned in ioACAccess by PBHGetDirAccess. That's where the
 267  *                      ioACUser names came from.
 268  *
 269  *                      The userPrivileges are user's effective privileges based on the
 270  *                      user ID and the groups that user belongs to, and the owner, group,
 271  *                      and everyone privileges for the given directory.
 272  */
 273
 274 enum
 275 {
 276         /* mask for just the access restriction bits */
 277         kioACUserAccessMask             = (kioACUserNoSeeFolderMask +
 278                                                            kioACUserNoSeeFilesMask +
 279                                                            kioACUserNoMakeChangesMask),
 280         /* common access privilege settings */
 281         kioACUserFull                   = 0x00, /* no access restiction bits on */
 282         kioACUserNone                   = kioACUserAccessMask, /* all access restiction bits on */
 283         kioACUserDropBox                = (kioACUserNoSeeFolderMask +
 284                                                            kioACUserNoSeeFilesMask), /* make changes, but not see files or folders */
 285         kioACUserBulletinBoard  = kioACUserNoMakeChangesMask /* see files and folders, but not make changes */
 286 };
 287
 288
 289 /* Macros for testing ioACUser bits. */
 290
 291 #define UserIsOwner(userPrivileges) \
 292                 (((userPrivileges) & kioACUserNotOwnerMask) == 0)
 293 #define UserHasFullAccess(userPrivileges)       \
 294                 (((userPrivileges) & (kioACUserAccessMask)) == kioACUserFull)
 295 #define UserHasDropBoxAccess(userPrivileges)    \
 296                 (((userPrivileges) & kioACUserAccessMask) == kioACUserDropBox)
 297 #define UserHasBulletinBoard(userPrivileges)    \
 298                 (((userPrivileges) & kioACUserAccessMask) == kioACUserBulletinBoard)
 299 #define UserHasNoAccess(userPrivileges)         \
 300                 (((userPrivileges) & kioACUserAccessMask) == kioACUserNone)
 301
 302 /*****************************************************************************/
 303
 304 #pragma mark ----- File Access Routines -----
 305
 306 /*****************************************************************************/
 307
 308 #pragma mark FSCopyFork
 309
 310 OSErr
 311 FSCopyFork(
 312         SInt16 srcRefNum,
 313         SInt16 dstRefNum,
 314         void *copyBufferPtr,
 315         ByteCount copyBufferSize);
 316
 317 /*
 318         The FSCopyFork function copies all data from the source fork to the
 319         destination fork of open file forks and makes sure the destination EOF
 320         is equal to the source EOF.
 321
 322         srcRefNum                       --> The source file reference number.
 323         dstRefNum                       --> The destination file reference number.
 324         copyBufferPtr           --> Pointer to buffer to use during copy. The
 325                                                         buffer should be at least 4K-bytes minimum.
 326                                                         The larger the buffer, the faster the copy
 327                                                         (up to a point).
 328         copyBufferSize          --> The size of the copy buffer.
 329 */
 330
 331 /*****************************************************************************/
 332
 333 #pragma mark ----- Volume Access Routines -----
 334
 335 /*****************************************************************************/
 336
 337 #pragma mark FSGetVolParms
 338
 339 OSErr
 340 FSGetVolParms(
 341         FSVolumeRefNum volRefNum,
 342         UInt32 bufferSize,
 343         GetVolParmsInfoBuffer *volParmsInfo,
 344         UInt32 *actualInfoSize);
 345
 346 /*
 347         The FSGetVolParms function returns information about the characteristics
 348         of a volume. A result of paramErr usually just means the volume doesn't
 349         support GetVolParms and the feature you were going to check
 350         for isn't available.
 351
 352         volRefNum                       --> Volume specification.
 353         bufferSize                      --> Size of buffer pointed to by volParmsInfo.
 354         volParmsInfo            <-- A GetVolParmsInfoBuffer record where the volume
 355                                                         attributes information is returned.
 356         actualInfoSize          <-- The number of bytes actually returned
 357                                                         in volParmsInfo.
 358
 359         __________
 360
 361         Also see:       The GetVolParmsInfoBuffer Macros for checking attribute bits
 362                                 in this file
 363 */
 364
 365 /*****************************************************************************/
 366
 367 #pragma mark FSGetVRefNum
 368
 369 OSErr
 370 FSGetVRefNum(
 371         const FSRef *ref,
 372         FSVolumeRefNum *vRefNum);
 373
 374 /*
 375         The FSGetVRefNum function determines the volume reference
 376         number of a volume from a FSRef.
 377
 378         ref                                     --> The FSRef.
 379         vRefNum                         <-- The volume reference number.
 380 */
 381
 382 /*****************************************************************************/
 383
 384 #pragma mark FSGetVInfo
 385
 386 OSErr
 387 FSGetVInfo(
 388         FSVolumeRefNum volume,
 389         HFSUniStr255 *volumeName,       /* can be NULL */
 390         UInt64 *freeBytes,                      /* can be NULL */
 391         UInt64 *totalBytes);            /* can be NULL */
 392
 393 /*
 394         The FSGetVInfo function returns the name, available space (in bytes),
 395         and total space (in bytes) for the specified volume.
 396
 397         volume                          --> The volume reference number.
 398         volumeName                      <** An optional pointer to a HFSUniStr255.
 399                                                         If not NULL, the volume name will be returned in
 400                                                         the HFSUniStr255.
 401         freeBytes                       <** An optional pointer to a UInt64.
 402                                                         If not NULL, the number of free bytes on the
 403                                                         volume will be returned in the UInt64.
 404         totalBytes                      <** An optional pointer to a UInt64.
 405                                                         If not NULL, the total number of bytes on the
 406                                                         volume will be returned in the UInt64.
 407 */
 408
 409 /*****************************************************************************/
 410
 411 #pragma mark FSGetVolFileSystemID
 412
 413 OSErr
 414 FSGetVolFileSystemID(
 415         FSVolumeRefNum volume,
 416         UInt16 *fileSystemID,   /* can be NULL */
 417         UInt16 *signature);             /* can be NULL */
 418
 419 /*
 420         The FSGetVolFileSystemID function returns the file system ID and signature
 421         of a mounted volume. The file system ID identifies the file system
 422         that handles requests to a particular volume. The signature identifies the
 423         volume type of the volume (for example, FSID 0 is Macintosh HFS Plus, HFS
 424         or MFS, where a signature of 0x4244 identifies the volume as HFS).
 425         Here's a partial list of file system ID numbers (only Apple's file systems
 426         are listed):
 427                 FSID    File System
 428                 -----   -----------------------------------------------------
 429                 $0000   Macintosh HFS Plus, HFS or MFS
 430                 $0100   ProDOS File System
 431                 $0101   PowerTalk Mail Enclosures
 432                 $4147   ISO 9660 File Access (through Foreign File Access)
 433                 $4242   High Sierra File Access (through Foreign File Access)
 434                 $464D   QuickTake File System (through Foreign File Access)
 435                 $4953   Macintosh PC Exchange (MS-DOS)
 436                 $4A48   Audio CD Access (through Foreign File Access)
 437                 $4D4B   Apple Photo Access (through Foreign File Access)
 438                 $6173   AppleShare (later versions of AppleShare only)
 439
 440         See the Technical Note "FL 35 - Determining Which File System
 441         Is Active" and the "Guide to the File System Manager" for more
 442         information.
 443
 444         volume                          --> The volume reference number.
 445         fileSystemID            <** An optional pointer to a UInt16.
 446                                                         If not NULL, the volume's file system ID will
 447                                                         be returned in the UInt16.
 448         signature                       <** An optional pointer to a UInt16.
 449                                                         If not NULL, the volume's signature will
 450                                                         be returned in the UInt16.
 451 */
 452
 453 /*****************************************************************************/
 454
 455 #pragma mark FSGetMountedVolumes
 456
 457 OSErr
 458 FSGetMountedVolumes(
 459         FSRef ***volumeRefsHandle,      /* pointer to handle of FSRefs */
 460         ItemCount *numVolumes);
 461
 462 /*
 463         The FSGetMountedVolumes function returns the list of volumes currently
 464         mounted in an array of FSRef records. The array of FSRef records is
 465         returned in a Handle, volumeRefsHandle, which is allocated by
 466         FSGetMountedVolumes. The caller is responsible for disposing of
 467         volumeRefsHandle if the FSGetMountedVolumes returns noErr.
 468
 469         volumeRefsHandle        <-- Pointer to an FSRef Handle where the array of
 470                                                         FSRefs is to be returned.
 471         numVolumes                      <-- The number of volumes returned in the array.
 472 */
 473
 474 /*****************************************************************************/
 475
 476 #pragma mark ----- FSRef/FSpec/Path/Name Conversion Routines -----
 477
 478 /*****************************************************************************/
 479
 480 #pragma mark FSRefMakeFSSpec
 481
 482 OSErr
 483 FSRefMakeFSSpec(
 484         const FSRef *ref,
 485         FSSpec *spec);
 486
 487 /*
 488         The FSRefMakeFSSpec function returns an FSSpec for the file or
 489         directory specified by the ref parameter.
 490
 491         ref                                     --> An FSRef specifying the file or directory.
 492         spec                            <-- The FSSpec.
 493 */
 494
 495 /*****************************************************************************/
 496
 497 #pragma mark FSMakeFSRef
 498
 499 OSErr
 500 FSMakeFSRef(
 501         FSVolumeRefNum volRefNum,
 502         SInt32 dirID,
 503         ConstStr255Param name,
 504         FSRef *ref);
 505
 506 /*
 507         The FSMakeFSRef function creates an FSRef from the traditional
 508         volume reference number, directory ID and pathname inputs. It is
 509         functionally equivalent to FSMakeFSSpec followed by FSpMakeFSRef.
 510
 511         volRefNum                       --> Volume specification.
 512         dirID                           --> Directory specification.
 513         name                            --> The file or directory name, or NULL.
 514         ref                                     <-- The FSRef.
 515 */
 516
 517 /*****************************************************************************/
 518
 519 #pragma mark FSMakePath
 520
 521 OSStatus
 522 FSMakePath(
 523         SInt16 vRefNum,
 524         SInt32 dirID,
 525         ConstStr255Param name,
 526         UInt8 *path,
 527         UInt32 maxPathSize);
 528
 529 /*
 530         The FSMakePath function creates a pathname from the traditional volume reference
 531         number, directory ID, and pathname inputs. It is functionally equivalent to
 532         FSMakeFSSpec, FSpMakeFSRef, FSRefMakePath.
 533
 534         volRefNum                       --> Volume specification.
 535         dirID                           --> Directory specification.
 536         name                            --> The file or directory name, or NULL.
 537         path                            <-- A pointer to a buffer which FSMakePath will
 538                                                         fill with a C string representing the pathname
 539                                                         to the file or directory specified. The format of
 540                                                         the pathname returned can be determined with the
 541                                                         Gestalt selector gestaltFSAttr's
 542                                                         gestaltFSUsesPOSIXPathsForConversion bit.
 543                                                         If the gestaltFSUsesPOSIXPathsForConversion bit is
 544                                                         clear, the pathname is a Mac OS File Manager full
 545                                                         pathname in a C string, and file or directory names
 546                                                         in the pathname may be mangled as returned by
 547                                                         the File Manager. If the
 548                                                         gestaltFSUsesPOSIXPathsForConversion bit is set,
 549                                                         the pathname is a UTF8 encoded POSIX absolute
 550                                                         pathname in a C string. In either case, the
 551                                                         pathname returned can be passed back to
 552                                                         FSPathMakeRef to create an FSRef to the file or
 553                                                         directory, or FSPathMakeFSSpec to craete an FSSpec
 554                                                         to the file or directory.
 555         maxPathSize                     --> The size of the path buffer in bytes. If the path
 556                                                         buffer is too small for the pathname string,
 557                                                         FSMakePath returns pathTooLongErr or
 558                                                         buffersTooSmall.
 559 */
 560
 561 /*****************************************************************************/
 562
 563 #pragma mark FSPathMakeFSSpec
 564
 565 OSStatus
 566 FSPathMakeFSSpec(
 567         const UInt8 *path,
 568         FSSpec *spec,
 569         Boolean *isDirectory);  /* can be NULL */
 570
 571 /*
 572         The FSPathMakeFSSpec function converts a pathname to an FSSpec.
 573
 574         path                            --> A pointer to a C String that is the pathname. The
 575                                                         format of the pathname you must supply can be
 576                                                         determined with the Gestalt selector gestaltFSAttr's
 577                                                         gestaltFSUsesPOSIXPathsForConversion bit.
 578                                                         If the gestaltFSUsesPOSIXPathsForConversion bit is
 579                                                         clear, the pathname must be a Mac OS File Manager
 580                                                         full pathname in a C string. If the
 581                                                         gestaltFSUsesPOSIXPathsForConversion bit is set,
 582                                                         the pathname must be a UTF8 encoded POSIX absolute
 583                                                         pathname in a C string.
 584         spec                            <-- The FSSpec.
 585         isDirectory                     <** An optional pointer to a Boolean.
 586                                                         If not NULL, true will be returned in the Boolean
 587                                                         if the specified path is a directory, or false will
 588                                                         be returned in the Boolean if the specified path is
 589                                                         a file.
 590 */
 591
 592 /*****************************************************************************/
 593
 594 #pragma mark UnicodeNameGetHFSName
 595
 596 OSErr
 597 UnicodeNameGetHFSName(
 598         UniCharCount nameLength,
 599         const UniChar *name,
 600         TextEncoding textEncodingHint,
 601         Boolean isVolumeName,
 602         Str31 hfsName);
 603
 604 /*
 605         The UnicodeNameGetHFSName function converts a Unicode string
 606         to a Pascal Str31 (or Str27) string using an algorithm similar to that used
 607         by the File Manager. Note that if the name is too long or cannot be converted
 608         using the given text encoding hint, you will get an error instead of the
 609         mangled name that the File Manager would return.
 610
 611         nameLength                      --> Number of UniChar in name parameter.
 612         name                            --> The Unicode string to convert.
 613         textEncodingHint        --> The text encoding hint used for the conversion.
 614                                                         You can pass kTextEncodingUnknown to use the
 615                                                         "default" textEncodingHint.
 616         isVolumeName            --> If true, the output name will be limited to
 617                                                         27 characters (kHFSMaxVolumeNameChars). If false,
 618                                                         the output name will be limited to 31 characters
 619                                                         (kHFSMaxFileNameChars).
 620         hfsName                         <-- The hfsName as a Pascal string.
 621
 622         __________
 623
 624         Also see:       HFSNameGetUnicodeName
 625 */
 626
 627 /*****************************************************************************/
 628
 629 #pragma mark HFSNameGetUnicodeName
 630
 631 OSErr
 632 HFSNameGetUnicodeName(
 633         ConstStr31Param hfsName,
 634         TextEncoding textEncodingHint,
 635         HFSUniStr255 *unicodeName);
 636
 637 /*
 638         The HFSNameGetUnicodeName function converts a Pascal Str31 string to an
 639         Unicode HFSUniStr255 string using the same routines as the File Manager.
 640
 641         hfsName                         --> The Pascal string to convert.
 642         textEncodingHint        --> The text encoding hint used for the conversion.
 643                                                         You can pass kTextEncodingUnknown to use the
 644                                                         "default" textEncodingHint.
 645         unicodeName                     <-- The Unicode string.
 646
 647         __________
 648
 649         Also see:       UnicodeNameGetHFSName
 650 */
 651
 652 /*****************************************************************************/
 653
 654 #pragma mark ----- File/Directory Manipulation Routines -----
 655
 656 /*****************************************************************************/
 657
 658 #pragma mark FSRefValid
 659
 660 Boolean FSRefValid(const FSRef *ref);
 661
 662 /*
 663         The FSRefValid function determines if an FSRef is valid. If the result is
 664         true, then the FSRef refers to an existing file or directory.
 665
 666         ref                                     --> FSRef to a file or directory.
 667 */
 668
 669 /*****************************************************************************/
 670
 671 #pragma mark FSGetParentRef
 672
 673 OSErr
 674 FSGetParentRef(
 675         const FSRef *ref,
 676         FSRef *parentRef);
 677
 678 /*
 679         The FSGetParentRef function gets the parent directory FSRef of the
 680         specified object.
 681
 682         Note: FSRefs always point to real file system objects. So, there cannot
 683         be a FSRef to the parent of volume root directories. If you call
 684         FSGetParentRef with a ref to the root directory of a volume, the
 685         function result will be noErr and the parentRef will be invalid (using it
 686         for other file system requests will fail).
 687
 688         ref                                     --> FSRef to a file or directory.
 689         parentRef                       <-- The parent directory's FSRef.
 690 */
 691
 692 /*****************************************************************************/
 693
 694 #pragma mark FSGetFileDirName
 695
 696 OSErr
 697 FSGetFileDirName(
 698         const FSRef *ref,
 699         HFSUniStr255 *outName);
 700
 701 /*
 702         The FSGetFileDirName function gets the name of the file or directory
 703         specified.
 704
 705         ref                                     --> FSRef to a file or directory.
 706         outName                         <-- The file or directory name.
 707 */
 708
 709 /*****************************************************************************/
 710
 711 #pragma mark FSGetNodeID
 712
 713 OSErr
 714 FSGetNodeID(
 715         const FSRef *ref,
 716         long *nodeID,                   /* can be NULL */
 717         Boolean *isDirectory);  /* can be NULL */
 718
 719 /*
 720         The GetNodeIDFromFSRef function gets the node ID number of the
 721         file or directory specified (note: the node ID is the directory ID
 722         for directories).
 723
 724         ref                                     --> FSRef to a file or directory.
 725         nodeID                          <** An optional pointer to a long.
 726                                                         If not NULL, the node ID will be returned in
 727                                                         the long.
 728         isDirectory                     <** An optional pointer to a Boolean.
 729                                                         If not NULL, true will be returned in the Boolean
 730                                                         if the object is a directory, or false will be
 731                                                         returned in the Boolean if object is a file.
 732 */
 733
 734 /*****************************************************************************/
 735
 736 #pragma mark FSGetUserPrivilegesPermissions
 737
 738 OSErr
 739 FSGetUserPrivilegesPermissions(
 740         const FSRef *ref,
 741         UInt8 *userPrivileges,          /* can be NULL */
 742         UInt32 permissions[4]);         /* can be NULL */
 743
 744 /*
 745         The FSGetUserPrivilegesPermissions function gets the userPrivileges and/or
 746         permissions of the file or directory specified.
 747
 748         ref                                     --> FSRef to a file or directory.
 749         userPrivileges          <** An optional pointer to a UInt8.
 750                                                         If not NULL, the userPrivileges will be returned
 751                                                         in the UInt8.
 752         permissions                     <** An optional pointer to an UInt32[4] array.
 753                                                         If not NULL, the permissions will be returned
 754                                                         in the UInt32[4] array.
 755 */
 756
 757 /*****************************************************************************/
 758
 759 #pragma mark FSCheckLock
 760
 761 OSErr
 762 FSCheckLock(
 763         const FSRef *ref);
 764
 765 /*
 766         The FSCheckLock function determines if a file or directory is locked.
 767         If FSCheckLock returns noErr, then the file or directory is not locked
 768         and the volume it is on is not locked either. If FSCheckLock returns
 769         fLckdErr, then the file or directory is locked. If FSCheckLock returns
 770         wPrErr, then the volume is locked by hardware (i.e., locked tab on
 771         removable media). If FSCheckLock returns vLckdErr, then the volume is
 772         locked by software.
 773
 774         ref                                     --> FSRef to a file or directory.
 775 */
 776
 777 /*****************************************************************************/
 778
 779 #pragma mark FSGetForkSizes
 780
 781 OSErr
 782 FSGetForkSizes(
 783         const FSRef *ref,
 784         UInt64 *dataLogicalSize,        /* can be NULL */
 785         UInt64 *rsrcLogicalSize);       /* can be NULL */
 786
 787 /*
 788         The FSGetForkSizes returns the size of the data and/or resource fork for
 789         the specified file.
 790
 791         ref                                     --> FSRef to a file or directory.
 792         dataLogicalSize         <** An optional pointer to a UInt64.
 793                                                         If not NULL, the data fork's size will be
 794                                                         returned in the UInt64.
 795         rsrcLogicalSize         <** An optional pointer to a UInt64.
 796                                                         If not NULL, the resource fork's size will be
 797                                                         returned in the UInt64.
 798
 799         __________
 800
 801         Also see:       FSGetTotalForkSizes
 802 */
 803
 804 /*****************************************************************************/
 805
 806 #pragma mark FSGetTotalForkSizes
 807
 808 OSErr
 809 FSGetTotalForkSizes(
 810         const FSRef *ref,
 811         UInt64 *totalLogicalSize,       /* can be NULL */
 812         UInt64 *totalPhysicalSize,      /* can be NULL */
 813         ItemCount *forkCount);          /* can be NULL */
 814
 815 /*
 816         The FSGetTotalForkSizes returns the total logical size and/or the total
 817         physical size of the specified file (i.e., it adds the sizes of all file
 818         forks). It optionally returns the number of file forks.
 819
 820         ref                                     --> FSRef to a file or directory.
 821         totalLogicalSize        <** An optional pointer to a UInt64.
 822                                                         If not NULL, the sum of all fork logical sizes
 823                                                         will be returned in the UInt64.
 824         totalPhysicalSize       <** An optional pointer to a UInt64.
 825                                                         If not NULL, the sum of all fork physical sizes
 826                                                         will be returned in the UInt64.
 827         forkCount                       <** An optional pointer to a ItemCount.
 828                                                         If not NULL, the number of file forks
 829                                                         will be returned in the ItemCount.
 830
 831         __________
 832
 833         Also see:       FSGetForkSizes
 834 */
 835
 836 /*****************************************************************************/
 837
 838 #pragma mark FSBumpDate
 839
 840 OSErr
 841 FSBumpDate(
 842         const FSRef *ref);
 843
 844 /*
 845         The FSBumpDate function changes the content modification date of a file
 846         or directory to the current date/time. If the content modification date
 847         is already equal to the current date/time, then add one second to the
 848         content modification date.
 849
 850         ref                                     --> FSRef to a file or directory.
 851 */
 852
 853 /*****************************************************************************/
 854
 855 #pragma mark FSGetFinderInfo
 856
 857 OSErr
 858 FSGetFinderInfo(
 859         const FSRef *ref,
 860         FinderInfo *info,                                       /* can be NULL */
 861         ExtendedFinderInfo *extendedInfo,       /* can be NULL */
 862         Boolean *isDirectory);                          /* can be NULL */
 863
 864 /*
 865         The FSGetFinderInfo function gets the finder information for a file or
 866         directory.
 867
 868         ref                                     --> FSRef to a file or directory.
 869         info                            <** An optional pointer to a FinderInfo.
 870                                                         If not NULL, the FileInfo (if ref is a file) or
 871                                                         the FolderInfo (if ref is a folder) will be
 872                                                         returned in the FinderInfo.
 873         extendedInfo            <** An optional pointer to a ExtendedFinderInfo.
 874                                                         If not NULL, the ExtendedFileInfo (if ref is a file)
 875                                                         or the ExtendedFolderInfo (if ref is a folder) will
 876                                                         be returned in the ExtendedFinderInfo.
 877         isDirectory                     <** An optional pointer to a Boolean.
 878                                                         If not NULL, true will be returned in the Boolean
 879                                                         if the object is a directory, or false will be
 880                                                         returned in the Boolean if object is a file.
 881
 882         __________
 883
 884         Also see:       FSSetFinderInfo
 885 */
 886
 887 /*****************************************************************************/
 888
 889 #pragma mark FSSetFinderInfo
 890
 891 OSErr
 892 FSSetFinderInfo(
 893         const FSRef *ref,
 894         const FinderInfo *info,                                         /* can be NULL */
 895         const ExtendedFinderInfo *extendedInfo);        /* can be NULL */
 896
 897 /*
 898         The FSSetFinderInfo function sets the finder information for a file or
 899         directory.
 900
 901         ref                                     --> FSRef to a file or directory.
 902         info                            **> A pointer to a FinderInfo record with the new
 903                                                         FileInfo (if ref is a file) or new FolderInfo
 904                                                         (if ref is a folder), or NULL if the FinderInfo
 905                                                         is not to be changed.
 906         extendedInfo            **> A pointer to a FinderInfo record with the new
 907                                                         ExtendedFileInfo (if ref is a file) or new
 908                                                         ExtendedFolderInfo (if ref is a folder), or NULL
 909                                                         if the ExtendedFinderInfo is not to be changed.
 910
 911         __________
 912
 913         Also see:       FSGetFinderInfo
 914 */
 915
 916 /*****************************************************************************/
 917
 918 #pragma mark FSChangeCreatorType
 919
 920 OSErr
 921 FSChangeCreatorType(
 922         const FSRef *ref,
 923         OSType fileCreator,
 924         OSType fileType);
 925
 926 /*
 927         The FSChangeCreatorType function changes the creator and/or file type of a file.
 928
 929         ref                                     --> FSRef to a file.
 930         creator                         --> The new creator type or 0x00000000 to leave
 931                                                         the creator type alone.
 932         fileType                        --> The new file type or 0x00000000 to leave the
 933                                                         file type alone.
 934 */
 935
 936 /*****************************************************************************/
 937
 938 #pragma mark FSChangeFinderFlags
 939
 940 OSErr
 941 FSChangeFinderFlags(
 942         const FSRef *ref,
 943         Boolean setBits,
 944         UInt16 flagBits);
 945
 946 /*
 947         The FSChangeFinderFlags function sets or clears flag bits in
 948         the finderFlags field of a file's FileInfo record or a
 949         directory's FolderInfo record.
 950
 951         ref                                     --> FSRef to a file or directory.
 952         setBits                         --> If true, then set the bits specified in flagBits.
 953                                                         If false, then clear the bits specified in flagBits.
 954         flagBits                        --> The flagBits parameter specifies which Finder Flag
 955                                                         bits to set or clear. If a bit in flagBits is set,
 956                                                         then the same bit in fdFlags is either set or
 957                                                         cleared depending on the state of the setBits
 958                                                         parameter.
 959 */
 960
 961 /*****************************************************************************/
 962
 963 #pragma mark FSSetInvisible
 964
 965 OSErr
 966 FSSetInvisible(
 967         const FSRef *ref);
 968
 969 #pragma mark FSClearInvisible
 970
 971 OSErr
 972 FSClearInvisible(
 973         const FSRef *ref);
 974
 975 /*
 976         The FSSetInvisible and FSClearInvisible functions set or clear the
 977         kIsInvisible bit in the finderFlags field of the specified file or
 978         directory's finder information.
 979
 980         ref                                     --> FSRef to a file or directory.
 981 */
 982
 983 /*****************************************************************************/
 984
 985 #pragma mark FSSetNameLocked
 986
 987 OSErr
 988 FSSetNameLocked(
 989         const FSRef *ref);
 990
 991 #pragma mark FSClearNameLocked
 992
 993 OSErr
 994 FSClearNameLocked(
 995         const FSRef *ref);
 996
 997 /*
 998         The FSSetNameLocked and FSClearNameLocked functions set or clear the
 999         kNameLocked bit bit in the finderFlags field of the specified file or
1000         directory's finder information.
1001
1002         ref                                     --> FSRef to a file or directory.
1003 */
1004
1005 /*****************************************************************************/
1006
1007 #pragma mark FSSetIsStationery
1008
1009 OSErr
1010 FSSetIsStationery(
1011         const FSRef *ref);
1012
1013 #pragma mark FSClearIsStationery
1014
1015 OSErr
1016 FSClearIsStationery(
1017         const FSRef *ref);
1018
1019 /*
1020         The FSSetIsStationery and FSClearIsStationery functions set or clear the
1021         kIsStationery bit bit in the finderFlags field of the specified file or
1022         directory's finder information.
1023
1024         ref                                     --> FSRef to a file or directory.
1025 */
1026
1027 /*****************************************************************************/
1028
1029 #pragma mark FSSetHasCustomIcon
1030
1031 OSErr
1032 FSSetHasCustomIcon(
1033         const FSRef *ref);
1034
1035 #pragma mark FSClearHasCustomIcon
1036
1037 OSErr
1038 FSClearHasCustomIcon(
1039         const FSRef *ref);
1040
1041 /*
1042         The FSSetHasCustomIcon and FSClearHasCustomIcon functions set or clear the
1043         kHasCustomIcon bit bit in the finderFlags field of the specified file or
1044         directory's finder information.
1045
1046         ref                                     --> FSRef to a file or directory.
1047 */
1048
1049 /*****************************************************************************/
1050
1051 #pragma mark FSClearHasBeenInited
1052
1053 OSErr
1054 FSClearHasBeenInited(
1055         const FSRef *ref);
1056
1057 /*
1058         The FSClearHasBeenInited function clears the kHasBeenInited bit in the
1059         finderFlags field of the specified file or directory's finder information.
1060
1061         Note:   There is no FSSetHasBeenInited function because ONLY the Finder
1062                         should set the kHasBeenInited bit.
1063
1064         ref                                     --> FSRef to a file or directory.
1065 */
1066
1067 /*****************************************************************************/
1068
1069 #pragma mark FSCopyFileMgrAttributes
1070
1071 OSErr
1072 FSCopyFileMgrAttributes(
1073         const FSRef *sourceRef,
1074         const FSRef *destinationRef,
1075         Boolean copyLockBit);
1076
1077 /*
1078         The CopyFileMgrAttributes function copies all File Manager attributes
1079         from the source file or directory to the destination file or directory.
1080         If copyLockBit is true, then set the locked state of the destination
1081         to match the source.
1082
1083         sourceRef                       --> FSRef to a file or directory.
1084         destinationRef          --> FSRef to a file or directory.
1085         copyLockBit                     --> If true, set the locked state of the destination
1086                                                         to match the source.
1087 */
1088
1089 /*****************************************************************************/
1090
1091 #pragma mark FSMoveRenameObjectUnicode
1092
1093 OSErr
1094 FSMoveRenameObjectUnicode(
1095         const FSRef *ref,
1096         const FSRef *destDirectory,
1097         UniCharCount nameLength,
1098         const UniChar *name,                    /* can be NULL (no rename during move) */
1099         TextEncoding textEncodingHint,
1100         FSRef *newRef);                                 /* if function fails along the way, newRef is final location of file */
1101
1102 /*
1103         The FSMoveRenameObjectUnicode function moves a file or directory and
1104         optionally renames it.  The source and destination locations must be on
1105         the same volume.
1106
1107         Note:   If the input ref parameter is invalid, this call will fail and
1108                         newRef, like ref, will be invalid.
1109
1110         ref                                     --> FSRef to a file or directory.
1111         destDirectory           --> FSRef to the destination directory.
1112         nameLength                      --> Number of UniChar in name parameter.
1113         name                            --> An Unicode string with the new name for the
1114                                                         moved object, or NULL if no rename is wanted.
1115         textEncodingHint        --> The text encoding hint used for the rename.
1116                                                         You can pass kTextEncodingUnknown to use the
1117                                                         "default" textEncodingHint.
1118         newRef                          <-- The new FSRef of the object moved. Note that if
1119                                                         this function fails at any step along the way,
1120                                                         newRef is still then final location of the object.
1121 */
1122
1123 /*****************************************************************************/
1124
1125 #pragma mark FSDeleteContainerContents
1126
1127 OSErr
1128 FSDeleteContainerContents(
1129         const FSRef *container);
1130
1131 /*
1132         The FSDeleteContainerContents function deletes the contents of a container
1133         directory. All files and subdirectories in the specified container are
1134         deleted. If a locked file or directory is encountered, it is unlocked and
1135         then deleted. If any unexpected errors are encountered,
1136         FSDeleteContainerContents quits and returns to the caller.
1137
1138         container                       --> FSRef to a directory.
1139
1140         __________
1141
1142         Also see:       FSDeleteContainer
1143 */
1144
1145 /*****************************************************************************/
1146
1147 #pragma mark FSDeleteContainer
1148
1149 OSErr
1150 FSDeleteContainer(
1151         const FSRef *container);
1152
1153 /*
1154         The FSDeleteContainer function deletes a container directory and its contents.
1155         All files and subdirectories in the specified container are deleted.
1156         If a locked file or directory is encountered, it is unlocked and then
1157         deleted.  After deleting the container's contents, the container is
1158         deleted. If any unexpected errors are encountered, FSDeleteContainer
1159         quits and returns to the caller.
1160
1161         container                       --> FSRef to a directory.
1162
1163         __________
1164
1165         Also see:       FSDeleteContainerContents
1166 */
1167
1168 /*****************************************************************************/
1169
1170 #pragma mark IterateContainerFilterProcPtr
1171
1172 typedef CALLBACK_API( Boolean , IterateContainerFilterProcPtr ) (
1173         Boolean containerChanged,
1174         ItemCount currentLevel,
1175         const FSCatalogInfo *catalogInfo,
1176         const FSRef *ref,
1177         const FSSpec *spec,
1178         const HFSUniStr255 *name,
1179         void *yourDataPtr);
1180
1181 /*
1182         This is the prototype for the IterateContainerFilterProc function which
1183         is called once for each file and directory found by FSIterateContainer.
1184         The IterateContainerFilterProc can use the read-only data it receives for
1185         whatever it wants.
1186
1187         The result of the IterateContainerFilterProc function indicates if
1188         iteration should be stopped. To stop iteration, return true; to continue
1189         iteration, return false.
1190
1191         The yourDataPtr parameter can point to whatever data structure you might
1192         want to access from within the IterateContainerFilterProc.
1193
1194         containerChanged        --> Set to true if the container's contents changed
1195                                                         during iteration.
1196         currentLevel            --> The current recursion level into the container.
1197                                                         1 = the container, 2 = the container's immediate
1198                                                         subdirectories, etc.
1199         catalogInfo                     --> The catalog information for the current object.
1200                                                         Only the fields requested by the whichInfo
1201                                                         parameter passed to FSIterateContainer are valid.
1202         ref                                     --> The FSRef to the current object.
1203         spec                            --> The FSSpec to the current object if the wantFSSpec
1204                                                         parameter passed to FSIterateContainer is true.
1205         name                            --> The name of the current object if the wantName
1206                                                         parameter passed to FSIterateContainer is true.
1207         yourDataPtr                     --> An optional pointer to whatever data structure you
1208                                                         might want to access from within the
1209                                                         IterateFilterProc.
1210         result                          <-- To stop iteration, return true; to continue
1211                                                         iteration, return false.
1212
1213         __________
1214
1215         Also see:       FSIterateContainer
1216 */
1217
1218 /*****************************************************************************/
1219
1220 #pragma mark CallIterateContainerFilterProc
1221
1222 #define CallIterateContainerFilterProc(userRoutine, containerChanged, currentLevel, catalogInfo, ref, spec, name, yourDataPtr) \
1223         (*(userRoutine))((containerChanged), (currentLevel), (catalogInfo), (ref), (spec), (name), (yourDataPtr))
1224
1225 /*****************************************************************************/
1226
1227 #pragma mark FSIterateContainer
1228
1229 OSErr
1230 FSIterateContainer(
1231         const FSRef *container,
1232         ItemCount maxLevels,
1233         FSCatalogInfoBitmap whichInfo,
1234         Boolean wantFSSpec,
1235         Boolean wantName,
1236         IterateContainerFilterProcPtr iterateFilter,
1237         void *yourDataPtr);
1238
1239 /*
1240         The FSIterateContainer function performs a recursive iteration (scan) of the
1241         specified container directory and calls your IterateContainerFilterProc
1242         function once for each file and directory found.
1243
1244         The maxLevels parameter lets you control how deep the recursion goes.
1245         If maxLevels is 1, FSIterateContainer only scans the specified directory;
1246         if maxLevels is 2, FSIterateContainer scans the specified directory and
1247         one subdirectory below the specified directory; etc. Set maxLevels to
1248         zero to scan all levels.
1249
1250         The yourDataPtr parameter can point to whatever data structure you might
1251         want to access from within your IterateContainerFilterProc.
1252
1253         container                       --> The FSRef to the container directory to iterate.
1254         maxLevels                       --> Maximum number of directory levels to scan or
1255                                                         zero to scan all directory levels.
1256         whichInfo                       --> The fields of the FSCatalogInfo you wish to get.
1257         wantFSSpec                      --> Set to true if you want the FSSpec to each
1258                                                         object passed to your IterateContainerFilterProc.
1259         wantName                        --> Set to true if you want the name of each
1260                                                         object passed to your IterateContainerFilterProc.
1261         iterateFilter           --> A pointer to the IterateContainerFilterProc you
1262                                                         want called once for each file and directory found
1263                                                         by FSIterateContainer.
1264         yourDataPtr                     --> An optional pointer to whatever data structure you
1265                                                         might want to access from within the
1266                                                         IterateFilterProc.
1267 */
1268
1269 /*****************************************************************************/
1270
1271 #pragma mark FSGetDirectoryItems
1272
1273 OSErr
1274 FSGetDirectoryItems(
1275         const FSRef *container,
1276         FSRef ***refsHandle,    /* pointer to handle of FSRefs */
1277         ItemCount *numRefs,
1278         Boolean *containerChanged);
1279
1280 /*
1281         The FSGetDirectoryItems function returns the list of items in the specified
1282         container. The array of FSRef records is returned in a Handle, refsHandle,
1283         which is allocated by FSGetDirectoryItems. The caller is responsible for
1284         disposing of refsHandle if the FSGetDirectoryItems returns noErr.
1285
1286         container                       --> FSRef to a directory.
1287         refsHandle                      <-- Pointer to an FSRef Handle where the array of
1288                                                         FSRefs is to be returned.
1289         numRefs                         <-- The number of FSRefs returned in the array.
1290         containerChanged        <-- Set to true if the container changes while the
1291                                                         list of items is being obtained.
1292 */
1293
1294 /*****************************************************************************/
1295
1296 #pragma mark FSExchangeObjectsCompat
1297
1298 OSErr
1299 FSExchangeObjectsCompat(
1300         const FSRef *sourceRef,
1301         const FSRef *destRef,
1302         FSRef *newSourceRef,
1303         FSRef *newDestRef);
1304
1305 /*
1306         The FSExchangeObjectsCompat function exchanges the data between two files.
1307
1308         The FSExchangeObjectsCompat function is an enhanced version of
1309         FSExchangeObjects function. The two enhancements FSExchangeObjectsCompat
1310         provides are:
1311
1312         1,      FSExchangeObjectsCompat will work on volumes which do not support
1313                 FSExchangeObjects. FSExchangeObjectsCompat does this by emulating
1314                 FSExchangeObjects through a series of File Manager operations. If
1315                 there is a failure at any step along the way, FSExchangeObjectsCompat
1316                 attempts to undo any steps already taken to leave the files in their
1317                 original state in their original locations.
1318
1319         2.      FSExchangeObjectsCompat returns new FSRefs to the source and
1320                 destination files. Note that if this function fails at any step along
1321                 the way, newSourceRef and newDestRef still give you access to the final
1322                 locations of the files being exchanged -- even if they are renamed or
1323                 not in their original locations.
1324
1325         sourceRef                       --> FSRef to the source file.
1326         destRef                         --> FSRef to the destination file.
1327         newSourceRef            <-- The new FSRef to the source file.
1328         newDestRef                      <-- The new FSRef to the destination file.
1329 */
1330
1331 /*****************************************************************************/
1332
1333 #pragma mark ----- Shared Environment Routines -----
1334
1335 /*****************************************************************************/
1336
1337 #pragma mark FSLockRange
1338
1339 OSErr
1340 FSLockRange(
1341         SInt16 refNum,
1342         SInt32 rangeLength,
1343         SInt32 rangeStart);
1344
1345 /*
1346         The LockRange function locks (denies access to) a portion of a file
1347         that was opened with shared read/write permission.
1348
1349         refNum                          --> The file reference number of an open file.
1350         rangeLength                     --> The number of bytes in the range.
1351         rangeStart                      --> The starting byte in the range to lock.
1352
1353         __________
1354
1355         Also see:       UnlockRange
1356 */
1357
1358 /*****************************************************************************/
1359
1360 #pragma mark FSUnlockRange
1361
1362 OSErr
1363 FSUnlockRange(
1364         SInt16 refNum,
1365         SInt32 rangeLength,
1366         SInt32 rangeStart);
1367
1368 /*
1369         The UnlockRange function unlocks (allows access to) a previously locked
1370         portion of a file that was opened with shared read/write permission.
1371
1372         refNum                          --> The file reference number of an open file.
1373         rangeLength                     --> The number of bytes in the range.
1374         rangeStart                      --> The starting byte in the range to unlock.
1375
1376         __________
1377
1378         Also see:       LockRange
1379 */
1380
1381 /*****************************************************************************/
1382
1383 #pragma mark FSGetDirAccess
1384
1385 OSErr
1386 FSGetDirAccess(
1387         const FSRef *ref,
1388         SInt32 *ownerID,                /* can be NULL */
1389         SInt32 *groupID,                /* can be NULL */
1390         SInt32 *accessRights);  /* can be NULL */
1391
1392 /*
1393         The FSGetDirAccess function retrieves the directory access control
1394         information for a directory on a shared volume.
1395
1396         ref                                     --> An FSRef specifying the directory.
1397         ownerID                         <** An optional pointer to a SInt32.
1398                                                         If not NULL, the directory's owner ID
1399                                                         will be returned in the SInt32.
1400         groupID                         <** An optional pointer to a SInt32.
1401                                                         If not NULL, the directory's group ID, or 0
1402                                                         if no group affiliation, will be returned in
1403                                                         the SInt32.
1404         accessRights            <** An optional pointer to a SInt32.
1405                                                         If not NULL, the directory's access rights
1406                                                         will be returned in the SInt32.
1407
1408         __________
1409
1410         Also see:       FSSetDirAccess, FSMapID, FSMapName
1411 */
1412
1413 /*****************************************************************************/
1414
1415 #pragma mark FSSetDirAccess
1416
1417 OSErr
1418 FSSetDirAccess(
1419         const FSRef *ref,
1420         SInt32 ownerID,
1421         SInt32 groupID,
1422         SInt32 accessRights);
1423
1424 /*
1425         The FSpSetDirAccess function changes the directory access control
1426         information for a directory on a shared volume. You must be the owner of
1427         a directory to change its access control information.
1428
1429         ref                                     --> An FSRef specifying the directory.
1430         ownerID                         --> The directory's owner ID.
1431         groupID                         --> The directory's group ID or 0 if no group affiliation.
1432         accessRights            --> The directory's access rights.
1433
1434         __________
1435
1436         Also see:       FSGetDirAccess, FSMapID, FSMapName
1437 */
1438
1439 /*****************************************************************************/
1440
1441 #pragma mark FSGetVolMountInfoSize
1442
1443 OSErr
1444 FSGetVolMountInfoSize(
1445         FSVolumeRefNum volRefNum,
1446         SInt16 *size);
1447
1448 /*
1449         The FSGetVolMountInfoSize function determines the how much space the
1450         program needs to allocate for a volume mounting information record.
1451
1452         volRefNum                       --> Volume specification.
1453         size                            <-- The space needed (in bytes) of the volume
1454                                                         mounting information record.
1455
1456         __________
1457
1458         Also see:       FSGetVolMountInfo, VolumeMount
1459 */
1460
1461 /*****************************************************************************/
1462
1463 #pragma mark FSGetVolMountInfo
1464
1465 OSErr
1466 FSGetVolMountInfo(
1467         FSVolumeRefNum volRefNum,
1468         void *volMountInfo);
1469
1470 /*
1471         The FSGetVolMountInfo function retrieves a volume mounting information
1472         record containing all the information needed to mount the volume,
1473         except for passwords.
1474
1475         volRefNum                       --> Volume specification.
1476         volMountInfo            <-- The volume mounting information.
1477
1478         __________
1479
1480         Also see:       FSGetVolMountInfoSize, VolumeMount
1481 */
1482
1483 /*****************************************************************************/
1484
1485 #pragma mark FSVolumeMount
1486
1487 OSErr
1488 FSVolumeMount(
1489         const void *volMountInfo,
1490         FSVolumeRefNum *volRefNum);
1491
1492 /*
1493         The VolumeMount function mounts a volume using a volume mounting
1494         information record.
1495
1496         volMountInfo            --> A volume mounting information record.
1497         volRefNum                       <-- The volume reference number.
1498
1499         __________
1500
1501         Also see:       FSGetVolMountInfoSize, FSGetVolMountInfo
1502 */
1503
1504 /*****************************************************************************/
1505
1506 #pragma mark FSMapID
1507
1508 OSErr
1509 FSMapID(
1510         FSVolumeRefNum volRefNum,
1511         SInt32 ugID,
1512         SInt16 objType,
1513         Str31 name);
1514
1515 /*
1516         The FSMapID function determines the name of a user or group if you know
1517         the user or group ID.
1518
1519         volRefNum                       --> Volume specification.
1520         objType                         --> The mapping function code:
1521                                                         kOwnerID2Name to map a user ID to a user name
1522                                                         kGroupID2Name to map a group ID to a group name
1523         name                            <** An optional pointer to a buffer (minimum Str31).
1524                                                         If not NULL, the user or group name
1525                                                         will be returned in the buffer.
1526
1527         __________
1528
1529         Also see:       FSGetDirAccess, FSSetDirAccess, FSMapName
1530 */
1531
1532 /*****************************************************************************/
1533
1534 #pragma mark FSMapName
1535
1536 OSErr
1537 FSMapName(
1538         FSVolumeRefNum volRefNum,
1539         ConstStr255Param name,
1540         SInt16 objType,
1541         SInt32 *ugID);
1542
1543 /*
1544         The FSMapName function determines the user or group ID if you know the
1545         user or group name.
1546
1547         volRefNum                       --> Volume specification.
1548         name                            --> The user or group name.
1549         objType                         --> The mapping function code:
1550                                                         kOwnerName2ID to map a user name to a user ID
1551                                                         kGroupName2ID to map a user name to a group ID
1552         ugID                            <-- The user or group ID.
1553
1554         __________
1555
1556         Also see:       FSGetDirAccess, FSSetDirAccess, FSMapID
1557 */
1558
1559 /*****************************************************************************/
1560
1561 #pragma mark FSCopyFile
1562
1563 OSErr
1564 FSCopyFile(
1565         const FSRef *srcFileRef,
1566         const FSRef *dstDirectoryRef,
1567         UniCharCount nameLength,
1568         const UniChar *copyName,        /* can be NULL (no rename during copy) */
1569         TextEncoding textEncodingHint,
1570         FSRef *newRef);                         /* can be NULL */
1571
1572 /*
1573         The FSCopyFile function duplicates a file and optionally renames it.
1574         The source and destination volumes must be on the same file server.
1575         This function instructs the server to copy the file.
1576
1577         srcFileRef                      --> An FSRef specifying the source file.
1578         dstDirectoryRef         --> An FSRef specifying the destination directory.
1579         nameLength                      --> Number of UniChar in copyName parameter (ignored
1580                                                         if copyName is NULL).
1581         copyName                        --> Points to the new file name if the file is to be
1582                                                         renamed, or NULL if the file isn't to be renamed.
1583         textEncodingHint        --> The text encoding hint used for the rename.
1584                                                         You can pass kTextEncodingUnknown to use the
1585                                                         "default" textEncodingHint.
1586         newRef                          <** An optional pointer to a FSRef.
1587                                                         If not NULL, the FSRef of the duplicated file
1588                                                         will be returned in the FSRef.
1589 */
1590
1591 /*****************************************************************************/
1592
1593 #pragma mark FSMoveRename
1594
1595 OSErr
1596 FSMoveRename(
1597         const FSRef *srcFileRef,
1598         const FSRef *dstDirectoryRef,
1599         UniCharCount nameLength,
1600         const UniChar *moveName,        /* can be NULL (no rename during move) */
1601         TextEncoding textEncodingHint,
1602         FSRef *newRef);                         /* can be NULL */
1603
1604 /*
1605         The FSMoveRename function moves a file or directory (object), and
1606         optionally renames it. The source and destination locations must be on
1607         the same shared volume.
1608
1609         srcFileRef                      --> An FSRef specifying the source file.
1610         dstDirectoryRef         --> An FSRef specifying the destination directory.
1611         nameLength                      --> Number of UniChar in moveName parameter (ignored
1612                                                         if copyName is NULL)
1613         moveName                        --> Points to the new object name if the object is to be
1614                                                         renamed, or NULL if the object isn't to be renamed.
1615         textEncodingHint        --> The text encoding hint used for the rename.
1616                                                         You can pass kTextEncodingUnknown to use the
1617                                                         "default" textEncodingHint.
1618         newRef                          <** An optional pointer to a FSRef.
1619                                                         If not NULL, the FSRef of the moved object
1620                                                         will be returned in the FSRef.
1621 */
1622
1623 /*****************************************************************************/
1624
1625 #pragma mark ----- File ID Routines -----
1626
1627 /*****************************************************************************/
1628
1629 #pragma mark FSResolveFileIDRef
1630
1631 OSErr
1632 FSResolveFileIDRef(
1633         FSVolumeRefNum volRefNum,
1634         SInt32 fileID,
1635         FSRef *ref);
1636
1637 /*
1638         The FSResolveFileIDRef function returns an FSRef for the file with the
1639         specified file ID reference.
1640
1641         volRefNum                       --> Volume specification.
1642         fileID                          --> The file ID reference.
1643         ref                                     <-- The FSRef for the file ID reference.
1644
1645         __________
1646
1647         Also see:       FSCreateFileIDRef, FSDeleteFileIDRef
1648 */
1649
1650 /*****************************************************************************/
1651
1652 #pragma mark FSCreateFileIDRef
1653
1654 OSErr
1655 FSCreateFileIDRef(
1656         const FSRef *ref,
1657         SInt32 *fileID);
1658
1659 /*
1660         The FSCreateFileIDRef function creates a file ID reference for the
1661         specified file, or if a file ID reference already exists, supplies
1662         the file ID reference and returns the result code fidExists or afpIDExists.
1663
1664         ref                                     --> The FSRef for the file.
1665         fileID                          <-- The file ID reference (if result is noErr,
1666                                                         fidExists, or afpIDExists).
1667
1668         __________
1669
1670         Also see:       GetFSRefFromFileIDRef, FSDeleteFileIDRef
1671 */
1672
1673 /*****************************************************************************/
1674
1675 #pragma mark FSDeleteFileIDRef
1676
1677 /*
1678         Why is there no FSDeleteFileIDRef routine? There are two reasons:
1679
1680         1.      Since Mac OS 8.1, PBDeleteFileIDRef hasn't deleted file ID references.
1681                 On HFS volumes, deleting a file ID reference breaks aliases (which
1682                 use file ID references to track files as they are moved around on a
1683                 volume) and file ID references are automatically deleted when the file
1684                 they refer to is deleted. On HFS Plus volumes, file ID references are
1685                 always created when a file is created, deleted when the file is deleted,
1686                 and cannot be deleted at any other time.
1687
1688         2.      PBDeleteFileIDRef causes a memory access fault under Mac OS X 10.0
1689                 through 10.1.x. While this will be fixed in a future release, the
1690                 implementation, like the Mac OS 8/9 implementation, does not delete
1691                 file ID references.
1692
1693         __________
1694
1695         Also see:       GetFSRefFromFileIDRef, FSCreateFileIDRef
1696 */
1697
1698 /*****************************************************************************/
1699
1700 #pragma mark ----- Utility Routines -----
1701
1702 /*****************************************************************************/
1703
1704 #pragma mark GetTempBuffer
1705
1706 Ptr
1707 GetTempBuffer(
1708         ByteCount buffReqSize,
1709         ByteCount *buffActSize);
1710
1711 /*
1712         The GetTempBuffer function allocates a temporary buffer for file system
1713         operations which is at least 4K bytes and a multiple of 4K bytes.
1714
1715         buffReqSize                     --> Size you'd like the buffer to be.
1716         buffActSize                     <-- The size of the buffer allocated.
1717         function result         <-- Pointer to memory allocated, or NULL if no memory
1718                                                         was available. The caller is responsible for
1719                                                         disposing of this buffer with DisposePtr.
1720 */
1721
1722 /*****************************************************************************/
1723
1724 #pragma mark FileRefNumGetFSRef
1725
1726 OSErr
1727 FileRefNumGetFSRef(
1728         short refNum,
1729         FSRef *ref);
1730
1731 /*
1732         The FileRefNumGetFSRef function gets the FSRef of an open file.
1733
1734         refNum                          --> The file reference number of an open file.
1735         ref                                     <-- The FSRef to the open file.
1736 */
1737
1738 /*****************************************************************************/
1739
1740 #pragma mark FSSetDefault
1741
1742 OSErr
1743 FSSetDefault(
1744         const FSRef *newDefault,
1745         FSRef *oldDefault);
1746
1747 /*
1748         The FSSetDefault function sets the current working directory to the
1749         directory specified by newDefault. The previous current working directory
1750         is returned in oldDefault and must be used to restore the current working
1751         directory to its previous state with the FSRestoreDefault function.
1752         These two functions are designed to be used as a wrapper around
1753         Standard I/O routines where the location of the file is implied to be the
1754         current working directory. This is how you should use these functions:
1755
1756                 result = FSSetDefault(&newDefault, &oldDefault);
1757                 if ( noErr == result )
1758                 {
1759                         // call the Stdio functions like remove, rename,
1760                         // fopen, freopen, etc here!
1761
1762                         result = FSRestoreDefault(&oldDefault);
1763                 }
1764
1765         newDefault                      --> An FSRef that specifies the new current working
1766                                                         directory.
1767         oldDefault                      <-- The previous current working directory's FSRef.
1768
1769         __________
1770
1771         Also see:       FSRestoreDefault
1772 */
1773
1774 /*****************************************************************************/
1775
1776 #pragma mark FSRestoreDefault
1777
1778 OSErr
1779 FSRestoreDefault(
1780         const FSRef *oldDefault);
1781
1782 /*
1783         The FSRestoreDefault function restores the current working directory
1784         to the directory specified by oldDefault. The oldDefault parameter was
1785         previously obtained from the FSSetDefault function.
1786         These two functions are designed to be used as a wrapper around
1787         Standard I/O routines where the location of the file is implied to be the
1788         current working directory. This is how you should use these functions:
1789
1790                 result = FSSetDefault(&newDefault, &oldDefault);
1791                 if ( noErr == result )
1792                 {
1793                         // call the Stdio functions like remove, rename,
1794                         // fopen, freopen, etc here!
1795
1796                         result = FSRestoreDefault(&oldDefault);
1797                 }
1798
1799         oldDefault                      --> The FSRef of the location to restore.
1800
1801         __________
1802
1803         Also see:       FSSetDefault
1804 */
1805
1806 /*****************************************************************************/
1807
1808 #if PRAGMA_STRUCT_ALIGN
1809         #pragma options align=reset
1810 #elif PRAGMA_STRUCT_PACKPUSH
1811         #pragma pack(pop)
1812 #elif PRAGMA_STRUCT_PACK
1813         #pragma pack()
1814 #endif
1815
1816 #ifdef PRAGMA_IMPORT_OFF
1817 #pragma import off
1818 #elif PRAGMA_IMPORT
1819 #pragma import reset
1820 #endif
1821
1822 #ifdef __cplusplus
1823 }
1824 #endif
1825
1826 #endif /* __MOREFILESX__ */
1827
1828