Mac Developer Library

Developer

Foundation Framework Reference NSFileVersion Class Reference

Options
Deployment Target:

On This Page
Language:

NSFileVersion

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

Inheritance


Conforms To


Import Statement


import Foundation @import Foundation;

Availability


Available in OS X v10.7 and later.
  • 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

    import Foundation

    Availability

    Available in OS X v10.7 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

    import Foundation

    Availability

    Available in OS X v10.7 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

    import Foundation

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    class func temporaryDirectoryURLForNewVersionOfItemAtURL(_ url: NSURL) -> NSURL

    Objective-C

    + (NSURL *)temporaryDirectoryURLForNewVersionOfItemAtURL:(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.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 and later.

  • Creates a version of the file at the specified location.

    Declaration

    Swift

    class func addVersionOfItemAtURL(_ url: NSURL, withContentsOfURL contentsURL: NSURL, options options: NSFileVersionAddingOptions, error outError: NSErrorPointer) -> NSFileVersion?

    Objective-C

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

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 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

    import Foundation

    Availability

    Available in OS X v10.7 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

    import Foundation

    Availability

    Available in OS X v10.7 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

    import Foundation

    Availability

    Available in OS X v10.7 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

    import Foundation

    Availability

    Available in OS X v10.7 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

    import Foundation

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    var discardable: Bool

    Objective-C

    @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 YEStrue, do not set this property to NOfalse again. Doing so causes the system to raise an exception. In addition, if you set this property to YEStrue for the version of the file returned by the currentVersionOfItemAtURL: method, the system raises an exception.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 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

    import Foundation

    Availability

    Available in OS X v10.7 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

    import Foundation

    Availability

    Available in OS X v10.7 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

    import Foundation

    Availability

    Available in OS X v10.7 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

    import Foundation

    Availability

    Available in OS X v10.7 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

    import Foundation

    Availability

    Available in OS X v10.7 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

    import Foundation

    Availability

    Available in OS X v10.7 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 OS X v10.7 and later.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 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 OS X v10.7 and later.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 and later.