MoreFilesX.h

Go to the documentation of this file.
00001 /*
00002 File:       MoreFilesX.h
00003 
00004 Abstract:   A collection of useful high-level File Manager routines which use
00005             the HFS Plus APIs wherever possible.
00006 
00007 Version:    1.0.2
00008 
00009 Disclaimer: IMPORTANT:  This Apple software is supplied to you by Apple
00010 Computer, Inc. ("Apple") in consideration of your agreement to the
00011 following terms, and your use, installation, modification or
00012 redistribution of this Apple software constitutes acceptance of these
00013 terms.  If you do not agree with these terms, please do not use,
00014 install, modify or redistribute this Apple software.
00015 
00016 In consideration of your agreement to abide by the following terms, and
00017 subject to these terms, Apple grants you a personal, non-exclusive
00018 license, under Apple's copyrights in this original Apple software (the
00019 "Apple Software"), to use, reproduce, modify and redistribute the Apple
00020 Software, with or without modifications, in source and/or binary forms;
00021 provided that if you redistribute the Apple Software in its entirety and
00022 without modifications, you must retain this notice and the following
00023 text and disclaimers in all such redistributions of the Apple Software. 
00024 Neither the name, trademarks, service marks or logos of Apple Computer,
00025 Inc. may be used to endorse or promote products derived from the Apple
00026 Software without specific prior written permission from Apple.  Except
00027 as expressly stated in this notice, no other rights or licenses, express
00028 or implied, are granted by Apple herein, including but not limited to
00029 any patent rights that may be infringed by your derivative works or by
00030 other works in which the Apple Software may be incorporated.
00031 
00032 The Apple Software is provided by Apple on an "AS IS" basis.  APPLE
00033 MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION
00034 THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS
00035 FOR A PARTICULAR PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND
00036 OPERATION ALONE OR IN COMBINATION WITH YOUR PRODUCTS.
00037 
00038 IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL
00039 OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
00040 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00041 INTERRUPTION) ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION,
00042 MODIFICATION AND/OR DISTRIBUTION OF THE APPLE SOFTWARE, HOWEVER CAUSED
00043 AND WHETHER UNDER THEORY OF CONTRACT, TORT (INCLUDING NEGLIGENCE),
00044 STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN ADVISED OF THE
00045 POSSIBILITY OF SUCH DAMAGE.
00046 
00047 Copyright  1992-2005 Apple Computer, Inc., All Rights Reserved
00048 
00049 For bug reports, consult the following page on the World Wide Web:
00050     <http://developer.apple.com/bugreporter/>
00051 
00052 Change History (most recent first):
00053 
00054     <4> 18 Dec 2004 <rdar://problem/3926695>
00055                     Replaced FSLockRange and FSUnlockRange with
00056                     FSLockRangeCompat and FSUnlockRangeCompat.
00057     <3> 19 Apr 2002 <rdar://problem/2853905>
00058                     Fixed #if test around header includes.
00059     <2> 19 Apr 2002 <rdar://problem/2853901>
00060                     Updated standard disclaimer.
00061     <1> 25 Jan 2002 MoreFilesX 1.0
00062     
00063 Notes:
00064     What do those arrows in the documentation for each routine mean?
00065         
00066         --> The parameter is an input
00067         
00068         <-- The parameter is an output. The pointer to the variable
00069             where the output will be returned (must not be NULL).
00070         
00071         <** The parameter is an optional output. If it is not a
00072             NULL pointer, it points to the variable where the output
00073             will be returned. If it is a NULL pointer, the output will
00074             not be returned and will possibly let the routine and the
00075             File Manager do less work. If you don't need an optional output,
00076             don't ask for it.
00077         **> The parameter is an optional input. If it is not a
00078             NULL pointer, it points to the variable containing the
00079             input data. If it is a NULL pointer, the input is not used
00080             and will possibly let the routine and the File Manager
00081             do less work.
00082 */
00083 
00084 #ifndef __MOREFILESX__
00085 #define __MOREFILESX__
00086 
00087 #ifndef __CARBON__
00088     #if defined(__MACH__)
00089         #include <Carbon/Carbon.h>
00090     #else
00091         #include <Carbon.h>
00092     #endif
00093 #endif
00094 
00095 #if PRAGMA_ONCE
00096 #pragma once
00097 #endif
00098 
00099 #ifdef __cplusplus
00100 extern "C" {
00101 #endif
00102 
00103 #if PRAGMA_IMPORT
00104 #pragma import on
00105 #endif
00106 
00107 #if PRAGMA_STRUCT_ALIGN
00108     #pragma options align=mac68k
00109 #elif PRAGMA_STRUCT_PACKPUSH
00110     #pragma pack(push, 2)
00111 #elif PRAGMA_STRUCT_PACK
00112     #pragma pack(2)
00113 #endif
00114 
00115 /*****************************************************************************/
00116 
00117 #pragma mark ----- FinderInfo and ExtendedFinderInfo -----
00118 
00119 /*
00120  *  FSGetFinderInfo and FSSetFinderInfo use these unions for Finder information.
00121  */
00122 
00123 union FinderInfo
00124 {
00125   FileInfo              file;
00126   FolderInfo            folder;
00127 };
00128 typedef union FinderInfo FinderInfo;
00129 
00130 union ExtendedFinderInfo
00131 {
00132   ExtendedFileInfo      file;
00133   ExtendedFolderInfo    folder;
00134 };
00135 typedef union ExtendedFinderInfo ExtendedFinderInfo;
00136 
00137 /*****************************************************************************/
00138 
00139 #pragma mark ----- GetVolParmsInfoBuffer Macros -----
00140 
00141 /*
00142  *  Macros to get information out of GetVolParmsInfoBuffer.
00143  */
00144 
00145 /* version 1 field getters */
00146 #define GetVolParmsInfoVersion(volParms) \
00147         ((volParms)->vMVersion)
00148 #define GetVolParmsInfoAttrib(volParms) \
00149         ((volParms)->vMAttrib)
00150 #define GetVolParmsInfoLocalHand(volParms) \
00151         ((volParms)->vMLocalHand)
00152 #define GetVolParmsInfoServerAdr(volParms) \
00153         ((volParms)->vMServerAdr)
00154 
00155 /* version 2 field getters (assume zero result if version < 2) */
00156 #define GetVolParmsInfoVolumeGrade(volParms) \
00157         (((volParms)->vMVersion >= 2) ? (volParms)->vMVolumeGrade : 0)
00158 #define GetVolParmsInfoForeignPrivID(volParms) \
00159         (((volParms)->vMVersion >= 2) ? (volParms)->vMForeignPrivID : 0)
00160 
00161 /* version 3 field getters (assume zero result if version < 3) */
00162 #define GetVolParmsInfoExtendedAttributes(volParms) \
00163         (((volParms)->vMVersion >= 3) ? (volParms)->vMExtendedAttributes : 0)
00164 
00165 /* attribute bits supported by all versions of GetVolParmsInfoBuffer */
00166 #define VolIsNetworkVolume(volParms) \
00167         ((volParms)->vMServerAdr != 0)
00168 #define VolHasLimitFCBs(volParms) \
00169         (((volParms)->vMAttrib & (1L << bLimitFCBs)) != 0)
00170 #define VolHasLocalWList(volParms) \
00171         (((volParms)->vMAttrib & (1L << bLocalWList)) != 0)
00172 #define VolHasNoMiniFndr(volParms) \
00173         (((volParms)->vMAttrib & (1L << bNoMiniFndr)) != 0)
00174 #define VolHasNoVNEdit(volParms) \
00175         (((volParms)->vMAttrib & (1L << bNoVNEdit)) != 0)
00176 #define VolHasNoLclSync(volParms) \
00177         (((volParms)->vMAttrib & (1L << bNoLclSync)) != 0)
00178 #define VolHasTrshOffLine(volParms) \
00179         (((volParms)->vMAttrib & (1L << bTrshOffLine)) != 0)
00180 #define VolHasNoSwitchTo(volParms) \
00181         (((volParms)->vMAttrib & (1L << bNoSwitchTo)) != 0)
00182 #define VolHasNoDeskItems(volParms) \
00183         (((volParms)->vMAttrib & (1L << bNoDeskItems)) != 0)
00184 #define VolHasNoBootBlks(volParms) \
00185         (((volParms)->vMAttrib & (1L << bNoBootBlks)) != 0)
00186 #define VolHasAccessCntl(volParms) \
00187         (((volParms)->vMAttrib & (1L << bAccessCntl)) != 0)
00188 #define VolHasNoSysDir(volParms) \
00189         (((volParms)->vMAttrib & (1L << bNoSysDir)) != 0)
00190 #define VolHasExtFSVol(volParms) \
00191         (((volParms)->vMAttrib & (1L << bHasExtFSVol)) != 0)
00192 #define VolHasOpenDeny(volParms) \
00193         (((volParms)->vMAttrib & (1L << bHasOpenDeny)) != 0)
00194 #define VolHasCopyFile(volParms) \
00195         (((volParms)->vMAttrib & (1L << bHasCopyFile)) != 0)
00196 #define VolHasMoveRename(volParms) \
00197         (((volParms)->vMAttrib & (1L << bHasMoveRename)) != 0)
00198 #define VolHasDesktopMgr(volParms) \
00199         (((volParms)->vMAttrib & (1L << bHasDesktopMgr)) != 0)
00200 #define VolHasShortName(volParms) \
00201         (((volParms)->vMAttrib & (1L << bHasShortName)) != 0)
00202 #define VolHasFolderLock(volParms) \
00203         (((volParms)->vMAttrib & (1L << bHasFolderLock)) != 0)
00204 #define VolHasPersonalAccessPrivileges(volParms) \
00205         (((volParms)->vMAttrib & (1L << bHasPersonalAccessPrivileges)) != 0)
00206 #define VolHasUserGroupList(volParms) \
00207         (((volParms)->vMAttrib & (1L << bHasUserGroupList)) != 0)
00208 #define VolHasCatSearch(volParms) \
00209         (((volParms)->vMAttrib & (1L << bHasCatSearch)) != 0)
00210 #define VolHasFileIDs(volParms) \
00211         (((volParms)->vMAttrib & (1L << bHasFileIDs)) != 0)
00212 #define VolHasBTreeMgr(volParms) \
00213         (((volParms)->vMAttrib & (1L << bHasBTreeMgr)) != 0)
00214 #define VolHasBlankAccessPrivileges(volParms) \
00215         (((volParms)->vMAttrib & (1L << bHasBlankAccessPrivileges)) != 0)
00216 #define VolSupportsAsyncRequests(volParms) \
00217         (((volParms)->vMAttrib & (1L << bSupportsAsyncRequests)) != 0)
00218 #define VolSupportsTrashVolumeCache(volParms) \
00219         (((volParms)->vMAttrib & (1L << bSupportsTrashVolumeCache)) != 0)
00220 
00221 /* attribute bits supported by version 3 and greater versions of GetVolParmsInfoBuffer */
00222 #define VolIsEjectable(volParms) \
00223         ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bIsEjectable)) != 0)
00224 #define VolSupportsHFSPlusAPIs(volParms) \
00225         ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsHFSPlusAPIs)) != 0)
00226 #define VolSupportsFSCatalogSearch(volParms) \
00227         ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsFSCatalogSearch)) != 0)
00228 #define VolSupportsFSExchangeObjects(volParms) \
00229         ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsFSExchangeObjects)) != 0)
00230 #define VolSupports2TBFiles(volParms) \
00231         ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupports2TBFiles)) != 0)
00232 #define VolSupportsLongNames(volParms) \
00233         ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsLongNames)) != 0)
00234 #define VolSupportsMultiScriptNames(volParms) \
00235         ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsMultiScriptNames)) != 0)
00236 #define VolSupportsNamedForks(volParms) \
00237         ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsNamedForks)) != 0)
00238 #define VolSupportsSubtreeIterators(volParms) \
00239         ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsSubtreeIterators)) != 0)
00240 #define VolL2PCanMapFileBlocks(volParms) \
00241         ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bL2PCanMapFileBlocks)) != 0)
00242 #define VolParentModDateChanges(volParms) \
00243         ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bParentModDateChanges)) != 0)
00244 #define VolAncestorModDateChanges(volParms) \
00245         ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bAncestorModDateChanges)) != 0)
00246 #define VolSupportsSymbolicLinks(volParms) \
00247         ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bSupportsSymbolicLinks)) != 0)
00248 #define VolIsAutoMounted(volParms) \
00249         ((GetVolParmsInfoExtendedAttributes(volParms) & (1L << bIsAutoMounted)) != 0)
00250 
00251 /*****************************************************************************/
00252 
00253 #pragma mark ----- userPrivileges Bit Masks and Macros -----
00254 
00255 /*
00256  *  Bit masks and macros to get common information out of userPrivileges byte
00257  *  returned by FSGetCatalogInfo.
00258  *
00259  *  Note:   The userPrivileges byte is the same as the ioACUser byte returned
00260  *          by PBGetCatInfo, and is the 1's complement of the user's privileges
00261  *          byte returned in ioACAccess by PBHGetDirAccess. That's where the
00262  *          ioACUser names came from.
00263  *
00264  *          The userPrivileges are user's effective privileges based on the
00265  *          user ID and the groups that user belongs to, and the owner, group,
00266  *          and everyone privileges for the given directory.
00267  */
00268 
00269 enum
00270 {
00271     /* mask for just the access restriction bits */
00272     kioACUserAccessMask     = (kioACUserNoSeeFolderMask +
00273                                kioACUserNoSeeFilesMask +
00274                                kioACUserNoMakeChangesMask),
00275     /* common access privilege settings */
00276     kioACUserFull           = 0x00, /* no access restiction bits on */
00277     kioACUserNone           = kioACUserAccessMask, /* all access restiction bits on */
00278     kioACUserDropBox        = (kioACUserNoSeeFolderMask +
00279                                kioACUserNoSeeFilesMask), /* make changes, but not see files or folders */
00280     kioACUserBulletinBoard  = kioACUserNoMakeChangesMask /* see files and folders, but not make changes */
00281 };
00282 
00283 
00284 /* Macros for testing ioACUser bits. */
00285 
00286 #define UserIsOwner(userPrivileges) \
00287         (((userPrivileges) & kioACUserNotOwnerMask) == 0)
00288 #define UserHasFullAccess(userPrivileges)   \
00289         (((userPrivileges) & (kioACUserAccessMask)) == kioACUserFull)
00290 #define UserHasDropBoxAccess(userPrivileges)    \
00291         (((userPrivileges) & kioACUserAccessMask) == kioACUserDropBox)
00292 #define UserHasBulletinBoard(userPrivileges)    \
00293         (((userPrivileges) & kioACUserAccessMask) == kioACUserBulletinBoard)
00294 #define UserHasNoAccess(userPrivileges)     \
00295         (((userPrivileges) & kioACUserAccessMask) == kioACUserNone)
00296 
00297 /*****************************************************************************/
00298 
00299 #pragma mark ----- File Access Routines -----
00300 
00301 /*****************************************************************************/
00302 
00303 #pragma mark FSCopyFork
00304 
00305 OSErr
00306 FSCopyFork(
00307     SInt16 srcRefNum,
00308     SInt16 dstRefNum,
00309     void *copyBufferPtr,
00310     ByteCount copyBufferSize);
00311 
00312 /*
00313     The FSCopyFork function copies all data from the source fork to the
00314     destination fork of open file forks and makes sure the destination EOF
00315     is equal to the source EOF.
00316 
00317     srcRefNum           --> The source file reference number.
00318     dstRefNum           --> The destination file reference number.
00319     copyBufferPtr       --> Pointer to buffer to use during copy. The
00320                             buffer should be at least 4K-bytes minimum.
00321                             The larger the buffer, the faster the copy
00322                             (up to a point).
00323     copyBufferSize      --> The size of the copy buffer.
00324 */
00325 
00326 /*****************************************************************************/
00327 
00328 #pragma mark ----- Volume Access Routines -----
00329 
00330 /*****************************************************************************/
00331 
00332 #pragma mark FSGetVolParms
00333 
00334 OSErr
00335 FSGetVolParms(
00336     FSVolumeRefNum volRefNum,
00337     UInt32 bufferSize,
00338     GetVolParmsInfoBuffer *volParmsInfo,
00339     UInt32 *actualInfoSize);
00340 
00341 /*
00342     The FSGetVolParms function returns information about the characteristics
00343     of a volume. A result of paramErr usually just means the volume doesn't
00344     support GetVolParms and the feature you were going to check
00345     for isn't available.
00346     
00347     volRefNum           --> Volume specification.
00348     bufferSize          --> Size of buffer pointed to by volParmsInfo.
00349     volParmsInfo        <-- A GetVolParmsInfoBuffer record where the volume
00350                             attributes information is returned.
00351     actualInfoSize      <-- The number of bytes actually returned
00352                             in volParmsInfo.
00353     
00354     __________
00355     
00356     Also see:   The GetVolParmsInfoBuffer Macros for checking attribute bits
00357                 in this file
00358 */
00359 
00360 /*****************************************************************************/
00361 
00362 #pragma mark FSGetVRefNum
00363 
00364 OSErr
00365 FSGetVRefNum(
00366     const FSRef *ref,
00367     FSVolumeRefNum *vRefNum);
00368 
00369 /*
00370     The FSGetVRefNum function determines the volume reference
00371     number of a volume from a FSRef.
00372 
00373     ref                 --> The FSRef.
00374     vRefNum             <-- The volume reference number.
00375 */
00376 
00377 /*****************************************************************************/
00378 
00379 #pragma mark FSGetVInfo
00380 
00381 OSErr
00382 FSGetVInfo(
00383     FSVolumeRefNum volume,
00384     HFSUniStr255 *volumeName,   /* can be NULL */
00385     UInt64 *freeBytes,          /* can be NULL */
00386     UInt64 *totalBytes);        /* can be NULL */
00387 
00388 /*
00389     The FSGetVInfo function returns the name, available space (in bytes),
00390     and total space (in bytes) for the specified volume.
00391 
00392     volume              --> The volume reference number.
00393     volumeName          <** An optional pointer to a HFSUniStr255.
00394                             If not NULL, the volume name will be returned in
00395                             the HFSUniStr255.
00396     freeBytes           <** An optional pointer to a UInt64.
00397                             If not NULL, the number of free bytes on the
00398                             volume will be returned in the UInt64.
00399     totalBytes          <** An optional pointer to a UInt64.
00400                             If not NULL, the total number of bytes on the
00401                             volume will be returned in the UInt64.
00402 */
00403 
00404 /*****************************************************************************/
00405 
00406 #pragma mark FSGetVolFileSystemID
00407 
00408 OSErr
00409 FSGetVolFileSystemID(
00410     FSVolumeRefNum volume,
00411     UInt16 *fileSystemID,   /* can be NULL */
00412     UInt16 *signature);     /* can be NULL */
00413 
00414 /*
00415     The FSGetVolFileSystemID function returns the file system ID and signature
00416     of a mounted volume. The file system ID identifies the file system
00417     that handles requests to a particular volume. The signature identifies the
00418     volume type of the volume (for example, FSID 0 is Macintosh HFS Plus, HFS
00419     or MFS, where a signature of 0x4244 identifies the volume as HFS).
00420     Here's a partial list of file system ID numbers (only Apple's file systems
00421     are listed):
00422         FSID    File System
00423         -----   -----------------------------------------------------
00424         $0000   Macintosh HFS Plus, HFS or MFS
00425         $0100   ProDOS File System
00426         $0101   PowerTalk Mail Enclosures
00427         $4147   ISO 9660 File Access (through Foreign File Access)
00428         $4242   High Sierra File Access (through Foreign File Access)
00429         $464D   QuickTake File System (through Foreign File Access)
00430         $4953   Macintosh PC Exchange (MS-DOS)
00431         $4A48   Audio CD Access (through Foreign File Access)
00432         $4D4B   Apple Photo Access (through Foreign File Access)
00433         $6173   AppleShare (later versions of AppleShare only)
00434     
00435     See the Technical Note "FL 35 - Determining Which File System
00436     Is Active" and the "Guide to the File System Manager" for more
00437     information.
00438     
00439     volume              --> The volume reference number.
00440     fileSystemID        <** An optional pointer to a UInt16.
00441                             If not NULL, the volume's file system ID will
00442                             be returned in the UInt16.
00443     signature           <** An optional pointer to a UInt16.
00444                             If not NULL, the volume's signature will
00445                             be returned in the UInt16.
00446 */
00447 
00448 /*****************************************************************************/
00449 
00450 #pragma mark FSGetMountedVolumes
00451 
00452 OSErr
00453 FSGetMountedVolumes(
00454     FSRef ***volumeRefsHandle,  /* pointer to handle of FSRefs */
00455     ItemCount *numVolumes);
00456 
00457 /*
00458     The FSGetMountedVolumes function returns the list of volumes currently
00459     mounted in an array of FSRef records. The array of FSRef records is
00460     returned in a Handle, volumeRefsHandle, which is allocated by
00461     FSGetMountedVolumes. The caller is responsible for disposing of
00462     volumeRefsHandle if the FSGetMountedVolumes returns noErr.
00463         
00464     volumeRefsHandle    <-- Pointer to an FSRef Handle where the array of
00465                             FSRefs is to be returned.
00466     numVolumes          <-- The number of volumes returned in the array.
00467 */
00468 
00469 /*****************************************************************************/
00470 
00471 #pragma mark ----- FSRef/FSpec/Path/Name Conversion Routines -----
00472 
00473 /*****************************************************************************/
00474 
00475 #pragma mark FSRefMakeFSSpec
00476 
00477 OSErr
00478 FSRefMakeFSSpec(
00479     const FSRef *ref,
00480     FSSpec *spec);
00481 
00482 /*
00483     The FSRefMakeFSSpec function returns an FSSpec for the file or
00484     directory specified by the ref parameter.
00485 
00486     ref                 --> An FSRef specifying the file or directory.
00487     spec                <-- The FSSpec.
00488 */
00489 
00490 /*****************************************************************************/
00491 
00492 #pragma mark FSMakeFSRef
00493 
00494 OSErr
00495 FSMakeFSRef(
00496     FSVolumeRefNum volRefNum,
00497     SInt32 dirID,
00498     ConstStr255Param name,
00499     FSRef *ref);
00500 
00501 /*
00502     The FSMakeFSRef function creates an FSRef from the traditional
00503     volume reference number, directory ID and pathname inputs. It is
00504     functionally equivalent to FSMakeFSSpec followed by FSpMakeFSRef.
00505     
00506     volRefNum           --> Volume specification.
00507     dirID               --> Directory specification.
00508     name                --> The file or directory name, or NULL.
00509     ref                 <-- The FSRef.
00510 */
00511 
00512 /*****************************************************************************/
00513 
00514 #pragma mark FSMakePath
00515 
00516 OSStatus
00517 FSMakePath(
00518     SInt16 vRefNum,
00519     SInt32 dirID,
00520     ConstStr255Param name,
00521     UInt8 *path,
00522     UInt32 maxPathSize);
00523 
00524 /*
00525     The FSMakePath function creates a pathname from the traditional volume reference
00526     number, directory ID, and pathname inputs. It is functionally equivalent to
00527     FSMakeFSSpec, FSpMakeFSRef, FSRefMakePath.
00528     
00529     volRefNum           --> Volume specification.
00530     dirID               --> Directory specification.
00531     name                --> The file or directory name, or NULL.
00532     path                <-- A pointer to a buffer which FSMakePath will
00533                             fill with a C string representing the pathname
00534                             to the file or directory specified. The format of
00535                             the pathname returned can be determined with the
00536                             Gestalt selector gestaltFSAttr's
00537                             gestaltFSUsesPOSIXPathsForConversion bit.
00538                             If the gestaltFSUsesPOSIXPathsForConversion bit is
00539                             clear, the pathname is a Mac OS File Manager full
00540                             pathname in a C string, and file or directory names
00541                             in the pathname may be mangled as returned by
00542                             the File Manager. If the
00543                             gestaltFSUsesPOSIXPathsForConversion bit is set,
00544                             the pathname is a UTF8 encoded POSIX absolute
00545                             pathname in a C string. In either case, the
00546                             pathname returned can be passed back to
00547                             FSPathMakeRef to create an FSRef to the file or
00548                             directory, or FSPathMakeFSSpec to craete an FSSpec
00549                             to the file or directory.
00550     maxPathSize         --> The size of the path buffer in bytes. If the path
00551                             buffer is too small for the pathname string,
00552                             FSMakePath returns pathTooLongErr or
00553                             buffersTooSmall.
00554 */
00555 
00556 /*****************************************************************************/
00557 
00558 #pragma mark FSPathMakeFSSpec
00559 
00560 OSStatus
00561 FSPathMakeFSSpec(
00562     const UInt8 *path,
00563     FSSpec *spec,
00564     Boolean *isDirectory);  /* can be NULL */
00565 
00566 /*
00567     The FSPathMakeFSSpec function converts a pathname to an FSSpec.
00568     
00569     path                --> A pointer to a C String that is the pathname. The
00570                             format of the pathname you must supply can be
00571                             determined with the Gestalt selector gestaltFSAttr's
00572                             gestaltFSUsesPOSIXPathsForConversion bit.
00573                             If the gestaltFSUsesPOSIXPathsForConversion bit is
00574                             clear, the pathname must be a Mac OS File Manager
00575                             full pathname in a C string. If the
00576                             gestaltFSUsesPOSIXPathsForConversion bit is set,
00577                             the pathname must be a UTF8 encoded POSIX absolute
00578                             pathname in a C string.
00579     spec                <-- The FSSpec.
00580     isDirectory         <** An optional pointer to a Boolean.
00581                             If not NULL, true will be returned in the Boolean
00582                             if the specified path is a directory, or false will
00583                             be returned in the Boolean if the specified path is
00584                             a file.
00585 */
00586 
00587 /*****************************************************************************/
00588 
00589 #pragma mark UnicodeNameGetHFSName
00590 
00591 OSErr
00592 UnicodeNameGetHFSName(
00593     UniCharCount nameLength,
00594     const UniChar *name,
00595     TextEncoding textEncodingHint,
00596     Boolean isVolumeName,
00597     Str31 hfsName);
00598 
00599 /*
00600     The UnicodeNameGetHFSName function converts a Unicode string
00601     to a Pascal Str31 (or Str27) string using an algorithm similar to that used
00602     by the File Manager. Note that if the name is too long or cannot be converted
00603     using the given text encoding hint, you will get an error instead of the
00604     mangled name that the File Manager would return.
00605     
00606     nameLength          --> Number of UniChar in name parameter.
00607     name                --> The Unicode string to convert.
00608     textEncodingHint    --> The text encoding hint used for the conversion.
00609                             You can pass kTextEncodingUnknown to use the
00610                             "default" textEncodingHint.
00611     isVolumeName        --> If true, the output name will be limited to
00612                             27 characters (kHFSMaxVolumeNameChars). If false,
00613                             the output name will be limited to 31 characters
00614                             (kHFSMaxFileNameChars).
00615     hfsName             <-- The hfsName as a Pascal string.
00616     
00617     __________
00618     
00619     Also see:   HFSNameGetUnicodeName
00620 */
00621 
00622 /*****************************************************************************/
00623 
00624 #pragma mark HFSNameGetUnicodeName
00625 
00626 OSErr
00627 HFSNameGetUnicodeName(
00628     ConstStr31Param hfsName,
00629     TextEncoding textEncodingHint,
00630     HFSUniStr255 *unicodeName);
00631 
00632 /*
00633     The HFSNameGetUnicodeName function converts a Pascal Str31 string to an
00634     Unicode HFSUniStr255 string using the same routines as the File Manager.
00635     
00636     hfsName             --> The Pascal string to convert.
00637     textEncodingHint    --> The text encoding hint used for the conversion.
00638                             You can pass kTextEncodingUnknown to use the
00639                             "default" textEncodingHint.
00640     unicodeName         <-- The Unicode string.
00641     
00642     __________
00643     
00644     Also see:   UnicodeNameGetHFSName
00645 */
00646 
00647 /*****************************************************************************/
00648 
00649 #pragma mark ----- File/Directory Manipulation Routines -----
00650 
00651 /*****************************************************************************/
00652 
00653 #pragma mark FSRefValid
00654 
00655 Boolean FSRefValid(const FSRef *ref);
00656 
00657 /*
00658     The FSRefValid function determines if an FSRef is valid. If the result is
00659     true, then the FSRef refers to an existing file or directory.
00660     
00661     ref                 --> FSRef to a file or directory.
00662 */
00663 
00664 /*****************************************************************************/
00665 
00666 #pragma mark FSGetParentRef
00667 
00668 OSErr
00669 FSGetParentRef(
00670     const FSRef *ref,
00671     FSRef *parentRef);
00672 
00673 /*
00674     The FSGetParentRef function gets the parent directory FSRef of the
00675     specified object.
00676     
00677     Note: FSRefs always point to real file system objects. So, there cannot
00678     be a FSRef to the parent of volume root directories. If you call
00679     FSGetParentRef with a ref to the root directory of a volume, the
00680     function result will be noErr and the parentRef will be invalid (using it
00681     for other file system requests will fail).
00682 
00683     ref                 --> FSRef to a file or directory.
00684     parentRef           <-- The parent directory's FSRef.
00685 */
00686 
00687 /*****************************************************************************/
00688 
00689 #pragma mark FSGetFileDirName
00690 
00691 OSErr
00692 FSGetFileDirName(
00693     const FSRef *ref,
00694     HFSUniStr255 *outName);
00695 
00696 /*
00697     The FSGetFileDirName function gets the name of the file or directory
00698     specified.
00699 
00700     ref                 --> FSRef to a file or directory.
00701     outName             <-- The file or directory name.
00702 */
00703 
00704 /*****************************************************************************/
00705 
00706 #pragma mark FSGetNodeID
00707 
00708 OSErr
00709 FSGetNodeID(
00710     const FSRef *ref,
00711     long *nodeID,           /* can be NULL */
00712     Boolean *isDirectory);  /* can be NULL */
00713 
00714 /*
00715     The GetNodeIDFromFSRef function gets the node ID number of the
00716     file or directory specified (note: the node ID is the directory ID
00717     for directories).
00718 
00719     ref                 --> FSRef to a file or directory.
00720     nodeID              <** An optional pointer to a long.
00721                             If not NULL, the node ID will be returned in
00722                             the long.
00723     isDirectory         <** An optional pointer to a Boolean.
00724                             If not NULL, true will be returned in the Boolean
00725                             if the object is a directory, or false will be
00726                             returned in the Boolean if object is a file.
00727 */
00728 
00729 /*****************************************************************************/
00730 
00731 #pragma mark FSGetUserPrivilegesPermissions
00732 
00733 OSErr
00734 FSGetUserPrivilegesPermissions(
00735     const FSRef *ref,
00736     UInt8 *userPrivileges,      /* can be NULL */
00737     UInt32 permissions[4]);     /* can be NULL */
00738 
00739 /*
00740     The FSGetUserPrivilegesPermissions function gets the userPrivileges and/or
00741     permissions of the file or directory specified.
00742 
00743     ref                 --> FSRef to a file or directory.
00744     userPrivileges      <** An optional pointer to a UInt8.
00745                             If not NULL, the userPrivileges will be returned
00746                             in the UInt8.
00747     permissions         <** An optional pointer to an UInt32[4] array.
00748                             If not NULL, the permissions will be returned
00749                             in the UInt32[4] array.
00750 */
00751 
00752 /*****************************************************************************/
00753 
00754 #pragma mark FSCheckLock
00755 
00756 OSErr
00757 FSCheckLock(
00758     const FSRef *ref);
00759 
00760 /*
00761     The FSCheckLock function determines if a file or directory is locked.
00762     If FSCheckLock returns noErr, then the file or directory is not locked
00763     and the volume it is on is not locked either. If FSCheckLock returns
00764     fLckdErr, then the file or directory is locked. If FSCheckLock returns
00765     wPrErr, then the volume is locked by hardware (i.e., locked tab on
00766     removable media). If FSCheckLock returns vLckdErr, then the volume is
00767     locked by software.
00768     
00769     ref                 --> FSRef to a file or directory.
00770 */
00771 
00772 /*****************************************************************************/
00773 
00774 #pragma mark FSGetForkSizes
00775 
00776 OSErr
00777 FSGetForkSizes(
00778     const FSRef *ref,
00779     UInt64 *dataLogicalSize,    /* can be NULL */
00780     UInt64 *rsrcLogicalSize);   /* can be NULL */
00781 
00782 /*
00783     The FSGetForkSizes returns the size of the data and/or resource fork for
00784     the specified file.
00785     
00786     ref                 --> FSRef to a file or directory.
00787     dataLogicalSize     <** An optional pointer to a UInt64.
00788                             If not NULL, the data fork's size will be
00789                             returned in the UInt64.
00790     rsrcLogicalSize     <** An optional pointer to a UInt64.
00791                             If not NULL, the resource fork's size will be
00792                             returned in the UInt64.
00793     
00794     __________
00795     
00796     Also see:   FSGetTotalForkSizes
00797 */
00798 
00799 /*****************************************************************************/
00800 
00801 #pragma mark FSGetTotalForkSizes
00802 
00803 OSErr
00804 FSGetTotalForkSizes(
00805     const FSRef *ref,
00806     UInt64 *totalLogicalSize,   /* can be NULL */
00807     UInt64 *totalPhysicalSize,  /* can be NULL */
00808     ItemCount *forkCount);      /* can be NULL */
00809 
00810 /*
00811     The FSGetTotalForkSizes returns the total logical size and/or the total
00812     physical size of the specified file (i.e., it adds the sizes of all file
00813     forks). It optionally returns the number of file forks.
00814     
00815     ref                 --> FSRef to a file or directory.
00816     totalLogicalSize    <** An optional pointer to a UInt64.
00817                             If not NULL, the sum of all fork logical sizes
00818                             will be returned in the UInt64.
00819     totalPhysicalSize   <** An optional pointer to a UInt64.
00820                             If not NULL, the sum of all fork physical sizes
00821                             will be returned in the UInt64.
00822     forkCount           <** An optional pointer to a ItemCount.
00823                             If not NULL, the number of file forks
00824                             will be returned in the ItemCount.
00825     
00826     __________
00827     
00828     Also see:   FSGetForkSizes
00829 */
00830 
00831 /*****************************************************************************/
00832 
00833 #pragma mark FSBumpDate
00834 
00835 OSErr
00836 FSBumpDate(
00837     const FSRef *ref);
00838 
00839 /*
00840     The FSBumpDate function changes the content modification date of a file
00841     or directory to the current date/time. If the content modification date
00842     is already equal to the current date/time, then add one second to the
00843     content modification date.
00844 
00845     ref                 --> FSRef to a file or directory.
00846 */
00847 
00848 /*****************************************************************************/
00849 
00850 #pragma mark FSGetFinderInfo
00851 
00852 OSErr
00853 FSGetFinderInfo(
00854     const FSRef *ref,
00855     FinderInfo *info,                   /* can be NULL */
00856     ExtendedFinderInfo *extendedInfo,   /* can be NULL */
00857     Boolean *isDirectory);              /* can be NULL */
00858 
00859 /*
00860     The FSGetFinderInfo function gets the finder information for a file or
00861     directory.
00862 
00863     ref                 --> FSRef to a file or directory.
00864     info                <** An optional pointer to a FinderInfo.
00865                             If not NULL, the FileInfo (if ref is a file) or
00866                             the FolderInfo (if ref is a folder) will be
00867                             returned in the FinderInfo.
00868     extendedInfo        <** An optional pointer to a ExtendedFinderInfo.
00869                             If not NULL, the ExtendedFileInfo (if ref is a file)
00870                             or the ExtendedFolderInfo (if ref is a folder) will
00871                             be returned in the ExtendedFinderInfo.
00872     isDirectory         <** An optional pointer to a Boolean.
00873                             If not NULL, true will be returned in the Boolean
00874                             if the object is a directory, or false will be
00875                             returned in the Boolean if object is a file.
00876 
00877     __________
00878 
00879     Also see:   FSSetFinderInfo
00880 */
00881 
00882 /*****************************************************************************/
00883 
00884 #pragma mark FSSetFinderInfo
00885 
00886 OSErr
00887 FSSetFinderInfo(
00888     const FSRef *ref,
00889     const FinderInfo *info,                     /* can be NULL */
00890     const ExtendedFinderInfo *extendedInfo);    /* can be NULL */
00891 
00892 /*
00893     The FSSetFinderInfo function sets the finder information for a file or
00894     directory.
00895 
00896     ref                 --> FSRef to a file or directory.
00897     info                **> A pointer to a FinderInfo record with the new
00898                             FileInfo (if ref is a file) or new FolderInfo
00899                             (if ref is a folder), or NULL if the FinderInfo
00900                             is not to be changed.
00901     extendedInfo        **> A pointer to a FinderInfo record with the new
00902                             ExtendedFileInfo (if ref is a file) or new
00903                             ExtendedFolderInfo (if ref is a folder), or NULL
00904                             if the ExtendedFinderInfo is not to be changed.
00905         
00906     __________
00907 
00908     Also see:   FSGetFinderInfo
00909 */
00910 
00911 /*****************************************************************************/
00912 
00913 #pragma mark FSChangeCreatorType
00914 
00915 OSErr
00916 FSChangeCreatorType(
00917     const FSRef *ref,
00918     OSType fileCreator,
00919     OSType fileType);
00920 
00921 /*
00922     The FSChangeCreatorType function changes the creator and/or file type of a file.
00923 
00924     ref                 --> FSRef to a file.
00925     creator             --> The new creator type or 0x00000000 to leave
00926                             the creator type alone.
00927     fileType            --> The new file type or 0x00000000 to leave the
00928                             file type alone.
00929 */
00930 
00931 /*****************************************************************************/
00932 
00933 #pragma mark FSChangeFinderFlags
00934 
00935 OSErr
00936 FSChangeFinderFlags(
00937     const FSRef *ref,
00938     Boolean setBits,
00939     UInt16 flagBits);
00940 
00941 /*
00942     The FSChangeFinderFlags function sets or clears flag bits in
00943     the finderFlags field of a file's FileInfo record or a
00944     directory's FolderInfo record.
00945 
00946     ref                 --> FSRef to a file or directory.
00947     setBits             --> If true, then set the bits specified in flagBits.
00948                             If false, then clear the bits specified in flagBits.
00949     flagBits            --> The flagBits parameter specifies which Finder Flag
00950                             bits to set or clear. If a bit in flagBits is set,
00951                             then the same bit in fdFlags is either set or
00952                             cleared depending on the state of the setBits
00953                             parameter.
00954 */
00955 
00956 /*****************************************************************************/
00957 
00958 #pragma mark FSSetInvisible
00959 
00960 OSErr
00961 FSSetInvisible(
00962     const FSRef *ref);
00963 
00964 #pragma mark FSClearInvisible
00965 
00966 OSErr
00967 FSClearInvisible(
00968     const FSRef *ref);
00969 
00970 /*
00971     The FSSetInvisible and FSClearInvisible functions set or clear the
00972     kIsInvisible bit in the finderFlags field of the specified file or
00973     directory's finder information.
00974 
00975     ref                 --> FSRef to a file or directory.
00976 */
00977 
00978 /*****************************************************************************/
00979 
00980 #pragma mark FSSetNameLocked
00981 
00982 OSErr
00983 FSSetNameLocked(
00984     const FSRef *ref);
00985 
00986 #pragma mark FSClearNameLocked
00987 
00988 OSErr
00989 FSClearNameLocked(
00990     const FSRef *ref);
00991 
00992 /*
00993     The FSSetNameLocked and FSClearNameLocked functions set or clear the
00994     kNameLocked bit bit in the finderFlags field of the specified file or
00995     directory's finder information.
00996 
00997     ref                 --> FSRef to a file or directory.
00998 */
00999 
01000 /*****************************************************************************/
01001 
01002 #pragma mark FSSetIsStationery
01003 
01004 OSErr
01005 FSSetIsStationery(
01006     const FSRef *ref);
01007 
01008 #pragma mark FSClearIsStationery
01009 
01010 OSErr
01011 FSClearIsStationery(
01012     const FSRef *ref);
01013 
01014 /*
01015     The FSSetIsStationery and FSClearIsStationery functions set or clear the
01016     kIsStationery bit bit in the finderFlags field of the specified file or
01017     directory's finder information.
01018 
01019     ref                 --> FSRef to a file or directory.
01020 */
01021 
01022 /*****************************************************************************/
01023 
01024 #pragma mark FSSetHasCustomIcon
01025 
01026 OSErr
01027 FSSetHasCustomIcon(
01028     const FSRef *ref);
01029 
01030 #pragma mark FSClearHasCustomIcon
01031 
01032 OSErr
01033 FSClearHasCustomIcon(
01034     const FSRef *ref);
01035 
01036 /*
01037     The FSSetHasCustomIcon and FSClearHasCustomIcon functions set or clear the
01038     kHasCustomIcon bit bit in the finderFlags field of the specified file or
01039     directory's finder information.
01040 
01041     ref                 --> FSRef to a file or directory.
01042 */
01043 
01044 /*****************************************************************************/
01045 
01046 #pragma mark FSClearHasBeenInited
01047 
01048 OSErr
01049 FSClearHasBeenInited(
01050     const FSRef *ref);
01051 
01052 /*
01053     The FSClearHasBeenInited function clears the kHasBeenInited bit in the
01054     finderFlags field of the specified file or directory's finder information.
01055     
01056     Note:   There is no FSSetHasBeenInited function because ONLY the Finder
01057             should set the kHasBeenInited bit.
01058 
01059     ref                 --> FSRef to a file or directory.
01060 */
01061 
01062 /*****************************************************************************/
01063 
01064 #pragma mark FSCopyFileMgrAttributes
01065 
01066 OSErr
01067 FSCopyFileMgrAttributes(
01068     const FSRef *sourceRef,
01069     const FSRef *destinationRef,
01070     Boolean copyLockBit);
01071 
01072 /*
01073     The CopyFileMgrAttributes function copies all File Manager attributes
01074     from the source file or directory to the destination file or directory.
01075     If copyLockBit is true, then set the locked state of the destination
01076     to match the source.
01077 
01078     sourceRef           --> FSRef to a file or directory.
01079     destinationRef      --> FSRef to a file or directory.
01080     copyLockBit         --> If true, set the locked state of the destination
01081                             to match the source.
01082 */
01083 
01084 /*****************************************************************************/
01085 
01086 #pragma mark FSMoveRenameObjectUnicode
01087 
01088 OSErr
01089 FSMoveRenameObjectUnicode(
01090     const FSRef *ref,
01091     const FSRef *destDirectory,
01092     UniCharCount nameLength,
01093     const UniChar *name,            /* can be NULL (no rename during move) */
01094     TextEncoding textEncodingHint,
01095     FSRef *newRef);                 /* if function fails along the way, newRef is final location of file */
01096 
01097 /*
01098     The FSMoveRenameObjectUnicode function moves a file or directory and
01099     optionally renames it.  The source and destination locations must be on
01100     the same volume.
01101     
01102     Note:   If the input ref parameter is invalid, this call will fail and
01103             newRef, like ref, will be invalid.
01104 
01105     ref                 --> FSRef to a file or directory.
01106     destDirectory       --> FSRef to the destination directory.
01107     nameLength          --> Number of UniChar in name parameter.
01108     name                --> An Unicode string with the new name for the
01109                             moved object, or NULL if no rename is wanted.
01110     textEncodingHint    --> The text encoding hint used for the rename.
01111                             You can pass kTextEncodingUnknown to use the
01112                             "default" textEncodingHint.
01113     newRef              <-- The new FSRef of the object moved. Note that if
01114                             this function fails at any step along the way,
01115                             newRef is still then final location of the object.
01116 */
01117 
01118 /*****************************************************************************/
01119 
01120 #pragma mark FSDeleteContainerContents
01121 
01122 OSErr
01123 FSDeleteContainerContents(
01124     const FSRef *container);
01125 
01126 /*
01127     The FSDeleteContainerContents function deletes the contents of a container
01128     directory. All files and subdirectories in the specified container are
01129     deleted. If a locked file or directory is encountered, it is unlocked and
01130     then deleted. If any unexpected errors are encountered,
01131     FSDeleteContainerContents quits and returns to the caller.
01132     
01133     container           --> FSRef to a directory.
01134     
01135     __________
01136     
01137     Also see:   FSDeleteContainer
01138 */
01139 
01140 /*****************************************************************************/
01141 
01142 #pragma mark FSDeleteContainer
01143 
01144 OSErr
01145 FSDeleteContainer(
01146     const FSRef *container);
01147 
01148 /*
01149     The FSDeleteContainer function deletes a container directory and its contents.
01150     All files and subdirectories in the specified container are deleted.
01151     If a locked file or directory is encountered, it is unlocked and then
01152     deleted.  After deleting the container's contents, the container is
01153     deleted. If any unexpected errors are encountered, FSDeleteContainer
01154     quits and returns to the caller.
01155     
01156     container           --> FSRef to a directory.
01157     
01158     __________
01159     
01160     Also see:   FSDeleteContainerContents
01161 */
01162 
01163 /*****************************************************************************/
01164 
01165 #pragma mark IterateContainerFilterProcPtr
01166 
01167 typedef CALLBACK_API( Boolean , IterateContainerFilterProcPtr ) (
01168     Boolean containerChanged,
01169     ItemCount currentLevel,
01170     const FSCatalogInfo *catalogInfo,
01171     const FSRef *ref,
01172     const FSSpec *spec,
01173     const HFSUniStr255 *name,
01174     void *yourDataPtr);
01175 
01176 /*
01177     This is the prototype for the IterateContainerFilterProc function which
01178     is called once for each file and directory found by FSIterateContainer.
01179     The IterateContainerFilterProc can use the read-only data it receives for
01180     whatever it wants.
01181 
01182     The result of the IterateContainerFilterProc function indicates if
01183     iteration should be stopped. To stop iteration, return true; to continue
01184     iteration, return false.
01185 
01186     The yourDataPtr parameter can point to whatever data structure you might
01187     want to access from within the IterateContainerFilterProc.
01188 
01189     containerChanged    --> Set to true if the container's contents changed
01190                             during iteration.
01191     currentLevel        --> The current recursion level into the container.
01192                             1 = the container, 2 = the container's immediate
01193                             subdirectories, etc.
01194     catalogInfo         --> The catalog information for the current object.
01195                             Only the fields requested by the whichInfo
01196                             parameter passed to FSIterateContainer are valid.
01197     ref                 --> The FSRef to the current object.
01198     spec                --> The FSSpec to the current object if the wantFSSpec
01199                             parameter passed to FSIterateContainer is true.
01200     name                --> The name of the current object if the wantName
01201                             parameter passed to FSIterateContainer is true.
01202     yourDataPtr         --> An optional pointer to whatever data structure you
01203                             might want to access from within the
01204                             IterateFilterProc.
01205     result              <-- To stop iteration, return true; to continue
01206                             iteration, return false.
01207 
01208     __________
01209 
01210     Also see:   FSIterateContainer
01211 */
01212 
01213 /*****************************************************************************/
01214 
01215 #pragma mark CallIterateContainerFilterProc
01216 
01217 #define CallIterateContainerFilterProc(userRoutine, containerChanged, currentLevel, catalogInfo, ref, spec, name, yourDataPtr) \
01218     (*(userRoutine))((containerChanged), (currentLevel), (catalogInfo), (ref), (spec), (name), (yourDataPtr))
01219 
01220 /*****************************************************************************/
01221 
01222 #pragma mark FSIterateContainer
01223 
01224 OSErr
01225 FSIterateContainer(
01226     const FSRef *container,
01227     ItemCount maxLevels,
01228     FSCatalogInfoBitmap whichInfo,
01229     Boolean wantFSSpec,
01230     Boolean wantName,
01231     IterateContainerFilterProcPtr iterateFilter,
01232     void *yourDataPtr);
01233 
01234 /*
01235     The FSIterateContainer function performs a recursive iteration (scan) of the
01236     specified container directory and calls your IterateContainerFilterProc
01237     function once for each file and directory found.
01238 
01239     The maxLevels parameter lets you control how deep the recursion goes.
01240     If maxLevels is 1, FSIterateContainer only scans the specified directory;
01241     if maxLevels is 2, FSIterateContainer scans the specified directory and
01242     one subdirectory below the specified directory; etc. Set maxLevels to
01243     zero to scan all levels.
01244 
01245     The yourDataPtr parameter can point to whatever data structure you might
01246     want to access from within your IterateContainerFilterProc.
01247 
01248     container           --> The FSRef to the container directory to iterate.
01249     maxLevels           --> Maximum number of directory levels to scan or
01250                             zero to scan all directory levels.
01251     whichInfo           --> The fields of the FSCatalogInfo you wish to get.
01252     wantFSSpec          --> Set to true if you want the FSSpec to each
01253                             object passed to your IterateContainerFilterProc.
01254     wantName            --> Set to true if you want the name of each
01255                             object passed to your IterateContainerFilterProc.
01256     iterateFilter       --> A pointer to the IterateContainerFilterProc you
01257                             want called once for each file and directory found
01258                             by FSIterateContainer.
01259     yourDataPtr         --> An optional pointer to whatever data structure you
01260                             might want to access from within the
01261                             IterateFilterProc.
01262 */
01263 
01264 /*****************************************************************************/
01265 
01266 #pragma mark FSGetDirectoryItems
01267 
01268 OSErr
01269 FSGetDirectoryItems(
01270     const FSRef *container,
01271     FSRef ***refsHandle,    /* pointer to handle of FSRefs */
01272     ItemCount *numRefs,
01273     Boolean *containerChanged);
01274 
01275 /*
01276     The FSGetDirectoryItems function returns the list of items in the specified
01277     container. The array of FSRef records is returned in a Handle, refsHandle,
01278     which is allocated by FSGetDirectoryItems. The caller is responsible for
01279     disposing of refsHandle if the FSGetDirectoryItems returns noErr.
01280         
01281     container           --> FSRef to a directory.
01282     refsHandle          <-- Pointer to an FSRef Handle where the array of
01283                             FSRefs is to be returned.
01284     numRefs             <-- The number of FSRefs returned in the array.
01285     containerChanged    <-- Set to true if the container changes while the
01286                             list of items is being obtained.
01287 */
01288 
01289 /*****************************************************************************/
01290 
01291 #pragma mark FSExchangeObjectsCompat
01292 
01293 OSErr
01294 FSExchangeObjectsCompat(
01295     const FSRef *sourceRef,
01296     const FSRef *destRef,
01297     FSRef *newSourceRef,
01298     FSRef *newDestRef);
01299 
01300 /*
01301     The FSExchangeObjectsCompat function exchanges the data between two files.
01302     
01303     The FSExchangeObjectsCompat function is an enhanced version of
01304     FSExchangeObjects function. The two enhancements FSExchangeObjectsCompat
01305     provides are:
01306     
01307     1,  FSExchangeObjectsCompat will work on volumes which do not support
01308         FSExchangeObjects. FSExchangeObjectsCompat does this by emulating
01309         FSExchangeObjects through a series of File Manager operations. If
01310         there is a failure at any step along the way, FSExchangeObjectsCompat
01311         attempts to undo any steps already taken to leave the files in their
01312         original state in their original locations.
01313         
01314     2.  FSExchangeObjectsCompat returns new FSRefs to the source and
01315         destination files. Note that if this function fails at any step along
01316         the way, newSourceRef and newDestRef still give you access to the final
01317         locations of the files being exchanged -- even if they are renamed or
01318         not in their original locations.
01319 
01320     sourceRef           --> FSRef to the source file.
01321     destRef             --> FSRef to the destination file.
01322     newSourceRef        <-- The new FSRef to the source file.
01323     newDestRef          <-- The new FSRef to the destination file.
01324 */
01325 
01326 /*****************************************************************************/
01327 
01328 #pragma mark ----- Shared Environment Routines -----
01329 
01330 /*****************************************************************************/
01331 
01332 #pragma mark FSLockRange
01333 #pragma mark FSUnlockRange
01334 
01335 /*
01336     Mac OS X version 10.4 added FSLockRange and FSUnlockRange as APIs to
01337     CoreServices.framework which causes a name conflict with MoreFilesX.
01338     In addition, PBLockRangeSync and PBUnlockRangeSync are considered
01339     deprecated in Mac OS X version 10.4. Overall, this is a good because
01340     PBLockRangeSync and PBUnlockRangeSync are limited to working with
01341     2 GB files. However, it means that developers get to change their sources
01342     if they are using FSLockRange or FSUnlockRange from MoreFilesX 1.0 or 1.0.1.
01343     
01344     Because one of the goals of MoreFilesX is to encourage developers to use
01345     APIs that work best with Mac OS X, our recommendation is that developers
01346     change their code to use the FSLockRange and FSUnlockRange APIs. However,
01347     that presents a problem because the FSLockRange and FSUnlockRange APIs are
01348     not available prior to version 10.4. So, we've left the old routines in
01349     MoreFilesX but renamed them to FSLockRangeCompat and FSUnlockRangeCompat.
01350     
01351     If you want to switch to the new APIs, it's easy. Here's an example. Note
01352     that the new APIs *can* work with files larger than 2 GB, so make sure
01353     the rest of your code is using APIs that work with large files.
01354     
01355     Old MoreFilesX:
01356         result = FSLockRange(refNum, rangeLength, rangeStart);
01357         result = FSUnlockRange(refNum, rangeLength, rangeStart);
01358     
01359     New:
01360         UInt64 out_rangeStart;
01361         result = FSLockRange(refNum, fsFromStart, rangeStart, rangeLength, &out_rangeStart);
01362         result = FSUnlockRange(refNum, fsFromStart, rangeStart, rangeLength, &out_rangeStart);
01363  */
01364 
01365 #pragma mark FSLockRangeCompat
01366 
01367 OSErr
01368 FSLockRangeCompat(
01369     SInt16 refNum,
01370     SInt32 rangeLength,
01371     SInt32 rangeStart);
01372 
01373 /*
01374     The LockRange function locks (denies access to) a portion of a file
01375     that was opened with shared read/write permission.
01376 
01377     refNum              --> The file reference number of an open file.
01378     rangeLength         --> The number of bytes in the range.
01379     rangeStart          --> The starting byte in the range to lock.
01380 
01381     __________
01382 
01383     This function is deprecated in Mac OS X 10.4. Use the FSLockRange API instead.
01384     Also see:   UnlockRange
01385 */
01386 
01387 /*****************************************************************************/
01388 
01389 #pragma mark FSUnlockRangeCompat
01390 
01391 OSErr
01392 FSUnlockRangeCompat(
01393     SInt16 refNum,
01394     SInt32 rangeLength,
01395     SInt32 rangeStart);
01396 
01397 /*
01398     The UnlockRange function unlocks (allows access to) a previously locked
01399     portion of a file that was opened with shared read/write permission.
01400 
01401     refNum              --> The file reference number of an open file.
01402     rangeLength         --> The number of bytes in the range.
01403     rangeStart          --> The starting byte in the range to unlock.
01404 
01405     __________
01406 
01407     This function is deprecated in Mac OS X 10.4. Use the FSUnlockRange API instead.
01408     Also see:   LockRange
01409 */
01410 
01411 /*****************************************************************************/
01412 
01413 #pragma mark FSGetDirAccess
01414 
01415 OSErr
01416 FSGetDirAccess(
01417     const FSRef *ref,
01418     SInt32 *ownerID,        /* can be NULL */
01419     SInt32 *groupID,        /* can be NULL */
01420     SInt32 *accessRights);  /* can be NULL */
01421 
01422 /*
01423     The FSGetDirAccess function retrieves the directory access control
01424     information for a directory on a shared volume.
01425 
01426     ref                 --> An FSRef specifying the directory.
01427     ownerID             <** An optional pointer to a SInt32.
01428                             If not NULL, the directory's owner ID
01429                             will be returned in the SInt32.
01430     groupID             <** An optional pointer to a SInt32.
01431                             If not NULL, the directory's group ID, or 0
01432                             if no group affiliation, will be returned in
01433                             the SInt32.
01434     accessRights        <** An optional pointer to a SInt32.
01435                             If not NULL, the directory's access rights
01436                             will be returned in the SInt32.
01437 
01438     __________
01439 
01440     Also see:   FSSetDirAccess, FSMapID, FSMapName
01441 */
01442 
01443 /*****************************************************************************/
01444 
01445 #pragma mark FSSetDirAccess
01446 
01447 OSErr
01448 FSSetDirAccess(
01449     const FSRef *ref,
01450     SInt32 ownerID,
01451     SInt32 groupID,
01452     SInt32 accessRights);
01453 
01454 /*
01455     The FSpSetDirAccess function changes the directory access control
01456     information for a directory on a shared volume. You must be the owner of
01457     a directory to change its access control information.
01458     
01459     ref                 --> An FSRef specifying the directory.
01460     ownerID             --> The directory's owner ID.
01461     groupID             --> The directory's group ID or 0 if no group affiliation.
01462     accessRights        --> The directory's access rights.
01463     
01464     __________
01465     
01466     Also see:   FSGetDirAccess, FSMapID, FSMapName
01467 */
01468 
01469 /*****************************************************************************/
01470 
01471 #pragma mark FSGetVolMountInfoSize
01472 
01473 OSErr
01474 FSGetVolMountInfoSize(
01475     FSVolumeRefNum volRefNum,
01476     SInt16 *size);
01477 
01478 /*
01479     The FSGetVolMountInfoSize function determines the how much space the
01480     program needs to allocate for a volume mounting information record.
01481 
01482     volRefNum           --> Volume specification.
01483     size                <-- The space needed (in bytes) of the volume
01484                             mounting information record.
01485 
01486     __________
01487 
01488     Also see:   FSGetVolMountInfo, VolumeMount
01489 */
01490 
01491 /*****************************************************************************/
01492 
01493 #pragma mark FSGetVolMountInfo
01494 
01495 OSErr
01496 FSGetVolMountInfo(
01497     FSVolumeRefNum volRefNum,
01498     void *volMountInfo);
01499 
01500 /*
01501     The FSGetVolMountInfo function retrieves a volume mounting information
01502     record containing all the information needed to mount the volume,
01503     except for passwords.
01504 
01505     volRefNum           --> Volume specification.
01506     volMountInfo        <-- The volume mounting information.
01507 
01508     __________
01509 
01510     Also see:   FSGetVolMountInfoSize, VolumeMount
01511 */
01512 
01513 /*****************************************************************************/
01514 
01515 #pragma mark FSVolumeMount
01516 
01517 OSErr
01518 FSVolumeMount(
01519     const void *volMountInfo,
01520     FSVolumeRefNum *volRefNum);
01521 
01522 /*
01523     The VolumeMount function mounts a volume using a volume mounting
01524     information record.
01525 
01526     volMountInfo        --> A volume mounting information record.
01527     volRefNum           <-- The volume reference number.
01528 
01529     __________
01530 
01531     Also see:   FSGetVolMountInfoSize, FSGetVolMountInfo
01532 */
01533 
01534 /*****************************************************************************/
01535 
01536 #pragma mark FSMapID
01537 
01538 OSErr
01539 FSMapID(
01540     FSVolumeRefNum volRefNum,
01541     SInt32 ugID,
01542     SInt16 objType,
01543     Str31 name);
01544 
01545 /*
01546     The FSMapID function determines the name of a user or group if you know
01547     the user or group ID.
01548 
01549     volRefNum           --> Volume specification.
01550     objType             --> The mapping function code:
01551                             kOwnerID2Name to map a user ID to a user name
01552                             kGroupID2Name to map a group ID to a group name
01553     name                <** An optional pointer to a buffer (minimum Str31).
01554                             If not NULL, the user or group name
01555                             will be returned in the buffer.
01556 
01557     __________
01558 
01559     Also see:   FSGetDirAccess, FSSetDirAccess, FSMapName
01560 */
01561 
01562 /*****************************************************************************/
01563 
01564 #pragma mark FSMapName
01565 
01566 OSErr
01567 FSMapName(
01568     FSVolumeRefNum volRefNum,
01569     ConstStr255Param name,
01570     SInt16 objType,
01571     SInt32 *ugID);
01572 
01573 /*
01574     The FSMapName function determines the user or group ID if you know the
01575     user or group name.
01576     
01577     volRefNum           --> Volume specification.
01578     name                --> The user or group name.
01579     objType             --> The mapping function code:
01580                             kOwnerName2ID to map a user name to a user ID
01581                             kGroupName2ID to map a user name to a group ID
01582     ugID                <-- The user or group ID.
01583 
01584     __________
01585     
01586     Also see:   FSGetDirAccess, FSSetDirAccess, FSMapID
01587 */
01588 
01589 /*****************************************************************************/
01590 
01591 #pragma mark FSCopyFile
01592 
01593 OSErr
01594 FSCopyFile(
01595     const FSRef *srcFileRef,
01596     const FSRef *dstDirectoryRef,
01597     UniCharCount nameLength,
01598     const UniChar *copyName,    /* can be NULL (no rename during copy) */
01599     TextEncoding textEncodingHint,
01600     FSRef *newRef);             /* can be NULL */
01601 
01602 /*
01603     The FSCopyFile function duplicates a file and optionally renames it.
01604     The source and destination volumes must be on the same file server.
01605     This function instructs the server to copy the file.
01606     
01607     srcFileRef          --> An FSRef specifying the source file.
01608     dstDirectoryRef     --> An FSRef specifying the destination directory.
01609     nameLength          --> Number of UniChar in copyName parameter (ignored
01610                             if copyName is NULL).
01611     copyName            --> Points to the new file name if the file is to be
01612                             renamed, or NULL if the file isn't to be renamed.
01613     textEncodingHint    --> The text encoding hint used for the rename.
01614                             You can pass kTextEncodingUnknown to use the
01615                             "default" textEncodingHint.
01616     newRef              <** An optional pointer to a FSRef.
01617                             If not NULL, the FSRef of the duplicated file
01618                             will be returned in the FSRef.
01619 */
01620 
01621 /*****************************************************************************/
01622 
01623 #pragma mark FSMoveRename
01624 
01625 OSErr
01626 FSMoveRename(
01627     const FSRef *srcFileRef,
01628     const FSRef *dstDirectoryRef,
01629     UniCharCount nameLength,
01630     const UniChar *moveName,    /* can be NULL (no rename during move) */
01631     TextEncoding textEncodingHint,
01632     FSRef *newRef);             /* can be NULL */
01633 
01634 /*
01635     The FSMoveRename function moves a file or directory (object), and
01636     optionally renames it. The source and destination locations must be on
01637     the same shared volume.
01638     
01639     srcFileRef          --> An FSRef specifying the source file.
01640     dstDirectoryRef     --> An FSRef specifying the destination directory.
01641     nameLength          --> Number of UniChar in moveName parameter (ignored
01642                             if copyName is NULL)
01643     moveName            --> Points to the new object name if the object is to be
01644                             renamed, or NULL if the object isn't to be renamed.
01645     textEncodingHint    --> The text encoding hint used for the rename.
01646                             You can pass kTextEncodingUnknown to use the
01647                             "default" textEncodingHint.
01648     newRef              <** An optional pointer to a FSRef.
01649                             If not NULL, the FSRef of the moved object
01650                             will be returned in the FSRef.
01651 */
01652 
01653 /*****************************************************************************/
01654 
01655 #pragma mark ----- File ID Routines -----
01656 
01657 /*****************************************************************************/
01658 
01659 #pragma mark FSResolveFileIDRef
01660 
01661 OSErr
01662 FSResolveFileIDRef(
01663     FSVolumeRefNum volRefNum,
01664     SInt32 fileID,
01665     FSRef *ref);
01666 
01667 /*
01668     The FSResolveFileIDRef function returns an FSRef for the file with the
01669     specified file ID reference.
01670 
01671     volRefNum           --> Volume specification.
01672     fileID              --> The file ID reference.
01673     ref                 <-- The FSRef for the file ID reference.
01674 
01675     __________
01676 
01677     Also see:   FSCreateFileIDRef, FSDeleteFileIDRef
01678 */
01679 
01680 /*****************************************************************************/
01681 
01682 #pragma mark FSCreateFileIDRef
01683 
01684 OSErr
01685 FSCreateFileIDRef(
01686     const FSRef *ref,
01687     SInt32 *fileID);
01688 
01689 /*
01690     The FSCreateFileIDRef function creates a file ID reference for the
01691     specified file, or if a file ID reference already exists, supplies
01692     the file ID reference and returns the result code fidExists or afpIDExists.
01693 
01694     ref                 --> The FSRef for the file.
01695     fileID              <-- The file ID reference (if result is noErr,
01696                             fidExists, or afpIDExists).
01697 
01698     __________
01699 
01700     Also see:   GetFSRefFromFileIDRef, FSDeleteFileIDRef
01701 */
01702 
01703 /*****************************************************************************/
01704 
01705 #pragma mark FSDeleteFileIDRef
01706 
01707 /*
01708     Why is there no FSDeleteFileIDRef routine? There are two reasons:
01709     
01710     1.  Since Mac OS 8.1, PBDeleteFileIDRef hasn't deleted file ID references.
01711         On HFS volumes, deleting a file ID reference breaks aliases (which
01712         use file ID references to track files as they are moved around on a
01713         volume) and file ID references are automatically deleted when the file
01714         they refer to is deleted. On HFS Plus volumes, file ID references are
01715         always created when a file is created, deleted when the file is deleted,
01716         and cannot be deleted at any other time.
01717         
01718     2.  PBDeleteFileIDRef causes a memory access fault under Mac OS X 10.0
01719         through 10.1.x. While this will be fixed in a future release, the
01720         implementation, like the Mac OS 8/9 implementation, does not delete
01721         file ID references.
01722         
01723     __________
01724 
01725     Also see:   GetFSRefFromFileIDRef, FSCreateFileIDRef
01726 */
01727 
01728 /*****************************************************************************/
01729 
01730 #pragma mark ----- Utility Routines -----
01731 
01732 /*****************************************************************************/
01733 
01734 #pragma mark GetTempBuffer
01735 
01736 Ptr
01737 GetTempBuffer(
01738     ByteCount buffReqSize,
01739     ByteCount *buffActSize);
01740 
01741 /*
01742     The GetTempBuffer function allocates a temporary buffer for file system
01743     operations which is at least 4K bytes and a multiple of 4K bytes.
01744     
01745     buffReqSize         --> Size you'd like the buffer to be.
01746     buffActSize         <-- The size of the buffer allocated.
01747     function result     <-- Pointer to memory allocated, or NULL if no memory
01748                             was available. The caller is responsible for
01749                             disposing of this buffer with DisposePtr.
01750 */
01751 
01752 /*****************************************************************************/
01753 
01754 #pragma mark FileRefNumGetFSRef
01755 
01756 OSErr
01757 FileRefNumGetFSRef(
01758     short refNum,
01759     FSRef *ref);
01760 
01761 /*
01762     The FileRefNumGetFSRef function gets the FSRef of an open file.
01763 
01764     refNum              --> The file reference number of an open file.
01765     ref                 <-- The FSRef to the open file.
01766 */
01767 
01768 /*****************************************************************************/
01769 
01770 #pragma mark FSSetDefault
01771 
01772 OSErr
01773 FSSetDefault(
01774     const FSRef *newDefault,
01775     FSRef *oldDefault);
01776 
01777 /*
01778     The FSSetDefault function sets the current working directory to the
01779     directory specified by newDefault. The previous current working directory
01780     is returned in oldDefault and must be used to restore the current working
01781     directory to its previous state with the FSRestoreDefault function.
01782     These two functions are designed to be used as a wrapper around
01783     Standard I/O routines where the location of the file is implied to be the
01784     current working directory. This is how you should use these functions:
01785     
01786         result = FSSetDefault(&newDefault, &oldDefault);
01787         if ( noErr == result )
01788         {
01789             // call the Stdio functions like remove, rename,
01790             // fopen, freopen, etc here!
01791 
01792             result = FSRestoreDefault(&oldDefault);
01793         }
01794     
01795     newDefault          --> An FSRef that specifies the new current working
01796                             directory.
01797     oldDefault          <-- The previous current working directory's FSRef.
01798     
01799     __________
01800     
01801     Also see:   FSRestoreDefault
01802 */
01803 
01804 /*****************************************************************************/
01805 
01806 #pragma mark FSRestoreDefault
01807 
01808 OSErr
01809 FSRestoreDefault(
01810     const FSRef *oldDefault);
01811 
01812 /*
01813     The FSRestoreDefault function restores the current working directory
01814     to the directory specified by oldDefault. The oldDefault parameter was
01815     previously obtained from the FSSetDefault function.
01816     These two functions are designed to be used as a wrapper around
01817     Standard I/O routines where the location of the file is implied to be the
01818     current working directory. This is how you should use these functions:
01819     
01820         result = FSSetDefault(&newDefault, &oldDefault);
01821         if ( noErr == result )
01822         {
01823             // call the Stdio functions like remove, rename,
01824             // fopen, freopen, etc here!
01825 
01826             result = FSRestoreDefault(&oldDefault);
01827         }
01828         
01829     oldDefault          --> The FSRef of the location to restore.
01830     
01831     __________
01832     
01833     Also see:   FSSetDefault
01834 */
01835 
01836 /*****************************************************************************/
01837 
01838 #if PRAGMA_STRUCT_ALIGN
01839     #pragma options align=reset
01840 #elif PRAGMA_STRUCT_PACKPUSH
01841     #pragma pack(pop)
01842 #elif PRAGMA_STRUCT_PACK
01843     #pragma pack()
01844 #endif
01845 
01846 #ifdef PRAGMA_IMPORT_OFF
01847 #pragma import off
01848 #elif PRAGMA_IMPORT
01849 #pragma import reset
01850 #endif
01851 
01852 #ifdef __cplusplus
01853 }
01854 #endif
01855 
01856 #endif /* __MOREFILESX__ */
01857 

Generated on Wed May 31 18:19:56 2006 for frontierkernel 10.1.10a by  doxygen 1.4.6