Class: NSFileVersion

Inherits:
NSObject show all

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.

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from NSObject

#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version

Constructor Details

This class inherits a constructor from NSObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class NSObject

Instance Attribute Details

- (Boolean) conflict (readonly)

A Boolean value indicating whether the contents of the version are in conflict with the contents of another version. (read-only) 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.

Returns:

  • (Boolean)

- (String) localizedName (readonly)

The string containing the user-presentable name of the file version. (read-only) When displaying different versions of a file to the user, you should present this string to the user instead of the version’s URL.

Returns:

- (String) localizedNameOfSavingComputer (readonly)

The user-presentable name of the computer on which the revision was saved. (read-only) 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.

Returns:

- (NSDate) modificationDate (readonly)

The modification date of the version. (read-only) If the version has been deleted, this value is nil.

Returns:

- (Object) persistentIdentifier (readonly)

The identifier for this version of the file. (read-only) 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.

Returns:

- (Boolean) resolved

A Boolean value indicating whether the version object is not in conflict. 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.Important: Never set the value of this property to NO in your own code. Doing so causes the version object to raise an exception.

Returns:

  • (Boolean)

- (NSURL) URL (readonly)

The URL identifying the location of the data associated with the current file version object. (read-only) 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.

Returns:

Class Method Details

+ (NSFileVersion) currentVersionOfItemAtURL(url)

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

Parameters:

  • url (NSURL)

    The URL of the file whose version object you want.

Returns:

  • (NSFileVersion)

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

+ (Array) otherVersionsOfItemAtURL(url)

Returns all versions of the specified file except the current version. 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.

Parameters:

  • url (NSURL)

    The URL of the file whose versions you want.

Returns:

  • (Array)

    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.

+ (Boolean) removeOtherVersionsOfItemAtURL(inFileURL, error:outError)

Removes all versions of the file (except the current one) from the version store. 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.

Parameters:

  • inFileURL (NSURL)

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

    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.

Returns:

  • (Boolean)

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

+ (Array) unresolvedConflictVersionsOfItemAtURL(url)

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

Parameters:

  • url (NSURL)

    The URL of the file that has associated version objects.

Returns:

  • (Array)

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

+ (NSFileVersion) versionOfItemAtURL(url, forPersistentIdentifier:persistentIdentifier)

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

Parameters:

  • url (NSURL)

    The URL of the file whose version you want.

  • persistentIdentifier (Object)

    The persistent ID of the NSFileVersion object you want.

Returns:

  • (NSFileVersion)

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

Instance Method Details

- (Boolean) removeAndReturnError(outError)

Remove this version object from the version store. 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.

Parameters:

  • outError (Pointer)

    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.

Returns:

  • (Boolean)

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

- (NSURL) replaceItemAtURL(url, options:options, error:error)

Replace the contents of the specified file with the contents of the current version’s file. 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.)

Parameters:

  • url (NSURL)

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

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

  • error (Pointer)

    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.

Returns:

  • (NSURL)

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