xpcom/io/nsIScriptableInputStream.idl

   1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 interface nsIInputStream;
   9
  10 /**
  11  * nsIScriptableInputStream provides scriptable access to an nsIInputStream
  12  * instance.
  13  */
  14 [scriptable, uuid(3fce9015-472a-4080-ac3e-cd875dbe361e)]
  15 interface nsIScriptableInputStream : nsISupports
  16 {
  17     /**
  18      * Closes the stream.
  19      */
  20     void close();
  21
  22     /**
  23      * Wrap the given nsIInputStream with this nsIScriptableInputStream.
  24      *
  25      * @param aInputStream parameter providing the stream to wrap
  26      */
  27     void init(in nsIInputStream aInputStream);
  28
  29     /**
  30      * Return the number of bytes currently available in the stream
  31      *
  32      * @return the number of bytes
  33      *
  34      * @throws NS_BASE_STREAM_CLOSED if called after the stream has been closed
  35      */
  36     unsigned long long available();
  37
  38     /**
  39      * Read data from the stream.
  40      *
  41      * WARNING: If the data contains a null byte, then this method will return
  42      * a truncated string.
  43      *
  44      * @param aCount the maximum number of bytes to read
  45      *
  46      * @return the data, which will be an empty string if the stream is at EOF.
  47      *
  48      * @throws NS_BASE_STREAM_CLOSED if called after the stream has been closed
  49      * @throws NS_ERROR_NOT_INITIALIZED if init was not called
  50      */
  51     string read(in unsigned long aCount);
  52
  53     /**
  54      * Read data from the stream, including NULL bytes.
  55      *
  56      * @param aCount the maximum number of bytes to read.
  57      *
  58      * @return the data from the stream, which will be an empty string if EOF
  59      *         has been reached.
  60      *
  61      * @throws NS_BASE_STREAM_WOULD_BLOCK if reading from the input stream
  62      *         would block the calling thread (non-blocking mode only).
  63      * @throws NS_ERROR_FAILURE if there are not enough bytes available to read
  64      *         aCount amount of data.
  65      */
  66     ACString readBytes(in unsigned long aCount);
  67 };