Back to index

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