NSFileVersion Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 5.0 and later.
Declared in
NSFileVersion.h

Overview

An NSFileVersion object represents a snapshot of a file at a specific point in time. You use the NSFileVersion class to access and create and manage file revisions in your application. Each instance of this class contains meta information about a single revision, such as the location of the file containing the revision data, 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

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 version that are in conflict.

Availability
  • Available in iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 and later.
Declared In
NSFileVersion.h

resolved

A Boolean value indicating whether the version object is not in conflict.

@property (getter=isResolved) BOOL resolved
Discussion

When the system detects a conflict involving this version, it sets this property to NO. After resolving the conflict, set this property to YES to let the system know that it is resolved. Resolving a conflict causes the current version object to be removed from any reports about conflicting versions, such as those returned by the unresolvedConflictVersionsOfItemAtURL: method.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSFileVersion.h

URL

The URL identifying the location of the data associated with the current 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.

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

Availability
  • Available in iOS 5.0 and later.
Declared In
NSFileVersion.h

Class Methods

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 iOS 5.0 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 iOS 5.0 and later.
Declared In
NSFileVersion.h

removeOtherVersionsOfItemAtURL:error:

Removes all versions of the 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 and later.
See Also
Declared In
NSFileVersion.h

Instance Methods

removeAndReturnError:

Remove this version object 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 and later.

Declared in NSFileVersion.h.



© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-10-12)

Did this document help you? Yes It's good, but... Not helpful...