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 47extern "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 64EXTERN_API( OSErr ) 65IndexedSearch( 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 113EXTERN_API( OSErr ) 114PBCatSearchSyncCompat(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 160EXTERN_API( OSErr ) 161NameFileSearch( 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 221EXTERN_API( OSErr ) 222CreatorTypeFileSearch( 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 305