---

NSInputStream Class Reference

Overview

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

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 reimplement existing initializers. You must also provide complete implementations of the following methods:

• read:maxLength:

  From the current read index, take up to the number of bytes specified in the second parameter from the stream and place them in the client-supplied buffer (first parameter). The buffer must be of the size specified by the second parameter. Return the actual number of bytes placed in the buffer; if there is nothing left in the stream, return 0. Reset the index into the stream for the next read operation.

• getBuffer:length:

  Return in 0(1) a pointer to the subclass-allocated buffer (first parameter). Return by reference in the second parameter the number of bytes actually put into the buffer. The buffer’s contents are valid only until the next stream operation. Return NO if you cannot access data in the buffer; otherwise, return YES. If this method is not appropriate for your type of stream, you may return NO.

• hasBytesAvailable

  Return YES if there is more data to read in the stream, NO if there is not. If you want to be semantically compatible with NSInputStream, return YES if a read must be attempted to determine if bytes are available.

Tasks

Creating Streams

• + inputStreamWithData:
• + inputStreamWithFileAtPath:
• – initWithData:
• – initWithFileAtPath:

Using Streams

• – read:maxLength:
• – getBuffer:length:
• – hasBytesAvailable

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 Mac OS X v10.3 and later.

See Also

• + inputStreamWithFileAtPath:
• – initWithData:

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. If the file specified by path doesn’t exist or is unreadable, returns nil.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• + inputStreamWithData:
• – initWithFileAtPath:

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 Mac OS X v10.3 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 Mac OS X v10.3 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 Mac OS X v10.3 and later.

See Also

• – initWithFileAtPath:
• + inputStreamWithData:

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. If the file specified by path doesn’t exist or is unreadable, returns nil.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – initWithData:
• + inputStreamWithFileAtPath:

Declared In

NSStream.h

read:maxLength:

Reads up to a given number of bytes into a given buffer, and returns the actual number of bytes read.

- (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

The actual number of bytes read.

Availability

• Available in Mac OS X v10.3 and later.

Related Sample Code

• CocoaEcho
• CocoaHTTPServer
• CocoaSOAP

Declared In

NSStream.h

---