xpcom/MoreFiles/FSCopyObject.h

   1 /*
   2         File:           FSCopyObject.h
   3
   4         Contains:       A Copy/Delete Files/Folders engine which uses the HFS+ API's
   5
   6         Disclaimer:     IMPORTANT:  This Apple software is supplied to you by Apple Computer, Inc.
   7                                 ("Apple") in consideration of your agreement to the following terms, and your
   8                                 use, installation, modification or redistribution of this Apple software
   9                                 constitutes acceptance of these terms.  If you do not agree with these terms,
  10                                 please do not use, install, modify or redistribute this Apple software.
  11
  12                                 In consideration of your agreement to abide by the following terms, and subject
  13                                 to these terms, Apple grants you a personal, non-exclusive license, under AppleÕs
  14                                 copyrights in this original Apple software (the "Apple Software"), to use,
  15                                 reproduce, modify and redistribute the Apple Software, with or without
  16                                 modifications, in source and/or binary forms; provided that if you redistribute
  17                                 the Apple Software in its entirety and without modifications, you must retain
  18                                 this notice and the following text and disclaimers in all such redistributions of
  19                                 the Apple Software.  Neither the name, trademarks, service marks or logos of
  20                                 Apple Computer, Inc. may be used to endorse or promote products derived from the
  21                                 Apple Software without specific prior written permission from Apple.  Except as
  22                                 expressly stated in this notice, no other rights or licenses, express or implied,
  23                                 are granted by Apple herein, including but not limited to any patent rights that
  24                                 may be infringed by your derivative works or by other works in which the Apple
  25                                 Software may be incorporated.
  26
  27                                 The Apple Software is provided by Apple on an "AS IS" basis.  APPLE MAKES NO
  28                                 WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED
  29                                 WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  30                                 PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR IN
  31                                 COMBINATION WITH YOUR PRODUCTS.
  32
  33                                 IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR
  34                                 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  35                                 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  36                                 ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION
  37                                 OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, TORT
  38                                 (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN
  39                                 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  40
  41         Copyright © 2002 Apple Computer, Inc., All Rights Reserved
  42 */
  43
  44 // Modified 2006-01-23 - added this comment.
  45
  46 #ifndef __FSCOPYOBJECT_H__
  47 #define __FSCOPYOBJECT_H__
  48
  49 #include <Files.h>
  50
  51 #ifdef __cplusplus
  52 extern "C" {
  53 #endif
  54
  55 #define DEBUG_COPY_OBJECT  0    // set to zero if you don't want debug spew
  56
  57 #define QuoteExceptionString(x) #x
  58
  59 #if DEBUG_COPY_OBJECT
  60         #include <stdio.h>
  61
  62         #define mycheck_noerr(error)                                                \
  63             do {                                                                    \
  64                 OSStatus localError = error;                                        \
  65                 if (localError == noErr) ;                                          \
  66                 else {                                                              \
  67                    printf(QuoteExceptionString(error) " != noErr in File: %s, Function: %s, Line: %d, Error: %d\n",     \
  68                                                                           __FILE__, __FUNCTION__, __LINE__, localError);                \
  69                 }                                                                   \
  70             } while (false)
  71
  72         #define mycheck(assertion)                                                      \
  73             do {                                                                        \
  74                 if (assertion) ;                                                        \
  75                 else {                                                                  \
  76                    printf(QuoteExceptionString(assertion) " failed in File: %s, Function: %s, Line: %d\n",      \
  77                                                                           __FILE__, __FUNCTION__, __LINE__);    \
  78                 }                                                                       \
  79             } while (false)
  80     #define myverify(assertion)       mycheck(assertion)
  81     #define myverify_noerr(assertion) mycheck_noerr( (assertion) )
  82 #else
  83         #define mycheck(assertion)
  84         #define mycheck_noerr(err)
  85     #define myverify(assertion)       do { (void) (assertion); } while (0)
  86     #define myverify_noerr(assertion) myverify(assertion)
  87 #endif
  88
  89 /*
  90         This code is a combination of MoreFilesX (by Jim Luther) and MPFileCopy (by Quinn)
  91         with some added features and bug fixes.  This code will run in OS 9.1 and up
  92         and 10.1.x (Classic and Carbon)
  93 */
  94
  95 /*****************************************************************************/
  96
  97 #pragma mark CopyObjectFilterProcPtr
  98
  99 /*
 100         This is the prototype for the CallCopyObjectFilterProc function which
 101         is called once for each file and directory found by FSCopyObject.
 102         The CallCopyObjectFilterProc can use the read-only data it receives for
 103         whatever it wants.
 104
 105         The result of the CallCopyObjectFilterProc function indicates if
 106         iteration should be stopped. To stop iteration, return true; to continue
 107         iteration, return false.
 108
 109         The yourDataPtr parameter can point to whatever data structure you might
 110         want to access from within the CallCopyObjectFilterProc.
 111
 112         containerChanged        --> Set to true if the container's contents changed
 113                                                         during iteration.
 114         currentLevel            --> The current recursion level into the container.
 115                                                         1 = the container, 2 = the container's immediate
 116                                                         subdirectories, etc.
 117         currentOSErr            --> The current error code, shows the results of the
 118                                                         copy of the current object (ref)
 119         catalogInfo                     --> The catalog information for the current object.
 120                                                         Only the fields requested by the whichInfo
 121                                                         parameter passed to FSIterateContainer are valid.
 122         ref                                     --> The FSRef to the current object.
 123         spec                            --> The FSSpec to the current object if the wantFSSpec
 124                                                         parameter passed to FSCopyObject is true.
 125         name                            --> The name of the current object if the wantName
 126                                                         parameter passed to FSCopyObject is true.
 127         yourDataPtr                     --> An optional pointer to whatever data structure you
 128                                                         might want to access from within the
 129                                                         CallCopyObjectFilterProc.
 130         result                          <-- To stop iteration, return true; to continue
 131                                                         iteration, return false.
 132
 133         __________
 134
 135         Also see:       FSCopyObject
 136 */
 137
 138 typedef CALLBACK_API( Boolean , CopyObjectFilterProcPtr ) (
 139         Boolean containerChanged,
 140         ItemCount currentLevel,
 141         OSErr currentOSErr,
 142         const FSCatalogInfo *catalogInfo,
 143         const FSRef *ref,
 144         const FSSpec *spec,
 145         const HFSUniStr255 *name,
 146         void *yourDataPtr);
 147
 148
 149 /*****************************************************************************/
 150
 151 #pragma mark CallCopyObjectFilterProc
 152
 153 #define CallCopyObjectFilterProc(userRoutine, containerChanged, currentLevel, currentOSErr, catalogInfo, ref, spec, name, yourDataPtr) \
 154         (*(userRoutine))((containerChanged), (currentLevel), (currentOSErr), (catalogInfo), (ref), (spec), (name), (yourDataPtr))
 155
 156 /*****************************************************************************/
 157
 158 #pragma mark FSCopyObject
 159
 160 /*
 161         The FSCopyObject function takes a source object (can be a file or directory)
 162         and copies it (and its contents if it's a directory) to the new destination
 163         directory.
 164
 165         It will call your CopyObjectFilterProcPtr once for each file/directory
 166         copied
 167
 168         The maxLevels parameter is only used when the object is a directory,
 169         ignored otherwise.
 170         It lets you control how deep the recursion goes.
 171         If maxLevels is 1, FSCopyObject only scans the specified directory;
 172         if maxLevels is 2, FSCopyObject scans the specified directory and
 173         one subdirectory below the specified directory; etc. Set maxLevels to
 174         zero to scan all levels.
 175
 176         The yourDataPtr parameter can point to whatever data structure you might
 177         want to access from within your CopyObjectFilterProcPtr.
 178
 179         source                          --> The FSRef to the object you want to copy
 180         destDir                         --> The FSRef to the directory you wish to copy source to
 181         maxLevels                       --> Maximum number of directory levels to scan or
 182                                                         zero to scan all directory levels, ignored if the
 183                                                         object is a file
 184         whichInfo                       --> The fields of the FSCatalogInfo you wish passed
 185                                                         to you in your CopyObjectFilterProc
 186         wantFSSpec                      --> Set to true if you want the FSSpec to each
 187                                                         object passed to your CopyObjectFilterProc.
 188         wantName                        --> Set to true if you want the name of each
 189                                                         object passed to your CopyObjectFilterProc.
 190         iterateFilter           --> A pointer to the CopyObjectFilterProc you
 191                                                         want called once for each object found
 192                                                         by FSCopyObject.
 193         yourDataPtr                     --> An optional pointer to whatever data structure you
 194                                                         might want to access from within the
 195                                                         CopyObjectFilterProc.
 196 */
 197
 198 OSErr FSCopyObject(     const FSRef *source,
 199                                         const FSRef *destDir,
 200                                         UniCharCount nameLength,
 201                                         const UniChar *copyName,                        // can be NULL (no rename during copy)
 202                                         ItemCount maxLevels,
 203                                         FSCatalogInfoBitmap whichInfo,
 204                                         Boolean wantFSSpec,
 205                                         Boolean wantName,
 206                                         CopyObjectFilterProcPtr filterProcPtr,  // can be NULL
 207                                         void *yourDataPtr,                                              // can be NULL
 208                                         FSRef *newObject);                                              // can be NULL
 209
 210 /*****************************************************************************/
 211
 212 #pragma mark FSDeleteObjects
 213
 214 /*
 215         The FSDeleteObjects function takes an FSRef to a file or directory
 216         and attempts to delete it.  If the object is a directory, all files
 217         and subdirectories in the specified directory are deleted. If a
 218         locked file or directory is encountered, it is unlocked and then
 219         deleted.  After deleting the directory's contents, the directory
 220         is deleted. If any unexpected errors are encountered,
 221         FSDeleteContainer quits and returns to the caller.
 222
 223         source                          --> FSRef to an object (can be file or directory).
 224
 225         __________
 226 */
 227
 228 OSErr FSDeleteObjects(  const FSRef *source );
 229
 230 #ifdef __cplusplus
 231 }
 232 #endif
 233
 234 #endif