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.
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.
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).
@throws NS_BASE_STREAM_CLOSED if the stream is closed normally.
@throws
| number of bytes currently available in the stream. |
Read data from the stream.
@throws NS_BASE_STREAM_WOULD_BLOCK if reading from the input stream would
block the calling thread (non-blocking mode only)
@throws
NOTE: this method should not throw NS_BASE_STREAM_CLOSED.
| aBuf | the buffer into which the data is to be read |
| aCount | the maximum number of bytes to be read |
| 0 if reached end-of-file |
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.
@throws NS_BASE_STREAM_WOULD_BLOCK if reading from the input stream would
block the calling thread (non-blocking mode only)
@throws NS_ERROR_NOT_IMPLEMENTED if the stream has no underlying buffer
@throws
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.
| aWriter | the "consumer" of the data to be read |
| aClosure | opaque parameter passed to writer |
| aCount | the maximum number of bytes to be read |
| 0 if reached end-of-file (or if aWriter refused to consume data) |
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.
| true if stream is non-blocking |