An abstract class representing a stream.


@interface NSStream : NSObject


This class's interface is common to all Cocoa stream classes, including its concrete subclasses NSInputStream and NSOutputStream.

NSStream objects provide an easy way to read and write data to and from a variety of media in a device-independent way. You can create stream objects for data located in memory, in a file, or on a network (using sockets), and you can use stream objects without loading all of the data into memory at once.

By default, NSStream instances that are not file-based are non-seekable, one-way streams (although custom seekable subclasses are possible). Once the data has been provided or consumed, the data cannot be retrieved from the stream.

Subclassing Notes

NSStream is an abstract class, incapable of instantiation and intended to be subclassed. It publishes a programmatic interface that all subclasses must adopt and provide implementations for. The two Apple-provided concrete subclasses of NSStream, NSInputStream and NSOutputStream, are suitable for most purposes. However, there might be situations when you want a peer subclass to NSInputStream and NSOutputStream. For example, you might want a class that implements a full-duplex (two-way) stream, or a class whose instances are capable of seeking through a stream.

Methods to Override

All subclasses must fully implement the following methods, which are presented in functional pairs:

  • open and close

    Implement open to open the stream for reading or writing and make the stream available to the client directly or, if the stream object is scheduled on a run loop, to the delegate. Implement close to close the stream and remove the stream object from the run loop, if necessary. A closed stream should still be able to accept new properties and report its current properties. Once a stream is closed, it cannot be reopened.

  • delegate and delegate

    Return and set the delegate. By a default, a stream object must be its own delegate; so a delegate message with an argument of nil should restore this delegate. Do not retain the delegate to prevent retain cycles.

    To learn about delegates and delegation, read "Delegation" in Cocoa Fundamentals Guide.

  • scheduleInRunLoop:forMode: and removeFromRunLoop:forMode:

    Implement scheduleInRunLoop:forMode: to schedule the stream object on the specified run loop for the specified mode. Implement removeFromRunLoop:forMode: to remove the object from the run loop. See the documentation of the NSRunLoop class for details. Once the stream object for an open stream is scheduled on a run loop, it is the responsibility of the subclass as it processes stream data to send stream:handleEvent: messages to its delegate.

  • propertyForKey: and setProperty:forKey:

    Implement these methods to return and set, respectively, the property value for the specified key. You may add custom properties, but be sure to handle all properties defined by NSStream as well.

  • streamStatus and streamError

    Implement streamStatus to return the current status of the stream as a NSStreamStatus constant; you may define new NSStreamStatus constants, but be sure to handle the NSStream-defined constants properly. ImplementstreamError to return an NSError object representing the current error. You might decide to return a custom NSError object that can provide complete and localized information about the error.


Creating Streams

+ getStreamsToHost:port:inputStream:outputStream:

Creates and returns by reference an NSInputStream object and NSOutputStream object for a socket connection with a given host on a given port.


Configuring Streams

- propertyForKey:

Returns the receiver’s property for a given key.

- setProperty:forKey:

Attempts to set the value of a given property of the receiver and returns a Boolean value that indicates whether the value is accepted by the receiver.


Sets the receiver’s delegate.

Using Streams

- open

Opens the receiving stream.

- close

Closes the receiver.

Managing Run Loops

- scheduleInRunLoop:forMode:

Schedules the receiver on a given run loop in a given mode.

- removeFromRunLoop:forMode:

Removes the receiver from a given run loop running in a given mode.

Getting Stream Information


Returns the receiver’s status.


Returns an NSError object representing the stream error.



The type declared for the constants listed in Stream Status Constants.

Stream Status Constants

These constants indicate the current status of a stream. They are returned by streamStatus.


Describes the constants that may be sent to the delegate as a bit field in the second parameter of stream:handleEvent: to specify the kind of stream event.


NSStream defines these string constants for specifying the service type of a stream.


NSStream defines these string constants for specifying the secure-socket layer (SSL) security level.


NSStream defines these string constants as keys for accessing stream properties using propertyForKey: and setting properties with setProperty:forKey::


The error domain used by NSError when reporting SSL errors.


The error domain used by NSError when reporting SOCKS errors.

Type Methods


Inherits From

See Also



A stream that provides read-only stream functionality.


A stream that provides write-only stream functionality.


An interface that delegates of a stream instance use to handle events on the stream.