- Inherits from:
- NSObject
- Conforms to:
- NSCoding
- NSObject (NSObject)
Declared in:
- AppKit/NSFileWrapper.h
An NSFileWrapper holds a file's contents in dynamic memory. In this role it enables a document object to embed a file, treating it as a unit of data that can be displayed as an image (and possibly edited in place), saved to disk, or transmitted to another application. It can also store an icon for representing the file in a document or in a dragging operation.
Instances of this class are referred to as file wrapper objects, and when no confusion will result, merely as file wrappers. A file wrapper can be one of three specific types: a regular file wrapper, which holds the contents of a single actual file; a directory wrapper, which holds a directory and all of the files or directories within it; or a link wrapper, which simply represents a symbolic link in the file system (sometimes called a shortcut or alias). Some NSFileWrapper methods apply only to a specific type, and an exception is raised if sent to a file wrapper of the wrong type. To determine the type of a file wrapper, use the isRegularFile, isDirectory, and isSymbolicLink methods.
You can create a file wrapper from data in memory using initWithSerializedRepresentation: or from data on disk using initWithPath:. Both create the appropriate type of file wrapper based on the nature of the serialized representation or of the file on disk. Three convenience methods each create a file wrapper of a specific type: initRegularFileWithContents:, initDirectoryWithFileWrappers:, and initSymbolicLinkWithDestination:. Because each initialization method creates file wrappers of different types or states, they're all designated initializers for this class-subclasses must meaningfully override them all as necessary.
Because the purpose of a file wrapper is to represent files in memory, it's very loosely coupled to any disk representation. A file wrapper doesn't record the path to the disk representation of its contents. This allows you to save the same file wrapper with different paths, but it also requires you to record those paths if you want to update the file wrapper from disk later. NSFileWrapper allows you to set a preferred filename for save operations and records the last filename it was actually saved to; the preferredFilename and filename methods return these names. This feature is more important for directory wrappers, though, and so is discussed under "Working with Directory Wrappers" below.
A file wrapper stores file system information (such as modification time and access permissions), which it updates when reading from disk and uses when writing files to disk. The fileAttributes method returns this information in the format described in the NSFileManager class specification. You can also set the file attributes using the setFileAttributes: method.
When saving a file wrapper to disk, you typically determine the directory you want to save it in, then append the preferred filename to that directory path and use writeToFile:atomically:updateFilenames:, which saves the file wrapper's contents and updates the file attributes. You can save a file wrapper under a different name if you wish, but this may result in the recorded filename differing from the preferred filename, depending on how you invoke the writeToFile:atomically:updateFilenames: method.
Besides saving its contents to disk, a file wrapper can re-read them from disk when necessary. The needsToBeUpdatedFromPath: method determines whether a disk representation may have changed, based on the file attributes stored the last time the file was read or written. If the file wrapper's modification time or access permissions are different from those of the file on disk, this method returns YES. You can then use updateFromPath: to re-read the file from disk.
Finally, to transmit a file wrapper to another process or
system (for example, over a distributed objects connection or through
the pasteboard), you use the serializedRepresentation method
to get an NSData object containing the file wrapper's contents
in the NSFileContentsPboardType
format.
You can safely transmit this representation over whatever channel
you desire. The recipient of the representation can then reconstitute
the file wrapper using the initWithSerializedRepresentation: method.
A directory wrapper contains other file wrappers (of any type), and allows you to access them by keys derived from their preferred filenames. You can add any type of file wrapper to a directory wrapper with addFileWrapper: or addFileWithPath:, and remove it with removeFileWrapper:. The convenience methods addRegularFileWithContents:preferredFilename: and addSymbolicLinkWithDestination:preferredFilename: allow you to add regular file and link wrappers while also setting their preferred names.
A directory wrapper stores its contents in an NSDictionary, which you can retrieve using the fileWrappers method. The keys of this dictionary are based on the preferred filenames of each file wrapper contained in the directory wrapper. There exist, then, three identifiers for a file wrapper within a directory wrapper:
When working with the contents of a directory wrapper, you can use a dictionary enumerator to retrieve each file wrapper and perform whatever operation you need. Note that with the exceptions of saving and updating, a directory file wrapper defines no recursive operations for its contents. To set the file attributes for all contained file wrappers, or to perform any other such operation, you must define a recursive method that examines the type of each file wrapper and invokes itself anew for any directory wrapper it encounters.
- Initializing a file wrapper
- - initWithPath:
- - initDirectoryWithFileWrappers:
- - initRegularFileWithContents:
- - initSymbolicLinkWithDestination:
- - initWithSerializedRepresentation:
- Writing to a file or serializing
- - writeToFile:atomically:updateFilenames:
- - serializedRepresentation
- Checking a file wrapper's type
- - isRegularFile
- - isDirectory
- - isSymbolicLink
- Setting attributes
- - setFilename:
- - filename
- - setPreferredFilename:
- - preferredFilename
- - setIcon:
- - icon
- - setFileAttributes:
- - fileAttributes
- Updating
- - needsToBeUpdatedFromPath:
- - updateFromPath:
- Modifying a directory wrapper
- - addFileWrapper:
- - removeFileWrapper:
- - addFileWithPath:
- - addRegularFileWithContents:preferredFilename:
- - addSymbolicLinkWithDestination:preferredFilename:
- - fileWrappers
- - keyForFileWrapper:
- Inspecting a regular file wrapper
- - regularFileContents
- Inspecting a link wrapper
- - symbolicLinkDestination
- (NSString *)addFileWithPath:(NSString
*)path
See Also: - addRegularFileWithContents:preferredFilename:, - addSymbolicLinkWithDestination:preferredFilename:, - removeFileWrapper:, - fileWrappers
- (NSString *)addFileWrapper:(NSFileWrapper
*)wrapper
See Also: - addFileWithPath:, - addRegularFileWithContents:preferredFilename:, - addSymbolicLinkWithDestination:preferredFilename:, - removeFileWrapper:, - fileWrappers
- (NSString *)addRegularFileWithContents:(NSData
*)contents
preferredFilename:(NSString *)filename
nil
or empty.See Also: - addFileWithPath:, - addSymbolicLinkWithDestination:preferredFilename:, - removeFileWrapper:, - fileWrappers
- (NSString *)addSymbolicLinkWithDestination:(NSString
*)path
preferredFilename:(NSString *)filename
nil
or empty.See Also: - addFileWithPath:, - addFileWrapper:, - addRegularFileWithContents:preferredFilename:, - removeFileWrapper:, - fileWrappers
- (NSDictionary *)fileAttributes
- (NSString *)filename
nil
if
the receiver has no filename. The filename is
used for record-keeping purposes only, and is set automatically
when the file wrapper is created from disk using initWithPath: and
when it's saved to a disk using writeToFile:atomically:updateFilenames: (although
this method allows you to request that the filename not be updated).See Also: - preferredFilename, - setFilename:
- (NSDictionary *)fileWrappers
See Also: - filename, - addFileWrapper:
- (NSImage *)icon
nil
if
the file wrapper has none. You don't have to
use this image; for example, a file viewer typically looks up icons automatically
based on file extensions, and so wouldn't need this image. Similarly,
if a file wrapper represents an image file, you can display the
image directly rather than a file icon.See Also: - setIcon:
- (id)initDirectoryWithFileWrappers:(NSDictionary
*)wrappers
If any file wrapper in wrappers doesn't have a preferred name, its preferred name is automatically set to its corresponding dictionary key in wrappers.
This method is a designated initializer for the NSFileWrapper class. Returns self.
See Also: - setPreferredFilename:, - filename, - setFileAttributes:
- (id)initRegularFileWithContents:(NSData
*)contents
This method is a designated initializer for the NSFileWrapper class. Returns self.
See Also: - setPreferredFilename:, - filename, - fileAttributes
- (id)initSymbolicLinkWithDestination:(NSString
*)path
This method is a designated initializer for the NSFileWrapper class. Returns self.
See Also: - setPreferredFilename:, - filename, - fileAttributes
- (id)initWithPath:(NSString
*)path
This method is a designated initializer for the NSFileWrapper class. Returns self.
See Also: - setPreferredFilename:, - filename, - fileAttributes
- (id)initWithSerializedRepresentation:(NSData
*)data
NSFileContentsPboardType
.
Data of this format is returned by such methods as serializedRepresentation or NSAttributedString's RTFDFromRange:.The new file wrapper has no filename or associated disk representation until you save it using writeToFile:atomically:updateFilenames:. This method is a designated initializer for the NSFileWrapper class. Returns self.
See Also: - setPreferredFilename:, - filename, - fileAttributes
- (BOOL)isDirectory
See Also: - isRegularFile, - isSymbolicLink
- (BOOL)isRegularFile
See Also: - isDirectory, - isSymbolicLink
- (BOOL)isSymbolicLink
See Also: - isDirectory, - isRegularFile
- (NSString *)keyForFileWrapper:(NSFileWrapper
*)wrapper
See Also: - filename
- (BOOL)needsToBeUpdatedFromPath:(NSString
*)path
See Also: - updateFromPath:, - fileAttributes
- (NSString *)preferredFilename
See Also: - setPreferredFilename:, - filename
- (NSData *)regularFileContents
- (void)removeFileWrapper:(NSFileWrapper
*)wrapper
See Also: - addFileWithPath:, - addFileWrapper:, - addRegularFileWithContents:preferredFilename:, - addSymbolicLinkWithDestination:preferredFilename:, - fileWrappers
- (NSData *)serializedRepresentation
NSFileContentsPboardType
.See Also: - initWithSerializedRepresentation:
- (void)setFileAttributes:(NSDictionary
*)attributes
See Also: - fileAttributes
- (void)setFilename:(NSString
*)filename
Raises an NSInvalidArgumentException
if filename is nil
or empty.
See Also: - setPreferredFilename:, - filename
- (void)setIcon:(NSImage
*)anImage
See Also: - icon
- (void)setPreferredFilename:(NSString
*)filename
nil
or
empty.See Also: - preferredFilename, - addFileWrapper:, - setFilename:
- (NSString *)symbolicLinkDestination
- (BOOL)updateFromPath:(NSString
*)path
See Also: - needsToBeUpdatedFromPath:, - updateAttachmentsFromPath: (NSAttributedString)
- (BOOL)writeToFile:(NSString
*)path
atomically:(BOOL)atomicFlag
updateFilenames:(BOOL)updateNamesFlag
If you're executing a "save" or "save as" style operation, pass YES for updateNamesFlag; if you're executing a "save to" style operation, pass NO for updateNamesFlag.
See Also: - filename