Platforms to show: All Mac Windows Linux Cross-Platform

Back to NSFileHandleMBS class.

NSFileHandleMBS.acceptConnectionInBackgroundAndNotify

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Tasks MBS MacCocoa Plugin 9.7 ✅ Yes ❌ No ❌ No ✅ Yes All
Accepts a socket connection (for stream-type sockets only) in the background and creates a file handle for the "near" (client) end of the communications channel.

This method is asynchronous. In a separate "safe" thread it accepts a connection, creates a file handle for the other end of the connection, and returns that object to the client by posting an NSFileHandleConnectionAcceptedNotification in the run loop of the client. The notification includes as data a userInfo dictionary containing the created NSFileHandle object; access this object using the NSFileHandleNotificationFileHandleItem key.
The receiver must be created by an fileHandleWithFileDescriptor 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 file handle must add itself as an observer of NSFileHandleConnectionAcceptedNotification.
Note that this method does not continue to listen for connection requests after it posts NSFileHandleConnectionAcceptedNotification. If you want to keep getting notified, you need to call acceptConnectionInBackgroundAndNotify again in your observer method.

NSFileHandleMBS.AvailableBytes as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Tasks MBS MacCocoa Plugin 14.1 ✅ Yes ❌ No ❌ No ✅ Yes All
Queries number of available bytes.

Returns -1 if query failed.
You can use this value with readDataOfLength function to have it not block.

NSFileHandleMBS.availableData as MemoryBlock

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Tasks MBS MacCocoa Plugin 9.7 ✅ Yes ❌ No ❌ No ✅ Yes All
Returns the data available through the receiver.

If the receiver is a file, returns the data obtained by reading the file from the file pointer to the end of the file. If the receiver is a communications channel, reads up to a buffer of data and returns it; if no data is available, the method blocks. Returns an empty data object if the end of file is reached. Raises NSFileHandleOperationException if attempts to determine file-handle type fail or if attempts to read from the file or channel fail.

NSFileHandleMBS.closeFile

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Tasks MBS MacCocoa Plugin 9.7 ✅ Yes ❌ No ❌ No ✅ Yes All
Disallows further access to the represented file or communications channel and signals end of file on communications channels that permit writing.
Example
// file must exist for this sample:

dim f as FolderItem = SpecialFolder.Desktop.Child("test.txt")
dim e as NSErrorMBS
dim n as NSFileHandleMBS = NSFileHandleMBS.fileHandleForReadingFromFile(f,e)

if e<>Nil then
MsgBox e.localizedDescription
end if

if n<>Nil then
MsgBox n.readDataOfLength(5)
n.closeFile
end if

The file or communications channel is available for other uses after the file handle represented by the receiver is closed. Further read and write messages sent to a file handle to which closeFile has been sent raises an exception.
Sending closeFile to a file handle does not cause its deallocation. The deallocation of an NSFileHandle object deletes its descriptor and closes the represented file or channel unless the NSFileHandle object was created with fileHandleWithFileDescriptor with false as the parameter argument.

NSFileHandleMBS.Constructor   Private

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Tasks MBS MacCocoa Plugin 13.1 ✅ Yes ❌ No ❌ No ✅ Yes All
The private constructor.

NSFileHandleMBS.fileDescriptor as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Tasks MBS MacCocoa Plugin 9.7 ✅ Yes ❌ No ❌ No ✅ Yes All
Returns the file descriptor associated with the receiver.

Returns the POSIX file descriptor associated with the receiver.

You can send this message to file handles originating from both file descriptors and file handles and receive a valid file descriptor so long as the file handle is open. If the file handle has been closed by sending it closeFile, this method raises an exception.

NSFileHandleMBS.offsetInFile as UInt64

Type Topic Plugin Version macOS Windows Linux iOS Targets
property Cocoa Tasks MBS MacCocoa Plugin 9.7 ✅ Yes ❌ No ❌ No ✅ Yes All
Returns the position of the file pointer within the file represented by the receiver.
Example
// file must exist for this sample:

dim f as FolderItem = SpecialFolder.Desktop.Child("test.txt")
dim e as NSErrorMBS
dim n as NSFileHandleMBS = NSFileHandleMBS.fileHandleForReadingFromFile(f,e)

if e<>Nil then
MsgBox e.localizedDescription
end if

if n<>Nil then
MsgBox n.readDataOfLength(5)
MsgBox str(n.offsetInFile) // shows 5
end if

The position of the file pointer within the file represented by the receiver.

Raises an exception if the message is sent to a file handle representing a pipe or socket or if the file descriptor is closed.
(Read and Write computed property)

NSFileHandleMBS.readDataOfLength(length as Integer) as MemoryBlock

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Tasks MBS MacCocoa Plugin 9.7 ✅ Yes ❌ No ❌ No ✅ Yes All
Reads data up to a specified number of bytes from the receiver.
Example
// file must exist for this sample:

dim f as FolderItem = SpecialFolder.Desktop.Child("test.txt")
dim n as NSFileHandleMBS = NSFileHandleMBS.fileHandleForReadingAtFile(f)

if n<>Nil then
MsgBox n.readDataOfLength(5)
end if

length: The number of bytes to read from the receiver.

Returns the data available through the receiver up to a maximum of length bytes.

If the receiver is a file, returns the data obtained by reading from the file pointer to length or to the end of the file, whichever comes first. If the receiver is a communications channel, the method reads data from the channel up to length. Returns an empty memoryblock if the file is positioned at the end of the file or if an end-of-file indicator is returned on a communications channel. Raises NSFileHandleOperationException if attempts to determine file-handle type fail or if attempts to read from the file or channel fail.

Some examples using this method:

NSFileHandleMBS.readDataToEndOfFile as MemoryBlock

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Tasks MBS MacCocoa Plugin 9.7 ✅ Yes ❌ No ❌ No ✅ Yes All
Returns the data available through the receiver up to the end of file or maximum number of bytes.
Example
// file must exist for this sample:

dim f as FolderItem = SpecialFolder.Desktop.Child("test.txt")
dim n as NSFileHandleMBS = NSFileHandleMBS.fileHandleForReadingAtFile(f)

if n<>Nil then
MsgBox n.readDataToEndOfFile
end if

Returns the data available through the receiver up to UINT_MAX bytes (the maximum value for unsigned integers) or, if a communications channel, until an end-of-file indicator is returned.

This method invokes readDataOfLength as part of its implementation.

Some examples using this method:

NSFileHandleMBS.readInBackgroundAndNotify

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Tasks MBS MacCocoa Plugin 9.7 ✅ Yes ❌ No ❌ No ✅ Yes All
Reads from the file or communications channel in the background and posts a notification when finished.

This method performs an asynchronous availableData operation on a file or communications channel and posts an NSFileHandleReadCompletionNotification to the client process's run loop.
The length of the data is limited to the buffer size of the underlying operating system. The notification includes a userInfo dictionary that contains the data read; access this object using the 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.
Note that this method does not cause a continuous stream of notifications to be sent. If you wish to keep getting notified, you'll also need to call readInBackgroundAndNotify in your observer method.

NSFileHandleMBS.readToEndOfFileInBackgroundAndNotify

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Tasks MBS MacCocoa Plugin 9.7 ✅ Yes ❌ No ❌ No ✅ Yes All
Reads to the end of file from the file or communications channel in the background and posts a notification when finished.
Example
dim path as string = "/tmp/NSFileHandle async reading.txt"
dim f as FolderItem = GetFolderItem(path, FolderItem.PathTypeShell)
dim n as NSFileHandleMBS = NSFileHandleMBS.fileHandleForReadingAtFile(f)

n.readToEndOfFileInBackgroundAndNotify

This method performs an asynchronous readToEndOfFile operation on a file or communications channel and posts an NSFileHandleReadToEndOfFileCompletionNotification to the client process's run loop.
The notification includes a userInfo dictionary that contains the data read; access this object using the 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.

Some examples using this method:

NSFileHandleMBS.seekToEndOfFile as UInt64

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Tasks MBS MacCocoa Plugin 9.7 ✅ Yes ❌ No ❌ No ✅ Yes All
Puts the file pointer at the end of the file referenced by the receiver and returns the new file offset.

Returns the file offset with the file pointer at the end of the file. This is therefore equal to the size of the file.

Raises an exception if the message is sent to an NSFileHandle object representing a pipe or socket or if the file descriptor is closed.

NSFileHandleMBS.seekToFileOffset(offset as UInt64)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Tasks MBS MacCocoa Plugin 9.7 ✅ Yes ❌ No ❌ No ✅ Yes All
Moves the file pointer to the specified offset within the file represented by the receiver.

Raises an exception if the message is sent to an NSFileHandle object representing a pipe or socket, if the file descriptor is closed, or if any other error occurs in seeking.

NSFileHandleMBS.synchronizeFile

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Tasks MBS MacCocoa Plugin 9.7 ✅ Yes ❌ No ❌ No ✅ Yes All
Causes all in-memory data and attributes of the file represented by the receiver to be written to permanent storage.

This method should be invoked by programs that require the file to always be in a known state. An invocation of this method does not return until memory is flushed.

NSFileHandleMBS.truncateFileAtOffset(offset as UInt64)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Tasks MBS MacCocoa Plugin 9.7 ✅ Yes ❌ No ❌ No ✅ Yes All
Truncates or extends the file represented by the receiver to a specified offset within the file and puts the file pointer at that position.

offset: The offset within the file that will mark the new end of the file.

If the file is extended (if offset is beyond the current end of file), the added characters are null bytes.

NSFileHandleMBS.waitForDataInBackgroundAndNotify

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Tasks MBS MacCocoa Plugin 9.7 ✅ Yes ❌ No ❌ No ✅ Yes All
Checks to see if data is available in a background thread.

When the data becomes available, the thread notifies all observers with NSFileHandleDataAvailableNotification. After the notification has been posted, the thread is terminated.

NSFileHandleMBS.writeData(data as MemoryBlock)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Tasks MBS MacCocoa Plugin 9.7 ✅ Yes ❌ No ❌ No ✅ Yes All
Synchronously writes data to the file, device, pipe, or socket represented by the receiver.
Example
// file must exist for this sample:

dim f as FolderItem = SpecialFolder.Desktop.Child("test.txt")
dim n as NSFileHandleMBS = NSFileHandleMBS.fileHandleForWritingAtFile(f)

if n<>Nil then
n.writeData "Hello World"
n.closeFile
end if

If the receiver is a file, writing takes place at the file pointer's current position. After it writes the data, the method advances the file pointer by the number of bytes written. Raises an exception if the file descriptor is closed or is not valid, if the receiver represents an unconnected pipe or socket endpoint, if no free space is left on the file system, or if any other writing error occurs.

The items on this page are in the following plugins: MBS MacCocoa Plugin.


The biggest plugin in space...