Class: NSFileWrapper

Inherits:
NSObject show all

Overview

The NSFileWrapper class provides access to the attributes and contents of file-system nodes. A file-system node is a file, directory, or symbolic link. Instances of this class are known as file wrappers.

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 Method Details

- (String) addFileWrapper(child)

Adds a child file wrapper to the receiver, which must be a directory file wrapper. Use this method to add an existing file wrapper as a child of a directory file wrapper. If the file wrapper does not have a preferred filename, use the setPreferredFilename: method to give it one before calling addFileWrapper:. To create a new file wrapper and add it to a directory, use the addRegularFileWithContents:preferredFilename: method.

Parameters:

Returns:

  • (String) —

    Dictionary key used to store fileWrapper in the directory’s list of file wrappers. The dictionary key is a unique filename, which is the same as the passed-in file wrapper’s preferred filename unless that name is already in use as a key in the directory’s dictionary of children. See “Working With Directory Wrappers” in Application File Management for more information about the file-wrapper list structure.

- (String) addRegularFileWithContents(data, preferredFilename:filename)

Creates a regular-file file wrapper with the given contents and adds it to the receiver, which must be a directory file wrapper. This is a convenience method. The default implementation allocates a new file wrapper, initializes it with initRegularFileWithContents:, sends it setPreferredFilename:, adds it to the directory with addFileWrapper:, and returns what addFileWrapper: returned.

Parameters:

  • data (NSData) —

    Contents for the new regular-file file wrapper.

  • filename (String) —

    Preferred filename for the new regular-file file wrapper.

Returns:

  • (String) —

    Dictionary key used to store the new file wrapper in the directory’s list of file wrappers. The dictionary key is a unique filename, which is the same as the passed-in file wrapper’s preferred filename unless that name is already in use as a key in the directory’s dictionary of children. See “Working With Directory Wrappers” in Application File Management for more information about the file-wrapper list structure.

- (Hash) fileAttributes

Returns a file wrapper’s file attributes.

Returns:

  • (Hash) —

    File attributes, in a dictionary of the same sort as that returned by attributesOfItemAtPath:error: (NSFileManager).

- (String) filename

Provides the filename of a file wrapper. The filename is used for record-keeping purposes only and is set automatically when the file wrapper is created from the file system using initWithURL:options:error: and when it’s saved to the file system using writeToURL:options:originalContentsURL:error: (although this method allows you to request that the filename not be updated).The filename is usually the same as the preferred filename, but might instead be a name derived from the preferred filename. You can use this method to get the name of a child that’s just been read. Don’t use this method to get the name of a child that’s about to be written, because the name might be about to change; send keyForFileWrapper: to the parent instead.

Returns:

  • (String) —

    The file wrapper’s filename; nil when the file wrapper has no corresponding file-system node.

- (Hash) fileWrappers

Returns the file wrappers contained by a directory file wrapper. Returns a dictionary whose values are the file wrapper's children and whose keys are the unique filenames that have been assigned to each one. This method may return nil if the user modifies the directory after you call readFromURL:options:error: or initWithURL:options:error: but before NSFileWrapper has read the contents of the directory. Use the NSFileWrapperReadingImmediate reading option to reduce the likelihood of that problem.

Returns:

  • (Hash) —

    A key-value dictionary of the file wrappers contained in the directory. The dictionary contains entries whose values are the file wrappers and whose keys are the unique filenames that have been assigned to each one. See “Working With Directory Wrappers” in Application File Management for more information about the file-wrapper list structure.

- (Object) initDirectoryWithFileWrappers(childrenByPreferredName)

Initializes the receiver as a directory file wrapper, with a given file-wrapper list. After initialization, the file wrapper is not associated with a file-system node until you save it using writeToURL:options:originalContentsURL:error:. The receiver is initialized with open permissions: anyone can read, write, or modify the directory on disk. If any file wrapper in the directory doesn’t have a preferred filename, its preferred name is automatically set to its corresponding key in the childrenByPreferredName dictionary.

Parameters:

  • childrenByPreferredName (Hash) —

    Key-value dictionary of file wrappers with which to initialize the receiver. The dictionary must contain entries whose values are the file wrappers that are to become children and whose keys are filenames. See “Working With Directory Wrappers” in Application File Management for more information about the file-wrapper list structure.

Returns:

  • (Object) —

    Initialized file wrapper for fileWrappers.

- (Object) initRegularFileWithContents(contents)

Initializes the receiver as a regular-file file wrapper. After initialization, the file wrapper is not associated with a file-system node until you save it using writeToURL:options:originalContentsURL:error:. The file wrapper is initialized with open permissions: anyone can write to or read the file wrapper. .

Parameters:

  • contents (NSData) —

    Contents of the file.

Returns:

  • (Object) —

    Initialized regular-file file wrapper containing contents.

- (Object) initSymbolicLinkWithDestinationURL(url)

Initializes the receiver as a symbolic-link file wrapper that links to a specified file. The file wrapper is not associated with a file-system node until you save it using writeToURL:options:originalContentsURL:error:. The file wrapper is initialized with open permissions: anyone can modify or read the file reference. .

Parameters:

  • url (NSURL) —

    URL of the file the file wrapper is to reference.

Returns:

  • (Object) —

    Initialized symbolic-link file wrapper referencing url.

- (Object) initWithSerializedRepresentation(serializedRepresentation)

Initializes the receiver as a regular-file file wrapper from given serialized data. The file wrapper is not associated with a file-system node until you save it using writeToURL:options:originalContentsURL:error:.

Parameters:

  • serializedRepresentation (NSData) —

    Serialized representation of a file wrapper in the format used for the NSFileContentsPboardType pasteboard type. Data of this format is returned by such methods as serializedRepresentation and RTFDFromRange:documentAttributes: (NSAttributedString).

Returns:

  • (Object) —

    Regular-file file wrapper initialized from serializedRepresentation.

- (Object) initWithURL(url, options:options, error:outError)

Initializes a file wrapper instance whose kind is determined by the type of file-system node located by the URL. If url is a directory, this method recursively creates file wrappers for each node within that directory. Use the fileWrappers method to get the file wrappers of the nodes contained by the directory.

Parameters:

  • url (NSURL) —

    URL of the file-system node the file wrapper is to represent.

  • options (NSFileWrapperReadingOptions) —

    Option flags for reading the node located at url. See “File Wrapper Reading Options” for possible values.

  • outError (Pointer) —

    If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Returns:

  • (Object) —

    File wrapper for the file-system node at url. May be a directory, file, or symbolic link, depending on what is located at the URL. Returns NO (0) if reading is not successful.

- (Boolean) isDirectory

Indicates whether the receiver is a directory file wrapper. Invocations of readFromURL:options:error: may change what is returned by subsequent invocations of this method if the type of the file on disk has changed.

Returns:

  • (Boolean) —

    YES when the receiver is a directory file wrapper, NO otherwise.

- (Boolean) isRegularFile

Indicates whether the receiver is a regular-file file wrapper. Invocations of readFromURL:options:error: may change what is returned by subsequent invocations of this method if the type of the file on disk has changed.

Returns:

  • (Boolean) —

    YES when the receiver is a regular-file wrapper, NO otherwise.

- (Boolean) isSymbolicLink

Indicates whether the receiver is a symbolic-link file wrapper. Invocations of readFromURL:options:error: may change what is returned by subsequent invocations of this method if the type of the file on disk has changed.

Returns:

  • (Boolean) —

    YES when the receiver is a symbolic-link file wrapper, NO otherwise.

- (String) keyForFileWrapper(child)

Returns the dictionary key used by a directory to identify a given file wrapper.

Parameters:

  • child (NSFileWrapper) —

    The child file wrapper for which you want the key.

Returns:

  • (String) —

    Dictionary key used to store the file wrapper in the directory’s list of file wrappers. The dictionary key is a unique filename, which may not be the same as the passed-in file wrapper’s preferred filename if more than one file wrapper in the directory’s dictionary of children has the same preferred filename. See “Working With Directory Wrappers” in Application File Management for more information about the file-wrapper list structure. Returns nil if the file wrapper specified in child is not a child of the directory.

- (Boolean) matchesContentsOfURL(url)

Indicates whether the contents of a file wrapper matches a directory, regular file, or symbolic link on disk. The contents of files are not compared; matching of regular files is based on file modification dates. For a directory, children are compared against the files in the directory, recursively. Because children of directory file wrappers are not read immediately by the initWithURL:options:error: method unless the NSFileWrapperReadingImmediate reading option is used, even a newly-created directory file wrapper might not have the same contents as the directory on disk. You can use this method to determine whether the file wrapper's contents in memory need to be updated. If the file wrapper needs updating, use the readFromURL:options:error: method with the NSFileWrapperReadingImmediate reading option.This table describes which attributes of the file wrapper and file-system node are compared to determine whether the file wrapper matches the node on disk:File-wrapper typeComparison determinantsRegular fileModification date and access permissions.DirectoryChildren (recursive).Symbolic linkDestination pathname.

Parameters:

  • url (NSURL) —

    URL of the file-system node with which to compare the file wrapper.

Returns:

  • (Boolean) —

    YES when the contents of the file wrapper match the contents of url, NO otherwise.

- (String) preferredFilename

Provides the preferred filename for a file wrapper. This name is normally used as the dictionary key when a child file wrapper is added to a directory file wrapper. However, if another file wrapper with the same preferred name already exists in the directory file wrapper when the receiver is added, the filename assigned as the dictionary key may differ from the preferred filename.

Returns:

  • (String) —

    The file wrapper’s preferred filename.

- (Boolean) readFromURL(url, options:options, error:outError)

Recursively rereads the entire contents of a file wrapper from the specified location on disk.

When reading a directory, children are added and removed as necessary to match the file system.

Parameters:

  • url (NSURL) —

    URL of the file-system node corresponding to the file wrapper.

  • options (NSFileWrapperReadingOptions) —

    Option flags for reading the node located at url. See “File Wrapper Reading Options” for possible values.

  • outError (Pointer) —

    If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Returns:

  • (Boolean) —

    YES if successful. If not successful, returns NO after setting outError to an NSError object that describes the reason why the file wrapper could not be reread.

- (NSData) regularFileContents

Returns the contents of the file-system node associated with a regular-file file wrapper. This method may return nil if the user modifies the file after you call readFromURL:options:error: or initWithURL:options:error: but before NSFileWrapper has read the contents of the file. Use the NSFileWrapperReadingImmediate reading option to reduce the likelihood of that problem.

Returns:

  • (NSData) —

    Contents of the file-system node the file wrapper represents.

- (Object) removeFileWrapper(child)

Removes a child file wrapper from the receiver, which must be a directory file wrapper.

Parameters:

Returns:

- (NSData) serializedRepresentation

Returns the contents of the file wrapper as an opaque collection of data. Returns an NSData object suitable for passing to initWithSerializedRepresentation:. This method may return nil if the user modifies the contents of the file-system node after you call readFromURL:options:error: or initWithURL:options:error: but before NSFileWrapper has read the contents of the file. Use the NSFileWrapperReadingImmediate reading option to reduce the likelihood of that problem.

Returns:

  • (NSData) —

    The file wrapper’s contents in the format used for the pasteboard type NSFileContentsPboardType.

- (Object) setFileAttributes(fileAttributes)

Specifies a file wrapper’s file attributes.

Parameters:

  • fileAttributes (Hash) —

    File attributes for the file wrapper, in a dictionary of the same sort as that used by setAttributes:ofItemAtPath:error: (NSFileManager).

Returns:

- (Object) setFilename(filename)

Specifies the filename of a file wrapper. The file name is a dictionary key used to store fileWrapper in a directory’s list of child file wrappers. The dictionary key is a unique filename, which is the same as the child file wrapper’s preferred filename unless that name is already in use as a key in the directory’s dictionary of children. See “Working With Directory Wrappers” in Application File Management for more information about the file-wrapper list structure. In general, the filename is set for you by the initWithURL:options:error:, initDirectoryWithFileWrappers:, or writeToURL:options:originalContentsURL:error: methods; you do not normally have to call this method directly.

Parameters:

  • filename (String) —

    Filename of the file wrapper.

Returns:

- (Object) setPreferredFilename(filename)

Specifies the receiver’s preferred filename. When a file wrapper is added to a parent directory file wrapper, the parent attempts to use the child’s preferred filename as the key in its dictionary of children. If that key is already in use, then the parent derives a unique filename from the preferred filename and uses that for the key. When you change the preferred filename of a file wrapper, the default implementation of this method causes existing parent directory file wrappers to remove and re-add the child to accommodate the change. Preferred filenames of children are not preserved when you write a file wrapper to disk and then later instantiate another file wrapper by reading the file from disk. If you need to preserve the user-visible names of attachments, you have to store the names yourself.

Parameters:

  • filename (String) —

    Preferred filename for the receiver.

Returns:

- (NSURL) symbolicLinkDestinationURL

Provides the URL referenced by the receiver, which must be a symbolic-link file wrapper. This method may return nil if the user modifies the symbolic link after you call readFromURL:options:error: or initWithURL:options:error: but before NSFileWrapper has read the contents of the link. Use the NSFileWrapperReadingImmediate reading option to reduce the likelihood of that problem.

Returns:

  • (NSURL) —

    Pathname the file wrapper references (that is, the destination of the symbolic link the file wrapper represents).

- (Boolean) writeToURL(url, options:options, originalContentsURL:originalContentsURL, error:outError)

Recursively writes the entire contents of a file wrapper to a given file-system URL.

Parameters:

  • url —

    URL of the file-system node to which the file wrapper’s contents are written.

  • options —

    Option flags for writing to the node located at url. See “File Wrapper Writing Options” for possible values.

  • originalContentsURL —

    The location of a previous revision of the contents being written. The default implementation of this method attempts to avoid unnecessary I/O by writing hard links to regular files instead of actually writing out their contents when the contents have not changed. The child file wrappers must return accurate values when sent the filename method for this to work. Use the NSFileWrapperWritingWithNameUpdating writing option to increase the likelihood of that.Specify nil for this parameter if there is no earlier version of the contents or if you want to ensure that all the contents are written to files.

  • updateNames —

    YES to update the receiver’s filenames (its filename and—for directory file wrappers—the filenames of its sub–file wrappers) be changed to the filenames of the corresponding nodes in the file system, after a successful write operation. Use this in Save or Save As operations.NO to specify that the receiver’s filenames not be updated. Use this in Save To operations.

  • outError —

    If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Returns:

  • (Boolean) —

    YES when the write operation is successful. If not successful, returns NO after setting outError to an NSError object that describes the reason why the file wrapper’s contents could not be written.