Source/MoreFilesX.h

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