Instance Property

backupFileURL

The URL for the document’s backup file that was created during an autosave operation.

Declaration

@property(readonly, copy) NSURL *backupFileURL;

Discussion

This property specifies the location of the backup file, if any. If a backup file cannot be created or is not needed, the value of this property is nil.

Starting in OS X v10.8, document versions can be preserved using a backup file created during an autosave operation, which supports document versioning. This property gives you access to the backup file’s URL.

Using an autosave backup file for preserving versions is efficient. This is because an NSDocument instance is able to use the NSFileVersionReplacingByMoving option when it calls the replaceItemAtURL:options:error: method. The document gets the value of this property twice during saving:

  1. Before calling the writeSafelyToURL:ofType:forSaveOperation:error: method: This is to check whether using the replace-by-moving option is possible and, if not, to allow the system to preserve data by instead using copying.

  2. Within the writeSafelyToURL:ofType:forSaveOperation:error: method: This is to discover where to put the backup file.

When you implement the writeSafelyToURL:ofType:forSaveOperation:error: method with the NSSaveOperation or NSAutosaveInPlaceOperation operation type, you must check this property’s value. If it is not nil, move the previous contents of the file (that would be overwritten) to the URL’s location. The default implementation of writeSafelyToURL:ofType:forSaveOperation:error: does this.

To create a backup file from within your custom implementation of the writeSafelyToURL:ofType:forSaveOperation:error: method, call the NSFileManager method replaceItemAtURL:withItemAtURL:backupItemName:options:resultingItemURL:error:, using a backup item name of [[self backupFileURL] lastPathComponent] and an option of NSFileManagerItemReplacementWithoutDeletingBackupItem option. If your custom implementation is unable to keep the backup file, you must override this property and return nil to ensure that the document’s file gets correctly preserved before it gets overwritten.

The default implementation of the writeSafelyToURL:ofType:forSaveOperation:error: method returns a non-nil value based on the value of [self fileURL], but only if the document’s file needs to be preserved prior to saving or if the preservesVersions method returns NO. Otherwise, it returns nil.

See Also

Reading From and Writing to Files

- readFromFileWrapper:ofType:error:

Sets the contents of this document by reading from a file wrapper of a specified type.

fileModificationDate

The last known modification date of the document’s on-disk representation.

- runModalSavePanelForSaveOperation:delegate:didSaveSelector:contextInfo:

Presents a modal Save panel to the user, then tries to save the document if the user approves the panel.

shouldRunSavePanelWithAccessoryView

A Boolean value indicating whether the document’s Save panel displays a list of supported writable document types.

keepBackupFile

A Boolean value indicating whether the document keeps the backup files created before the document data is written to a file.

fileURL

The location of the document’s on-disk representation.

draft

A Boolean value indicating whether the document is a draft that the user has not expressed an interest in keeping around.