Class: NSFileCoordinator

Inherits:
NSObject show all

Overview

The NSFileCoordinator class coordinates the reading and writing of files and directories among multiple processes and objects in the same process. You use instances of this class as-is to read from, write to, modify the attributes of, change the location of, or delete a file or directory. Before your code to perform those actions executes, though, the file coordinator lets registered file presenter objects perform any tasks that they might require to ensure their own integrity. For example, if you want to change the location of a file, other objects interested in that file need to know where you intend to move it so that they can update their references.

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from NSObject

#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version

Constructor Details

This class inherits a constructor from NSObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class NSObject

Class Method Details

+ (Object) addFilePresenter(filePresenter)

Registers the specified file presenter object so that it can receive notifications. This method registers the file presenter object process-wide. Thus, any file coordinator objects you create later automatically know about the file presenter object and know to message it when its file or directory is affected.In a managed memory application—that is, an application that uses retain and release calls—it is your responsibility to balance calls to this method with a corresponding call to the removeFilePresenter: method. You must remove file presenters from the process-wide registry before the object is deallocated. If your application is garbage collected, file presenters automatically unregister themselves in their finalize method.If you call this method while file operations are already underway in another thread, your file presenter may not receive notifications for that operation. To prevent missing such notifications, create a file coordinator, call its coordinateReadingItemAtURL:options:error:byAccessor: method, and register your file presenter object there. Synchronizing on the presented file or directory guarantees that when your block executes, all other objects have completed any tasks and you have sole access to the item.

Parameters:

  • filePresenter (Object) —

    The file presenter object to register.

Returns:

+ (Array) filePresenters

Returns an array containing the currently registered file presenter objects.

Returns:

+ (Object) removeFilePresenter(filePresenter)

Unregisters the specified file presenter object. If your application uses a managed memory model, you must call this method to unregister file presenters before those objects are deallocated. In a garbage-collected application, file presenters are unregistered automatically when they are finalized.

Parameters:

  • filePresenter (Object) —

    The file presenter object to unregister. If the object is not currently registered, this method does nothing.

Returns:

Instance Method Details

- (Object) cancel

Cancels any active file coordination calls. Use this method to cancel any active calls to coordinate the reading or writing of a file. If the block passed to the file coordination call has not yet been executed—perhaps because the file coordinator is still waiting for a response from other file presenters—the file coordinator method stops waiting for a response, does not execute its block, and returns an error object with the error code NSUserCancelledError. However, if the block is already being executed, the file coordinator method does not return until the block finishes executing. You can call this method from any thread of your application and it returns immediately without waiting for the file coordinator object to respond. Thus, when this method returns, you cannot assume that the read or write operation occurred or did not occur. (In fact, it is possible for this method to return while the file coordinator is in the middle of executing a block.) If you want to know whether the operation actually occurred, you must track it yourself by setting a flag when the block starts executing or by using some other means.

Returns:

- (Object) coordinateReadingItemAtURL(url, options:options, error:outError, byAccessor:reader)

Initiates a read operation on a single file or directory using the specified options. 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 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 and other writers are writing to 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 NSFileCoordinatorWritingForDeleting or NSFileCoordinatorWritingForMoving option.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 NSFileCoordinatorWritingForDeleting or NSFileCoordinatorWritingForMoving option.This method calls the relinquishPresentedItemToReader: method of any relevant file presenters. This method is called both 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.Do not nest calls to file coordinator methods inside the block you pass to this method. If you call this method or any of the other file coordination methods from inside your block, the file coordinator object throws an exception. If you want to perform a write operation from inside a read block, use the coordinateWritingItemAtURL:options:writingItemAtURL:options:error:byAccessor: method instead. If you want to perform a batch read operation on multiple files, use the prepareForReadingItemsAtURLs:options:writingItemsAtURLs:options:error:byAccessor: method.

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 reader parameter may be different than the one in this parameter.

  • options —

    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.

  • 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 the reader 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 the url parameter.

Returns:

- (Object) coordinateReadingItemAtURL(readingURL, options:readingOptions, writingItemAtURL:writingURL, options:writingOptions, error:outError, byAccessor:readerWriter)

Initiates a read operation that contains a follow-up write operation. You use this method to perform a read operation that might also contain a write operation that needs to be coordinated. This method executes synchronously, blocking the current thread until the readerWriter block finishes executing. When performing the write operation, you may call the coordinateWritingItemAtURL:options:error:byAccessor: method from your readerWriter 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 coordinateReadingItemAtURL:options:error:byAccessor: method.

Parameters:

  • readingURL —

    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 block in the readerWriter parameter may be different than the one in this parameter.

  • 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.

  • writingURL —

    A URL identifying the 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 readerWriter parameter may be different than the one in this parameter.

  • 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 readerWriter parameter is not executed. If you cancel this operation before the readerWriter block is executed, this parameter contains an error object on output.

  • readerWriter —

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

Returns:

- (Object) coordinateWritingItemAtURL(url, options:options, error:outError, byAccessor:writer)

Initiates a write operation on a single file or directory using the specified options. You use this method to perform write-related operations on a file or directory in a coordinated manner. This method executes synchronously, blocking the current thread until the writer block finishes executing. Before executing the block, though, the file coordinator waits until other relevant file presenter objects finish in-progress actions. Similarly, your write 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 written is a file or directory and also depends on other related operations. If the url parameter specifies a file:This method waits for other readers and writers of the exact same file to finish in-progress actions. This method waits if the file is a file package and other writers are reading or writing items in the package directory.This method does not wait for readers or writers that are manipulating the parent directory of the file, unless one of those writers specified the NSFileCoordinatorWritingForDeleting or NSFileCoordinatorWritingForMoving option.If the url parameter specifies a directory:This method waits if other read or write operations are occurring on the exact same directory.This method does not wait if read or write operations are occurring on items inside the directory (but not on the directory itself).This method does not wait for readers or writers that are manipulating the parent directory of the directory, unless one of those writers specified the NSFileCoordinatorWritingForDeleting or NSFileCoordinatorWritingForMoving option.This method calls the relinquishPresentedItemToWriter: method of any relevant file presenters. This method is called both 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 writing a file package directory, file presenter objects that are currently reading or writing 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.Note: When deleting an item inside a file package using the NSFileCoordinatorWritingForDeleting option, the file coordinator does not call the accommodatePresentedItemDeletionWithCompletionHandler: method of any file presenters monitoring the file package directory itself. Instead, the delete operation is treated as a write operation on the file package. With one exception, do not nest calls to file coordinator methods inside the block you pass to this method. You may call the coordinateReadingItemAtURL:options:error:byAccessor: method to read the file if you discover through modification-date checking that the contents of the file have changed. However, if you call this method from inside your block, the file coordinator object throws an exception.

Parameters:

  • url —

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

  • options —

    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 write 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 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 the url parameter.

Returns:

- (Object) coordinateWritingItemAtURL(url1, options:options1, writingItemAtURL:url2, options:options2, error:outError, byAccessor:writer)

Initiates a write operation that involves a secondary write operation. 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.

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 than 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 than 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.

Returns:

- (Object) initWithFilePresenter(filePresenterOrNil)

Initializes and returns a file coordinator object using the specified file presenter. Specifying a file presenter at initialization time is strongly recommended, especially if the file presenter is initiating the file operation. Otherwise, the file presenter itself would receive notifications when it made changes to the file and would have to compensate for that fact. Receiving such notifications could also deadlock too if the file presenter’s code and its notifications run on the same thread.

Parameters:

  • filePresenterOrNil (Object) —

    The file presenter object that is initiating some action on its file or directory. This object is assumed to be performing the relevant file or directory operations and therefore does not receive notifications about those operations from the returned file coordinator object. This parameter may be nil.

Returns:

  • (Object) —

    A file coordinator object to use to coordinate file-related operations.

- (Object) itemAtURL(oldURL, didMoveToURL:newURL)

Notifies relevant file presenters that the location of a file or directory changed. If you move or rename a file or directory as part of a write operation, call this method to notify relevant file presenters that the change occurred. This method calls the presentedItemDidMoveToURL: method of any relevant file presenters. You must call this method from a block invoked by the coordinateWritingItemAtURL:options:error:byAccessor: or coordinateWritingItemAtURL:options:writingItemAtURL:options:error:byAccessor: method. Calling this method with the same URL in the oldURL and newURL parameters is harmless.

Parameters:

  • oldURL (NSURL) —

    The old location of the file or directory.

  • newURL (NSURL) —

    The new location of the file or directory.

Returns:

- (Object) itemAtURL(oldURL, willMoveToURL:newURL)

Announces that your app is moving a file to a new URL. This method is intended for apps that adopt App Sandbox.Some apps need to rename files while saving them. For example, when a user adds an attachment to a rich text document, TextEdit changes the document’s filename extension from .rtf to .rtfd. In such a case, in a sandboxed app, you must call this method to declare your intent to rename a file without user approval.After the renaming process succeeds, call the itemAtURL:didMoveToURL: method, with the same arguments, to provide your app with continued access to the file under its new name, while also giving up access to any file that appears with the old name.If your OS X app is not sandboxed, this method serves to purpose. This method is nonfunctional in iOS.

Parameters:

  • oldURL (NSURL) —

    The old location of the file or directory.

  • newURL (NSURL) —

    The new location of the file or directory.

Returns:

- (Object) prepareForReadingItemsAtURLs(readingURLs, options:readingOptions, writingItemsAtURLs:writingURLs, options:writingOptions, error:outError, byAccessor:batchAccessor)

Prepare to read or write from multiple files in a single batch operation. You use this method to prepare the file coordinator for multiple read and write operations. 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 but calls the coordinateReadingItemAtURL:options:error:byAccessor: and coordinateWritingItemAtURL:options:error:byAccessor: methods to perform them. The reason to call this method first is to improve performance when reading and writing large numbers of files or directories. 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.

Parameters:

  • readingURLs (Array) —

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

  • readingOptions (NSFileCoordinatorReadingOptions) —

    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 (Array) —

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

  • writingOptions (NSFileCoordinatorWritingOptions) —

    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 (Pointer) —

    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 (Object) —

    A Block object containing additional calls to methods of this class. This block receives a completion handler that it must execute when it has finished its read and write calls.

Returns: