Contents

Stream

An abstract class representing a stream.

Declaration

class Stream

Mentioned in

Overview

This class’s interface is common to all Cocoa stream classes, including its concrete subclasses InputStream and OutputStream.

Stream 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, Stream instances that aren’t file-based are non-seekable, one-way streams (although custom seekable subclasses are possible). After you provide or consume data, you can’t retrieve the data from the stream.

Subclassing Notes

Stream is an abstract class, incapable of instantiation and intended for you to subclass it. It publishes a programmatic interface that all subclasses must adopt and provide implementations for. The two Apple-provided concrete subclasses of Stream, InputStream and OutputStream, are suitable for most purposes. However, there might be situations when you want a peer subclass to InputStream and OutputStream. 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:

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 you close a stream, you can’t reopen it.

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. Don’t retain the delegate to prevent retain cycles.

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

Implement schedule(in:forMode:) to schedule the stream object on the specified run loop for the specified mode. Implement remove(from:forMode:) to remove the object from the run loop. See the documentation of the RunLoop 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(_:handle:) messages to its delegate.

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 Stream as well.

Implement streamStatus to return the current status of the stream as a Stream.Status constant; you may define new Stream.Status constants, but be sure to handle the system defined constants properly. Implement streamError 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

Configuring Streams

Using Streams

Managing Run Loops

Getting Stream Information

Constants

Type Methods

See Also

Streams