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