1 files changed, 85 insertions, 0 deletions
diff --git a/xpcom/io/nsIInputStreamLength.idl b/xpcom/io/nsIInputStreamLength.idl
new file mode 100644
index 0000000000..f9f685704a
--- /dev/null
+++ b/xpcom/io/nsIInputStreamLength.idl
@@ -0,0 +1,85 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+#include "nsISupports.idl"
+
+interface nsIEventTarget;
+interface nsIInputStreamLengthCallback;
+
+/**
+ * Note: Instead of using these interfaces directly, consider to use
+ * InputStreamLengthHelper class.
+ */
+
+[uuid(452d059f-9a9c-4434-8839-e10d1405647c)]
+interface nsIInputStreamLength : nsISupports
+{
+  /**
+   * Returns the total length of the stream if known. Otherwise it returns -1.
+   * This is different than calling available() which returns the number of
+   * bytes ready to be read from the stream.
+   * -1 is a valid value for a stream that doesn't know its length. For
+   * instance, a pipe stream could return such value.
+   *
+   * It could throw NS_BASE_STREAM_WOULD_BLOCK if the inputStream is
+   * non-blocking. If this happens, you should use
+   * nsIAsyncInputStreamLength::asyncLengthWait().
+   *
+   * If the stream has already been read (read()/readSegments()/close()/seek()
+   * methods has been called), length() returns NS_ERROR_NOT_AVAILABLE.
+   *
+   * This is not an attribute because a stream can change its length. For
+   * instance, if the stream is a file inputStream and the underlying OS file
+   * changes, its length will change as well.
+   */
+  long long length();
+};
+
+[uuid(b63f9ecf-4668-44a3-93bd-72dbc65a6125)]
+interface nsIAsyncInputStreamLength : nsISupports
+{
+  /**
+   * If the stream is non-blocking, nsIInputStreamLength::length() can return
+   * NS_BASE_STREAM_WOULD_BLOCK. The caller must then wait for the stream to
+   * know its length.
+   *
+   * If the stream implements nsIAsyncInputStreamLength, then the caller can
+   * use this interface to request an asynchronous notification when the
+   * stream's length becomes known (via the AsyncLengthWait method).
+   * If the length is already known, the aCallback will be still called
+   * asynchronously.
+   *
+   * If the stream has already been read (read()/readSegments()/close()/seek()
+   * methods has been called), length() returns NS_ERROR_NOT_AVAILABLE.
+   *
+   * @param aCallback
+   *        This object is notified when the length becomes known. This
+   *        parameter may be null to clear an existing callback.
+   * @param aEventTarget
+   *        Specify that the notification must be delivered to a specific event
+   *        target.
+   */
+  void asyncLengthWait(in nsIInputStreamLengthCallback aCallback,
+                      in nsIEventTarget aEventTarget);
+};
+
+/**
+ * This is a companion interface for
+ * nsIAsyncInputStreamLength::asyncLengthWait.
+ */
+[function, uuid(9c0c13b9-1b33-445d-8adb-a8a7866a6c06)]
+interface nsIInputStreamLengthCallback : nsISupports
+{
+  /**
+   * Called to inform what the total length of the stream is.
+   *
+   * @param aStream
+   *        The stream whose asyncLengthWait method was called.
+   * @param aLength
+   *        The stream's length. It can be -1 if the stream doesn't know its
+   *        length. For instance, this can happen for a pipe inputStream.
+   */
+  void onInputStreamLengthReady(in nsIAsyncInputStreamLength aStream,
+                                in long long aLength);
+};