Public Member Functions

nsIInputStream Interface Reference

nsIInputStream More...

import "nsIInputStream.idl";

Inheritance diagram for nsIInputStream:

List of all members.

Public Member Functions

void close ()
 Close the stream.
unsigned long available ()
 Determine number of bytes available in the stream.
unsigned long read (in charPtr aBuf, in unsigned long aCount)
 Read data from the stream.
unsigned long readSegments (in nsWriteSegmentFun aWriter, in voidPtr aClosure, in unsigned long aCount)
 Low-level read method that provides access to the stream's underlying buffer.
boolean isNonBlocking ()

Detailed Description

nsIInputStream

An interface describing a readable stream of data. An input stream may be "blocking" or "non-blocking" (see the IsNonBlocking method). A blocking input stream may suspend the calling thread in order to satisfy a call to Close, Available, Read, or ReadSegments. A non-blocking input stream, on the other hand, must not block the calling thread of execution.

NOTE: blocking input streams are often read on a background thread to avoid locking up the main application thread. For this reason, it is generally the case that a blocking input stream should be implemented using thread- safe AddRef and Release.


Member Function Documentation

unsigned long nsIInputStream::available (  ) 

Determine number of bytes available in the stream.

A non-blocking stream that does not yet have any data to read should return 0 bytes from this method (i.e., it must not throw the NS_BASE_STREAM_WOULD_BLOCK exception).

In addition to the number of bytes available in the stream, this method also informs the caller of the current status of the stream. A stream that is closed will throw an exception when this method is called. That enables the caller to know the condition of the stream before attempting to read from it. If a stream is at end-of-file, but not closed, then this method returns 0 bytes available. (Note: some nsIInputStream implementations automatically close when eof is reached; some do not).

Returns:
number of bytes currently available in the stream, or PR_UINT32_MAX if the size of the stream exceeds PR_UINT32_MAX.
Exceptions:
NS_BASE_STREAM_CLOSED if the stream is closed normally.
<other-error> if the stream is closed due to some error condition
void nsIInputStream::close (  ) 

Close the stream.

This method causes subsequent calls to Read and ReadSegments to return 0 bytes read to indicate end-of-file. Any subsequent calls to Available should throw NS_BASE_STREAM_CLOSED.

boolean nsIInputStream::isNonBlocking (  ) 
Returns:
true if stream is non-blocking

NOTE: reading from a blocking input stream will block the calling thread until at least one byte of data can be extracted from the stream.

NOTE: a non-blocking input stream may implement nsIAsyncInputStream to provide consumers with a way to wait for the stream to have more data once its read method is unable to return any data without blocking.

unsigned long nsIInputStream::read ( in charPtr  aBuf,
in unsigned long  aCount 
)

Read data from the stream.

Parameters:
aBuf the buffer into which the data is to be read
aCount the maximum number of bytes to be read
Returns:
number of bytes read (may be less than aCount).
0 if reached end-of-file
Exceptions:
NS_BASE_STREAM_WOULD_BLOCK if reading from the input stream would block the calling thread (non-blocking mode only)
<other-error> on failure

NOTE: this method should not throw NS_BASE_STREAM_CLOSED.

unsigned long nsIInputStream::readSegments ( in nsWriteSegmentFun  aWriter,
in voidPtr  aClosure,
in unsigned long  aCount 
)

Low-level read method that provides access to the stream's underlying buffer.

The writer function may be called multiple times for segmented buffers. ReadSegments is expected to keep calling the writer until either there is nothing left to read or the writer returns an error. ReadSegments should not call the writer with zero bytes to consume.

Parameters:
aWriter the "consumer" of the data to be read
aClosure opaque parameter passed to writer
aCount the maximum number of bytes to be read
Returns:
number of bytes read (may be less than aCount)
0 if reached end-of-file (or if aWriter refused to consume data)
Exceptions:
NS_BASE_STREAM_WOULD_BLOCK if reading from the input stream would block the calling thread (non-blocking mode only)
NS_ERROR_NOT_IMPLEMENTED if the stream has no underlying buffer
<other-error> on failure

NOTE: this function may be unimplemented if a stream has no underlying buffer (e.g., socket input stream).

NOTE: this method should not throw NS_BASE_STREAM_CLOSED.


The documentation for this interface was generated from the following file: