Mac Developer Library

Developer

Foundation Framework Reference NSFileWrapper Class Reference

Options
Deployment Target:

On This Page
Language:

NSFileWrapper

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in OS X v10.0 and later.

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:

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

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

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

    Declaration

    Swift

    init?(URL url: NSURL, options options: NSFileWrapperReadingOptions, error outError: NSErrorPointer)

    Objective-C

    - (instancetype)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 NOfalse (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 property to get the file wrappers of the nodes contained by the directory.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

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

    Deprecation Statement

    Use initWithURL:options:error: instead.

    Declaration

    Swift

    convenience init?(path node: String)

    Objective-C

    - (id)initWithPath:(NSString *)node

    Parameters

    node

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

    Return Value

    File wrapper for node.

    Discussion

    If node is a directory, this method recursively creates file wrappers for each node within that directory.

    Special Considerations

    Beginning with OS X v10.6, the preferred method of referring to files is with a file:// URL. Therefore, this method has been deprecated in favor of initWithURL:options:error:.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

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

    Declaration

    Swift

    init(directoryWithFileWrappers childrenByPreferredName: [NSObject : AnyObject])

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Initializes the receiver as a regular-file file wrapper.

    Declaration

    Swift

    init(regularFileWithContents contents: NSData)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Initializes the receiver as a symbolic-link file wrapper.

    Deprecation Statement

    Use initSymbolicLinkWithDestinationURL: instead.

    Declaration

    Swift

    convenience init(symbolicLinkWithDestination node: String)

    Objective-C

    - (id)initSymbolicLinkWithDestination:(NSString *)node

    Parameters

    node

    Pathname the receiver is to represent.

    Return Value

    Initialized symbolic-link file wrapper referencing node.

    Discussion

    The receiver is not associated to a file-system node until you save it using writeToFile:atomically:updateFilenames:. It’s also initialized with open permissions; anyone can read or write the disk representations it saves.

    Special Considerations

    Beginning with OS X v10.6, the preferred method of referring to files is with a file:// URL. Therefore, this method has been deprecated in favor of initSymbolicLinkWithDestinationURL:.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

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

    Declaration

    Swift

    init(symbolicLinkWithDestinationURL url: NSURL)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Swift

    init?(serializedRepresentation serializedRepresentation: NSData)

    Objective-C

    - (instancetype)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:.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • This property contains a boolean value that indicates whether the file wrapper object is a regular-file. (read-only)

    Declaration

    Swift

    var regularFile: Bool { get }

    Objective-C

    @property(readonly, getter=isRegularFile) BOOL regularFile

    Discussion

    This property contains YEStrue when the file wrapper object is a regular-file wrapper, otherwise it contains NOfalse. Invocations of readFromURL:options:error: may change the value of this property if the type of the file on disk has changed.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.10 and later.

  • directory directory Property

    This property contains a boolean value indicating whether the file wrapper is a directory file wrapper. (read-only)

    Declaration

    Swift

    var directory: Bool { get }

    Objective-C

    @property(readonly, getter=isDirectory) BOOL directory

    Discussion

    This property will contain YES when the file wrapper is a directory file wrapper, otherwise it contains NO.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.10 and later.

  • A boolean that indicates whether the file wrapper object is a symbolic-link file wrapper. (read-only)

    Declaration

    Swift

    var symbolicLink: Bool { get }

    Objective-C

    @property(readonly, getter=isSymbolicLink) BOOL symbolicLink

    Discussion

    This property contains YEStrue when the file wrapper object is a symbolic-link file wrapper, NOfalse otherwise.

    Invocations of readFromURL:options:error: may change the value contained by this property, if the type of the file on disk has changed.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.10 and later.

  • The file wrappers contained by a directory file wrapper. (read-only)

    Declaration

    Swift

    var fileWrappers: [NSObject : AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSDictionary *fileWrappers

    Discussion

    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.

    This property may contain 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 property raises NSInternalInconsistencyException if the file wrapper object is not a directory file wrapper.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func addFileWrapper(_ child: NSFileWrapper) -> String

    Objective-C

    - (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, set the preferredFilename property 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func removeFileWrapper(_ child: NSFileWrapper)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Creates a file wrapper from a given file-system node and adds it to the receiver, which must be a directory file wrapper.

    Deprecation Statement

    Use addFileWrapper: instead.

    Declaration

    Swift

    func addFileWithPath(_ node: String) -> String

    Objective-C

    - (NSString *)addFileWithPath:(NSString *)node

    Parameters

    node

    file-system node from which to create the file wrapper to add to the directory.

    Return Value

    Dictionary key used to store the new file wrapper in the directory’s list of file wrappers. See Working with Directory Wrappers in File System Programming Guide for more information.

    Special Considerations

    Beginning with OS X v10.6, the preferred method of referring to files is with a file:// URL. Instead of using this method, you can instantiate NSFileWrapper with one of the initializers, set its preferredFilename property if necessary, and pass the result to addFileWrapper:.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

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

    Declaration

    Swift

    func addRegularFileWithContents(_ data: NSData, preferredFilename filename: String) -> String

    Objective-C

    - (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:, set its preferredFilename property, 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Creates a symbolic-link file wrapper pointing to a given file-system node and adds it to the receiver, which must be a directory file wrapper.

    Deprecation Statement

    Use addFileWrapper: instead.

    Declaration

    Swift

    func addSymbolicLinkWithDestination(_ node: String, preferredFilename preferredFilename: String) -> String

    Objective-C

    - (NSString *)addSymbolicLinkWithDestination:(NSString *)node preferredFilename:(NSString *)preferredFilename

    Parameters

    node

    Pathname the new symbolic-link file wrapper is to reference.

    preferredFilename

    Preferred filename for the new symbolic-link file wrapper.

    Return Value

    Dictionary key used to store the new file wrapper in the directory’s list of file wrappers. See Working with Directory Wrappers in File System Programming Guide for more information.

    Special Considerations

    Beginning with OS X v10.6, the preferred method of referring to files is with a file:// URL. Instead of using this method, you can instantiate NSFileWrapper with one of the initializers, set its preferredFilename property if necessary, and pass the result to addFileWrapper:.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

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

    Declaration

    Swift

    func keyForFileWrapper(_ child: NSFileWrapper) -> String?

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    filename

  • Provides the pathname referenced by the file wrapper object, which must be a symbolic-link file wrapper.

    Deprecation Statement

    Use symbolicLinkDestinationURL instead.

    Declaration

    Swift

    func symbolicLinkDestination() -> String

    Objective-C

    - (NSString *)symbolicLinkDestination

    Return Value

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

    Special Considerations

    Beginning with OS X v10.6, the preferred method of referring to files is with a file:// URL. Therefore, this method has been deprecated in favor of symbolicLinkDestinationURL.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • The URL referenced by the file wrapper object, which must be a symbolic-link file wrapper. (read-only)

    Declaration

    Swift

    @NSCopying var symbolicLinkDestinationURL: NSURL { get }

    Objective-C

    @property(readonly, copy) NSURL *symbolicLinkDestinationURL

    Discussion

    This property may contain 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 property raises NSInternalInconsistencyException if the file wrapper object is not a symbolic-link file wrapper.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • Indicates whether the file wrapper needs to be updated to match a given file-system node.

    Deprecation Statement

    Use matchesContentsOfURL: instead.

    Declaration

    Swift

    func needsToBeUpdatedFromPath(_ node: String) -> Bool

    Objective-C

    - (BOOL)needsToBeUpdatedFromPath:(NSString *)node

    Parameters

    node

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

    Return Value

    NOfalse when the file wrapper needs to be updated to match node, NOfalse otherwise.

    Discussion

    This table describes which attributes of the file wrapper and node are compared to determine whether the file wrapper needs to be updated:

    File-wrapper type

    Comparison determinants

    Regular file

    Modification date and access permissions.

    Directory

    Member hierarchy (recursive).

    Symbolic link

    Destination pathname.

    Special Considerations

    Beginning with OS X v10.6, the preferred method of referring to files is with a file:// URL. Therefore, this method has been deprecated in favor of matchesContentsOfURL:.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

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

    Declaration

    Swift

    func matchesContentsOfURL(_ url: NSURL) -> Bool

    Objective-C

    - (BOOL)matchesContentsOfURL:(NSURL *)url

    Parameters

    url

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

    Return Value

    YEStrue when the contents of the file wrapper match the contents of url, NOfalse 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • Updates the file wrapper to match a given file-system node.

    Deprecation Statement

    Use readFromURL:options:error: instead.

    Declaration

    Swift

    func updateFromPath(_ path: String) -> Bool

    Objective-C

    - (BOOL)updateFromPath:(NSString *)path

    Return Value

    YEStrue if the update is carried out, NOfalse if it isn’t needed.

    Discussion

    For a directory file wrapper, the contained file wrappers are also sent updateFromPath: messages. If nodes in the corresponding directory on the file system have been added or removed, corresponding file wrappers are released or created as needed.

    Special Considerations

    Beginning with OS X v10.6, the preferred method of referring to files is with a file:// URL. Therefore, this method has been deprecated in favor of readFromURL:options:error:.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

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

    Declaration

    Swift

    func readFromURL(_ url: NSURL, options options: NSFileWrapperReadingOptions, error outError: NSErrorPointer) -> Bool

    Objective-C

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

    YEStrue if successful. If not successful, returns NOfalse 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • filename filename Property

    The filename of the file wrapper object

    Declaration

    Swift

    var filename: String?

    Objective-C

    @property(copy) NSString *filename

    Discussion

    This property contains the file wrapper’s filename, or 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • The preferred filename for the file wrapper object.

    Declaration

    Swift

    var preferredFilename: String

    Objective-C

    @property(copy) NSString *preferredFilename

    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 this object is added, the filename assigned as the dictionary key may differ from the preferred filename.

    When you change the preferred filename, the default implementation of this property causes the 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • A dictionary of file attributes.

    Declaration

    Swift

    var fileAttributes: [NSObject : AnyObject]

    Objective-C

    @property(copy) NSDictionary *fileAttributes

    Discussion

    The file attributes’ dictionary is the same format as that returned by attributesOfItemAtPath:error: (NSFileManager).

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • The contents of the file-system node associated with a regular-file file wrapper. (read-only)

    Declaration

    Swift

    @NSCopying var regularFileContents: NSData? { get }

    Objective-C

    @property(readonly, copy) NSData *regularFileContents

    Discussion

    This property may contain 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 property raises NSInternalInconsistencyException if the file wrapper object is not a regular-file file wrapper.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Writes a file wrapper’s contents to a given file-system node.

    Deprecation Statement

    Use writeToURL:options:originalContentsURL:error: instead.

    Declaration

    Swift

    func writeToFile(_ node: String, atomically atomically: Bool, updateFilenames updateNames: Bool) -> Bool

    Objective-C

    - (BOOL)writeToFile:(NSString *)node atomically:(BOOL)atomically updateFilenames:(BOOL)updateNames

    Parameters

    node

    Pathname of the file-system node to which the receiver’s contents are written.

    atomically

    YEStrue to write the file safely so that:

    • An existing file is not overwritten

    • The method fails if the file cannot be written in its entirety

    NOfalse to overwrite an existing file and ignore incomplete writes.

    updateNames

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

    NOfalse to specify that the receiver’s filenames not be updated. Use this in Save To operations.

    Return Value

    YEStrue when the write operation is successful, NOfalse otherwise.

    Special Considerations

    Beginning with OS X v10.6, the preferred method of referring to files is with a file:// URL. Therefore, this method has been deprecated in favor of writeToURL:options:originalContentsURL:error:.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

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

    Declaration

    Swift

    func writeToURL(_ url: NSURL, options options: NSFileWrapperWritingOptions, originalContentsURL originalContentsURL: NSURL?, error outError: NSErrorPointer) -> Bool

    Objective-C

    - (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 its filename property is accessed 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.

    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

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Swift

    struct NSFileWrapperReadingOptions : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var Immediate: NSFileWrapperReadingOptions { get } static var WithoutMapping: NSFileWrapperReadingOptions { get } }

    Objective-C

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

    Constants

    • Immediate

      NSFileWrapperReadingImmediate

      If reading with this option succeeds, then subsequent uses 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.

    • WithoutMapping

      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.

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Swift

    struct NSFileWrapperWritingOptions : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var Atomic: NSFileWrapperWritingOptions { get } static var WithNameUpdating: NSFileWrapperWritingOptions { get } }

    Objective-C

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

    Constants

    • Atomic

      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.

    • WithNameUpdating

      NSFileWrapperWritingWithNameUpdating

      Whether descendant file wrappers’filename properties are set 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.