src/mac/morefile/IterateD.h

   1 /*
   2 **      IterateDirectory: File Manager directory iterator routines.
   3 **
   4 **      by Jim Luther
   5 **
   6 **      File:           IterateDirectory.h
   7 **
   8 **      Copyright © 1995-1998 Jim Luther and Apple Computer, Inc.
   9 **      All rights reserved.
  10 **
  11 **      You may incorporate this sample code into your applications without
  12 **      restriction, though the sample code has been provided "AS IS" and the
  13 **      responsibility for its operation is 100% yours.
  14 **
  15 **      IterateDirectory is designed to drop into the MoreFiles sample code
  16 **      library I wrote while in Apple Developer Technical Support
  17 */
  18
  19 #ifndef __ITERATEDIRECTORY__
  20 #define __ITERATEDIRECTORY__
  21
  22 #include <Types.h>
  23 #include <Files.h>
  24
  25 #include "optim.h"
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31 /*****************************************************************************/
  32
  33 typedef pascal  void (*IterateFilterProcPtr) (const CInfoPBRec * const cpbPtr,
  34                                                                                           Boolean *quitFlag,
  35                                                                                           void *yourDataPtr);
  36 /*      ¦ Prototype for the IterateFilterProc function IterateDirectory calls.
  37         This is the prototype for the IterateFilterProc function which is
  38         called once for each file and directory found by IterateDirectory. The
  39         IterateFilterProc gets a pointer to the CInfoPBRec that IterateDirectory
  40         used to call PBGetCatInfo. The IterateFilterProc can use the read-only
  41         data in the CInfoPBRec for whatever it wants.
  42
  43         If the IterateFilterProc wants to stop IterateDirectory, it can set
  44         quitFlag to true (quitFlag will be passed to the IterateFilterProc
  45         false).
  46
  47         The yourDataPtr parameter can point to whatever data structure you might
  48         want to access from within the IterateFilterProc.
  49
  50         cpbPtr          input:  A pointer to the CInfoPBRec that IterateDirectory
  51                                                 used to call PBGetCatInfo. The CInfoPBRec and the
  52                                                 data it points to must not be changed by your
  53                                                 IterateFilterProc.
  54         quitFlag        output: Your IterateFilterProc can set quitFlag to true
  55                                                 if it wants to stop IterateDirectory.
  56         yourDataPtr     input:  A pointer to whatever data structure you might
  57                                                 want to access from within the IterateFilterProc.
  58
  59         __________
  60
  61         Also see:       IterateDirectory, FSpIterateDirectory
  62 */
  63
  64 #define CallIterateFilterProc(userRoutine, cpbPtr, quitFlag, yourDataPtr) \
  65                 (*(userRoutine))((cpbPtr), (quitFlag), (yourDataPtr))
  66
  67 /*****************************************************************************/
  68
  69 pascal  OSErr   IterateDirectory(short vRefNum,
  70                                                                  long dirID,
  71                                                                  ConstStr255Param name,
  72                                                                  unsigned short maxLevels,
  73                                                                  IterateFilterProcPtr iterateFilter,
  74                                                                  void *yourDataPtr);
  75 /*      ¦ Iterate (scan) through a directory's content.
  76         The IterateDirectory function performs a recursive iteration (scan) of
  77         the specified directory and calls your IterateFilterProc function once
  78         for each file and directory found.
  79
  80         The maxLevels parameter lets you control how deep the recursion goes.
  81         If maxLevels is 1, IterateDirectory only scans the specified directory;
  82         if maxLevels is 2, IterateDirectory scans the specified directory and
  83         one subdirectory below the specified directory; etc. Set maxLevels to
  84         zero to scan all levels.
  85
  86         The yourDataPtr parameter can point to whatever data structure you might
  87         want to access from within the IterateFilterProc.
  88
  89         vRefNum                 input:  Volume specification.
  90         dirID                   input:  Directory ID.
  91         name                    input:  Pointer to object name, or nil when dirID
  92                                                         specifies a directory that's the object.
  93         maxLevels               input:  Maximum number of directory levels to scan or
  94                                                         zero to scan all directory levels.
  95         iterateFilter   input:  A pointer to the routine you want called once
  96                                                         for each file and directory found by
  97                                                         IterateDirectory.
  98         yourDataPtr             input:  A pointer to whatever data structure you might
  99                                                         want to access from within the IterateFilterProc.
 100
 101         Result Codes
 102                 noErr                           0               No error
 103                 nsvErr                          -35             No such volume
 104                 ioErr                           -36             I/O error
 105                 bdNamErr                        -37             Bad filename
 106                 fnfErr                          -43             File not found
 107                 paramErr                        -50             No default volume or iterateFilter was NULL
 108                 dirNFErr                        -120    Directory not found or incomplete pathname
 109                                                                         or a file was passed instead of a directory
 110                 afpAccessDenied         -5000   User does not have the correct access
 111                 afpObjectTypeErr        -5025   Directory not found or incomplete pathname
 112
 113         __________
 114
 115         See also:       IterateFilterProcPtr, FSpIterateDirectory
 116 */
 117
 118 /*****************************************************************************/
 119
 120 pascal  OSErr   FSpIterateDirectory(const FSSpec *spec,
 121                                                                         unsigned short maxLevels,
 122                                                                         IterateFilterProcPtr iterateFilter,
 123                                                                         void *yourDataPtr);
 124 /*      ¦ Iterate (scan) through a directory's content.
 125         The FSpIterateDirectory function performs a recursive iteration (scan)
 126         of the specified directory and calls your IterateFilterProc function once
 127         for each file and directory found.
 128
 129         The maxLevels parameter lets you control how deep the recursion goes.
 130         If maxLevels is 1, FSpIterateDirectory only scans the specified directory;
 131         if maxLevels is 2, FSpIterateDirectory scans the specified directory and
 132         one subdirectory below the specified directory; etc. Set maxLevels to
 133         zero to scan all levels.
 134
 135         The yourDataPtr parameter can point to whatever data structure you might
 136         want to access from within the IterateFilterProc.
 137
 138         spec                    input:  An FSSpec record specifying the directory to scan.
 139         maxLevels               input:  Maximum number of directory levels to scan or
 140                                                         zero to scan all directory levels.
 141         iterateFilter   input:  A pointer to the routine you want called once
 142                                                         for each file and directory found by
 143                                                         FSpIterateDirectory.
 144         yourDataPtr             input:  A pointer to whatever data structure you might
 145                                                         want to access from within the IterateFilterProc.
 146
 147         Result Codes
 148                 noErr                           0               No error
 149                 nsvErr                          -35             No such volume
 150                 ioErr                           -36             I/O error
 151                 bdNamErr                        -37             Bad filename
 152                 fnfErr                          -43             File not found
 153                 paramErr                        -50             No default volume or iterateFilter was NULL
 154                 dirNFErr                        -120    Directory not found or incomplete pathname
 155                 afpAccessDenied         -5000   User does not have the correct access
 156                 afpObjectTypeErr        -5025   Directory not found or incomplete pathname
 157
 158         __________
 159
 160         See also:       IterateFilterProcPtr, IterateDirectory
 161 */
 162
 163 /*****************************************************************************/
 164
 165 #ifdef __cplusplus
 166 }
 167 #endif
 168
 169 #include "optimend.h"
 170
 171 #endif  /* __ITERATEDIRECTORY__ */