FSCopyObject.h

Go to the documentation of this file.
00001 
00032 /*
00033         File:           FSCopyObject.h
00034         
00035         Contains:       A Copy/Delete Files/Folders engine which uses the HFS+ API's
00036 
00037         Disclaimer:     IMPORTANT:  This Apple software is supplied to you by Apple Computer, Inc.
00038                                 ("Apple") in consideration of your agreement to the following terms, and your
00039                                 use, installation, modification or redistribution of this Apple software
00040                                 constitutes acceptance of these terms.  If you do not agree with these terms,
00041                                 please do not use, install, modify or redistribute this Apple software.
00042 
00043                                 In consideration of your agreement to abide by the following terms, and subject
00044                                 to these terms, Apple grants you a personal, non-exclusive license, under Apple’s
00045                                 copyrights in this original Apple software (the "Apple Software"), to use,
00046                                 reproduce, modify and redistribute the Apple Software, with or without
00047                                 modifications, in source and/or binary forms; provided that if you redistribute
00048                                 the Apple Software in its entirety and without modifications, you must retain
00049                                 this notice and the following text and disclaimers in all such redistributions of
00050                                 the Apple Software.  Neither the name, trademarks, service marks or logos of
00051                                 Apple Computer, Inc. may be used to endorse or promote products derived from the
00052                                 Apple Software without specific prior written permission from Apple.  Except as
00053                                 expressly stated in this notice, no other rights or licenses, express or implied,
00054                                 are granted by Apple herein, including but not limited to any patent rights that
00055                                 may be infringed by your derivative works or by other works in which the Apple
00056                                 Software may be incorporated.
00057 
00058                                 The Apple Software is provided by Apple on an "AS IS" basis.  APPLE MAKES NO
00059                                 WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED
00060                                 WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
00061                                 PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR IN
00062                                 COMBINATION WITH YOUR PRODUCTS.
00063 
00064                                 IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR
00065                                 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
00066                                 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00067                                 ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION
00068                                 OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, TORT
00069                                 (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN
00070                                 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00071 
00072         Copyright © 2002-2004 Apple Computer, Inc., All Rights Reserved
00073 */
00074 
00075 
00076 #ifndef __FSCOPYOBJECT_H__
00077 #define __FSCOPYOBJECT_H__
00078 
00079 #ifdef __cplusplus
00080 extern "C" {
00081 #endif
00082 
00083 #if TARGET_API_MAC_OSX || defined( __APPLE_CC__ )
00084 #include        <CoreServices/CoreServices.h>
00085 #endif
00086 
00087 #define DEBUG  1        /* set to zero if you don't want debug spew */
00088 
00089 #if DEBUG
00090         #include <stdio.h>
00091 
00092         #define QuoteExceptionString(x) #x
00093 
00094         #define dwarning(s)                                     do { printf s; fflush(stderr); } while( 0 )                                     
00095 
00096         #define mycheck_noerr( error )                                                                                          \
00097                 do {                                                                                                                                    \
00098                         if( (OSErr) error != noErr ) {                                                                          \
00099                    dwarning((QuoteExceptionString(error) " != noErr in File: %s, Function: %s, Line: %d, Error: %d\n",  \
00100                                                                           __FILE__, __FUNCTION__, __LINE__, (OSErr) error));            \
00101                  }                                                                                                                                      \
00102                 } while( false )
00103 
00104         #define mycheck( assertion )                                                                                            \
00105                 do {                                                                                                                                    \
00106                         if( ! assertion ) {                                                                                                     \
00107                    dwarning((QuoteExceptionString(assertion) " failed in File: %s, Function: %s, Line: %d\n",   \
00108                                                                           __FILE__, __FUNCTION__, __LINE__));   \
00109                         }                                                                                                                                       \
00110                 } while( false )
00111 
00112     #define myverify(assertion)                 mycheck(assertion)
00113     #define myverify_noerr(assertion)   mycheck_noerr( (assertion) )
00114 #else
00115     #define     dwarning(s)
00116     
00117         #define mycheck(assertion)
00118         #define mycheck_noerr(err)
00119     #define myverify(assertion)                 do { (void) (assertion); } while (0)
00120     #define myverify_noerr(assertion)   myverify(assertion)    
00121 #endif
00122 
00123 /*
00124         This code takes some tricks/techniques from MoreFilesX (by Jim Luther) and
00125         MPFileCopy (by Quinn), wraps them all up into an easy to use API, and adds a bunch of
00126         features and bug fixes.  It will run on Mac OS 9.1 through 9.2.x and 10.1.x
00127         and up (Classic, Carbon and Mach-O)
00128 */
00129 
00130         /* Different options that FSCopyObject can take during a copy */
00131 typedef UInt32                          DupeAction;
00132 enum {
00133         kDupeActionStandard,    /* will do the copy with no frills */
00134         kDupeActionReplace,             /* will delete the existing object and then copy over the new one */
00135         kDupeActionRename               /* will rename the new object if an object of the same name exists */
00136 };
00137 
00138 /*****************************************************************************/
00139 
00140 #pragma mark CopyObjectFilterProcPtr
00141 
00142 /*
00143         This is the prototype for the CallCopyObjectFilterProc function which
00144         is called once for each file and directory found by FSCopyObject.
00145         The CallCopyObjectFilterProc can use the read-only data it receives for
00146         whatever it wants.
00147 
00148         The result of the CallCopyObjectFilterProc function indicates if
00149         the copy should be stopped.  To stop the copy, return an error; to continue
00150         the copy, return noErr.
00151 
00152         The yourDataPtr parameter can point to whatever data structure you might
00153         want to access from within the CallCopyObjectFilterProc.
00154         
00155         Note: If an error had occured during the copy of the current object
00156         (currentOSErr != noErr) the FSRef etc might not be valid
00157 
00158         containerChanged        --> Set to true if the container's contents changed
00159                                                         during iteration.
00160         currentLevel            --> The current recursion level into the container.
00161                                                         1 = the container, 2 = the container's immediate
00162                                                         subdirectories, etc.
00163         currentOSErr            --> The current error code, shows the results of the
00164                                                         copy of the current object (ref)
00165         catalogInfo                     --> The catalog information for the current object.
00166                                                         Only the fields requested by the whichInfo
00167                                                         parameter passed to FSIterateContainer are valid.
00168         ref                                     --> The FSRef to the current object.
00169         spec                            --> The FSSpec to the current object if the wantFSSpec
00170                                                         parameter passed to FSCopyObject is true.
00171         name                            --> The name of the current object if the wantName
00172                                                         parameter passed to FSCopyObject is true.
00173         yourDataPtr                     --> An optional pointer to whatever data structure you
00174                                                         might want to access from within the
00175                                                         CallCopyObjectFilterProc.
00176         result                          <-- To continue the copy, return noErr
00177         
00178         __________
00179 
00180         Also see:       FSCopyObject
00181 */
00182 
00183 typedef CALLBACK_API( OSErr , CopyObjectFilterProcPtr ) (
00184         Boolean containerChanged,
00185         ItemCount currentLevel,
00186         OSErr currentOSErr,
00187         const FSCatalogInfo *catalogInfo,
00188         const FSRef *ref,
00189         const FSSpec *spec,
00190         const HFSUniStr255 *name,
00191         void *yourDataPtr);
00192 
00193 
00194 /*****************************************************************************/
00195 
00196 #pragma mark CallCopyObjectFilterProc
00197 
00198 #define CallCopyObjectFilterProc(userRoutine, containerChanged, currentLevel, currentOSErr, catalogInfo, ref, spec, name, yourDataPtr) \
00199         (*(userRoutine))((containerChanged), (currentLevel), (currentOSErr), (catalogInfo), (ref), (spec), (name), (yourDataPtr))
00200 
00201 /*****************************************************************************/
00202 
00203 #pragma mark FSCopyObject
00204 
00205 /*
00206         The FSCopyObject function takes a source object (can be a file or directory)
00207         and copies it (and its contents if it's a directory) to the new destination
00208         directory.
00209         
00210         It will call your CopyObjectFilterProcPtr once for each object copied
00211 
00212         The maxLevels parameter is only used when the object is a directory,
00213         ignored otherwise.
00214         It lets you control how deep the recursion goes.
00215         If maxLevels is 1, FSCopyObject only scans the specified directory;
00216         if maxLevels is 2, FSCopyObject scans the specified directory and
00217         one subdirectory below the specified directory; etc. Set maxLevels to
00218         zero to scan all levels.
00219 
00220         The yourDataPtr parameter can point to whatever data structure you might
00221         want to access from within your CopyObjectFilterProcPtr.
00222 
00223         source                          --> The FSRef to the object you want to copy
00224         destDir                         --> The FSRef to the directory you wish to copy source to
00225         maxLevels                       --> Maximum number of directory levels to scan or
00226                                                         zero to scan all directory levels, ignored if the
00227                                                         object is a file
00228         whichInfo                       --> The fields of the FSCatalogInfo you wish passed
00229                                                         to you in your CopyObjectFilterProc
00230         dupeAction                      --> The action to take if an object of the same name exists
00231                                                         in the destination
00232         newName                         --> The name you want the new object to have.  If you pass
00233                                                         in NULL, the source object name will be used. 
00234         wantFSSpec                      --> Set to true if you want the FSSpec to each
00235                                                         object passed to your CopyObjectFilterProc.
00236         wantName                        --> Set to true if you want the name of each
00237                                                         object passed to your CopyObjectFilterProc.
00238         filterProcPtr           --> A pointer to the CopyObjectFilterProc you
00239                                                         want called once for each object found
00240                                                         by FSCopyObject.
00241         yourDataPtr                     --> An optional pointer to whatever data structure you
00242                                                         might want to access from within the
00243                                                         CopyObjectFilterProc.
00244         newObjectRef            --> An optional pointer to an FSRef that, on return,
00245                                                         references the new object.  If you don't want this
00246                                                         info returned, pass in NULL
00247         newObjectSpec           --> An optional pointer to an FSSPec that, on return,
00248                                                         references the new object.  If you don't want this
00249                                                         info returned, pass in NULL
00250 */
00251 
00252 OSErr FSCopyObject(     const FSRef *source,
00253                                         const FSRef *destDir,
00254                                         ItemCount maxLevels,
00255                                         FSCatalogInfoBitmap whichInfo,
00256                                         DupeAction dupeAction,
00257                                         const HFSUniStr255 *newName,                    /* can be NULL */
00258                                         Boolean wantFSSpec,
00259                                         Boolean wantName,
00260                                         CopyObjectFilterProcPtr filterProcPtr,  /* can be NULL */
00261                                         void *yourDataPtr,                                              /* can be NULL */
00262                                         FSRef *newObjectRef,                                    /* can be NULL */
00263                                         FSSpec *newObjectSpec);                                 /* can be NULL */
00264 
00265 /*****************************************************************************/
00266 
00267 #pragma mark FSDeleteObjects
00268 
00269 /*
00270         The FSDeleteObjects function takes an FSRef to a file or directory
00271         and attempts to delete it.  If the object is a directory, all files
00272         and subdirectories in the specified directory are deleted. If a
00273         locked file or directory is encountered, it is unlocked and then
00274         deleted.  After deleting the directory's contents, the directory
00275         is deleted. If any unexpected errors are encountered, 
00276         FSDeleteContainer quits and returns to the caller.
00277         
00278         source                          --> FSRef to an object (can be file or directory).
00279         
00280         __________
00281 */
00282 
00283 OSErr FSDeleteObjects( const FSRef *source );
00284 
00285 #ifdef __cplusplus
00286 }
00287 #endif
00288 
00289 #endif

Generated on Thu Jul 1 06:08:17 2010 for Second Life Viewer by  doxygen 1.4.7