1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/xpcom/io/nsIAsyncInputStream.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,104 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +#include "nsIInputStream.idl"
1.9 +
1.10 +interface nsIInputStreamCallback;
1.11 +interface nsIEventTarget;
1.12 +
1.13 +/**
1.14 + * If an input stream is non-blocking, it may return NS_BASE_STREAM_WOULD_BLOCK
1.15 + * when read. The caller must then wait for the stream to have some data to
1.16 + * read. If the stream implements nsIAsyncInputStream, then the caller can use
1.17 + * this interface to request an asynchronous notification when the stream
1.18 + * becomes readable or closed (via the AsyncWait method).
1.19 + *
1.20 + * While this interface is almost exclusively used with non-blocking streams, it
1.21 + * is not necessary that nsIInputStream::isNonBlocking return true. Nor is it
1.22 + * necessary that a non-blocking nsIInputStream implementation also implement
1.23 + * nsIAsyncInputStream.
1.24 + */
1.25 +[scriptable, uuid(a5f255ab-4801-4161-8816-277ac92f6ad1)]
1.26 +interface nsIAsyncInputStream : nsIInputStream
1.27 +{
1.28 + /**
1.29 + * This method closes the stream and sets its internal status. If the
1.30 + * stream is already closed, then this method is ignored. Once the stream
1.31 + * is closed, the stream's status cannot be changed. Any successful status
1.32 + * code passed to this method is treated as NS_BASE_STREAM_CLOSED, which
1.33 + * has an effect equivalent to nsIInputStream::close.
1.34 + *
1.35 + * NOTE: this method exists in part to support pipes, which have both an
1.36 + * input end and an output end. If the input end of a pipe is closed, then
1.37 + * writes to the output end of the pipe will fail. The error code returned
1.38 + * when an attempt is made to write to a "broken" pipe corresponds to the
1.39 + * status code passed in when the input end of the pipe was closed, which
1.40 + * greatly simplifies working with pipes in some cases.
1.41 + *
1.42 + * @param aStatus
1.43 + * The error that will be reported if this stream is accessed after
1.44 + * it has been closed.
1.45 + */
1.46 + void closeWithStatus(in nsresult aStatus);
1.47 +
1.48 + /**
1.49 + * Asynchronously wait for the stream to be readable or closed. The
1.50 + * notification is one-shot, meaning that each asyncWait call will result
1.51 + * in exactly one notification callback. After the OnInputStreamReady event
1.52 + * is dispatched, the stream releases its reference to the
1.53 + * nsIInputStreamCallback object. It is safe to call asyncWait again from the
1.54 + * notification handler.
1.55 + *
1.56 + * This method may be called at any time (even if read has not been called).
1.57 + * In other words, this method may be called when the stream already has
1.58 + * data to read. It may also be called when the stream is closed. If the
1.59 + * stream is already readable or closed when AsyncWait is called, then the
1.60 + * OnInputStreamReady event will be dispatched immediately. Otherwise, the
1.61 + * event will be dispatched when the stream becomes readable or closed.
1.62 + *
1.63 + * @param aCallback
1.64 + * This object is notified when the stream becomes ready. This
1.65 + * parameter may be null to clear an existing callback.
1.66 + * @param aFlags
1.67 + * This parameter specifies optional flags passed in to configure
1.68 + * the behavior of this method. Pass zero to specify no flags.
1.69 + * @param aRequestedCount
1.70 + * Wait until at least this many bytes can be read. This is only
1.71 + * a suggestion to the underlying stream; it may be ignored. The
1.72 + * caller may pass zero to indicate no preference.
1.73 + * @param aEventTarget
1.74 + * Specify NULL to receive notification on ANY thread (possibly even
1.75 + * recursively on the calling thread -- i.e., synchronously), or
1.76 + * specify that the notification be delivered to a specific event
1.77 + * target.
1.78 + */
1.79 + void asyncWait(in nsIInputStreamCallback aCallback,
1.80 + in unsigned long aFlags,
1.81 + in unsigned long aRequestedCount,
1.82 + in nsIEventTarget aEventTarget);
1.83 +
1.84 + /**
1.85 + * If passed to asyncWait, this flag overrides the default behavior,
1.86 + * causing the OnInputStreamReady notification to be suppressed until the
1.87 + * stream becomes closed (either as a result of closeWithStatus/close being
1.88 + * called on the stream or possibly due to some error in the underlying
1.89 + * stream).
1.90 + */
1.91 + const unsigned long WAIT_CLOSURE_ONLY = (1<<0);
1.92 +};
1.93 +
1.94 +/**
1.95 + * This is a companion interface for nsIAsyncInputStream::asyncWait.
1.96 + */
1.97 +[function, scriptable, uuid(d1f28e94-3a6e-4050-a5f5-2e81b1fc2a43)]
1.98 +interface nsIInputStreamCallback : nsISupports
1.99 +{
1.100 + /**
1.101 + * Called to indicate that the stream is either readable or closed.
1.102 + *
1.103 + * @param aStream
1.104 + * The stream whose asyncWait method was called.
1.105 + */
1.106 + void onInputStreamReady(in nsIAsyncInputStream aStream);
1.107 +};
