Instance Method

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

Initiates a write operation that involves a secondary write operation.

Declaration

- (void)coordinateWritingItemAtURL:(NSURL *)url1 options:(NSFileCoordinatorWritingOptions)options1 writingItemAtURL:(NSURL *)url2 options:(NSFileCoordinatorWritingOptions)options2 error:(NSError * _Nullable *)outError byAccessor:(void (^)(NSURL *newURL1, NSURL *newURL2))writer;

Parameters

url1

A URL identifying the first file or directory to write. If other objects or processes are acting on the item at the URL, the actual URL passed to the block in the writer parameter may be different from the one in this parameter.

options1

One of the writing options described in NSFileCoordinatorWritingOptions.

url2

A URL identifying the other file or directory to write. If other objects or processes are acting on the item at the URL, the actual URL passed to the block in the writer parameter may be different from the one in this parameter.

options2

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 writer block is executed, this parameter contains an error object on output.

writer

A Block object containing the write operations you want to perform in a coordinated manner. This block receives NSURL objects containing the URLs of the items to write and returns no value. Always use the URLs passed into the block instead of the values in the url1 and url2 parameters.

Discussion

When invoking these methods, declare a __block 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.

You use this method to perform two write operations without the risk of those operations creating a deadlock. This method executes synchronously, blocking the current thread until the writer block finishes executing. You may call the coordinateWritingItemAtURL:options:error:byAccessor: method from your writer block. This method does the canonical lock ordering that is required to prevent a potential deadlock of the file operations.

This method makes the same calls to file presenters, and has the same general wait behavior, as the coordinateWritingItemAtURL:options:error:byAccessor: method.

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.

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

Prepare to read or write from multiple files in a single batch 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.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software