intl/uconv/nsIScriptableUConv.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 nsIInputStream;
   9
  10 %{C++
  11 // {0A698C44-3BFF-11d4-9649-00C0CA135B4E}
  12 #define NS_ISCRIPTABLEUNICODECONVERTER_CID { 0x0A698C44, 0x3BFF, 0x11d4, { 0x96, 0x49, 0x00, 0xC0, 0xCA, 0x13, 0x5B, 0x4E } }
  13 #define NS_ISCRIPTABLEUNICODECONVERTER_CONTRACTID "@mozilla.org/intl/scriptableunicodeconverter"
  14 %}
  15
  16 /**
  17  * In new code, please use the WebIDL TextDecoder and TextEncoder
  18  * instead. They represent bytes as Uint8Array (or as view to such
  19  * array), which is the current best practice for representing bytes
  20  * in JavaScript.
  21  *
  22  * This interface converts between UTF-16 in JavaScript strings
  23  * and bytes transported as the unsigned value of each byte
  24  * transported in a code unit of the same numeric value in
  25  * a JavaScript string.
  26  *
  27  * @created         8/Jun/2000
  28  * @author          Makoto Kato [m_kato@ga2.so-net.ne.jp]
  29  */
  30 [scriptable, uuid(f36ee324-5c1c-437f-ba10-2b4db7a18031)]
  31 interface nsIScriptableUnicodeConverter : nsISupports
  32 {
  33   /**
  34    * Converts the data from Unicode to one Charset.
  35    * Returns the converted string. After converting, Finish should be called
  36    * and its return value appended to this return value.
  37    */
  38   ACString ConvertFromUnicode(in AString aSrc);
  39
  40   /**
  41    * Returns the terminator string.
  42    * Should be called after ConvertFromUnicode() and appended to that
  43    * function's return value.
  44    */
  45   ACString Finish();
  46
  47   /**
  48    * Converts the data from one Charset to Unicode.
  49    */
  50   AString ConvertToUnicode(in ACString aSrc);
  51
  52   /**
  53    * Convert a unicode string to an array of bytes. Finish does not need to be
  54    * called.
  55    */
  56   void convertToByteArray(in AString aString,
  57                           [optional] out unsigned long aLen,
  58                           [array, size_is(aLen),retval] out octet aData);
  59
  60   /**
  61    * Converts a unicode string to an input stream. The bytes in the stream are
  62    * encoded according to the charset attribute.
  63    * The returned stream will be nonblocking.
  64    */
  65   nsIInputStream convertToInputStream(in AString aString);
  66
  67   /**
  68    * Current character set.
  69    *
  70    * @throw NS_ERROR_UCONV_NOCONV
  71    *        The requested charset is not supported.
  72    */
  73   attribute ACString charset;
  74
  75   /**
  76    * Meaningless
  77    */
  78   attribute boolean isInternal;
  79 };