src/mac/morefile/Search.h

   1 /*
   2 **      Apple Macintosh Developer Technical Support
   3 **
   4 **      IndexedSearch and the PBCatSearch compatibility function.
   5 **
   6 **      by Jim Luther, Apple Developer Technical Support Emeritus
   7 **
   8 **      File:           Search.h
   9 **
  10 **      Copyright © 1992-1998 Apple Computer, Inc.
  11 **      All rights reserved.
  12 **
  13 **      You may incorporate this sample code into your applications without
  14 **      restriction, though the sample code has been provided "AS IS" and the
  15 **      responsibility for its operation is 100% yours.  However, what you are
  16 **      not permitted to do is to redistribute the source as "DSC Sample Code"
  17 **      after having made changes. If you're going to re-distribute the source,
  18 **      we require that you make it clear in the source that the code was
  19 **      descended from Apple Sample Code, but that you've made changes.
  20 */
  21
  22 #ifndef __SEARCH__
  23 #define __SEARCH__
  24
  25 #include <Types.h>
  26 #include <Files.h>
  27
  28 #include "Optim.h"
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 /*****************************************************************************/
  35
  36 pascal  OSErr   IndexedSearch(CSParamPtr pb,
  37                                                           long dirID);
  38 /*      ¦ Search in and below a directory.
  39         The IndexedSearch function performs an indexed search in and below the
  40         specified directory using the same parameters (in pb) as is passed to
  41         PBCatSearch. See Inside Macintosh: Files for a description of the
  42         parameter block.
  43
  44         pb                      input:  A CSParamPtr record specifying the volume to search
  45                                                 and the search criteria.
  46                                 output: Fields in the parameter block are returned indicating
  47                                                 the number of matches found, the matches, and if the
  48                                                 search ended with noErr, the CatPosition record that
  49                                                 lets you resume a search where the last search left
  50                                                 off.
  51         dirID           input:  The directory to search. If fsRtDirID is passed,
  52                                                 the entire volume is searched.
  53
  54         Note:   If you use a high-level debugger and use ioSearchTime to limit
  55                         the length of time to run the search, you'll want to step over
  56                         calls to IndexedSearch because it installs a Time Manager task.
  57                         Most high-level debuggers don't deal gracefully with interrupt
  58                         driven code.
  59
  60         Result Codes
  61                 noErr                           0               No error
  62                 nsvErr                          -35             Volume not found
  63                 ioErr                           -36             I/O error
  64                 eofErr                          -39             End of catalog found (this is normal!)
  65                 paramErr                        -50             Parameter block has invalid parameters
  66                                                                         (see source for VerifyUserPB) or
  67                                                                         invalid catPosition record was passed
  68                 extFSErr                        -58             External file system error - no file
  69                                                                         system claimed this call.
  70                 memFullErr                      -108    Memory could not be allocated in heap
  71                 catChangedErr           -1304   Catalog has changed and catalog position
  72                                                                         record may be invalid
  73
  74         __________
  75
  76         See also:       PBCatSearch, PBCatSearchSyncCompat
  77 */
  78
  79 /*****************************************************************************/
  80
  81 pascal  OSErr   PBCatSearchSyncCompat(CSParamPtr paramBlock);
  82 /*      ¦ Search a volume using PBCatSearch or IndexedSearch.
  83         The PBCatSearchSyncCompat function uses PBCatSearch (if available) or
  84         IndexedSearch (if PBCatSearch is not available) to search a volume
  85         using a set of search criteria that you specify. It builds a list of all
  86         files or directories that meet your specifications.
  87
  88         pb                      input:  A CSParamPtr record specifying the volume to search
  89                                                 and the search criteria.
  90                                 output: Fields in the parameter block are returned indicating
  91                                                 the number of matches found, the matches, and if the
  92                                                 search ended with noErr, the CatPosition record that
  93                                                 lets you resume a search where the last search left
  94                                                 off.
  95
  96         Note:   If you use a high-level debugger and use ioSearchTime to limit
  97                         the length of time to run the search, you'll want to step over
  98                         calls to PBCatSearchSyncCompat because it calls IndexedSearch
  99                         which installs a Time Manager task. Most high-level debuggers
 100                         don't deal gracefully with interrupt driven code.
 101
 102         Result Codes
 103                 noErr                           0               No error
 104                 nsvErr                          -35             Volume not found
 105                 ioErr                           -36             I/O error
 106                 eofErr                          -39             End of catalog found (this is normal!)
 107                 paramErr                        -50             Parameter block has invalid parameters
 108                                                                         (see source for VerifyUserPB) or
 109                                                                         invalid catPosition record was passed
 110                 extFSErr                        -58             External file system error - no file
 111                                                                         system claimed this call.
 112                 memFullErr                      -108    Memory could not be allocated in heap
 113                 catChangedErr           -1304   Catalog has changed and catalog position
 114                                                                         record may be invalid
 115                 afpCatalogChanged       -5037   Catalog has changed and search cannot
 116                                                                         be resumed
 117
 118         __________
 119
 120         See also:       PBCatSearch, IndexedSearch
 121 */
 122
 123 /*****************************************************************************/
 124
 125 pascal  OSErr   NameFileSearch(ConstStr255Param volName,
 126                                                            short vRefNum,
 127                                                            ConstStr255Param fileName,
 128                                                            FSSpecPtr matches,
 129                                                            long reqMatchCount,
 130                                                            long *actMatchCount,
 131                                                            Boolean newSearch,
 132                                                            Boolean partial);
 133 /*      ¦ Search for files by file name with PBCatSearch.
 134         The NameFileSearch function searches for files with a specific file
 135         name on a volume that supports PBCatSearch.
 136         Note: A result of catChangedErr means the catalog has changed between
 137         searches, but the search can be continued with the possiblity that you
 138         may miss some matches or get duplicate matches.  For all other results
 139         (except for noErr), the search cannot be continued.
 140
 141         volName                 input:  A pointer to the name of a mounted volume
 142                                                         or nil.
 143         vRefNum                 input:  Volume specification.
 144         fileName                input:  The name of the file to search for.
 145         matches                 input:  Pointer to array of FSSpec where the match list is
 146                                                         returned.
 147         reqMatchCount   input:  Maximum number of matches to return     (the number of
 148                                                         elements in the matches array).
 149         actMatchCount   output: The number of matches actually returned.
 150         newSearch               input:  If true, start a new search. If false and if
 151                                                         vRefNum is the same as the last call to
 152                                                         NameFileSearch, then start searching at the
 153                                                         position where the last search left off.
 154         partial                 input:  If the partial parameter is false, then only files
 155                                                         that exactly match fileName will be found.  If the
 156                                                         partial parameter is true, then all file names that
 157                                                         contain fileName will be found.
 158
 159         Result Codes
 160                 noErr                           0               No error
 161                 nsvErr                          -35             Volume not found
 162                 ioErr                           -36             I/O error
 163                 eofErr                          -39             End of catalog found (this is normal!)
 164                 paramErr                        -50             Parameter block has invalid parameters
 165                                                                         (see source for VerifyUserPB) or
 166                                                                         invalid catPosition record was passed
 167                 extFSErr                        -58             External file system error - no file
 168                                                                         system claimed this call.
 169                 memFullErr                      -108    Memory could not be allocated in heap
 170                 catChangedErr           -1304   Catalog has changed and catalog position
 171                                                                         record may be invalid
 172                 afpCatalogChanged       -5037   Catalog has changed and search cannot
 173                                                                         be resumed
 174
 175         __________
 176
 177         Also see:       CreatorTypeFileSearch
 178 */
 179
 180 /*****************************************************************************/
 181
 182 pascal  OSErr   CreatorTypeFileSearch(ConstStr255Param volName,
 183                                                                           short vRefNum,
 184                                                                           OSType creator,
 185                                                                           OSType fileType,
 186                                                                           FSSpecPtr matches,
 187                                                                           long reqMatchCount,
 188                                                                           long *actMatchCount,
 189                                                                           Boolean newSearch);
 190 /*      ¦ Search for files by creator/fileType with PBCatSearch.
 191         The CreatorTypeFileSearch function searches for files with a specific
 192         creator or fileType on a volume that supports PBCatSearch.
 193         Note: A result of catChangedErr means the catalog has changed between
 194         searches, but the search can be continued with the possiblity that you
 195         may miss some matches or get duplicate matches.  For all other results
 196         (except for noErr), the search cannot be continued.
 197
 198         volName                 input:  A pointer to the name of a mounted volume
 199                                                         or nil.
 200         vRefNum                 input:  Volume specification.
 201         creator                 input:  The creator type of the file to search for.
 202                                                         To ignore the creator type, pass 0x00000000 in
 203                                                         this field.
 204         fileType                input:  The file type of the file to search for.
 205                                                         To ignore the file type, pass 0x00000000 in
 206                                                         this field.
 207         matches                 input:  Pointer to array of FSSpec where the match list is
 208                                                         returned.
 209         reqMatchCount   input:  Maximum number of matches to return     (the number of
 210                                                         elements in the matches array).
 211         actMatchCount   output: The number of matches actually returned.
 212         newSearch               input:  If true, start a new search. If false and if
 213                                                         vRefNum is the same as the last call to
 214                                                         CreatorTypeFileSearch, then start searching at the
 215                                                         position where the last search left off.
 216
 217         Result Codes
 218                 noErr                           0               No error
 219                 nsvErr                          -35             Volume not found
 220                 ioErr                           -36             I/O error
 221                 eofErr                          -39             End of catalog found (this is normal!)
 222                 paramErr                        -50             Parameter block has invalid parameters
 223                                                                         (see source for VerifyUserPB) or
 224                                                                         invalid catPosition record was passed
 225                 extFSErr                        -58             External file system error - no file
 226                                                                         system claimed this call.
 227                 memFullErr                      -108    Memory could not be allocated in heap
 228                 catChangedErr           -1304   Catalog has changed and catalog position
 229                                                                         record may be invalid
 230                 afpCatalogChanged       -5037   Catalog has changed and search cannot
 231                                                                         be resumed
 232
 233         __________
 234
 235         Also see:       NameFileSearch
 236 */
 237
 238 /*****************************************************************************/
 239
 240 #ifdef __cplusplus
 241 }
 242 #endif
 243
 244 #include "OptimEnd.h"
 245
 246 #endif  /* __SEARCH__ */