| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/AppKit.framework |
| Availability | Available in Mac OS X v10.0 and later. |
| Companion guide | |
| Declared in | NSFileWrapper.h |
| Related sample code |
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. It can also store an icon for representing the node in a document or in a dragging operation.
There are three types of file wrappers:
Regular-file file wrapper: Represents a regular file.
Directory file wrapper: Represents a directory.
Symbolic-link file wrapper: Represents a symbolic link.
A file wrapper has these attributes:
Filename. Name of the file-system node the file wrapper represents.
Icon: Image that represents the file wrapper to the user.
file-system attributes. See NSFileManager Class Reference for information on the contents of the attributes dictionary.
Regular-file contents. Applicable only to regular-file file wrappers.
File wrappers. Applicable only to directory file wrappers.
Destination node. Applicable only to symbolic-link file wrappers.
This class has several designated initializers.
– initWithURL:options:error:
– initDirectoryWithFileWrappers:
– initRegularFileWithContents:
– initSymbolicLinkWithDestinationURL:
– initWithSerializedRepresentation:
– initSymbolicLinkWithDestination: Deprecated in Mac OS X v10.6
– initWithPath: Deprecated in Mac OS X v10.6
– fileWrappers
– addFileWrapper:
– removeFileWrapper:
– addRegularFileWithContents:preferredFilename:
– keyForFileWrapper:
– symbolicLinkDestinationURL
– addFileWithPath: Deprecated in Mac OS X v10.6
– addSymbolicLinkWithDestination:preferredFilename: Deprecated in Mac OS X v10.6
– symbolicLinkDestination Deprecated in Mac OS X v10.6
– matchesContentsOfURL:
– readFromURL:options:error:
– needsToBeUpdatedFromPath: Deprecated in Mac OS X v10.6
– updateFromPath: Deprecated in Mac OS X v10.6
– filename
– setFilename:
– preferredFilename
– setPreferredFilename:
– icon
– setIcon:
– fileAttributes
– setFileAttributes:
– regularFileContents
– writeToURL:options:originalContentsURL:error:
– writeToFile:atomically:updateFilenames: Deprecated in Mac OS X v10.6
Adds a child file wrapper to the receiver, which must be a directory file wrapper.
- (NSString *)addFileWrapper:(NSFileWrapper *)child
File wrapper to add to the directory.
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.
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.
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.
– addRegularFileWithContents:preferredFilename:– removeFileWrapper:– fileWrappers– preferredFilenameNSFileWrapper.hCreates 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
Contents for the new regular-file file wrapper.
Preferred filename for the new regular-file file wrapper.
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.
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.
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.
NSFileWrapper.hReturns a file wrapper’s file attributes.
- (NSDictionary *)fileAttributes
File attributes, in a dictionary of the same sort as that returned by attributesOfItemAtPath:error: (NSFileManager).
NSFileWrapper.hProvides the filename of a file wrapper.
- (NSString *)filename
The file wrapper’s filename; nil when the file wrapper has no corresponding file-system node.
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.
NSFileWrapper.hReturns the file wrappers contained by a directory file wrapper.
- (NSDictionary *)fileWrappers
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.
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.
This method raises NSInternalInconsistencyException if the receiver is not a directory file wrapper.
NSFileWrapper.hReturns an icon that represents the file wrapper to the user.
- (NSImage *)icon
Icon that represents the file wrapper; nil when the file wrapper has no icon.
You don’t have to use this icon; for example, a file viewer typically looks up icons automatically based on file extensions, and so wouldn’t need this one. Similarly, if a file wrapper represents an image file, you can display the image directly rather than a file icon.
This method may return nil if the file wrapper is a child created when its parent was read from the file system, and the child was modified before it was read. Use the NSFileWrapperReadingImmediate reading option to reduce the likelihood of that problem.
Because the NSImage object that's returned might be shared by many NSFileWrapper objects, you must not mutate it. If you need to mutate the returned object, make a copy first and mutate the copy instead.
NSFileWrapper.hInitializes the receiver as a directory file wrapper, with a given file-wrapper list.
- (id)initDirectoryWithFileWrappers:(NSDictionary *)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 Application File Management for more information about the file-wrapper list structure.
Initialized file wrapper for fileWrappers.
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.
NSFileWrapper.hInitializes the receiver as a regular-file file wrapper.
- (id)initRegularFileWithContents:(NSData *)contents
Contents of the file.
Initialized regular-file file wrapper containing contents.
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. .
NSFileWrapper.hInitializes the receiver as a symbolic-link file wrapper that links to a specified file.
- (id)initSymbolicLinkWithDestinationURL:(NSURL *)url
URL of the file the file wrapper is to reference.
Initialized symbolic-link file wrapper referencing url.
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. .
NSFileWrapper.hInitializes the receiver as a regular-file file wrapper from given serialized data.
- (id)initWithSerializedRepresentation:(NSData *)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).
Regular-file file wrapper initialized from serializedRepresentation.
The file wrapper is not associated with a file-system node until you save it using writeToURL:options:originalContentsURL:error:.
NSFileWrapper.hInitializes 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
URL of the file-system node the file wrapper is to represent.
Option flags for reading the node located at url. See “File Wrapper Reading Options” for possible values.
If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.
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.
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.
NSFileWrapper.hIndicates whether the receiver is a directory file wrapper.
- (BOOL)isDirectory
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.
NSFileWrapper.hIndicates whether the receiver is a regular-file file wrapper.
- (BOOL)isRegularFile
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.
NSFileWrapper.hIndicates whether the receiver is a symbolic-link file wrapper.
- (BOOL)isSymbolicLink
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.
NSFileWrapper.hReturns the dictionary key used by a directory to identify a given file wrapper.
- (NSString *)keyForFileWrapper:(NSFileWrapper *)child
The child file wrapper for which you want the key.
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.
This method raises NSInternalInconsistencyException if the receiver is not a directory file wrapper.
NSFileWrapper.hIndicates whether the contents of a file wrapper matches a directory, regular file, or symbolic link on disk.
- (BOOL)matchesContentsOfURL:(NSURL *)url
URL of the file-system node with which to compare the file wrapper.
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. |
NSFileWrapper.hProvides the preferred filename for a file wrapper.
- (NSString *)preferredFilename
The file wrapper’s preferred filename.
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.
NSFileWrapper.hRecursively rereads the entire contents of a file wrapper from the specified location on disk.
- (BOOL)readFromURL:(NSURL *)url options:(NSFileWrapperReadingOptions)options error:(NSError **)outError
URL of the file-system node corresponding to the file wrapper.
Option flags for reading the node located at url. See “File Wrapper Reading Options” for possible values.
If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.
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.
When reading a directory, children are added and removed as necessary to match the file system.
– initWithURL:options:error:– fileWrappers– filename– fileAttributes– writeToURL:options:originalContentsURL:error:NSFileWrapper.hReturns the contents of the file-system node associated with a regular-file file wrapper.
- (NSData *)regularFileContents
Contents of the file-system node the file wrapper represents.
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.
This method raises NSInternalInconsistencyException if the receiver is not a regular-file file wrapper.
NSFileWrapper.hRemoves a child file wrapper from the receiver, which must be a directory file wrapper.
- (void)removeFileWrapper:(NSFileWrapper *)child
File wrapper to remove from the directory.
This method raises NSInternalInconsistencyException if the receiver is not a directory file wrapper.
NSFileWrapper.hReturns the contents of the file wrapper as an opaque collection of data.
- (NSData *)serializedRepresentation
The file wrapper’s contents in the format used for the pasteboard type NSFileContentsPboardType.
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.
NSFileWrapper.hSpecifies a file wrapper’s file attributes.
- (void)setFileAttributes:(NSDictionary *)fileAttributes
File attributes for the file wrapper, in a dictionary of the same sort as that used by setAttributes:ofItemAtPath:error: (NSFileManager).
NSFileWrapper.hSpecifies the filename of a file wrapper.
- (void)setFilename:(NSString *)filename
Filename of the 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.
This method raises NSInvalidArgumentException if you pass nil or an empty value for filename.
– filename– setPreferredFilename:– initWithURL:options:error:– initDirectoryWithFileWrappers: – writeToURL:options:originalContentsURL:error:NSFileWrapper.hSpecifies an image that can be used to represent the file wrapper to the user.
- (void)setIcon:(NSImage *)icon
Image that can be used to represent the file wrapper to the user.
An application does not have to use this icon; for example, a file viewer typically looks up icons automatically based on file extensions, and so wouldn’t need this one. Similarly, if a file wrapper represents an image file, an application can display the image directly rather than a file icon.
NSFileWrapper.hSpecifies the receiver’s preferred filename.
- (void)setPreferredFilename:(NSString *)filename
Preferred filename for the receiver.
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.
This method raises NSInvalidArgumentException if you pass nil or an empty value for filename.
– preferredFilename– setFilename:– addFileWrapper:– initWithURL:options:error:– initDirectoryWithFileWrappers: – writeToURL:options:originalContentsURL:error:NSFileWrapper.hProvides the URL referenced by the receiver, which must be a symbolic-link file wrapper.
- (NSURL *)symbolicLinkDestinationURL
Pathname the file wrapper references (that is, the destination of the symbolic link the file wrapper represents).
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.
This method raises NSInternalInconsistencyException if the receiver is not a symbolic-link file wrapper.
NSFileWrapper.hRecursively writes the entire contents of a file wrapper to a given file-system URL.
- (BOOL)writeToFile:(NSURL *)url options:(NSFileWrapperWritingOptions)options originalContentsURL:(NSURL *)originalContentsURL error:(NSError **)outError
URL of the file-system node to which the file wrapper’s contents are written.
Option flags for writing to the node located at url. See “File Wrapper Writing Options” for possible values.
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.
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.
If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.
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.
NSFileWrapper.hReading 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;
NSFileWrapperReadingImmediateWhether the contents and icons are read immediately; applied recursively in the case of directory file wrappers.
If reading with this option succeeds, then subsequent invocations of fileWrappers, regularFileContents, symbolicLinkDestinationURL, icon, 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 Mac OS X v10.6 and later.
Declared in NSFileWrapper.h.
NSFileWrapperReadingWithoutMappingWhether 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 Mac 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 Mac OS X v10.6 and later.
Declared in NSFileWrapper.h.
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.
Writing options that can be set by the writeToURL:options:originalContentsURL:error: method.
enum {
NSFileWrapperWritingAtomic = 1 << 0,
NSFileWrapperWritingWithNameUpdating = 1 << 1
};
typedef NSUInteger NSFileWrapperWritingOptions;
NSFileWrapperWritingAtomicWhether 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 Mac OS X v10.6 and later.
Declared in NSFileWrapper.h.
NSFileWrapperWritingWithNameUpdatingWhether 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 Mac OS X v10.6 and later.
Declared in NSFileWrapper.h.
Last updated: 2009-05-26
Mac OS X Reference Library Data Management: File Management NSFileWrapper Class Reference