MoreFilesX.h

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

Generated on Thu Jul 1 06:09:57 2010 for Second Life Viewer by  doxygen 1.4.7