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
1.4.7