- Inherits from:
- NSObject
- Conforms to:
- NSObject
- (NSObject)
Declared in:
- Foundation/NSFileHandle.h
NSFileHandle objects provide an object-oriented wrapper for accessing open files or communications channels.
The objects you create using this class are called file handle objects. Because of the nature of class clusters, file handle objects are not actual instances of the NSFileHandle class but of one of its private subclasses. Although a file handle object's class is private, its interface is public, as declared by the abstract superclass NSFileHandle.
Generally, you instantiate a file handle object by sending one of the fileHandle... messages to the NSFileHandle class object. These methods return a file handle object pointing to the appropriate file or communications channel. As a convenience, NSFileHandle provides class methods that create objects representing files and devices in the file system and that return objects representing the standard input, standard output, and standard error devices. You can also create file handle objects from file descriptors (such as found on BSD systems) using the initWithFileDescriptor: and initWithFileDescriptor:closeOnDealloc: methods. If you create file handle objects with these methods, you "own" the represented descriptor and are responsible for removing it from system tables, usually by sending the file handle object a closeFile message.
An NSFileHandle is an object that represents an open file or communications channel. It enables programs to read data from or write data to the represented file or channel. You can use other Cocoa methods for reading from and writing to files-NSFileManager's contentsAtPath: and NSData's writeToFile:atomically: are but a couple of examples. Why would you use NSFileHandle then? What are its advantages?
Instances of NSPipe, a class closely related to NSFileHandle, represent pipes: unidirectional interprocess communication channels. See the NSPipe specification for details.
Sockets are full-duplex communication channels between processes either local to the same host machine or where one process is on a remote host. Unlike pipes, in which data goes in one direction only, sockets allow processes both to send and receive data. NSFileHandle facilitates communication over stream-type sockets by providing mechanisms run in background threads that accept socket connections and read from sockets.
NSFileHandle currently handles only communication through stream-type sockets. If you want to use datagrams or other types of sockets, you must create and manage the connection using native system routines.
The process on one end of the communication channel (the server) starts by creating and preparing a socket using system routines. These routines vary slightly between BSD and non-BSD systems, but consist of the same sequence of steps:
Typically the other process (the client) then locates the named socket created by the first process. Instead of accepting a connection to the socket by calling the appropriate system routine, the client performs the following sequence of steps:
In a method implemented to respond to this notification, the
client extracts the NSFileHandle representing the "near"
socket of the connection from the notification's userInfo dictionary;
it uses the NSFileHandleNotificationFileHandleItem
key
to do this.
The client can now send data to the other process over the communications channel by sending writeData: to the NSFileHandle. (Note that writeData: can block.) The client can also read data directly from the NSFileHandle, but this would cause the process to block until the socket connection was closed, so it is usually better to read in the background. To do this, the process must:
NSFileHandleNotificationDataItem
key.You close the communications channel in both directions by sending closeFile to the NSFileHandle; either process can partially or totally close communication across the socket connection with a system-specific shutdown command.
- Getting an NSFileHandle
- + fileHandleForReadingAtPath:
- + fileHandleForWritingAtPath:
- + fileHandleForUpdatingAtPath:
- + fileHandleWithStandardError
- + fileHandleWithStandardInput
- + fileHandleWithStandardOutput
- + fileHandleWithNullDevice
- Creating an NSFileHandle
- - initWithFileDescriptor:
- - initWithFileDescriptor:closeOnDealloc:
- Getting a file descriptor
- - fileDescriptor
- Reading from an NSFileHandle
- - availableData
- - readDataToEndOfFile
- - readDataOfLength:
- Writing to an NSFileHandle
- - writeData:
- Communicating asynchronously in the background
- - acceptConnectionInBackgroundAndNotifyForModes:
- - acceptConnectionInBackgroundAndNotify
- - readInBackgroundAndNotifyForModes:
- - readInBackgroundAndNotify
- - readToEndOfFileInBackgroundAndNotifyForModes:
- - readToEndOfFileInBackgroundAndNotify
- Seeking within a file
- - offsetInFile
- - seekToEndOfFile
- - seekToFileOffset:
- Operating on a file
- - closeFile
- - synchronizeFile
- - truncateFileAtOffset:
+ fileHandleForReadingAtPath:(NSString
*)path
nil
.See Also: - availableData, - initWithFileDescriptor:, - readDataOfLength:, - readDataToEndOfFile
+ fileHandleForUpdatingAtPath:(NSString
*)path
nil
.See Also: - availableData, - initWithFileDescriptor:, - readDataOfLength:, - readDataToEndOfFile
+ fileHandleForWritingAtPath:(NSString
*)path
nil
.See Also: - initWithFileDescriptor:
+ fileHandleWithNullDevice
See Also: - initWithFileDescriptor:
+ fileHandleWithStandardError
See Also: + fileHandleWithNullDevice, - initWithFileDescriptor:
+ fileHandleWithStandardInput
See Also: + fileHandleWithNullDevice, - initWithFileDescriptor:
+ fileHandleWithStandardOutput
See Also: + fileHandleWithNullDevice, - initWithFileDescriptor:
- (void)acceptConnectionInBackgroundAndNotify
NSFileHandleNotificationFileHandleItem
key.The receiver must be created by an initWithFileDescriptor: message that takes as an argument a stream-type socket created by the appropriate system routine. The object that will write data to the returned NSFileHandle must add itself as an observer of NSFileHandleConnectionAcceptedNotification.
See Also: - enqueueNotification:postingStyle:coalesceMask:forModes: (NSNotificationQueue), - readInBackgroundAndNotify, - readToEndOfFileInBackgroundAndNotify
- (void)acceptConnectionInBackgroundAndNotifyForModes:(NSArray
*)modes
See Also: - enqueueNotification:postingStyle:coalesceMask:forModes: (NSNotificationQueue), - readInBackgroundAndNotifyForModes:, - readToEndOfFileInBackgroundAndNotifyForModes:
- (NSData *)availableData
See Also: - readDataOfLength:, - readDataToEndOfFile
- (void)closeFile
Sending closeFile to an NSFileHandle does not cause its deallocation; for that, you must send it release. Deallocation of an NSFileHandle, on the other hand, deletes its descriptor and closes the represented file or channel. Use closeFile when you want to close a file immediately and reclaim the descriptor; use release when it's acceptable to defer this.
- (int)fileDescriptor
See Also: - initWithFileDescriptor:
- (id)initWithFileDescriptor:(int)fileDescriptor
See Also: - closeFile
- (id)initWithFileDescriptor:(int)fileDescriptor
closeOnDealloc:(BOOL)flag
See Also: - closeFile
- (unsigned long long)offsetInFile
See Also: - seekToEndOfFile, - seekToFileOffset:
- (NSData *)readDataOfLength:(unsigned
int)length
See Also: - availableData, - readDataToEndOfFile
- (NSData *)readDataToEndFile
UNIT_MAX
bytes (the
maximum value for unsigned integers) or, if a communications channel,
until an end-of-file indicator is returned.See Also: - availableData
- (void)readInBackgroundAndNotify
NSFileHandleNotificationDataItem
key.Any object interested in receiving this data asynchronously must add itself as an observer of NSFileHandleReadCompletionNotification. In communication via stream-type sockets, the receiver is often the object returned in the userInfo dictionary of NSFileHandleConnectionAcceptedNotification.
See Also: - acceptConnectionInBackgroundAndNotify, - readToEndOfFileInBackgroundAndNotifyForModes:, - enqueueNotification:postingStyle:coalesceMask:forModes: (NSNotificationQueue)
- (void)readInBackgroundAndNotifyForModes:(NSArray
*)modes
See Also: - acceptConnectionInBackgroundAndNotifyForModes:, - enqueueNotification:postingStyle:coalesceMask:forModes: (NSNotificationQueue)
- (void)readToEndOfFileInBackgroundAndNotify
NSFileHandleNotificationDataItem
key.Any object interested in receiving this data asynchronously must add itself as an observer of NSFileHandleReadToEndOfFileCompletionNotification. In communication via stream-type sockets, the receiver is often the object returned in the userInfo dictionary of NSFileHandleConnectionAcceptedNotification.
See Also: - acceptConnectionInBackgroundAndNotify, - readToEndOfFileInBackgroundAndNotifyForModes:, - enqueueNotification:postingStyle:coalesceMask:forModes: (NSNotificationQueue)
- (void)readToEndOfFileInBackgroundAndNotifyForModes:(NSArray
*)modes
See Also: - acceptConnectionInBackgroundAndNotifyForModes:, - enqueueNotification:postingStyle:coalesceMask:forModes: (NSNotificationQueue)
- (unsigned long long)seekToEndOfFile
See Also: - offsetInFile
- (void)seekToFileOffset:(unsigned
long long)offset
See Also: - offsetInFile
- (void)synchronizeFile
- (void)truncateFileAtOffset:(unsigned
long long)offset
- (void)waitForDataInBackgroundAndNotify
See Also: - waitForDataInBackgroundAndNotifyForModes:
- (void)waitForDataInBackgroundAndNotifyForModes:(NSArray
*)modes
See Also: - waitForDataInBackgroundAndNotify
- (void)writeData:(NSData
*)data
See Also: - availableData, - readDataOfLength:, - readDataToEndOfFile
NSFileHandle posts several notifications related to asynchronous background I/O operations. They are set to post when the run loop of the thread that started the asynchronous operation is idle and for a specified set of run-loop modes (see userInfo dictionary).
This notification contains a notification object and a userInfo dictionary. The notification object is the NSFileHandle that sent the notification.
The userInfo dictionary contains these keys and values:
Key | Value |
NSFileHandleNotificationFileHandleItem |
The NSFileHandle representing the "near" end of a socket connection. |
NSFileHandleNotificationMonitorModes |
An NSArray containing the run-loop modes in which the notification can be posted. |
To cause the posting of this notification, you must send either acceptConnectionInBackgroundAndNotify or acceptConnectionInBackgroundAndNotifyForModes: to an NSFileHandle representing a server stream-type socket. This notification is posted when NSFileHandle establishes a socket connection between two processes, creates an NSFileHandle for one end of the connection, and makes this object available to observers by putting it in the userInfo dictionary.
This notification contains a notification object and no userInfo dictionary. The notification object is the NSFileHandle that sent the notification.
To cause the posting of this notification, you must send either waitForDataInBackgroundAndNotify or waitForDataInBackgroundAndNotifyForModes: to an appropriate NSFileHandle. This notification is posted when the background thread determines that data is currently available for reading in a file or at a communications channel. The observers can then issue the appropriate messages to begin reading the data.
This notification contains a notification object and a userInfo dictionary.
The notification object is the NSFileHandle that sent the notification. The userInfo dictionary contains these keys and values:
Key | Value |
NSFileHandleNotificationDataItem |
An NSData containing the available data read from a socket connection. |
NSFileHandleNotificationMonitorModes |
An NSArray containing the run-loop modes in which the notification can be posted. |
To cause the posting of this notification, you must send either readInBackgroundAndNotify or readInBackgroundAndNotifyForModes: to an appropriate NSFileHandle. This notification is posted when the background thread reads the data currently available in a file or at a communications channel. It makes the data available to observers by putting it in the userInfo dictionary.
This notification contains a notification object and a userInfo dictionary.
The notification object is the NSFileHandle that sent the notification. The userInfo dictionary contains these keys and values:
Key | Value |
NSFileHandleNotificationDataItem |
An NSData containing the available data read from a socket connection. |
NSFileHandleNotificationMonitorModes |
An NSArray containing the run-loop modes in which the notification can be posted. |
To cause the posting of this notification, you must send either readToEndOfFileInBackgroundAndNotify or readToEndOfFileInBackgroundAndNotifyForModes: to an appropriate NSFileHandle. This notification is posted when the background thread reads all data in the file or, if a communications channel, until the other process signals end of data. It makes the data available to observers by putting it in the userInfo dictionary.