NSInputStream 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
Related sample code

Overview

NSInputStream is a subclass of NSStream that provides read-only stream functionality.

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

Subclassing Notes

NSInputStream is a concrete subclass of NSStream that gives you standard read-only access to stream data. Although NSInputStream is probably sufficient for most situations requiring access to stream data, you can create a subclass of NSInputStream 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 NSInputStream you may have to implement initializers for the type of stream data supported and suitably re-implement existing initializers. You must also provide complete implementations of the following methods:

Tasks

Creating Streams

Using Streams

Class Methods

inputStreamWithData:

Creates and returns an initialized NSInputStream object for reading from a given NSData object.

+ (id)inputStreamWithData:(NSData *)data
Parameters
data

The data object from which to read. The contents of data are copied.

Return Value

An initialized NSInputStream object for reading from data. If data is not an NSData object, this method returns nil.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSStream.h

inputStreamWithFileAtPath:

Creates and returns an initialized NSInputStream object that reads data from the file at a given path.

+ (id)inputStreamWithFileAtPath:(NSString *)path
Parameters
path

The path to the file.

Return Value

An initialized NSInputStream object that reads data from the file at path.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSStream.h

inputStreamWithURL:

Creates and returns an initialized NSInputStream object that reads data from the file at a given URL.

+ (id)inputStreamWithURL:(NSURL *)url
Parameters
url

The URL to the file.

Return Value

An initialized NSInputStream object that reads data from the URL at url.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSStream.h

Instance Methods

getBuffer:length:

Returns by reference a pointer to a read buffer and, by reference, the number of bytes available, and returns a Boolean value that indicates whether the buffer is available.

- (BOOL)getBuffer:(uint8_t **)buffer length:(NSUInteger *)len
Parameters
buffer

Upon return, contains a pointer to a read buffer. The buffer is only valid until the next stream operation is performed.

len

Upon return, contains the number of bytes available.

Return Value

YES if the buffer is available, otherwise NO.

Subclasses of NSInputStream may return NO if this operation is not appropriate for the stream type.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSStream.h

hasBytesAvailable

Returns a Boolean value that indicates whether the receiver has bytes available to read.

- (BOOL)hasBytesAvailable
Return Value

YES if the receiver has bytes available to read, otherwise NO. May also return YES if a read must be attempted in order to determine the availability of bytes.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSStream.h

initWithData:

Initializes and returns an NSInputStream object for reading from a given NSData object.

- (id)initWithData:(NSData *)data
Parameters
data

The data object from which to read. The contents of data are copied.

Return Value

An initialized NSInputStream object for reading from data.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSStream.h

initWithFileAtPath:

Initializes and returns an NSInputStream object that reads data from the file at a given path.

- (id)initWithFileAtPath:(NSString *)path
Parameters
path

The path to the file.

Return Value

An initialized NSInputStream object that reads data from the file at path.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSStream.h

initWithURL:

Initializes and returns an NSInputStream object that reads data from the file at a given URL.

- (id)initWithURL:(NSURL *)url
Parameters
url

The URL to the file.

Return Value

An initialized NSInputStream object that reads data from the file at url.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSStream.h

read:maxLength:

Reads up to a given number of bytes into a given buffer.

- (NSInteger)read:(uint8_t *)buffer maxLength:(NSUInteger)len
Parameters
buffer

A data buffer. The buffer must be large enough to contain the number of bytes specified by len.

len

The maximum number of bytes to read.

Return Value

A number indicating the outcome of the operation:

  • A positive number indicates the number of bytes read;

  • 0 indicates that the end of the buffer was reached;

  • A negative number means that the operation failed.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSStream.h