Class

NSStream

An abstract class representing a stream.

Overview

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.

Topics

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.

Deprecated

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.

delegate

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

streamStatus

Returns the receiver’s status.

streamError

Returns an NSError object representing the stream error.

Constants

NSStreamStatus

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.

NSStreamEvent

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.

NSStreamNetworkServiceTypeValue

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

NSStreamSocketSecurityLevel

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

NSStreamPropertyKey

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

NSStreamSocketSSLErrorDomain

The error domain used by NSError when reporting SSL errors.

NSStreamSOCKSErrorDomain

The error domain used by NSError when reporting SOCKS errors.

Type Methods

Relationships

Inherits From

See Also

Streams

NSInputStream

A stream that provides read-only stream functionality.

NSOutputStream

A stream that provides write-only stream functionality.

NSStreamDelegate

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