Inherits from | |
Conforms to | |
Framework | /System/Library/Frameworks/Foundation.framework |
Availability | Available in Mac OS X v10.3 and later. |
Companion guide | |
Declared in | NSStream.h |
Related sample code |
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.
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.
All subclasses must fully implement the following methods, which are presented in functional pairs:
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 "Delegates and Data Sources" 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.
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.
– open
– close
– stream:handleEvent:
delegate method
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
The host to which to connect.
The port to connect to on host.
Upon return, contains the input stream. If nil
is passed, the stream object is not created.
Upon return, contains the output stream. If nil
is passed, the stream object is not created.
If neither port nor host is properly specified, no socket connection is made.
NSStream.h
Closes the receiver.
- (void)close
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.
NSStream.h
Returns the receiver’s delegate.
- (id)delegate
The receiver’s delegate.
By default, a stream is its own delegate, and subclasses of NSInputStream
and NSOutputStream
must maintain this contract.
NSStream.h
Opens the receiving stream.
- (void)open
A stream must be created before it can be opened. Once opened, a stream cannot be closed and reopened.
NSStream.h
Returns the receiver’s property for a given key.
- (id)propertyForKey:(NSString *)key
The key for one of the receiver's properties. See “Constants” for a description of the available property-key constants and associated values.
The receiver’s property for the key key.
NSStream.h
Removes the receiver from a given run loop running in a given mode.
- (void)removeFromRunLoop:(NSRunLoop *)aRunLoop forMode:(NSString *)mode
The run loop on which the receiver was scheduled.
The mode for the run loop.
NSStream.h
Schedules the receiver on a given run loop in a given mode.
- (void)scheduleInRunLoop:(NSRunLoop *)aRunLoop forMode:(NSString *)mode
The run loop on which to schedule the receiver.
The mode for the run loop.
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.
NSStream.h
Sets the receiver’s delegate.
- (void)setDelegate:(id)delegate
The delegate for the receiver.
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 "Delegates and Data Sources" in Cocoa Fundamentals Guide.
NSStream.h
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
The value for key.
The key for one of the receiver's properties. See “Constants” for a description of the available property-key constants and expected values.
YES
if the value is accepted by the receiver, otherwise NO
.
NSStream.h
Returns an NSError
object representing the stream error.
- (NSError *)streamError
An NSError
object representing the stream error, or nil
if no error has been encountered.
NSStream.h
Returns the receiver’s status.
- (NSStreamStatus)streamStatus
The receiver’s status.
See “Constants” for a description of the available NSStreamStatus constants.
NSStream.h
The delegate receives this message when a given event has occurred on a given stream.
- (void)stream:(NSStream *)theStream handleEvent:(NSStreamEvent)streamEvent
The stream on which streamEvent occurred.
The stream event that occurred,
The delegate receives this message only if theStream is scheduled on a run loop. The message is sent on the stream object’s thread. The delegate should examine streamEvent to determine the appropriate action it should take.
NSStream.h
The type declared for the constants listed in “Stream Status Constants.”
typedef NSUInteger NSStreamStatus;
NSStream.h
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 };
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 Mac 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 Mac OS X v10.3 and later.
Declared in NSStream.h
.
NSStreamStatusOpen
The stream is open, but no reading or writing is occurring.
Available in Mac 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 Mac 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 Mac 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 Mac OS X v10.3 and later.
Declared in NSStream.h
.
NSStreamStatusClosed
The stream is closed (close
has been called on it).
Available in Mac 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 Mac OS X v10.3 and later.
Declared in NSStream.h
.
NSStream.h
The type declared for the constants listed in “Stream Event Constants.”
typedef NSUInteger NSStreamEvent;
NSStream.h
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 { NSStreamEventNone = 0, NSStreamEventOpenCompleted = 1 << 0, NSStreamEventHasBytesAvailable = 1 << 1, NSStreamEventHasSpaceAvailable = 1 << 2, NSStreamEventErrorOccurred = 1 << 3, NSStreamEventEndEncountered = 1 << 4 };
NSStreamEventNone
No event has occurred.
Available in Mac OS X v10.3 and later.
Declared in NSStream.h
.
NSStreamEventOpenCompleted
The open has completed successfully.
Available in Mac OS X v10.3 and later.
Declared in NSStream.h
.
NSStreamEventHasBytesAvailable
The stream has bytes to be read.
Available in Mac OS X v10.3 and later.
Declared in NSStream.h
.
NSStreamEventHasSpaceAvailable
The stream can accept bytes for writing.
Available in Mac OS X v10.3 and later.
Declared in NSStream.h
.
NSStreamEventErrorOccurred
An error has occurred on the stream.
Available in Mac OS X v10.3 and later.
Declared in NSStream.h
.
NSStreamEventEndEncountered
The end of the stream has been reached.
Available in Mac OS X v10.3 and later.
Declared in NSStream.h
.
NSStream.h
NSStream
defines these string constants as keys for accessing stream properties using propertyForKey:
and setting properties with setProperty:forKey:
:
extern NSString * const NSStreamSocketSecurityLevelKey ; extern NSString * const NSStreamSocketSecurityLevelNone ; extern NSString * const NSStreamSocketSecurityLevelSSLv2 ; extern NSString * const NSStreamSocketSecurityLevelSSLv3 ; extern NSString * const NSStreamSocketSecurityLevelTLSv1 ; extern NSString * const NSStreamSocketSecurityLevelNegotiatedSSL; extern NSString * const NSStreamSOCKSProxyConfigurationKey ; extern NSString * const NSStreamSOCKSProxyHostKey ; extern NSString * const NSStreamSOCKSProxyPortKey ; extern NSString * const NSStreamSOCKSProxyVersionKey ; extern NSString * const NSStreamSOCKSProxyUserKey ; extern NSString * const NSStreamSOCKSProxyPasswordKey ; extern NSString * const NSStreamSOCKSProxyVersion4 ; extern NSString * const NSStreamSOCKSProxyVersion5 ; extern NSString * const NSStreamDataWrittenToMemoryStreamKey ; extern NSString * const NSStreamFileCurrentOffsetKey ;
NSStreamSocketSecurityLevelKey
The security level of the target stream. May be one of the following values: NSStreamSocketSecurityLevelNone
, NSStreamSocketSecurityLevelSSLv2
, NSStreamSocketSecurityLevelSSLv3
, NSStreamSocketSecurityLevelTLSv1
, or NSStreamSocketSecurityLevelNegotiatedSSL
.
Available in Mac 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 Mac 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 Mac 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 Mac OS X v10.3 and later.
Declared in NSStream.h
.
NSStream.h
NSStream
defines these string constants to represent error domains that can be returned by streamError
:
extern NSString * const NSStreamSocketSSLErrorDomain ; extern NSString * const NSStreamSOCKSErrorDomain ;
NSStreamSocketSSLErrorDomain
The error domain used by NSError
when reporting SSL errors.
Available in Mac OS X v10.3 and later.
Declared in NSStream.h
.
NSStreamSOCKSErrorDomain
The error domain used by NSError
when reporting SOCKS errors.
Available in Mac OS X v10.3 and later.
Declared in NSStream.h
.
NSStream.h
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
NSStreamSocketSecurityLevelNone
Specifies that no security level be set for a socket stream.
Available in Mac 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 Mac 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 Mac 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 Mac 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 Mac OS X v10.3 and later.
Declared in NSStream.h
.
You access and set these values using the NSStreamSocketSecurityLevelKey
property key.
NSStream.h
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
NSStreamSOCKSProxyHostKey
Value is an NSString
object that represents the SOCKS proxy host.
Available in Mac 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 Mac 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 Mac OS X v10.3 and later.
Declared in NSStream.h
.
NSStreamSOCKSProxyUserKey
Value is an NSString
object containing the user’s name.
Available in Mac OS X v10.3 and later.
Declared in NSStream.h
.
NSStreamSOCKSProxyPasswordKey
Value is an NSString
object containing the user’s password.
Available in Mac OS X v10.3 and later.
Declared in NSStream.h
.
NSStreamSOCKSProxyVersion4
Possible value for NSStreamSOCKSProxyVersionKey
.
Available in Mac OS X v10.3 and later.
Declared in NSStream.h
.
NSStreamSOCKSProxyVersion5
Possible value for NSStreamSOCKSProxyVersionKey
.
Available in Mac OS X v10.3 and later.
Declared in NSStream.h
.
You set the dictionary object as the current SOCKS proxy configuration using the NSStreamSOCKSProxyConfigurationKey
key
NSStream.h
© 2008 Apple Inc. All Rights Reserved. (Last updated: 2008-10-15)