![]() |
FSCatalogSearch |
||||
Header: | Files.h | Carbon status: | Supported | |
Searches for objects from a catalog iterator that match a given set of criteria.
OSErr FSCatalogSearch ( FSIterator iterator, const FSSearchParams *searchCriteria, ItemCount maximumObjects, ItemCount *actualObjects, Boolean *containerChanged, FSCatalogInfoBitmap whichInfo, FSCatalogInfo *catalogInfos, FSRef *refs, FSSpec *specs, HFSUniStr255 *names );
The iterator to use. Objects traversed by this iterator are matched against the criteria specified by searchCriteria.
A pointer to a structure containing the criteria that control the matching.
You can match against the objects name in Unicode and by the fields in a FSCatalogInfo structure. You may use the same search bits as passed in ioSearchBits to PBCatSearch; they control the corresponding FSCatalogInfo fields. The fsSBPartialName and fsSBFullName constants control matching against the Unicode name specified by searchNameLength and searchName.
There are a few new search criteria supported by FSCatalogSearch but not PBCatSearch. The fsSBNodeID, fsSBAttributeModDate, and fsSBAccessDate bits let you search by a range of nodeID, attributeModDate, and accessDate, respectively. The fsSBPermissions bit lets you search by mask/value match against the permissions.
If searchTime is non-zero, it is interpreted as a Time Manager duration (milliseconds if positive, or microseconds if negative); the search may terminate after this duration even if maximumObjects objects have not been returned and the entire catalog has not been scanned. If searchTime is zero, there is no time limit for the search.
If you are searching by partial or full name (fsSBPartialName or fsSBFullName), then searchName points to searchNameLength Unicode characters to match against. If you are searching by any other criteria, you must set searchInfo1 and searchInfo2 to point to FSCatalogInfo structures containing the values to match against. For fields that match against a range (such as dates), the minimum matching value should be placed in the searchInfo1 structure and the maximum matching value in the searchInfo2 structure. For fields that match by mask/value (such as permissions and Finder info), set the bits you wish to compare in the searchInfo2 structure; set the corresponding matching value in the searchInfo1 structure.
The maximum number of items to return.
On return, a pointer to the actual number of items found.
On return, a pointer to a value indicating whether the containers contents have changed. This is true if the containers contents changed since the previous FSCatalogSearch call.
Objects may still be returned even though the container changed. This output is optional; if you dont want it, pass a NULL pointer. Note that if the container has changed, then the total set of items returned may be incorrect; some items may be returned multiple times, and some items may not be returned at all.
The catalog information fields to return for each item.
A pointer to an array of catalog information structures; one for each returned item.
A pointer to an array of FSRefs; one for each returned item.
A pointer to an array of filenames; one for each returned item.
A result code. The call may complete with no error before scanning the entire volume. This typically happens because the time limit (searchTime) has been reached or maximumObjects items have been returned. When the entire volume has been searched, errFSNoMoreItems is returned.
A single search may span more than one call to FSCatalogSearch. Various information about each matching file or directory is returned.
You can get various information about all the matching files or directories. The whichInfo, catalogInfos, fsRefs, nameLengths, and names parameters are used in the same way as for the FSGetCatalogInfoBulk call.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 9, or later.
© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)