nsIOutputStream
An interface describing a writable stream of data. An output stream may be
“blocking” or “non-blocking” (see the IsNonBlocking method). A blocking
output stream may suspend the calling thread in order to satisfy a call to
Close, Flush, Write, WriteFrom, or WriteSegments. A non-blocking output
stream, on the other hand, must not block the calling thread of execution.
NOTE: blocking output streams are often written to on a background thread to
avoid locking up the main application thread. For this reason, it is
generally the case that a blocking output stream should be implemented using
thread- safe AddRef and Release.
Close the stream. Forces the output stream to flush any buffered data.
@throws NS_BASE_STREAM_WOULD_BLOCK if unable to flush without blocking
the calling thread (non-blocking mode only)
Flush the stream.
@throws NS_BASE_STREAM_WOULD_BLOCK if unable to flush without blocking
the calling thread (non-blocking mode only)
Write data into the stream.
@throws NS_BASE_STREAM_WOULD_BLOCK if writing to the output stream would
block the calling thread (non-blocking mode only)
@throws
| aBuf | the buffer containing the data to be written |
| aCount | the maximum number of bytes to be written |
| number of bytes written (may be less than aCount) |
Writes data into the stream from an input stream.
@throws NS_BASE_STREAM_WOULD_BLOCK if writing to the output stream would
block the calling thread (non-blocking mode only). This failure
means no bytes were transferred.
@throws
NOTE: This method is defined by this interface in order to allow the
output stream to efficiently copy the data from the input stream into
its internal buffer (if any). If this method was provided as an external
facility, a separate char* buffer would need to be used in order to call
the output stream’s other Write method.
| aFromStream | the stream containing the data to be written |
| aCount | the maximum number of bytes to be written |
| number of bytes written (may be less than aCount) |
Low-level write method that has access to the stream’s underlying buffer.
The reader function may be called multiple times for segmented buffers.
WriteSegments is expected to keep calling the reader until either there
is nothing left to write or the reader returns an error. WriteSegments
should not call the reader with zero bytes to provide.
@throws NS_BASE_STREAM_WOULD_BLOCK if writing to the output stream would
block the calling thread (non-blocking mode only). This failure
means no bytes were transferred.
@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 output stream).
| aReader | the "provider" of the data to be written |
| aClosure | opaque parameter passed to reader |
| aCount | the maximum number of bytes to be written |
| number of bytes written (may be less than aCount) |
NOTE: writing to a blocking output stream will block the calling thread
until all given data can be consumed by the stream.
NOTE: a non-blocking output stream may implement nsIAsyncOutputStream to
provide consumers with a way to wait for the stream to accept more data
once its write method is unable to accept any data without blocking.
| true if stream is non-blocking |