NSFileWrapper Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Declared in
NSFileWrapper.h
Related sample code

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.

File wrappers represent a file-system node as an object that can be displayed as an image (and possibly edited in place), saved to the file system, or transmitted to another application.

There are three types of file wrappers:

A file wrapper has these attributes:

Adopted Protocols

NSCoding

Tasks

Creating File Wrappers

This class has several designated initializers.

Querying File Wrappers

Accessing File-Wrapper Information

Updating File Wrappers

Serializing

Accessing Files

Writing Files

Instance Methods

addFileWrapper:

Adds a child file wrapper to the receiver, which must be a directory file wrapper.

- (NSString *)addFileWrapper:(NSFileWrapper *)child
Parameters
child

File wrapper to add to the directory.

Return Value

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 File System Programming Guide for more information about the file-wrapper list structure.

Discussion

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.

Special Considerations

This method raises NSInternalInconsistencyException if the receiver is not a directory file wrapper.

This method raises NSInvalidArgumentException if the child file wrapper doesn’t have a preferred name.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSFileWrapper.h

addRegularFileWithContents:preferredFilename:

Creates a regular-file file wrapper with the given contents and adds it to the receiver, which must be a directory file wrapper.

- (NSString *)addRegularFileWithContents:(NSData *)data preferredFilename:(NSString *)filename
Parameters
data

Contents for the new regular-file file wrapper.

filename

Preferred filename for the new regular-file file wrapper.

Return Value

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 File System Programming Guide for more information about the file-wrapper list structure.

Discussion

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.

Special Considerations

This method raises NSInternalInconsistencyException if the receiver is not a directory file wrapper.

This method raises NSInvalidArgumentException if you pass nil or an empty value for filename.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSFileWrapper.h

fileAttributes

Returns a file wrapper’s file attributes.

- (NSDictionary *)fileAttributes
Return Value

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSFileWrapper.h

filename

Provides the filename of a file wrapper.

- (NSString *)filename
Return Value

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

Discussion

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.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSFileWrapper.h

fileWrappers

Returns the file wrappers contained by a directory file wrapper.

- (NSDictionary *)fileWrappers
Return Value

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 File System Programming Guide for more information about the file-wrapper list structure.

Discussion

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.

Special Considerations

This method raises NSInternalInconsistencyException if the receiver is not a directory file wrapper.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSFileWrapper.h

initDirectoryWithFileWrappers:

Initializes the receiver as a directory file wrapper, with a given file-wrapper list.

- (id)initDirectoryWithFileWrappers:(NSDictionary *)childrenByPreferredName
Parameters
childrenByPreferredName

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 File System Programming Guide for more information about the file-wrapper list structure.

Return Value

Initialized file wrapper for fileWrappers.

Discussion

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.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSFileWrapper.h

initRegularFileWithContents:

Initializes the receiver as a regular-file file wrapper.

- (id)initRegularFileWithContents:(NSData *)contents
Parameters
contents

Contents of the file.

Return Value

Initialized regular-file file wrapper containing contents.

Discussion

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSFileWrapper.h

initSymbolicLinkWithDestinationURL:

Initializes the receiver as a symbolic-link file wrapper that links to a specified file.

- (id)initSymbolicLinkWithDestinationURL:(NSURL *)url
Parameters
url

URL of the file the file wrapper is to reference.

Return Value

Initialized symbolic-link file wrapper referencing url.

Discussion

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

Availability
  • Available in OS X v10.6 and later.
Declared In
NSFileWrapper.h

initWithSerializedRepresentation:

Initializes the receiver as a regular-file file wrapper from given serialized data.

- (id)initWithSerializedRepresentation:(NSData *)serializedRepresentation
Parameters
serializedRepresentation

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

Return Value

Regular-file file wrapper initialized from serializedRepresentation.

Discussion

The file wrapper is not associated with a file-system node until you save it using writeToURL:options:originalContentsURL:error:.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSFileWrapper.h

initWithURL:options:error:

Initializes a file wrapper instance whose kind is determined by the type of file-system node located by the URL.

- (id)initWithURL:(NSURL *)url options:(NSFileWrapperReadingOptions)options error:(NSError **)outError
Parameters
url

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

options

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

outError

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

Return Value

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.

Discussion

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.

Availability
  • Available in OS X v10.6 and later.
Related Sample Code
Declared In
NSFileWrapper.h

isDirectory

Indicates whether the receiver is a directory file wrapper.

- (BOOL)isDirectory
Return Value

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

Discussion

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSFileWrapper.h

isRegularFile

Indicates whether the receiver is a regular-file file wrapper.

- (BOOL)isRegularFile
Return Value

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

Discussion

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSFileWrapper.h

isSymbolicLink

Indicates whether the receiver is a symbolic-link file wrapper.

- (BOOL)isSymbolicLink
Return Value

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

Discussion

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSFileWrapper.h

keyForFileWrapper:

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

- (NSString *)keyForFileWrapper:(NSFileWrapper *)child
Parameters
child

The child file wrapper for which you want the key.

Return Value

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 File System Programming Guide 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.

Special Considerations

This method raises NSInternalInconsistencyException if the receiver is not a directory file wrapper.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSFileWrapper.h

matchesContentsOfURL:

Indicates whether the contents of a file wrapper matches a directory, regular file, or symbolic link on disk.

- (BOOL)matchesContentsOfURL:(NSURL *)url
Parameters
url

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

Return Value

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

Discussion

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 type

Comparison determinants

Regular file

Modification date and access permissions.

Directory

Children (recursive).

Symbolic link

Destination pathname.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSFileWrapper.h

preferredFilename

Provides the preferred filename for a file wrapper.

- (NSString *)preferredFilename
Return Value

The file wrapper’s preferred filename.

Discussion

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSFileWrapper.h

readFromURL:options:error:

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

- (BOOL)readFromURL:(NSURL *)url options:(NSFileWrapperReadingOptions)options error:(NSError **)outError
Parameters
url

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

options

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

outError

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

Return Value

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.

Discussion

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

Availability
  • Available in OS X v10.6 and later.
Declared In
NSFileWrapper.h

regularFileContents

Returns the contents of the file-system node associated with a regular-file file wrapper.

- (NSData *)regularFileContents
Return Value

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

Discussion

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.

Special Considerations

This method raises NSInternalInconsistencyException if the receiver is not a regular-file file wrapper.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSFileWrapper.h

removeFileWrapper:

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

- (void)removeFileWrapper:(NSFileWrapper *)child
Parameters
child

File wrapper to remove from the directory.

Special Considerations

This method raises NSInternalInconsistencyException if the receiver is not a directory file wrapper.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSFileWrapper.h

serializedRepresentation

Returns the contents of the file wrapper as an opaque collection of data.

- (NSData *)serializedRepresentation
Return Value

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

Discussion

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSFileWrapper.h

setFileAttributes:

Specifies a file wrapper’s file attributes.

- (void)setFileAttributes:(NSDictionary *)fileAttributes
Parameters
fileAttributes

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSFileWrapper.h

setFilename:

Specifies the filename of a file wrapper.

- (void)setFilename:(NSString *)filename
Parameters
filename

Filename of the file wrapper.

Discussion

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 File System Programming Guide 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.

Special Considerations

This method raises NSInvalidArgumentException if you pass nil or an empty value for filename.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSFileWrapper.h

setPreferredFilename:

Specifies the receiver’s preferred filename.

- (void)setPreferredFilename:(NSString *)filename
Parameters
filename

Preferred filename for the receiver.

Discussion

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.

Special Considerations

This method raises NSInvalidArgumentException if you pass nil or an empty value for filename.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSFileWrapper.h

symbolicLinkDestinationURL

Provides the URL referenced by the receiver, which must be a symbolic-link file wrapper.

- (NSURL *)symbolicLinkDestinationURL
Return Value

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

Discussion

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.

Special Considerations

This method raises NSInternalInconsistencyException if the receiver is not a symbolic-link file wrapper.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSFileWrapper.h

writeToURL:options:originalContentsURL:error:

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

- (BOOL)writeToURL:(NSURL *)url options:(NSFileWrapperWritingOptions)options originalContentsURL:(NSURL *)originalContentsURL error:(NSError **)outError
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.

Return Value

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSFileWrapper.h

Constants

File Wrapper Reading Options

Reading options that can be set by the initWithURL:options:error: and readFromURL:options:error: methods.

enum {
   NSFileWrapperReadingImmediate = 1 << 0,
   NSFileWrapperReadingWithoutMapping = 1 << 1,
};
typedef NSUInteger NSFileWrapperReadingOptions;
Constants
NSFileWrapperReadingImmediate

If reading with this option succeeds, then subsequent invocations of fileWrappers, regularFileContents, symbolicLinkDestinationURL, and serializedRepresentation sent to the file wrapper and all its child file wrappers will fail and return nil only if an actual error occurs (for example, the volume has disappeared or the file server is unreachable)—not as a result of the user moving or deleting files.

For performance reasons, NSFileWrapper may not read the contents of some file packages immediately even when this option is chosen. For example, because the contents of bundles (not all file packages are bundles) are immutable to the user, NSFileWrapper may read the children of such a directory lazily.

You can use this option to take a snapshot of a file or folder for writing later. For example, an application like TextEdit can use this option when creating new file wrappers to represent attachments that the user creates by copying and pasting or dragging and dropping from the Finder to a TextEdit document. Don't use this option when reading a document file package, because that would cause unnecessarily bad performance. For example, an application wouldn't use this option when creating file wrappers to represent attachments as it's opening a document stored in a file package.

Available in OS X v10.6 and later.

Declared in NSFileWrapper.h.

NSFileWrapperReadingWithoutMapping

Whether file mapping for regular file wrappers is disallowed.

You can use this option to keep NSFileWrapper from memory-mapping files. This is useful if you want to make sure your application doesn't hold files open (mapped files are open files), therefore preventing the user from ejecting DVDs, unmounting disk partitions, or unmounting disk images. In OS X v10.6 and later, NSFileWrapper memory-maps files that are on internal drives only. It never memory-maps files on external drives or network volumes, regardless of whether this option is used.

Available in OS X v10.6 and later.

Declared in NSFileWrapper.h.

Discussion

You can use the NSFileWrapperReadingImmediate and NSFileWrapperReadingWithoutMapping reading options together to take an exact snapshot of a file-system hierarchy that is safe from all errors (including the ones mentioned above) once reading has succeeded. If reading with both options succeeds, then subsequent invocations of the methods listed in the comment for the NSFileWrapperReadingImmediate reading option to the receiver and all its descendant file wrappers will never fail. However, note that reading with both options together is expensive in terms of both I/O and memory for large files, or directories containing large files, or even directories containing many small files.

File Wrapper Writing Options

Writing options that can be set by the writeToURL:options:originalContentsURL:error: method.

enum {
   NSFileWrapperWritingAtomic = 1 << 0,
   NSFileWrapperWritingWithNameUpdating = 1 << 1,
};
typedef NSUInteger NSFileWrapperWritingOptions;
Constants
NSFileWrapperWritingAtomic

Whether writing is done atomically.

You can use this option to ensure that, when overwriting a file package, the overwriting either completely succeeds or completely fails, with no possibility of leaving the file package in an inconsistent state. Because this option causes additional I/O, you shouldn't use it unnecessarily. For example, don't use this option in an override of -[NSDocument writeToURL:ofType:error:], because NSDocument safe-saving is already done atomically.

Available in OS X v10.6 and later.

Declared in NSFileWrapper.h.

NSFileWrapperWritingWithNameUpdating

Whether descendant file wrappers are sent the setFilename: method if the writing succeeds.

This option is necessary when your application passes a URL in the originalContentsURL parameter to the writeToURL:options:originalContentsURL:error: method. Without using this option (and reusing child file wrappers properly), subsequent invocations of writeToURL:options:originalContentsURL:error: would not be able to reliably create hard links in a new file package, because the record of names in the old file package would be out of date.

Available in OS X v10.6 and later.

Declared in NSFileWrapper.h.