Optional aInstancePtr: objectA run time mechanism for interface discovery.
NS_OK if the interface is supported by the associated instance, NS_NOINTERFACE if it is not.
aInstancePtr must not be null.
[in] A requested interface IID
[out] A pointer to an interface pointer to receive the result.
Asynchronously wait for the stream to be readable or closed. The notification is one-shot, meaning that each asyncWait call will result in exactly one notification callback. After the OnInputStreamReady event is dispatched, the stream releases its reference to the nsIInputStreamCallback object. It is safe to call asyncWait again from the notification handler.
This method may be called at any time (even if read has not been called). In other words, this method may be called when the stream already has data to read. It may also be called when the stream is closed and will NOT result in an error return, e.g., NS_BASE_STREAM_CLOSED. If the stream is already readable or closed when AsyncWait is called, then the OnInputStreamReady event will be dispatched immediately. Otherwise, the event will be dispatched when the stream becomes readable or closed.
This object is notified when the stream becomes ready. This parameter may be null to clear an existing callback.
This parameter specifies optional flags passed in to configure the behavior of this method. Pass zero to specify no flags.
Wait until at least this many bytes can be read. This is only a suggestion to the underlying stream; it may be ignored. The caller may pass zero to indicate no preference.
Specify NULL to receive notification on ANY thread (possibly even recursively on the calling thread -- i.e., synchronously), or specify that the notification be delivered to a specific event target.
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).
NOTE: Streams implementing nsIAsyncInputStream must automatically close when eof is reached, as otherwise it is impossible to distinguish between a stream waiting for more data and a stream at EOF using Available().
number of bytes currently available in the stream.
NS_BASE_STREAM_CLOSED if the stream is closed normally.
This method closes the stream and sets its internal status. If the stream is already closed, then this method is ignored. Once the stream is closed, the stream's status cannot be changed. Any successful status code passed to this method is treated as NS_BASE_STREAM_CLOSED, which has an effect equivalent to nsIInputStream::close.
NOTE: this method exists in part to support pipes, which have both an input end and an output end. If the input end of a pipe is closed, then writes to the output end of the pipe will fail. The error code returned when an attempt is made to write to a "broken" pipe corresponds to the status code passed in when the input end of the pipe was closed, which greatly simplifies working with pipes in some cases.
The error that will be reported if this stream is accessed after it has been closed.
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.
Read data from the stream.
number of bytes read (may be less than aCount).
0 if reached end-of-file
NS_BASE_STREAM_WOULD_BLOCK if reading from the input stream would block the calling thread (non-blocking mode only)
NOTE: this method should not throw NS_BASE_STREAM_CLOSED.
the buffer into which the data is to be read
the maximum number of bytes to be read
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.
number of bytes read (may be less than aCount)
0 if reached end-of-file (or if aWriter refused to consume data)
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
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 "consumer" of the data to be read
opaque parameter passed to writer
the maximum number of bytes to be read
Check 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.
This method will not throw NS_BASE_STREAM_WOULD_BLOCK, even if the stream is an non-blocking stream with no data. A non-blocking stream that does not yet have any data to read should return NS_OK.
NOTE: Unlike available, his method should not block the calling thread (e.g. to query the state of a file descriptor), even when called on a blocking stream.
NS_BASE_STREAM_CLOSED if the stream closed normally
Generated using TypeDoc
If an input stream is non-blocking, it may return NS_BASE_STREAM_WOULD_BLOCK when read. The caller must then wait for the stream to have some data to read. If the stream implements nsIAsyncInputStream, then the caller can use this interface to request an asynchronous notification when the stream becomes readable or closed (via the AsyncWait method).
While this interface is almost exclusively used with non-blocking streams, it is not necessary that nsIInputStream::isNonBlocking return true. Nor is it necessary that a non-blocking nsIInputStream implementation also implement nsIAsyncInputStream.