Instance Method

prepareForReadingItemsAtURLs:options:writingItemsAtURLs:options:error:byAccessor:

Prepare to read or write from multiple files in a single batch operation.

Declaration

- (void)prepareForReadingItemsAtURLs:(NSArray<NSURL *> *)readingURLs options:(NSFileCoordinatorReadingOptions)readingOptions writingItemsAtURLs:(NSArray<NSURL *> *)writingURLs options:(NSFileCoordinatorWritingOptions)writingOptions error:(NSError * _Nullable *)outError byAccessor:(void (^)(void (^completionHandler)(void)))batchAccessor;

Parameters

readingURLs

An array of NSURL objects identifying the items you want to read.

readingOptions

One of the reading options described in NSFileCoordinatorReadingOptions. If you pass 0 for this parameter, the savePresentedItemChangesWithCompletionHandler: method of relevant file presenters is called before your block executes.

writingURLs

An array of NSURL objects identifying the items you want to write.

writingOptions

One of the writing options described in NSFileCoordinatorWritingOptions. The options you specify partially determine how file presenters are notified and how this file coordinator object waits to execute your block.

outError

On input, a pointer to a pointer for an error object. If a file presenter encounters an error while preparing for this operation, that error is returned in this parameter and the block in the writer parameter is not executed. If you cancel this operation before the batchAccessor block is executed, this parameter contains an error object on output.

batchAccessor

A Block object containing additional calls to methods of this class.

The block takes the following parameter:

completionHandler

A completion handler block. The batch accessor must call the completion handler when it has finished its read and write calls.

Discussion

Use this method to prepare the file coordinator for multiple read and write operations. Because file coordination requires interprocess communication, it is much more efficient to batch changes to large numbers of files and directories than to change each item individually. The file coordinator uses the values in the readingURLs and writingURLs parameters, together with reading and writing options, to prepare any relevant file presenters for the upcoming operations. Specifically, it uses these parameters in the same way as the coordinateReadingItemAtURL:options:error:byAccessor: and coordinateWritingItemAtURL:options:error:byAccessor: methods to determine which file presenter methods to call.

This method executes synchronously, blocking the current thread until the batchAccessor block finishes executing. The block you provide for the batchAccessor parameter does not perform the actual operations itself. Instead, you must call the individual coordinated read and write methods from inside the batchAccessor block. You must then call the completion handler after all the coordinated reads and writes have completed. You can call the completion handler from any thread.

Don’t simply pass this method all the URLs that are passed into the nested coordinate methods. Instead pass only the top-level files and directories involved in the operation. This method triggers messages to the file presenters of those items and to the file presenters of any items contained by those items.

In most cases, passing the same reading and writing options to both this method and the contained coordination operations is redundant. For example, it is often appropriate to pass NSFileCoordinatorReadingWithoutChanges to nested read operations. This method has already triggered a call to savePresentedItemChangesWithCompletionHandler:. The individual read operations do not need to trigger additional calls.

See Also

Coordinating File Operations Synchronously

coordinateReadingItemAtURL:options:error:byAccessor:

Initiates a read operation on a single file or directory using the specified options.

coordinateWritingItemAtURL:options:error:byAccessor:

Initiates a write operation on a single file or directory using the specified options.

coordinateReadingItemAtURL:options:writingItemAtURL:options:error:byAccessor:

Initiates a read operation that contains a follow-up write operation.

coordinateWritingItemAtURL:options:writingItemAtURL:options:error:byAccessor:

Initiates a write operation that involves a secondary write operation.

itemAtURL:willMoveToURL:

Announces that your app is moving a file to a new URL.

itemAtURL:didMoveToURL:

Notifies relevant file presenters that the location of a file or directory changed.

cancel

Cancels any active file coordination calls.