Class

NSStream

NSStream is an abstract class for objects representing streams. Its interface is common to all Cocoa stream classes, including its concrete subclasses NSInput​Stream and NSOutput​Stream.

Overview

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 nonseekable, 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, NSInput​Stream and NSOutput​Stream, are suitable for most purposes. However, there might be situations when you want a peer subclass to NSInput​Stream and NSOutput​Stream. 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.

  • schedule​In​Run​Loop:​for​Mode:​ and remove​From​Run​Loop:​for​Mode:​

    Implement schedule​In​Run​Loop:​for​Mode:​ to schedule the stream object on the specified run loop for the specified mode. Implement remove​From​Run​Loop:​for​Mode:​ to remove the object from the run loop. See the documentation of the NSRun​Loop 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​Event:​ messages to its delegate.

  • property​For​Key:​ and set​Property:​for​Key:​

    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.

  • stream​Status and stream​Error

    Implement stream​Status 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. Implementstream​Error 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.

Symbols

Creating Streams

+ get​Streams​To​Host:​​port:​​input​Stream:​​output​Stream:​​

Creates and returns by reference an NSInput​Stream object and NSOutput​Stream object for a socket connection with a given host on a given port.

Deprecated

Configuring Streams

- property​For​Key:​​

Returns the receiver’s property for a given key.

- set​Property:​​for​Key:​​

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

- schedule​In​Run​Loop:​​for​Mode:​​

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

- remove​From​Run​Loop:​​for​Mode:​​

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

Getting Stream Information

stream​Status

Returns the receiver’s status.

stream​Error

Returns an NSError object representing the stream error.

Constants

NSStream​Status

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 stream​Status.

NSStream​Event

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

NSStream Property Keys

NSStream defines these string constants as keys for accessing stream properties using property​For​Key:​ and setting properties with set​Property:​for​Key:​:

NSStream Error Domains

NSStream defines these string constants to represent error domains that can be returned by stream​Error:

Secure-Socket Layer (SSL) Security Level

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

SOCKS Proxy Configuration Values

NSStream defines these string constants for use as keys to specify SOCKS proxy configuration values in an NSDictionary object.

Stream Service Types

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

Relationships

Inherits From