iOS Developer Library

Developer

Foundation Framework Reference NSOutputStream Class Reference

Options
Deployment Target:

On This Page
Language:

NSOutputStream

The NSOutputStream class is a subclass of NSStream that provides write-only stream functionality.

NSOutputStream is “toll-free bridged” with its Core Foundation counterpart, CFWriteStreamRef. For more information on toll-free bridging, see Toll-Free Bridging.

Subclassing Notes

NSOutputStream is a concrete subclass of NSStream that lets you write data to a stream. Although NSOutputStream is probably sufficient for most situations requiring this capability, you can create a subclass of NSOutputStream if you want more specialized behavior (for example, you want to record statistics on the data in a stream).

Methods to Override

To create a subclass of NSOutputStream you may have to implement initializers for the type of stream data supported and suitably reimplement existing initializers. You must also provide complete implementations of the following methods:

  • write:maxLength:

    From the current write pointer, take up to the number of bytes specified in the maxLength: parameter from the client-supplied buffer (first parameter) and put them onto the stream. The buffer must be of the size specified by the second parameter. To prepare for the next operation, offset the write pointer by the number of bytes written. Return a signed integer based on the outcome of the current operation:

    • If the write operation is successful, return the actual number of bytes put onto the stream.

    • If the stream is of a fixed length and has reached its capacity, return 0.

    • If there was an error writing to the stream, return -1.

  • hasSpaceAvailable

    Return YEStrue if the stream can currently accept more data, NOfalse if it cannot. If you want to be semantically compatible with NSOutputStream, return YEStrue if a write must be attempted to determine if space is available.

  • A boolean value that indicates whether the receiver can be written to. (read-only)

    Declaration

    Swift

    var hasSpaceAvailable: Bool { get }

    Objective-C

    @property(readonly) BOOL hasSpaceAvailable

    Discussion

    YEStrue if the receiver can be written to or if a write must be attempted in order to determine if space is available, NOfalse otherwise.

    Availability

    Available in iOS 2.0 and later.

  • Writes the contents of a provided data buffer to the receiver.

    Declaration

    Swift

    func write(_ buffer: UnsafePointer<UInt8>, maxLength len: Int) -> Int

    Objective-C

    - (NSInteger)write:(const uint8_t *)buffer maxLength:(NSUInteger)length

    Parameters

    buffer

    The data to write.

    length

    The length of the data buffer, in bytes.

    Return Value

    A number indicating the outcome of the operation:

    • A positive number indicates the number of bytes written.

    • 0 indicates that a fixed-length stream and has reached its capacity.

    • -1 means that the operation failed; more information about the error can be obtained with streamError.

    Availability

    Available in iOS 2.0 and later.