Initiates a read operation on a single file or directory using the specified options.
SDKs
- iOS 5.0+
- macOS 10.7+
- Mac Catalyst 13.0+
- tvOS 9.0+
- watchOS 2.0+
Framework
- Foundation
Declaration
func coordinate(readingItemAt url: URL, options: NSFile Coordinator.Reading Options = [], error outError: NSError Pointer, byAccessor reader: (URL) -> Void)
Parameters
url
A URL identifying the file or directory to read. If other objects or processes are acting on the item at the URL, the actual URL passed to the
reader
parameter may be different than the one in this parameter.options
One of the reading options described in
NSFile
. If you pass no options, theCoordinator .Reading Options save
method of relevant file presenters is called before your block executes.Presented Item Changes(completion Handler:) outError
On input, a pointer to a pointer for an error object. If a file presenter encounters an error while preparing for this read operation, that error is returned in this parameter and the block in the
reader
parameter is not executed. If you cancel this operation before thereader
block is executed, this parameter contains an error object on output.reader
A Block object containing the file operations you want to perform in a coordinated manner. This block receives an
NSURL
object containing the URL of the item and returns no value. Always use the URL passed into the block instead of the value in theurl
parameter.
Discussion
You use this method to perform read-related operations on a file or directory in a coordinated manner. This method executes synchronously, blocking the current thread until the reader
block finishes executing. Before executing that block, though, the file coordinator waits until other relevant file presenter objects finish in-progress actions. Similarly, your read operation may cause pending actions for other file presenters to wait until your operations are complete. Whether or not the file coordinator waits depends on whether the item being read is a file or a directory and also depends on other related operations.
If the
url
parameter specifies a file:This method waits for other writers of the exact same file to finish in-progress actions.
This method waits if the file is a file package or any item inside the file package and other writers are writing to other items in the package directory.
This method does not wait for other readers of the file.
This method does not wait for writers that are manipulating the parent directory of the file, unless one of those writers specified the
for
orDeleting for
option.Moving
If the
url
parameter specifies a directory:This method waits if other write operations are occurring on the exact same directory.
This method does not wait if write operations are occurring on items inside the directory (but not on the directory itself).
This method does not wait for other readers of the directory.
This method does not wait for writers that are manipulating the parent directory of the directory, unless one of those writers specified the
for
orDeleting for
option.Moving
When invoking these methods, declare a _
variable before the accessor block and initialize it to a value that signals failure, and then inside the accessor block set it to a value that indicates success. If the coordinated operation fails, then the accessor block never runs. The sentinel variable still holds a value that indicates failure, and the NSError
out parameter contains a reference that describes the error.
This method calls the relinquish
method of any relevant file presenters. This method is called for file presenters in the current process and in other processes. Depending on the options you specify, other methods of the file presenters may also be called. When reading a file package directory, file presenter objects that are currently reading the contents of that file package also receive these notifications. All of the called methods must return successfully before the file coordinator executes your block. If multiple file presenters are operating on the item, the order in which those presenters are notified is undefined.
If the device has not yet downloaded the file at the given URL, this method blocks (potentially for a long time) while the file is downloaded. If the file cannot be downloaded, this method fails. Alternatively; use a metadata query to check for the NSMetadata
key, and then call the start
method to download the file before trying to read it.
If you want to perform a write operation from inside a read block, use the coordinate(writing
method.
If you want to perform a batch read operation on multiple files, use the prepare(for
method instead.