NSOutputStream Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/Foundation.framework |
| Availability | Available in iOS 2.0 and later. |
| Companion guide | |
| Declared in | NSStream.h |
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:
From the current write pointer, take up to the number of bytes specified in the
maxLength:parameter from the client-supplied buffer (first parameter) and put them onto the stream. The buffer must be of the size specified by the second parameter. To prepare for the next operation, offset the write pointer by the number of bytes written. Return a signed integer based on the outcome of the current operation:If the write operation is successful, return the actual number of bytes put onto the stream.
If there was an error writing to the stream, return -1.
If the stream is of a fixed length and has reached its capacity, return zero.
Return
YESif the stream can currently accept more data,NOif it cannot. If you want to be semantically compatible withNSOutputStream, returnYESif a write must be attempted to determine if space is available.
Tasks
Creating Streams
-
+ outputStreamToMemory -
+ outputStreamToBuffer:capacity: -
+ outputStreamToFileAtPath:append: -
+ outputStreamWithURL:append: -
– initToMemory -
– initToBuffer:capacity: -
– initToFileAtPath:append: -
– initWithURL:append:
Using Streams
Class Methods
outputStreamToBuffer:capacity:
Creates and returns an initialized output stream that can write to a provided buffer.
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 iOS 2.0 and later.
Declared In
NSStream.houtputStreamToFileAtPath:append:
Creates and returns an initialized output stream for writing to a specified file.
Parameters
- path
The path to the file the output stream will write to.
- shouldAppend
YESif newly written data should be appended to any existing file contents,NOotherwise.
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 iOS 2.0 and later.
See Also
Declared In
NSStream.houtputStreamToMemory
Creates and returns an initialized output stream that will write stream data to memory.
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 iOS 2.0 and later.
Declared In
NSStream.houtputStreamWithURL:append:
Creates and returns an initialized output stream for writing to a specified URL.
Parameters
- url
The URL to the file the output stream will write to.
- shouldAppend
YESif newly written data should be appended to any existing file contents,NOotherwise.
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 iOS 4.0 and later.
Declared In
NSStream.hInstance Methods
hasSpaceAvailable
Returns whether the receiver can be written to.
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 iOS 2.0 and later.
Declared In
NSStream.hinitToBuffer:capacity:
Returns an initialized output stream that can write to a provided buffer.
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 iOS 2.0 and later.
Declared In
NSStream.hinitToFileAtPath:append:
Returns an initialized output stream for writing to a specified file.
Parameters
- path
The path to the file the output stream will write to.
- shouldAppend
YESif newly written data should be appended to any existing file contents,NOotherwise.
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 iOS 2.0 and later.
See Also
Declared In
NSStream.hinitToMemory
Returns an initialized output stream that will write to memory.
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 iOS 2.0 and later.
Declared In
NSStream.hinitWithURL:append:
Returns an initialized output stream for writing to a specified URL.
Parameters
- url
The URL to the file the output stream will write to.
- shouldAppend
YESif newly written data should be appended to any existing file contents,NOotherwise.
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 iOS 4.0 and later.
See Also
Declared In
NSStream.hwrite:maxLength:
Writes the contents of a provided data buffer to the receiver.
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 iOS 2.0 and later.
Declared In
NSStream.h© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-09-01)