NSFileVersion Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.7 and later.
Declared in
NSFileVersion.h

Overview

An NSFileVersion object represents a snapshot of a file at a specific point in time. Use the methods of this class to access, create, and manage file revisions in your app.

Each file version instance contains metainformation about a single revision, including the location of the associated file, the modification date of the revision, and whether the revision is discardable.

In Mac apps, you can use file version objects to track changes to a local file over time and to prevent the loss of data during editing. When managing local versions, the document architecture creates versions at specific points in the lifetime of your application. Your application can also create versions explicitly at times that your application designates as appropriate.

In addition to managing local files, the system also uses this class to manage cloud-based files. For files in the cloud, there is usually only one version of the file at any given time. However, additional file versions may be created in cases where two different computers attempt to save the file to the cloud at the same time. In that case, one file is chosen as the current version and any other versions are tagged as being in conflict with the original. Conflict versions are reported to the appropriate file presenter objects and should be resolved as soon as possible so that the corresponding files can be removed from the cloud.

Tasks

Getting the Version of a File

Creating a New Version

Accessing the Version Information

Handling Version Conflicts

Replacing and Deleting Versions

Properties

conflict

A Boolean value indicating whether the contents of the version are in conflict with the contents of another version. (read-only)

@property (readonly, getter=isConflict) BOOL conflict
Discussion

When two or more versions of a file are written at the same time, perhaps because the file is saved in the cloud and one or more of the writers were offline when they were writing, the system attempts to resolve the conflict automatically. It does this by picking one of the file versions to be the current file and setting this property to YES for the other file versions that are in conflict.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSFileVersion.h

discardable

A Boolean value that specifies whether the system can delete the associated file at some future time.

@property(getter=isDiscardable) BOOL discardable
Discussion

Marking a file version as discardable gives the system the flexibility to reclaim the space, occupied by the associated file, at some future time. Do not, however, depend on the file being discarded.

After setting this property to YES, do not set this property to NO again. Doing so causes the system to raise an exception. In addition, if you set this property to YES for the version of the file returned by the currentVersionOfItemAtURL: method, the system raises an exception.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSFileVersion.h

localizedName

The string containing the user-presentable name of the file version. (read-only)

@property(readonly) NSString *localizedName
Discussion

When displaying different versions of a file to the user, you should present this string to the user instead of the version’s URL.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSFileVersion.h

localizedNameOfSavingComputer

The user-presentable name of the computer on which the revision was saved. (read-only)

@property (readonly) NSString *localizedNameOfSavingComputer
Discussion

If the current revision has been deleted from disk, or if no computer name was recorded, the value in this property is nil. The computer name is guaranteed to be recorded only when the current version is in conflict with another version. The version object does not track changes to the computer name itself. Thus, if the computer name changed, the value in this string might be an old value.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSFileVersion.h

modificationDate

The modification date of the version. (read-only)

@property(readonly) NSDate *modificationDate
Discussion

If the version has been deleted, this value is nil.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSFileVersion.h

persistentIdentifier

The identifier for this version of the file. (read-only)

@property(readonly) id<NSCoding> persistentIdentifier
Discussion

You can save the value of this property persistently and use it to recreate the version object later. When recreating the version object using the versionOfItemAtURL:forPersistentIdentifier: method, the version object returned is equivalent to the current object.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSFileVersion.h

resolved

A Boolean value that indicates the version object is not in conflict (YES) or is in conflict (NO).

@property (getter=isResolved) BOOL resolved
Discussion

When the system detects a conflict involving versions of a file, it sets this property to NO to indicate an unresolved conflict. After you resolve the conflict, set this property to YES to tell the system it is resolved; you must then remove any versions of the file that are no longer useful.

To remove an unused version of a file, call the removeAndReturnError: method. To remove all unused versions of a file, call the removeOtherVersionsOfItemAtURL:error: method.

Resolving a conflict causes the file version object to be removed from any reports about conflicting versions, such as those returned by the unresolvedConflictVersionsOfItemAtURL: method.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSFileVersion.h

URL

The URL identifying the location of the file associated with the file version object. (read-only)

@property(readonly) NSURL *URL
Discussion

The URL identifies the location of the file associated with this version. If this version of the file has been deleted, the value in this property is nil.

Do not display any part of this URL to the user. The location of file versions is managed by the system and should not be exposed to the user. If you want to present the name of a file version, use the localizedName property.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSFileVersion.h

Class Methods

addVersionOfItemAtURL:withContentsOfURL:options:error:

Creates a version of the file at the specified location.

+ (NSFileVersion *)addVersionOfItemAtURL:(NSURL *)url withContentsOfURL:(NSURL *)contentsURL options:(NSFileVersionAddingOptions)options error:(NSError **)outError
Parameters
url

The location at which to store the new file version.

contentsURL

The URL that specifies the file to use for the version contents.

options

Specify 0 for this parameter if you want to create a copy of the file at the location specified by the url parameter. Alternatively, specify one of the constants described in “NSFileVersionAddingOptions.”

outError

On input, a pointer to an error object. If an error occurs, this pointer is set to an NSError object with information about the error.

Return Value

The file version object representing the new version or nil if an error occurred.

Discussion

You can use this method to save a version of your file to the location specified by the url parameter. The contents of the file are taken from the contentsURL parameter, whose value may be the same as the url parameter.

You should always add file versions as part of a coordinated write operation to a file. In other words, always call this method from a block passed to a file coordinator object to initiate a write operation. Doing so ensures that no other processes are operating on the file while you save the version to its new location.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSFileVersion.h

currentVersionOfItemAtURL:

Returns the most recent version object for the file at the specified URL.

+ (NSFileVersion *)currentVersionOfItemAtURL:(NSURL *)url
Parameters
url

The URL of the file whose version object you want.

Return Value

The version object representing the current version of the file or nil if there is no such file.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSFileVersion.h

otherVersionsOfItemAtURL:

Returns all versions of the specified file except the current version.

+ (NSArray *)otherVersionsOfItemAtURL:(NSURL *)url
Parameters
url

The URL of the file whose versions you want.

Return Value

An array of file version objects or nil if there is no such file. The array does not contain the version object returned by the currentVersionOfItemAtURL: method.

Discussion

For locally based files, this property typically contains versions of the file that you saved explicitly or that were saved at appropriate times while the file was being edited. For documents residing in the cloud, this property typically returns zero or more file versions representing conflicting versions of a file that need to be resolved with the current version.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSFileVersion.h

removeOtherVersionsOfItemAtURL:error:

Removes all versions of a file, except the current one, from the version store.

+ (BOOL)removeOtherVersionsOfItemAtURL:(NSURL *)inFileURL error:(NSError **)outError
Parameters
inFileURL

The file whose older versions you want to delete. If the file at this URL does not exist, a new file is created at the location.

outError

On input, a pointer to an error object. If an error occurs, this pointer is set to an NSError object with information about the error.

Return Value

YES if the older file versions were removed successfully or NO if an error occurred.

Discussion

This method removes all versions except the current one from the version store, freeing up the associated storage space.

You should always remove file versions as part of a coordinated write operation to a file. In other words, always call this method from a block passed to a file coordinator object to initiate a write operation. Doing so ensures that no other processes are operating on the file while you remove the version information.

If successful, subsequent requests for the versions of the file reflect that only the current version is available. You can use this method to free up disk space by removing versions that are no longer needed.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSFileVersion.h

temporaryDirectoryURLForNewVersionOfItemAtURL:

Creates and returns a temporary directory to use for saving the contents of the file.

+ (NSURL *)temporaryDirectoryURLForContentsOfNewVersionOfItemAtURL:(NSURL *)url
Parameters
url

The URL of the file whose contents you want to save.

Return Value

A URL identifying the temporary directory in which to create a the new file. You must delete the directory specified by this URL after you have created the file and moved it to its proper location.

Discussion

You can use this method in situations where you want to create a file in a temporary location. For example, you might use this method when saving the contents of a file to disk for the first time. When you finish creating the temporary file, move it to a more appropriate location, such as the user’s Documents directory. You must delete the directory returned by this method when you are done with it.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSFileVersion.h

unresolvedConflictVersionsOfItemAtURL:

Returns an array of version objects that are currently in conflict for the specified URL.

+ (NSArray *)unresolvedConflictVersionsOfItemAtURL:(NSURL *)url
Parameters
url

The URL of the file that has associated version objects.

Return Value

An array of NSFileVersion objects that represent the versions in conflict or nil if the file at URL does not exist.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSFileVersion.h

versionOfItemAtURL:forPersistentIdentifier:

Returns the version of the file that has the specified persistent ID.

+ (NSFileVersion *)versionOfItemAtURL:(NSURL *)url forPersistentIdentifier:(id)persistentIdentifier
Parameters
url

The URL of the file whose version you want.

persistentIdentifier

The persistent ID of the NSFileVersion object you want.

Return Value

The file version object with the specified ID or nil if no such version object exists.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSFileVersion.h

Instance Methods

removeAndReturnError:

Remove this version object and its associated file from the version store.

- (BOOL)removeAndReturnError:(NSError **)outError
Parameters
outError

On input, a pointer to an error object. If an error occurs, this pointer is set to an NSError object with information about the error.

Return Value

YES if this version was removed successfully or NO if it was not.

Discussion

This method removes this version object and its file from the version store, freeing up the associated storage space. You must not call this method for the current file version—that is, the version object returned by the currentVersionOfItemAtURL: method.

You should always remove file versions as part of a coordinated write operation to a file. In other words, always call this method from a block passed to a file coordinator object to initiate a write operation. Doing so ensures that no other processes are operating on the file while you remove the version information.

If successful, subsequent requests for the versions of the file do not include this version object (or any object with the same information). You can use this method to free up disk space by removing versions that are no longer needed.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSFileVersion.h

replaceItemAtURL:options:error:

Replace the contents of the specified file with the contents of the current version’s file.

- (NSURL *)replaceItemAtURL:(NSURL *)url options:(NSFileVersionReplacingOptions)options error:(NSError **)error
Parameters
url

The file whose contents you want to replace. If the file at this URL does not exist, a new file is created at the location.

options

Specify 0 to overwrite the file in place; otherwise, specify one of the constants described in “NSFileVersionReplacingOptions”.

error

On input, a pointer to an error object. If an error occurs, this pointer is set to an NSError object with information about the error.

Return Value

The URL of the file that was written, which may be different than the one specified in the url parameter.

Discussion

When replacing the contents of the file, this method does not normally replace the display name associated with the file. The only exception is when the file at url is of a different type than the file associated with this version object. In such a case, the file name remains the same but its filename extension changes to match the type of the new contents. (Of course, if filename extension hiding is enabled, this change is not noticeable to users.)

Availability
  • Available in OS X v10.7 and later.
Declared In
NSFileVersion.h

Constants

NSFileVersionAddingOptions

Options for adding a new file version.

enum {
   NSFileVersionAddingByMoving = 1 << 0
};
typedef NSUInteger NSFileVersionAddingOptions;
Constants
NSFileVersionAddingByMoving

When adding a file, you can specify this option if you want to create the version by moving the source file to the specified location.

Available in OS X v10.7 and later.

Declared in NSFileVersion.h.

NSFileVersionReplacingOptions

Options for replacing a file version.

enum {
   NSFileVersionReplacingByMoving = 1 << 0
};
typedef NSUInteger NSFileVersionReplacingOptions;
Constants
NSFileVersionReplacingByMoving

When replacing a file, move the old version of the file out of the version store instead of copying the new contents into the file’s version. You should use this option in conjunction with a file coordinator to make sure the operation is coordinated with other clients of the file.

Available in OS X v10.7 and later.

Declared in NSFileVersion.h.