src/mac/carbon/morefile/IterateDirectory.h

   1 /*
   2      File:       IterateDirectory.h
   3
   4      Contains:   File Manager directory iterator routines.
   5
   6      Version:    Technology: MoreFiles
   7                  Release:    1.5.2
   8
   9      Copyright:  © 1995-2001 by Jim Luther and Apple Computer, Inc., all rights reserved.
  10
  11      Bugs?:      For bug reports, consult the following page on
  12                  the World Wide Web:
  13
  14                      http://developer.apple.com/bugreporter/
  15
  16 */
  17
  18 /*
  19     You may incorporate this sample code into your applications without
  20     restriction, though the sample code has been provided "AS IS" and the
  21     responsibility for its operation is 100% yours.  However, what you are
  22     not permitted to do is to redistribute the source as "DSC Sample Code"
  23     after having made changes. If you're going to re-distribute the source,
  24     we require that you make it clear in the source that the code was
  25     descended from Apple Sample Code, but that you've made changes.
  26 */
  27
  28 #ifndef __ITERATEDIRECTORY__
  29 #define __ITERATEDIRECTORY__
  30
  31 #ifndef __MACTYPES__
  32 #include <MacTypes.h>
  33 #endif
  34
  35 #ifndef __FILES__
  36 #include <Files.h>
  37 #endif
  38
  39 #include "Optimization.h"
  40
  41
  42 #if PRAGMA_ONCE
  43 #pragma once
  44 #endif
  45
  46 #ifdef __cplusplus
  47 extern "C" {
  48 #endif
  49
  50 #if PRAGMA_IMPORT
  51 #pragma import on
  52 #endif
  53
  54 #if PRAGMA_STRUCT_ALIGN
  55     #pragma options align=mac68k
  56 #elif PRAGMA_STRUCT_PACKPUSH
  57     #pragma pack(push, 2)
  58 #elif PRAGMA_STRUCT_PACK
  59     #pragma pack(2)
  60 #endif
  61
  62 /*****************************************************************************/
  63
  64 typedef CALLBACK_API( void , IterateFilterProcPtr )(const CInfoPBRec *cpbPtr, Boolean *quitFlag, void *yourDataPtr);
  65 /*
  66     This is the prototype for the IterateFilterProc function which is
  67     called once for each file and directory found by IterateDirectory. The
  68     IterateFilterProc gets a pointer to the CInfoPBRec that IterateDirectory
  69     used to call PBGetCatInfo. The IterateFilterProc can use the read-only
  70     data in the CInfoPBRec for whatever it wants.
  71
  72     If the IterateFilterProc wants to stop IterateDirectory, it can set
  73     quitFlag to true (quitFlag will be passed to the IterateFilterProc
  74     false).
  75
  76     The yourDataPtr parameter can point to whatever data structure you might
  77     want to access from within the IterateFilterProc.
  78
  79     cpbPtr      input:  A pointer to the CInfoPBRec that IterateDirectory
  80                         used to call PBGetCatInfo. The CInfoPBRec and the
  81                         data it points to must not be changed by your
  82                         IterateFilterProc.
  83     quitFlag    output: Your IterateFilterProc can set quitFlag to true
  84                         if it wants to stop IterateDirectory.
  85     yourDataPtr input:  A pointer to whatever data structure you might
  86                         want to access from within the IterateFilterProc.
  87
  88     __________
  89
  90     Also see:   IterateDirectory, FSpIterateDirectory
  91 */
  92 #define CallIterateFilterProc(userRoutine, cpbPtr, quitFlag, yourDataPtr) \
  93     (*(userRoutine))((cpbPtr), (quitFlag), (yourDataPtr))
  94
  95 /*****************************************************************************/
  96
  97 EXTERN_API( OSErr )
  98 IterateDirectory(
  99   short                  vRefNum,
 100   long                   dirID,
 101   ConstStr255Param       name,
 102   unsigned short         maxLevels,
 103   IterateFilterProcPtr   iterateFilter,
 104   void *                 yourDataPtr);
 105
 106
 107 /*
 108     The IterateDirectory function performs a recursive iteration (scan) of
 109     the specified directory and calls your IterateFilterProc function once
 110     for each file and directory found.
 111
 112     The maxLevels parameter lets you control how deep the recursion goes.
 113     If maxLevels is 1, IterateDirectory only scans the specified directory;
 114     if maxLevels is 2, IterateDirectory scans the specified directory and
 115     one subdirectory below the specified directory; etc. Set maxLevels to
 116     zero to scan all levels.
 117
 118     The yourDataPtr parameter can point to whatever data structure you might
 119     want to access from within the IterateFilterProc.
 120
 121     vRefNum         input:  Volume specification.
 122     dirID           input:  Directory ID.
 123     name            input:  Pointer to object name, or nil when dirID
 124                             specifies a directory that's the object.
 125     maxLevels       input:  Maximum number of directory levels to scan or
 126                             zero to scan all directory levels.
 127     iterateFilter   input:  A pointer to the routine you want called once
 128                             for each file and directory found by
 129                             IterateDirectory.
 130     yourDataPtr     input:  A pointer to whatever data structure you might
 131                             want to access from within the IterateFilterProc.
 132
 133     Result Codes
 134         noErr               0       No error
 135         nsvErr              -35     No such volume
 136         ioErr               -36     I/O error
 137         bdNamErr            -37     Bad filename
 138         fnfErr              -43     File not found
 139         paramErr            -50     No default volume or iterateFilter was NULL
 140         dirNFErr            -120    Directory not found or incomplete pathname
 141                                     or a file was passed instead of a directory
 142         afpAccessDenied     -5000   User does not have the correct access
 143         afpObjectTypeErr    -5025   Directory not found or incomplete pathname
 144
 145     __________
 146
 147     See also:   IterateFilterProcPtr, FSpIterateDirectory
 148 */
 149
 150 /*****************************************************************************/
 151
 152 EXTERN_API( OSErr )
 153 FSpIterateDirectory(
 154   const FSSpec *         spec,
 155   unsigned short         maxLevels,
 156   IterateFilterProcPtr   iterateFilter,
 157   void *                 yourDataPtr);
 158
 159
 160 /*
 161     The FSpIterateDirectory function performs a recursive iteration (scan)
 162     of the specified directory and calls your IterateFilterProc function once
 163     for each file and directory found.
 164
 165     The maxLevels parameter lets you control how deep the recursion goes.
 166     If maxLevels is 1, FSpIterateDirectory only scans the specified directory;
 167     if maxLevels is 2, FSpIterateDirectory scans the specified directory and
 168     one subdirectory below the specified directory; etc. Set maxLevels to
 169     zero to scan all levels.
 170
 171     The yourDataPtr parameter can point to whatever data structure you might
 172     want to access from within the IterateFilterProc.
 173
 174     spec            input:  An FSSpec record specifying the directory to scan.
 175     maxLevels       input:  Maximum number of directory levels to scan or
 176                             zero to scan all directory levels.
 177     iterateFilter   input:  A pointer to the routine you want called once
 178                             for each file and directory found by
 179                             FSpIterateDirectory.
 180     yourDataPtr     input:  A pointer to whatever data structure you might
 181                             want to access from within the IterateFilterProc.
 182
 183     Result Codes
 184         noErr               0       No error
 185         nsvErr              -35     No such volume
 186         ioErr               -36     I/O error
 187         bdNamErr            -37     Bad filename
 188         fnfErr              -43     File not found
 189         paramErr            -50     No default volume or iterateFilter was NULL
 190         dirNFErr            -120    Directory not found or incomplete pathname
 191         afpAccessDenied     -5000   User does not have the correct access
 192         afpObjectTypeErr    -5025   Directory not found or incomplete pathname
 193
 194     __________
 195
 196     See also:   IterateFilterProcPtr, IterateDirectory
 197 */
 198
 199 /*****************************************************************************/
 200
 201 #include "OptimizationEnd.h"
 202
 203 #if PRAGMA_STRUCT_ALIGN
 204     #pragma options align=reset
 205 #elif PRAGMA_STRUCT_PACKPUSH
 206     #pragma pack(pop)
 207 #elif PRAGMA_STRUCT_PACK
 208     #pragma pack()
 209 #endif
 210
 211 #ifdef PRAGMA_IMPORT_OFF
 212 #pragma import off
 213 #elif PRAGMA_IMPORT
 214 #pragma import reset
 215 #endif
 216
 217 #ifdef __cplusplus
 218 }
 219 #endif
 220
 221 #endif /* __ITERATEDIRECTORY__ */
 222