nsIOutputStream
Last changed in Gecko 1.7 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
.
Method overview
void asyncWait(in nsIOutputStreamCallback aCallback, in unsigned long aFlags, in unsigned long aRequestedCount, in nsIEventTarget aEventTarget); |
void closeWithStatus(in nsresult reason); |
Constants
Constant | Value | Description |
WAIT_CLOSURE_ONLY | (1<<0) | If passed to asyncWait() , this flag overrides the default behavior, causing the OnOutputStreamReady notification to be suppressed until the stream becomes closed (either as a result of closeWithStatus() /close being called on the stream or possibly due to some error in the underlying stream). |
Methods
asyncWait()
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 nsIOutputStreamCallback.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 nsIOutputStreamCallback.onOutputStreamReady()
event will be dispatched immediately. Otherwise, the event will be dispatched when the stream becomes writable or closed.
void asyncWait( in nsIOutputStreamCallback aCallback, in unsigned long aFlags, in unsigned long aRequestedCount, in nsIEventTarget aEventTarget );
Parameters
aCallback
- This object is notified when the stream becomes ready. This parameter may be
null
to clear an existing callback. aFlags
- This parameter specifies optional flags passed in to configure the behavior of this method. Pass zero to specify no flags.
aRequestedCount
- 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.
aEventTarget
- Specify
null
to receive notification on ANY thread (possibly even recursively on the calling thread, that is synchronously), or specify that the notification be delivered to a specific event target.
closeWithStatus()
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()
.
void closeWithStatus( in nsresult reason );
Parameters
reason
- The error that will be reported if this stream is accessed after it has been closed.