src/mac/carbon/morefile/Search.h

   1 /*
   2      File:       Search.h
   3
   4      Contains:   IndexedSearch and the PBCatSearch compatibility function.
   5
   6      Version:    Technology: MoreFiles
   7                  Release:    1.5.2
   8
   9      Copyright:  © 1992-2001 by 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 __SEARCH__
  29 #define __SEARCH__
  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 EXTERN_API( OSErr )
  65 IndexedSearch(
  66   CSParamPtr   pb,
  67   long         dirID);
  68
  69
  70 /*
  71     The IndexedSearch function performs an indexed search in and below the
  72     specified directory using the same parameters (in pb) as is passed to
  73     PBCatSearch. See Inside Macintosh: Files for a description of the
  74     parameter block.
  75
  76     pb          input:  A CSParamPtr record specifying the volume to search
  77                         and the search criteria.
  78                 output: Fields in the parameter block are returned indicating
  79                         the number of matches found, the matches, and if the
  80                         search ended with noErr, the CatPosition record that
  81                         lets you resume a search where the last search left
  82                         off.
  83     dirID       input:  The directory to search. If fsRtDirID is passed,
  84                         the entire volume is searched.
  85
  86     Note:   If you use a high-level debugger and use ioSearchTime to limit
  87             the length of time to run the search, you'll want to step over
  88             calls to IndexedSearch because it installs a Time Manager task.
  89             Most high-level debuggers don't deal gracefully with interrupt
  90             driven code.
  91
  92     Result Codes
  93         noErr               0       No error
  94         nsvErr              -35     Volume not found
  95         ioErr               -36     I/O error
  96         eofErr              -39     End of catalog found (this is normal!)
  97         paramErr            -50     Parameter block has invalid parameters
  98                                     (see source for VerifyUserPB) or
  99                                     invalid catPosition record was passed
 100         extFSErr            -58     External file system error - no file
 101                                     system claimed this call.
 102         memFullErr          -108    Memory could not be allocated in heap
 103         catChangedErr       -1304   Catalog has changed and catalog position
 104                                     record may be invalid
 105
 106     __________
 107
 108     See also:   PBCatSearch, PBCatSearchSyncCompat
 109 */
 110
 111 /*****************************************************************************/
 112
 113 EXTERN_API( OSErr )
 114 PBCatSearchSyncCompat(CSParamPtr paramBlock);
 115
 116
 117 /*
 118     The PBCatSearchSyncCompat function uses PBCatSearch (if available) or
 119     IndexedSearch (if PBCatSearch is not available) to search a volume
 120     using a set of search criteria that you specify. It builds a list of all
 121     files or directories that meet your specifications.
 122
 123     pb          input:  A CSParamPtr record specifying the volume to search
 124                         and the search criteria.
 125                 output: Fields in the parameter block are returned indicating
 126                         the number of matches found, the matches, and if the
 127                         search ended with noErr, the CatPosition record that
 128                         lets you resume a search where the last search left
 129                         off.
 130
 131     Note:   If you use a high-level debugger and use ioSearchTime to limit
 132             the length of time to run the search, you'll want to step over
 133             calls to PBCatSearchSyncCompat because it calls IndexedSearch
 134             which installs a Time Manager task. Most high-level debuggers
 135             don't deal gracefully with interrupt driven code.
 136
 137     Result Codes
 138         noErr               0       No error
 139         nsvErr              -35     Volume not found
 140         ioErr               -36     I/O error
 141         eofErr              -39     End of catalog found (this is normal!)
 142         paramErr            -50     Parameter block has invalid parameters
 143                                     (see source for VerifyUserPB) or
 144                                     invalid catPosition record was passed
 145         extFSErr            -58     External file system error - no file
 146                                     system claimed this call.
 147         memFullErr          -108    Memory could not be allocated in heap
 148         catChangedErr       -1304   Catalog has changed and catalog position
 149                                     record may be invalid
 150         afpCatalogChanged   -5037   Catalog has changed and search cannot
 151                                     be resumed
 152
 153     __________
 154
 155     See also:   PBCatSearch, IndexedSearch
 156 */
 157
 158 /*****************************************************************************/
 159
 160 EXTERN_API( OSErr )
 161 NameFileSearch(
 162   ConstStr255Param   volName,
 163   short              vRefNum,
 164   ConstStr255Param   fileName,
 165   FSSpecPtr          matches,
 166   long               reqMatchCount,
 167   long *             actMatchCount,
 168   Boolean            newSearch,
 169   Boolean            partial);
 170
 171
 172 /*
 173     The NameFileSearch function searches for files with a specific file
 174     name on a volume that supports PBCatSearch.
 175     Note: A result of catChangedErr means the catalog has changed between
 176     searches, but the search can be continued with the possiblity that you
 177     may miss some matches or get duplicate matches.  For all other results
 178     (except for noErr), the search cannot be continued.
 179
 180     volName         input:  A pointer to the name of a mounted volume
 181                             or nil.
 182     vRefNum         input:  Volume specification.
 183     fileName        input:  The name of the file to search for.
 184     matches         input:  Pointer to array of FSSpec where the match list is
 185                             returned.
 186     reqMatchCount   input:  Maximum number of matches to return (the number of
 187                             elements in the matches array).
 188     actMatchCount   output: The number of matches actually returned.
 189     newSearch       input:  If true, start a new search. If false and if
 190                             vRefNum is the same as the last call to
 191                             NameFileSearch, then start searching at the
 192                             position where the last search left off.
 193     partial         input:  If the partial parameter is false, then only files
 194                             that exactly match fileName will be found.  If the
 195                             partial parameter is true, then all file names that
 196                             contain fileName will be found.
 197
 198     Result Codes
 199         noErr               0       No error
 200         nsvErr              -35     Volume not found
 201         ioErr               -36     I/O error
 202         eofErr              -39     End of catalog found (this is normal!)
 203         paramErr            -50     Parameter block has invalid parameters
 204                                     (see source for VerifyUserPB) or
 205                                     invalid catPosition record was passed
 206         extFSErr            -58     External file system error - no file
 207                                     system claimed this call.
 208         memFullErr          -108    Memory could not be allocated in heap
 209         catChangedErr       -1304   Catalog has changed and catalog position
 210                                     record may be invalid
 211         afpCatalogChanged   -5037   Catalog has changed and search cannot
 212                                     be resumed
 213
 214     __________
 215
 216     Also see:   CreatorTypeFileSearch
 217 */
 218
 219 /*****************************************************************************/
 220
 221 EXTERN_API( OSErr )
 222 CreatorTypeFileSearch(
 223   ConstStr255Param   volName,
 224   short              vRefNum,
 225   OSType             creator,
 226   OSType             fileType,
 227   FSSpecPtr          matches,
 228   long               reqMatchCount,
 229   long *             actMatchCount,
 230   Boolean            newSearch);
 231
 232
 233 /*
 234     The CreatorTypeFileSearch function searches for files with a specific
 235     creator or fileType on a volume that supports PBCatSearch.
 236     Note: A result of catChangedErr means the catalog has changed between
 237     searches, but the search can be continued with the possiblity that you
 238     may miss some matches or get duplicate matches.  For all other results
 239     (except for noErr), the search cannot be continued.
 240
 241     volName         input:  A pointer to the name of a mounted volume
 242                             or nil.
 243     vRefNum         input:  Volume specification.
 244     creator         input:  The creator type of the file to search for.
 245                             To ignore the creator type, pass 0x00000000 in
 246                             this field.
 247     fileType        input:  The file type of the file to search for.
 248                             To ignore the file type, pass 0x00000000 in
 249                             this field.
 250     matches         input:  Pointer to array of FSSpec where the match list is
 251                             returned.
 252     reqMatchCount   input:  Maximum number of matches to return (the number of
 253                             elements in the matches array).
 254     actMatchCount   output: The number of matches actually returned.
 255     newSearch       input:  If true, start a new search. If false and if
 256                             vRefNum is the same as the last call to
 257                             CreatorTypeFileSearch, then start searching at the
 258                             position where the last search left off.
 259
 260     Result Codes
 261         noErr               0       No error
 262         nsvErr              -35     Volume not found
 263         ioErr               -36     I/O error
 264         eofErr              -39     End of catalog found (this is normal!)
 265         paramErr            -50     Parameter block has invalid parameters
 266                                     (see source for VerifyUserPB) or
 267                                     invalid catPosition record was passed
 268         extFSErr            -58     External file system error - no file
 269                                     system claimed this call.
 270         memFullErr          -108    Memory could not be allocated in heap
 271         catChangedErr       -1304   Catalog has changed and catalog position
 272                                     record may be invalid
 273         afpCatalogChanged   -5037   Catalog has changed and search cannot
 274                                     be resumed
 275
 276     __________
 277
 278     Also see:   NameFileSearch
 279 */
 280
 281 /*****************************************************************************/
 282
 283 #include "OptimizationEnd.h"
 284
 285 #if PRAGMA_STRUCT_ALIGN
 286     #pragma options align=reset
 287 #elif PRAGMA_STRUCT_PACKPUSH
 288     #pragma pack(pop)
 289 #elif PRAGMA_STRUCT_PACK
 290     #pragma pack()
 291 #endif
 292
 293 #ifdef PRAGMA_IMPORT_OFF
 294 #pragma import off
 295 #elif PRAGMA_IMPORT
 296 #pragma import reset
 297 #endif
 298
 299 #ifdef __cplusplus
 300 }
 301 #endif
 302
 303 #endif /* __SEARCH__ */
 304