1/* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
4
5#include "nsIInputStream.idl"
6
7interface nsIInputStreamCallback;
8interface nsIEventTarget;
9
10/**
11 * If an input stream is non-blocking, it may return NS_BASE_STREAM_WOULD_BLOCK
12 * when read.  The caller must then wait for the stream to have some data to
13 * read.  If the stream implements nsIAsyncInputStream, then the caller can use
14 * this interface to request an asynchronous notification when the stream
15 * becomes readable or closed (via the AsyncWait method).
16 *
17 * While this interface is almost exclusively used with non-blocking streams, it
18 * is not necessary that nsIInputStream::isNonBlocking return true.  Nor is it
19 * necessary that a non-blocking nsIInputStream implementation also implement
20 * nsIAsyncInputStream.
21 */
22[scriptable, uuid(a5f255ab-4801-4161-8816-277ac92f6ad1)]
23interface nsIAsyncInputStream : nsIInputStream
24{
25    /**
26     * This method closes the stream and sets its internal status.  If the
27     * stream is already closed, then this method is ignored.  Once the stream
28     * is closed, the stream's status cannot be changed.  Any successful status
29     * code passed to this method is treated as NS_BASE_STREAM_CLOSED, which
30     * has an effect equivalent to nsIInputStream::close.
31     *
32     * NOTE: this method exists in part to support pipes, which have both an
33     * input end and an output end.  If the input end of a pipe is closed, then
34     * writes to the output end of the pipe will fail.  The error code returned
35     * when an attempt is made to write to a "broken" pipe corresponds to the
36     * status code passed in when the input end of the pipe was closed, which
37     * greatly simplifies working with pipes in some cases.
38     *
39     * @param aStatus
40     *        The error that will be reported if this stream is accessed after
41     *        it has been closed.
42     */
43    void closeWithStatus(in nsresult aStatus);
44
45    /**
46     * Asynchronously wait for the stream to be readable or closed.  The
47     * notification is one-shot, meaning that each asyncWait call will result
48     * in exactly one notification callback.  After the OnInputStreamReady event
49     * is dispatched, the stream releases its reference to the
50     * nsIInputStreamCallback object.  It is safe to call asyncWait again from the
51     * notification handler.
52     *
53     * This method may be called at any time (even if read has not been called).
54     * In other words, this method may be called when the stream already has
55     * data to read.  It may also be called when the stream is closed.  If the
56     * stream is already readable or closed when AsyncWait is called, then the
57     * OnInputStreamReady event will be dispatched immediately.  Otherwise, the
58     * event will be dispatched when the stream becomes readable or closed.
59     *
60     * @param aCallback
61     *        This object is notified when the stream becomes ready.  This
62     *        parameter may be null to clear an existing callback.
63     * @param aFlags
64     *        This parameter specifies optional flags passed in to configure
65     *        the behavior of this method.  Pass zero to specify no flags.
66     * @param aRequestedCount
67     *        Wait until at least this many bytes can be read.  This is only
68     *        a suggestion to the underlying stream; it may be ignored.  The
69     *        caller may pass zero to indicate no preference.
70     * @param aEventTarget
71     *        Specify NULL to receive notification on ANY thread (possibly even
72     *        recursively on the calling thread -- i.e., synchronously), or
73     *        specify that the notification be delivered to a specific event
74     *        target.
75     */
76    void asyncWait(in nsIInputStreamCallback aCallback,
77                   in unsigned long aFlags,
78                   in unsigned long aRequestedCount,
79                   in nsIEventTarget aEventTarget);
80
81    /**
82     * If passed to asyncWait, this flag overrides the default behavior,
83     * causing the OnInputStreamReady notification to be suppressed until the
84     * stream becomes closed (either as a result of closeWithStatus/close being
85     * called on the stream or possibly due to some error in the underlying
86     * stream).
87     */
88    const unsigned long WAIT_CLOSURE_ONLY = (1<<0);
89};
90
91/**
92 * This is a companion interface for nsIAsyncInputStream::asyncWait.
93 */
94[function, scriptable, uuid(d1f28e94-3a6e-4050-a5f5-2e81b1fc2a43)]
95interface nsIInputStreamCallback : nsISupports
96{
97    /**
98     * Called to indicate that the stream is either readable or closed.
99     *
100     * @param aStream
101     *        The stream whose asyncWait method was called.
102     */
103    void onInputStreamReady(in nsIAsyncInputStream aStream);
104};
105