Mac Developer Library

Developer

Foundation Framework Reference NSInputStream Class Reference

Options
Deployment Target:

On This Page
Language:

NSInputStream

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:

  • 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 NOfalse if you cannot access data in the buffer; otherwise, return YEStrue. If this method is not appropriate for your type of stream, you may return NOfalse.

  • hasBytesAvailable

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

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in OS X v10.3 and later.
  • Creates and returns an initialized NSInputStream object for reading from a given NSData object.

    Declaration

    Objective-C

    + (instancetype)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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Objective-C

    + (instancetype)inputStreamWithFileAtPath:(NSString *)path

    Parameters

    path

    The path to the file.

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Objective-C

    + (instancetype)inputStreamWithURL:(NSURL *)url

    Parameters

    url

    The URL to the file.

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.6 and later.

  • init(data:) - initWithData: Designated Initializer

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

    Declaration

    Swift

    init(data data: NSData)

    Objective-C

    - (instancetype)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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    convenience init?(fileAtPath path: String)

    Objective-C

    - (instancetype)initWithFileAtPath:(NSString *)path

    Parameters

    path

    The path to the file.

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

  • init(URL:) - initWithURL: Designated Initializer

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

    Declaration

    Swift

    init?(URL url: NSURL)

    Objective-C

    - (instancetype)initWithURL:(NSURL *)url

    Parameters

    url

    The URL to the file.

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Swift

    func read(_ buffer: UnsafeMutablePointer<UInt8>, maxLength len: Int) -> Int

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

  • 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.

    Declaration

    Swift

    func getBuffer(_ buffer: UnsafeMutablePointer<UnsafeMutablePointer<UInt8>>, length len: UnsafeMutablePointer<Int>) -> Bool

    Objective-C

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

    YEStrue if the buffer is available, otherwise NOfalse.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

  • A Boolean value that indicates whether the receiver has bytes available to read. (read-only)

    Declaration

    Swift

    var hasBytesAvailable: Bool { get }

    Objective-C

    @property(readonly) BOOL hasBytesAvailable

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.