PRUint32 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 should return 0 bytes available.

Returns:

number of bytes currently available in the stream, or PR_UINT32_MAX if the size of the stream exceeds PR_UINT32_MAX.

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

PRBool isNonBlocking ( )

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.

Returns:

true if stream is non-blocking

PRUint32 read ( charPtr* buf , PRUint32 count )

Read data from the stream.

NOTE: this method should not throw NS_BASE_STREAM_CLOSED.

Arguments:

buf: the buffer into which the data is to be read

count: the maximum number of bytes to be read

Returns:

0 if reached end-of-file

PRUint32 readSegments ( nsWriteSegmentFun writer , voidPtr* closure , PRUint32 count )

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.

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.

Arguments:

writer: the "consumer" of the data to be read

closure: opaque parameter passed to writer

count: the maximum number of bytes to be read

Returns:

0 if reached end-of-file (or if aWriter refused to consume data)