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/. */
5 #include
"nsISupports.idl"
7 interface nsIEventTarget
;
8 interface nsIInputStreamLengthCallback
;
11 * Note: Instead of using these interfaces directly, consider to use
12 * InputStreamLengthHelper class.
15 [uuid(452d059f
-9a9c
-4434-8839-e10d1405647c
)]
16 interface nsIInputStreamLength
: nsISupports
19 * Returns the total length of the stream if known. Otherwise it returns -1.
20 * This is different than calling available() which returns the number of
21 * bytes ready to be read from the stream.
22 * -1 is a valid value for a stream that doesn't know its length. For
23 * instance, a pipe stream could return such value.
25 * It could throw NS_BASE_STREAM_WOULD_BLOCK if the inputStream is
26 * non-blocking. If this happens, you should use
27 * nsIAsyncInputStreamLength::asyncLengthWait().
29 * If the stream has already been read (read()/readSegments()/close()/seek()
30 * methods has been called), length() returns NS_ERROR_NOT_AVAILABLE.
32 * This is not an attribute because a stream can change its length. For
33 * instance, if the stream is a file inputStream and the underlying OS file
34 * changes, its length will change as well.
39 [uuid(b63f9ecf
-4668-44a3
-93bd
-72dbc65a6125
)]
40 interface nsIAsyncInputStreamLength
: nsISupports
43 * If the stream is non-blocking, nsIInputStreamLength::length() can return
44 * NS_BASE_STREAM_WOULD_BLOCK. The caller must then wait for the stream to
47 * If the stream implements nsIAsyncInputStreamLength, then the caller can
48 * use this interface to request an asynchronous notification when the
49 * stream's length becomes known (via the AsyncLengthWait method).
50 * If the length is already known, the aCallback will be still called
53 * If the stream has already been read (read()/readSegments()/close()/seek()
54 * methods has been called), length() returns NS_ERROR_NOT_AVAILABLE.
57 * This object is notified when the length becomes known. This
58 * parameter may be null to clear an existing callback.
60 * Specify that the notification must be delivered to a specific event
63 void asyncLengthWait
(in nsIInputStreamLengthCallback aCallback
,
64 in nsIEventTarget aEventTarget
);
68 * This is a companion interface for
69 * nsIAsyncInputStreamLength::asyncLengthWait.
71 [function
, uuid(9c0c13b9
-1b33
-445d
-8adb
-a8a7866a6c06
)]
72 interface nsIInputStreamLengthCallback
: nsISupports
75 * Called to inform what the total length of the stream is.
78 * The stream whose asyncLengthWait method was called.
80 * The stream's length. It can be -1 if the stream doesn't know its
81 * length. For instance, this can happen for a pipe inputStream.
83 void onInputStreamLengthReady
(in nsIAsyncInputStreamLength aStream
,
84 in long long aLength
);