Back to index

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