enumerateDirectory(_:startingAt:verifier:attributes:packer:replyHandler:)
Enumerates the contents of the given directory.
Declaration
func enumerateDirectory(_ directory: FSItem, startingAt cookie: FSDirectoryCookie, verifier: FSDirectoryVerifier, attributes: FSItem.GetAttributesRequest?, packer: FSDirectoryEntryPacker, replyHandler reply: @escaping @Sendable (FSDirectoryVerifier, (any Error)?) -> Void)func enumerateDirectory(_ directory: FSItem, startingAt cookie: FSDirectoryCookie, verifier: FSDirectoryVerifier, attributes: FSItem.GetAttributesRequest?, packer: FSDirectoryEntryPacker) async throws -> FSDirectoryVerifierParameters
- directory:
The item to enumerate. FSKit guarantees this item is of type Directory.
- cookie:
A value that indicates the location within the directory from which to enumerate. Your implementation defines the semantics of the cookie values; they’re opaque to FSKit. The first call to the enumerate method passes Initial for this parameter. Subsequent calls pass whatever cookie value you previously passed to the packer’s
nextCookieparmeter. - verifier:
A tool to detect whether the directory contents changed since the last call to
enumerateDirectory. Your implementation defines the semantics of the verifier values; they’re opaque to FSKit. The first call to the enumerate method passes Initial for this parameter. Subsequent calls pass whatever cookie value you previously passed to the packer’scurrentVerifierparmeter. - attributes:
The desired attributes to provide, or
nilif the caller doesn’t require attributes. - packer:
An object that your implementation uses to enumerate directory items, packing one item per callback to
enumerateDirectory. - reply:
A block or closure to indicate success or failure. If enumeration succeeds, pass the current verifier and a
nilerror. If enumeration fails, pass the relevant error as the second parameter; FSKit ignores any verifier in this case. For anasyncSwift implementation, there’s no reply handler; simply return the current verifier or throw an error.
Discussion
This method uses the packEntry(name:itemType:itemID:nextCookie:attributes:) method of the packer parameter to deliver the enumerated items to the caller. The general flow of an enumeration implementation follows these steps:
Enumeration starts with a call to
enumerateDirectoryusing the initial next-cookie and verifier values initial and initial, respectively.The implementation uses
packerto pack the initial set of directory entries. Packing also sets anextCookieto use on the next call.The implementation replies with a new verifier value, a nonzero value that reflects the directory’s current version.
On the next call the implementation packs the next set of entries, starting with the item indicated by
cookie. Ifcookiedoesn’t resolve to a valid directory entry, complete the request with an error of domain NSPOSIXErrorDomain and code FSError.Code.invalidDirectoryCookie.
When packing, make sure to use acceptable directory entry names and unambiguous input to all file operations that take names without additional normalization, such aslookupName.