xpcom/io/nsIUnicharInputStream.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   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 nsIUnicharInputStream;
   9 interface nsIInputStream;
  10
  11 %{C++
  12 /**
  13  * The signature of the writer function passed to ReadSegments. This
  14  * is the "consumer" of data that gets read from the stream's buffer.
  15  *
  16  * @param aInStream stream being read
  17  * @param aClosure opaque parameter passed to ReadSegments
  18  * @param aFromSegment pointer to memory owned by the input stream
  19  * @param aToOffset number of UTF-16 code units already read
  20  *                  (since ReadSegments was called)
  21  * @param aCount length of fromSegment
  22  * @param aWriteCount number of UTF-16 code units read
  23  *
  24  * Implementers should return the following:
  25  *
  26  * @throws <any-error> if not interested in consuming any data
  27  *
  28  * Errors are never passed to the caller of ReadSegments.
  29  *
  30  * NOTE: returning NS_OK and (*aWriteCount = 0) has undefined behavior.
  31  */
  32 typedef nsresult (*nsWriteUnicharSegmentFun)(nsIUnicharInputStream *aInStream,
  33                                              void *aClosure,
  34                                              const char16_t *aFromSegment,
  35                                              uint32_t aToOffset,
  36                                              uint32_t aCount,
  37                                              uint32_t *aWriteCount);
  38 %}
  39 native nsWriteUnicharSegmentFun(nsWriteUnicharSegmentFun);
  40
  41 /**
  42  * Abstract UTF-16 input stream
  43  * @see nsIInputStream
  44  */
  45 [scriptable, uuid(d5e3bd80-6723-4b92-b0c9-22f6162fd94f)]
  46 interface nsIUnicharInputStream : nsISupports {
  47   /**
  48    * Reads into a caller-provided array.
  49    *
  50    * @return The number of utf-16 code units that were successfully read.
  51    *         May be less than aCount, even if there is more data in the input
  52    *         stream. A return value of 0 means EOF.
  53    *
  54    * @note To read more than 2^32 code units, call this method multiple times.
  55    */
  56   [noscript] unsigned long read([array, size_is(aCount)] in char16_t aBuf,
  57                                 in unsigned long aCount);
  58
  59   /**
  60    * Low-level read method that has access to the stream's underlying buffer.
  61    * The writer function may be called multiple times for segmented buffers.
  62    * ReadSegments is expected to keep calling the writer until either there is
  63    * nothing left to read or the writer returns an error.  ReadSegments should
  64    * not call the writer with zero UTF-16 code units to consume.
  65    *
  66    * @param aWriter the "consumer" of the data to be read
  67    * @param aClosure opaque parameter passed to writer
  68    * @param aCount the maximum number of UTF-16 code units to be read
  69    *
  70    * @return number of UTF-16 code units read (may be less than aCount)
  71    * @return 0 if reached end of file (or if aWriter refused to consume data)
  72    *
  73    * @throws NS_BASE_STREAM_WOULD_BLOCK if reading from the input stream would
  74    *   block the calling thread (non-blocking mode only)
  75    * @throws <other-error> on failure
  76    *
  77    * NOTE: this function may be unimplemented if a stream has no underlying
  78    * buffer
  79    */
  80   [noscript] unsigned long readSegments(in nsWriteUnicharSegmentFun aWriter,
  81                                         in voidPtr aClosure,
  82                                         in unsigned long aCount);
  83
  84   /**
  85    * Read into a string object.
  86    *
  87    * @param aCount The number of UTF-16 code units that should be read
  88    * @return The number of UTF-16 code units that were read.
  89    */
  90   unsigned long readString(in unsigned long aCount, out AString aString);
  91
  92   /**
  93    * Close the stream and free associated resources. This also closes the
  94    * underlying stream, if any.
  95    */
  96   void close();
  97 };