Mac Developer Library

Developer

Foundation Framework Reference NSStream Class Reference

Options
Deployment Target:

On This Page
Language:

NSStream

Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in OS X v10.3 and later.

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:

  • 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 setDelegate:

    Return and set the delegate. By a default, a stream object must be its own delegate; so a setDelegate: 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.

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

    Declaration

    Swift

    class func getStreamsToHost(_ host: NSHost, port port: Int, inputStream inputStream: AutoreleasingUnsafeMutablePointer<NSInputStream?>, outputStream outputStream: AutoreleasingUnsafeMutablePointer<NSOutputStream?>)

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.10.

  • Returns the receiver’s property for a given key.

    Declaration

    Swift

    func propertyForKey(_ key: String) -> AnyObject?

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

  • 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.

    Declaration

    Swift

    func setProperty(_ property: AnyObject?, forKey key: String) -> Bool

    Objective-C

    - (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

    YEStrue if the value is accepted by the receiver, otherwise NOfalse.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

  • Returns the receiver’s delegate.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSStreamDelegate?

    Objective-C

    @property(assign) 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

  • Sets the receiver’s delegate.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSStreamDelegate?

    Objective-C

    @property(assign) 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

    See Also

    – delegate

  • Opens the receiving stream.

    Declaration

    Swift

    func open()

    Objective-C

    - (void)open

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

    See Also

    – close

  • Closes the receiver.

    Declaration

    Swift

    func close()

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

    See Also

    – open

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

    Declaration

    Swift

    func scheduleInRunLoop(_ aRunLoop: NSRunLoop, forMode mode: String)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func removeFromRunLoop(_ aRunLoop: NSRunLoop, forMode mode: String)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

  • Returns the receiver’s status.

    Declaration

    Swift

    var streamStatus: NSStreamStatus { get }

    Objective-C

    @property(readonly) NSStreamStatus streamStatus

    Return Value

    The receiver’s status.

    Discussion

    See Constants for a description of the available NSStreamStatus constants.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

  • Returns an NSError object representing the stream error.

    Declaration

    Swift

    @NSCopying var streamError: NSError? { get }

    Objective-C

    @property(readonly, copy) NSError *streamError

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

Data Types

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

    Declaration

    Swift

    enum NSStreamStatus : UInt { case NotOpen case Opening case Open case Reading case Writing case AtEnd case Closed case Error }

    Objective-C

    typedef NSUInteger NSStreamStatus;

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    case NotOpen case Opening case Open case Reading case Writing case AtEnd case Closed case Error

    Objective-C

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

    Constants

    • NotOpen

      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.

    • Opening

      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.

    • Open

      NSStreamStatusOpen

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

      Available in OS X v10.3 and later.

    • Reading

      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.

    • Writing

      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.

    • AtEnd

      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.

    • Closed

      NSStreamStatusClosed

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

      Available in OS X v10.3 and later.

    • Error

      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.

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

    Declaration

    Swift

    struct NSStreamEvent : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var None: NSStreamEvent { get } static var OpenCompleted: NSStreamEvent { get } static var HasBytesAvailable: NSStreamEvent { get } static var HasSpaceAvailable: NSStreamEvent { get } static var ErrorOccurred: NSStreamEvent { get } static var EndEncountered: NSStreamEvent { get } }

    Objective-C

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

    Constants

    • None

      NSStreamEventNone

      No event has occurred.

      Available in OS X v10.3 and later.

    • OpenCompleted

      NSStreamEventOpenCompleted

      The open has completed successfully.

      Available in OS X v10.3 and later.

    • HasBytesAvailable

      NSStreamEventHasBytesAvailable

      The stream has bytes to be read.

      Available in OS X v10.3 and later.

    • HasSpaceAvailable

      NSStreamEventHasSpaceAvailable

      The stream can accept bytes for writing.

      Available in OS X v10.3 and later.

    • ErrorOccurred

      NSStreamEventErrorOccurred

      An error has occurred on the stream.

      Available in OS X v10.3 and later.

    • EndEncountered

      NSStreamEventEndEncountered

      The end of the stream has been reached.

      Available in OS X v10.3 and later.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    let NSStreamSocketSecurityLevelKey: String let NSStreamSOCKSProxyConfigurationKey: String let NSStreamDataWrittenToMemoryStreamKey: String let NSStreamFileCurrentOffsetKey: String let NSStreamNetworkServiceType: String

    Objective-C

    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

      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.

    • NSStreamSOCKSProxyConfigurationKey

      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.

    • NSStreamDataWrittenToMemoryStreamKey

      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.

    • NSStreamFileCurrentOffsetKey

      NSStreamFileCurrentOffsetKey

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

      Available in OS X v10.3 and later.

    • NSStreamNetworkServiceType

      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.

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

    Declaration

    Swift

    let NSStreamSocketSSLErrorDomain: String let NSStreamSOCKSErrorDomain: String

    Objective-C

    NSString * const NSStreamSocketSSLErrorDomain ; NSString * const NSStreamSOCKSErrorDomain ;

    Constants

    • NSStreamSocketSSLErrorDomain

      NSStreamSocketSSLErrorDomain

      The error domain used by NSError when reporting SSL errors.

      Available in OS X v10.3 and later.

    • NSStreamSOCKSErrorDomain

      NSStreamSOCKSErrorDomain

      The error domain used by NSError when reporting SOCKS errors.

      Available in OS X v10.3 and later.

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

    Declaration

    Swift

    let NSStreamSocketSecurityLevelNone: String let NSStreamSocketSecurityLevelSSLv2: String let NSStreamSocketSecurityLevelSSLv3: String let NSStreamSocketSecurityLevelTLSv1: String let NSStreamSocketSecurityLevelNegotiatedSSL: String

    Objective-C

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

    Constants

    • NSStreamSocketSecurityLevelNone

      NSStreamSocketSecurityLevelNone

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

      Available in OS X v10.3 and later.

    • NSStreamSocketSecurityLevelSSLv2

      NSStreamSocketSecurityLevelSSLv2

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

      Available in OS X v10.3 and later.

    • NSStreamSocketSecurityLevelSSLv3

      NSStreamSocketSecurityLevelSSLv3

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

      Available in OS X v10.3 and later.

    • NSStreamSocketSecurityLevelTLSv1

      NSStreamSocketSecurityLevelTLSv1

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

      Available in OS X v10.3 and later.

    • NSStreamSocketSecurityLevelNegotiatedSSL

      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.

    Discussion

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

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

    Declaration

    Swift

    let NSStreamSOCKSProxyHostKey: String let NSStreamSOCKSProxyPortKey: String let NSStreamSOCKSProxyVersionKey: String let NSStreamSOCKSProxyUserKey: String let NSStreamSOCKSProxyPasswordKey: String let NSStreamSOCKSProxyVersion4: String let NSStreamSOCKSProxyVersion5: String

    Objective-C

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

    Constants

    • NSStreamSOCKSProxyHostKey

      NSStreamSOCKSProxyHostKey

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

      Available in OS X v10.3 and later.

    • NSStreamSOCKSProxyPortKey

      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.

    • NSStreamSOCKSProxyVersionKey

      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.

    • NSStreamSOCKSProxyUserKey

      NSStreamSOCKSProxyUserKey

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

      Available in OS X v10.3 and later.

    • NSStreamSOCKSProxyPasswordKey

      NSStreamSOCKSProxyPasswordKey

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

      Available in OS X v10.3 and later.

    • NSStreamSOCKSProxyVersion4

      NSStreamSOCKSProxyVersion4

      Possible value for NSStreamSOCKSProxyVersionKey.

      Available in OS X v10.3 and later.

    • NSStreamSOCKSProxyVersion5

      NSStreamSOCKSProxyVersion5

      Possible value for NSStreamSOCKSProxyVersionKey.

      Available in OS X v10.3 and later.

    Discussion

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

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

    Declaration

    Swift

    let NSStreamNetworkServiceTypeVoIP: String let NSStreamNetworkServiceTypeVideo: String let NSStreamNetworkServiceTypeBackground: String let NSStreamNetworkServiceTypeVoice: String

    Objective-C

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

    Constants

    • NSStreamNetworkServiceTypeVoIP

      NSStreamNetworkServiceTypeVoIP

      Specifies that the stream is providing VoIP service.

      Available in OS X v10.7 and later.

    • NSStreamNetworkServiceTypeVideo

      NSStreamNetworkServiceTypeVideo

      Specifies that the stream is providing video service.

      Available in OS X v10.7 and later.

    • NSStreamNetworkServiceTypeBackground

      NSStreamNetworkServiceTypeBackground

      Specifies that the stream is providing a background service.

      Available in OS X v10.7 and later.

    • NSStreamNetworkServiceTypeVoice

      NSStreamNetworkServiceTypeVoice

      Specifies that the stream is providing voice service.

      Available in OS X v10.7 and later.