Mac Developer Library

Developer

Foundation Framework Reference NSStream Class Reference

Options
Deployment Target:

On This Page
Language:

NSStream

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

Conforms To


Import Statement


import Foundation @import Foundation;

Availability


Available in OS X v10.3 and later.
  • 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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    enum NSStreamStatus : UInt { 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.

    Import Statement

  • 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

    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: NSString! let NSStreamSOCKSProxyConfigurationKey: NSString! let NSStreamDataWrittenToMemoryStreamKey: NSString! let NSStreamFileCurrentOffsetKey: NSString! let NSStreamNetworkServiceType: NSString!

    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.

    Import Statement

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

    Declaration

    Swift

    let NSStreamSocketSSLErrorDomain: NSString! let NSStreamSOCKSErrorDomain: NSString!

    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.

    Import Statement

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

    Declaration

    Swift

    let NSStreamSocketSecurityLevelNone: NSString! let NSStreamSocketSecurityLevelSSLv2: NSString! let NSStreamSocketSecurityLevelSSLv3: NSString! let NSStreamSocketSecurityLevelTLSv1: NSString! let NSStreamSocketSecurityLevelNegotiatedSSL: NSString!

    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.

    Import Statement

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

    Declaration

    Swift

    let NSStreamSOCKSProxyHostKey: NSString! let NSStreamSOCKSProxyPortKey: NSString! let NSStreamSOCKSProxyVersionKey: NSString! let NSStreamSOCKSProxyUserKey: NSString! let NSStreamSOCKSProxyPasswordKey: NSString! let NSStreamSOCKSProxyVersion4: NSString! let NSStreamSOCKSProxyVersion5: NSString!

    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

    Import Statement

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

    Declaration

    Swift

    let NSStreamNetworkServiceTypeVoIP: NSString! let NSStreamNetworkServiceTypeVideo: NSString! let NSStreamNetworkServiceTypeBackground: NSString! let NSStreamNetworkServiceTypeVoice: NSString!

    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.

    Import Statement