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 writable or closed. The notification is one-shot, meaning that each asyncWait call will result in exactly one notification callback. After the OnOutputStreamReady event is dispatched, the stream releases its reference to the nsIOutputStreamCallback object. It is safe to call asyncWait again from the notification handler.
This method may be called at any time (even if write has not been called). In other words, this method may be called when the stream already has room for more data. It may also be called when the stream is closed. If the stream is already writable or closed when AsyncWait is called, then the OnOutputStreamReady event will be dispatched immediately. Otherwise, the event will be dispatched when the stream becomes writable 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 written. 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.
Close the stream. Forces the output stream to flush any buffered data. Any subsequent calls to StreamStatus should throw NS_BASE_STREAM_CLOSED. Succeeds without effect if already closed.
NS_BASE_STREAM_WOULD_BLOCK if unable to flush without blocking the calling thread (non-blocking mode only)
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 is 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 output end of a pipe is closed, then reads from the input end of the pipe will fail. The error code returned when an attempt is made to read from a "closed" pipe corresponds to the status code passed in when the output end of the pipe is closed, which greatly simplifies working with pipes in some cases.
true if stream is non-blocking
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.
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 write into it.
This method will not throw NS_BASE_STREAM_WOULD_BLOCK, even if the stream is a non-blocking stream with no available space. A non-blocking stream which has not been closed, but has no available room should return NS_OK.
NOTE: This 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
Write data into the stream.
number of bytes written (may be less than aCount)
NS_BASE_STREAM_WOULD_BLOCK if writing to the output stream would block the calling thread (non-blocking mode only)
the buffer containing the data to be written
the maximum number of bytes to be written
Writes data into the stream from an input stream.
number of bytes written (may be less than aCount)
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.
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.
the stream containing the data to be written
the maximum number of bytes to be written
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.
number of bytes written (may be less than aCount)
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.
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 output stream).
the "provider" of the data to be written
opaque parameter passed to reader
the maximum number of bytes to be written
Generated using TypeDoc
If an output stream is non-blocking, it may return NS_BASE_STREAM_WOULD_BLOCK when written to. The caller must then wait for the stream to become writable. If the stream implements nsIAsyncOutputStream, then the caller can use this interface to request an asynchronous notification when the stream becomes writable or closed (via the AsyncWait method).
While this interface is almost exclusively used with non-blocking streams, it is not necessary that nsIOutputStream::isNonBlocking return true. Nor is it necessary that a non-blocking nsIOutputStream implementation also implement nsIAsyncOutputStream.