xpcom/io/nsIInputStreamLength.idl

   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 "nsISupports.idl"
   6
   7 interface nsIEventTarget;
   8 interface nsIInputStreamLengthCallback;
   9
  10 /**
  11  * Note: Instead of using these interfaces directly, consider to use
  12  * InputStreamLengthHelper class.
  13  */
  14
  15 [uuid(452d059f-9a9c-4434-8839-e10d1405647c)]
  16 interface nsIInputStreamLength : nsISupports
  17 {
  18   /**
  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.
  24    *
  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().
  28    *
  29    * If the stream has already been read (read()/readSegments()/close()/seek()
  30    * methods has been called), length() returns NS_ERROR_NOT_AVAILABLE.
  31    *
  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.
  35    */
  36   long long length();
  37 };
  38
  39 [uuid(b63f9ecf-4668-44a3-93bd-72dbc65a6125)]
  40 interface nsIAsyncInputStreamLength : nsISupports
  41 {
  42   /**
  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
  45    * know its length.
  46    *
  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
  51    * asynchronously.
  52    *
  53    * If the stream has already been read (read()/readSegments()/close()/seek()
  54    * methods has been called), length() returns NS_ERROR_NOT_AVAILABLE.
  55    *
  56    * @param aCallback
  57    *        This object is notified when the length becomes known. This
  58    *        parameter may be null to clear an existing callback.
  59    * @param aEventTarget
  60    *        Specify that the notification must be delivered to a specific event
  61    *        target.
  62    */
  63   void asyncLengthWait(in nsIInputStreamLengthCallback aCallback,
  64                       in nsIEventTarget aEventTarget);
  65 };
  66
  67 /**
  68  * This is a companion interface for
  69  * nsIAsyncInputStreamLength::asyncLengthWait.
  70  */
  71 [function, uuid(9c0c13b9-1b33-445d-8adb-a8a7866a6c06)]
  72 interface nsIInputStreamLengthCallback : nsISupports
  73 {
  74   /**
  75    * Called to inform what the total length of the stream is.
  76    *
  77    * @param aStream
  78    *        The stream whose asyncLengthWait method was called.
  79    * @param aLength
  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.
  82    */
  83   void onInputStreamLengthReady(in nsIAsyncInputStreamLength aStream,
  84                                 in long long aLength);
  85 };