NSStream Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.3 and later.
Companion guide
Declared in
NSStream.h
Related sample code

Overview

NSStream is an abstract class for objects representing streams. Its 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:

Tasks

Creating Streams

Configuring Streams

Using Streams

Managing Run Loops

Getting Stream Information

Class Methods

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.

+ (void)getStreamsToHost:(NSHost *)host port:(NSInteger)port inputStream:(NSInputStream **)inputStream outputStream:(NSOutputStream **)outputStream
Parameters
host

The host to which to connect.

port

The port to connect to on host.

inputStream

Upon return, contains the input stream. If nil is passed, the stream object is not created.

outputStream

Upon return, contains the output stream. If nil is passed, the stream object is not created.

Discussion

If neither port nor host is properly specified, no socket connection is made.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSStream.h

Instance Methods

close

Closes the receiver.

- (void)close
Discussion

Closing the stream terminates the flow of bytes and releases system resources that were reserved for the stream when it was opened. If the stream has been scheduled on a run loop, closing the stream implicitly removes the stream from the run loop. A stream that is closed can still be queried for its properties.

Availability
  • Available in OS X v10.3 and later.
See Also
Declared In
NSStream.h

delegate

Returns the receiver’s delegate.

- (id < NSStreamDelegate >)delegate
Return Value

The receiver’s delegate. The delegate must implement the NSStreamDelegate Protocol.

Discussion

By default, a stream is its own delegate, and subclasses of NSInputStream and NSOutputStream must maintain this contract.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSStream.h

open

Opens the receiving stream.

- (void)open
Discussion

A stream must be created before it can be opened. Once opened, a stream cannot be closed and reopened.

Availability
  • Available in OS X v10.3 and later.
See Also
Declared In
NSStream.h

propertyForKey:

Returns the receiver’s property for a given key.

- (id)propertyForKey:(NSString *)key
Parameters
key

The key for one of the receiver's properties. See “Constants” for a description of the available property-key constants and associated values.

Return Value

The receiver’s property for the key key.

Availability
  • Available in OS X v10.3 and later.
Related Sample Code
Declared In
NSStream.h

removeFromRunLoop:forMode:

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

- (void)removeFromRunLoop:(NSRunLoop *)aRunLoop forMode:(NSString *)mode
Parameters
aRunLoop

The run loop on which the receiver was scheduled.

mode

The mode for the run loop.

Availability
  • Available in OS X v10.3 and later.
Related Sample Code
Declared In
NSStream.h

scheduleInRunLoop:forMode:

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

- (void)scheduleInRunLoop:(NSRunLoop *)aRunLoop forMode:(NSString *)mode
Parameters
aRunLoop

The run loop on which to schedule the receiver.

mode

The mode for the run loop.

Discussion

Unless the client is polling the stream, it is responsible for ensuring that the stream is scheduled on at least one run loop and that at least one of the run loops on which the stream is scheduled is being run.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSStream.h

setDelegate:

Sets the receiver’s delegate.

- (void)setDelegate:(id < NSStreamDelegate >)delegate
Parameters
delegate

The delegate for the receiver.

Discussion

By default, a stream is its own delegate, and subclasses of NSInputStream and NSOutputStream must maintain this contract. If you override this method in a subclass, passing nil must restore the receiver as its own delegate. Delegates are not retained.

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

Availability
  • Available in OS X v10.3 and later.
See Also
Declared In
NSStream.h

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.

- (BOOL)setProperty:(id)property forKey:(NSString *)key
Parameters
property

The value for key.

key

The key for one of the receiver's properties. See “Constants” for a description of the available property-key constants and expected values.

Return Value

YES if the value is accepted by the receiver, otherwise NO.

Availability
  • Available in OS X v10.3 and later.
Related Sample Code
Declared In
NSStream.h

streamError

Returns an NSError object representing the stream error.

- (NSError *)streamError
Return Value

An NSError object representing the stream error, or nil if no error has been encountered.

Availability
  • Available in OS X v10.3 and later.
Related Sample Code
Declared In
NSStream.h

streamStatus

Returns the receiver’s status.

- (NSStreamStatus)streamStatus
Return Value

The receiver’s status.

Discussion

See “Constants” for a description of the available NSStreamStatus constants.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSStream.h

Constants

NSStreamStatus

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

typedef NSUInteger NSStreamStatus;
Availability
  • Available in OS X v10.3 and later.
Declared In
NSStream.h

Stream Status Constants

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

typedef enum {
   NSStreamStatusNotOpen = 0,
   NSStreamStatusOpening = 1,
   NSStreamStatusOpen = 2,
   NSStreamStatusReading = 3,
   NSStreamStatusWriting = 4,
   NSStreamStatusAtEnd = 5,
   NSStreamStatusClosed = 6,
   NSStreamStatusError = 7
};
Constants
NSStreamStatusNotOpen

The stream is not open for reading or writing. This status is returned before the underlying call to open a stream but after it’s been created.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamStatusOpening

The stream is in the process of being opened for reading or for writing. For network streams, this status might include the time after the stream was opened, but while network DNS resolution is happening.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamStatusOpen

The stream is open, but no reading or writing is occurring.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamStatusReading

Data is being read from the stream. This status would be returned if code on another thread were to call streamStatus on the stream while a read:maxLength: call (NSInputStream) was in progress.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamStatusWriting

Data is being written to the stream. This status would be returned if code on another thread were to call streamStatus on the stream while a write:maxLength: call (NSOutputStream) was in progress.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamStatusAtEnd

There is no more data to read, or no more data can be written to the stream. When this status is returned, the stream is in a “non-blocking” mode and no data are available.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamStatusClosed

The stream is closed (close has been called on it).

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamStatusError

The remote end of the connection can’t be contacted, or the connection has been severed for some other reason.

Available in OS X v10.3 and later.

Declared in NSStream.h.

Stream Event Constants

One or more of these constants may be sent to the delegate as a bit field in the second parameter of stream:handleEvent:.

typedef enum : NSUInteger {
   NSStreamEventNone = 0,
   NSStreamEventOpenCompleted = 1 << 0,
   NSStreamEventHasBytesAvailable = 1 << 1,
   NSStreamEventHasSpaceAvailable = 1 << 2,
   NSStreamEventErrorOccurred = 1 << 3,
   NSStreamEventEndEncountered = 1 << 4
} NSStreamEvent;
Constants
NSStreamEventNone

No event has occurred.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamEventOpenCompleted

The open has completed successfully.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamEventHasBytesAvailable

The stream has bytes to be read.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamEventHasSpaceAvailable

The stream can accept bytes for writing.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamEventErrorOccurred

An error has occurred on the stream.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamEventEndEncountered

The end of the stream has been reached.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStream Property Keys

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

NSString * const NSStreamSocketSecurityLevelKey;
NSString * const NSStreamSOCKSProxyConfigurationKey;
NSString * const NSStreamSOCKSProxyHostKey;
NSString * const NSStreamSOCKSProxyPortKey;
NSString * const NSStreamSOCKSProxyVersionKey;
NSString * const NSStreamSOCKSProxyUserKey;
NSString * const NSStreamSOCKSProxyPasswordKey;
NSString * const NSStreamSOCKSProxyVersion4;
NSString * const NSStreamSOCKSProxyVersion5;
NSString * const NSStreamDataWrittenToMemoryStreamKey;
NSString * const NSStreamFileCurrentOffsetKey;
NSString * const NSStreamNetworkServiceType;
Constants
NSStreamSocketSecurityLevelKey

The security level of the target stream. See “Secure-Socket Layer (SSL) Security Level” for a list of possible values.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamSOCKSProxyConfigurationKey

Value is an NSDictionary object containing SOCKS proxy configuration information.

The dictionary returned from the System Configuration framework for SOCKS proxies usually suffices.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamDataWrittenToMemoryStreamKey

Value is an NSData instance containing the data written to a memory stream.

Use this property when you have an output-stream object instantiated to collect written data in memory. The value of this property is read-only.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamFileCurrentOffsetKey

Value is an NSNumber object containing the current absolute offset of the stream.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamNetworkServiceType

The type of service for the stream. Providing the service type allows the system to properly handle certain attributes of the stream, including routing and suspension behavior. Most streams do not need to set this property. See “Stream Service Types” for a list of possible values.

Available in OS X v10.7 and later.

Declared in NSStream.h.

Declared In
NSStream.h

NSStream Error Domains

NSStream defines these string constants to represent error domains that can be returned by streamError:

NSString * const NSStreamSocketSSLErrorDomain  ;
NSString * const NSStreamSOCKSErrorDomain  ;
Constants
NSStreamSocketSSLErrorDomain

The error domain used by NSError when reporting SSL errors.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamSOCKSErrorDomain

The error domain used by NSError when reporting SOCKS errors.

Available in OS X v10.3 and later.

Declared in NSStream.h.

Secure-Socket Layer (SSL) Security Level

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

NSString * const NSStreamSocketSecurityLevelNone;
NSString * const NSStreamSocketSecurityLevelSSLv2;
NSString * const NSStreamSocketSecurityLevelSSLv3;
NSString * const NSStreamSocketSecurityLevelTLSv1;
NSString * const NSStreamSocketSecurityLevelNegotiatedSSL
Constants
NSStreamSocketSecurityLevelNone

Specifies that no security level be set for a socket stream.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamSocketSecurityLevelSSLv2

Specifies that SSL version 2 be set as the security protocol for a socket stream.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamSocketSecurityLevelSSLv3

Specifies that SSL version 3 be set as the security protocol for a socket stream.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamSocketSecurityLevelTLSv1

Specifies that TLS version 1 be set as the security protocol for a socket stream.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamSocketSecurityLevelNegotiatedSSL

Specifies that the highest level security protocol that can be negotiated be set as the security protocol for a socket stream.

Available in OS X v10.3 and later.

Declared in NSStream.h.

Discussion

You access and set these values using the NSStreamSocketSecurityLevelKey property key.

SOCKS Proxy Configuration Values

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

NSString * const NSStreamSOCKSProxyHostKey;
NSString * const NSStreamSOCKSProxyPortKey;
NSString * const NSStreamSOCKSProxyVersionKey;
NSString * const NSStreamSOCKSProxyUserKey;
NSString * const NSStreamSOCKSProxyPasswordKey;
NSString * const NSStreamSOCKSProxyVersion4;
NSString * const NSStreamSOCKSProxyVersion5
Constants
NSStreamSOCKSProxyHostKey

Value is an NSString object that represents the SOCKS proxy host.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamSOCKSProxyPortKey

Value is an NSNumber object containing an integer that represents the port on which the proxy listens.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamSOCKSProxyVersionKey

Value is either NSStreamSOCKSProxyVersion4 or NSStreamSOCKSProxyVersion5.

If this key is not present, NSStreamSOCKSProxyVersion5 is used by default.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamSOCKSProxyUserKey

Value is an NSString object containing the user’s name.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamSOCKSProxyPasswordKey

Value is an NSString object containing the user’s password.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamSOCKSProxyVersion4

Possible value for NSStreamSOCKSProxyVersionKey.

Available in OS X v10.3 and later.

Declared in NSStream.h.

NSStreamSOCKSProxyVersion5

Possible value for NSStreamSOCKSProxyVersionKey.

Available in OS X v10.3 and later.

Declared in NSStream.h.

Discussion

You set the dictionary object as the current SOCKS proxy configuration using the NSStreamSOCKSProxyConfigurationKey key

Stream Service Types

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

NSString * const NSStreamNetworkServiceTypeVoIP
NSString * const NSStreamNetworkServiceTypeVideo
NSString * const NSStreamNetworkServiceTypeBackground
NSString * const NSStreamNetworkServiceTypeVoice
Constants
NSStreamNetworkServiceTypeVoIP

Specifies that the stream is providing VoIP service.

Available in OS X v10.7 and later.

Declared in NSStream.h.

NSStreamNetworkServiceTypeVideo

Specifies that the stream is providing video service.

Available in OS X v10.7 and later.

Declared in NSStream.h.

NSStreamNetworkServiceTypeBackground

Specifies that the stream is providing a background service.

Available in OS X v10.7 and later.

Declared in NSStream.h.

NSStreamNetworkServiceTypeVoice

Specifies that the stream is providing voice service.

Available in OS X v10.7 and later.

Declared in NSStream.h.