NSOutputStream 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

The NSOutputStream class is a subclass of NSStream that provides write-only stream functionality.

NSOutputStream is “toll-free bridged” with its Core Foundation counterpart, CFWriteStreamRef. For more information on toll-free bridging, see “Toll-Free Bridging”.

Subclassing Notes

NSOutputStream is a concrete subclass of NSStream that lets you write data to a stream. Although NSOutputStream is probably sufficient for most situations requiring this capability, you can create a subclass of NSOutputStream if you want more specialized behavior (for example, you want to record statistics on the data in a stream).

Methods to Override

To create a subclass of NSOutputStream you may have to implement initializers for the type of stream data supported and suitably reimplement existing initializers. You must also provide complete implementations of the following methods:

Tasks

Creating Streams

Using Streams

Class Methods

outputStreamToBuffer:capacity:

Creates and returns an initialized output stream that can write to a provided buffer.

+ (id)outputStreamToBuffer:(uint8_t *)buffer capacity:(NSUInteger)capacity
Parameters
buffer

The buffer the output stream will write to.

capacity

The size of the buffer in bytes.

Return Value

An initialized output stream that can write to buffer.

Discussion

The stream must be opened before it can be used.

When the number of bytes written to buffer has reached capacity, the stream’s streamStatus will return NSStreamStatusAtEnd.

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

outputStreamToFileAtPath:append:

Creates and returns an initialized output stream for writing to a specified file.

+ (id)outputStreamToFileAtPath:(NSString *)path append:(BOOL)shouldAppend
Parameters
path

The path to the file the output stream will write to.

shouldAppend

YES if newly written data should be appended to any existing file contents, NO otherwise.

Return Value

An initialized output stream that can write to path.

Discussion

The stream must be opened before it can be used.

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

outputStreamToMemory

Creates and returns an initialized output stream that will write stream data to memory.

+ (id)outputStreamToMemory
Return Value

An initialized output stream that will write stream data to memory.

Discussion

The stream must be opened before it can be used.

You retrieve the contents of the memory stream by sending the message propertyForKey: to the receiver with an argument of NSStreamDataWrittenToMemoryStreamKey.

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

outputStreamWithURL:append:

Creates and returns an initialized output stream for writing to a specified URL.

+ (id)outputStreamWithURL:(NSURL *)url append:(BOOL)shouldAppend
Parameters
url

The URL to the file the output stream will write to.

shouldAppend

YES if newly written data should be appended to any existing file contents, NO otherwise.

Return Value

An initialized output stream that can write to url.

Discussion

The stream must be opened before it can be used.

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

Instance Methods

hasSpaceAvailable

Returns whether the receiver can be written to.

- (BOOL)hasSpaceAvailable
Return Value

YES if the receiver can be written to or if a write must be attempted in order to determine if space is available, NO otherwise.

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

initToBuffer:capacity:

Returns an initialized output stream that can write to a provided buffer.

- (id)initToBuffer:(uint8_t *)buffer capacity:(NSUInteger)capacity
Parameters
buffer

The buffer the output stream will write to.

capacity

The size of the buffer in bytes.

Return Value

An initialized output stream that can write to buffer.

Discussion

The stream must be opened before it can be used.

When the number of bytes written to buffer has reached capacity, the stream’s streamStatus will return NSStreamStatusAtEnd.

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

initToFileAtPath:append:

Returns an initialized output stream for writing to a specified file.

- (id)initToFileAtPath:(NSString *)path append:(BOOL)shouldAppend
Parameters
path

The path to the file the output stream will write to.

shouldAppend

YES if newly written data should be appended to any existing file contents, NO otherwise.

Return Value

An initialized output stream that can write to path.

Discussion

The stream must be opened before it can be used.

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

initToMemory

Returns an initialized output stream that will write to memory.

- (id)initToMemory
Return Value

An initialized output stream that will write stream data to memory.

Discussion

The stream must be opened before it can be used.

The contents of the memory stream are retrieved by passing the constant NSStreamDataWrittenToMemoryStreamKey to propertyForKey:.

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

initWithURL:append:

Returns an initialized output stream for writing to a specified URL.

- (id)initWithURL:(NSURL *)url append:(BOOL)shouldAppend
Parameters
url

The URL to the file the output stream will write to.

shouldAppend

YES if newly written data should be appended to any existing file contents, NO otherwise.

Return Value

An initialized output stream that can write to url.

Discussion

The stream must be opened before it can be used.

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

write:maxLength:

Writes the contents of a provided data buffer to the receiver.

- (NSInteger)write:(const uint8_t *)buffer maxLength:(NSUInteger)length
Parameters
buffer

The data to write.

length

The length of the data buffer, in bytes.

Return Value

The number of bytes actually written, or -1 if an error occurs. More information about the error can be obtained with streamError. If the receiver is a fixed-length stream and has reached its capacity, 0 is returned.

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