iOS Developer Library

Developer

Foundation Framework Reference NSFileVersion Class Reference

Options
Deployment Target:

On This Page
Language:

NSFileVersion

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 5.0 and later.

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.

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

    Declaration

    Swift

    class func currentVersionOfItemAtURL(_ url: NSURL) -> NSFileVersion?

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    class func otherVersionsOfItemAtURL(_ url: NSURL) -> [AnyObject]?

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    init?(ofItemAtURL url: NSURL, forPersistentIdentifier persistentIdentifier: AnyObject) -> NSFileVersion

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later.

  • URL URL Property

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

    Declaration

    Swift

    @NSCopying var URL: NSURL { get }

    Objective-C

    @property(readonly, copy) 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    var localizedName: String? { get }

    Objective-C

    @property(readonly, copy) 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    var localizedNameOfSavingComputer: String? { get }

    Objective-C

    @property(readonly, copy) 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    @NSCopying var modificationDate: NSDate? { get }

    Objective-C

    @property(readonly, copy) NSDate *modificationDate

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    var persistentIdentifier: NSCoding { get }

    Objective-C

    @property(readonly, retain) 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later.

  • conflict conflict Property

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

    Declaration

    Swift

    var conflict: Bool { get }

    Objective-C

    @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 YEStrue for the other file versions that are in conflict.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later.

  • resolved resolved Property

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

    Declaration

    Swift

    var resolved: Bool

    Objective-C

    @property(getter=isResolved) BOOL resolved

    Discussion

    When the system detects a conflict involving versions of a file, it sets this property to NOfalse to indicate an unresolved conflict. After you resolve the conflict, set this property to YEStrue 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    class func unresolvedConflictVersionsOfItemAtURL(_ url: NSURL) -> [AnyObject]?

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    func replaceItemAtURL(_ url: NSURL, options options: NSFileVersionReplacingOptions, error error: NSErrorPointer) -> NSURL?

    Objective-C

    - (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.)

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    func removeAndReturnError(_ outError: NSErrorPointer) -> Bool

    Objective-C

    - (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

    YEStrue if this version was removed successfully or NOfalse 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    class func removeOtherVersionsOfItemAtURL(_ inFileURL: NSURL, error outError: NSErrorPointer) -> Bool

    Objective-C

    + (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

    YEStrue if the older file versions were removed successfully or NOfalse 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later.

  • Options for adding a new file version.

    Declaration

    Swift

    struct NSFileVersionAddingOptions : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var ByMoving: NSFileVersionAddingOptions { get } }

    Objective-C

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

    Constants

    • ByMoving

      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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later.

  • Options for replacing a file version.

    Declaration

    Swift

    struct NSFileVersionReplacingOptions : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var ByMoving: NSFileVersionReplacingOptions { get } }

    Objective-C

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

    Constants

    • ByMoving

      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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later.