intl/uconv/nsITextToSubURI.idl

   1 /* -*- Mode: C++; 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
   9 %{C++
  10 // {8B042E22-6F87-11d3-B3C8-00805F8A6670}
  11 #define NS_TEXTTOSUBURI_CID { 0x8b042e22, 0x6f87, 0x11d3, { 0xb3, 0xc8, 0x0, 0x80, 0x5f, 0x8a, 0x66, 0x70 } }
  12 #define NS_ITEXTTOSUBURI_CONTRACTID "@mozilla.org/intl/texttosuburi;1"
  13 %}
  14
  15 [scriptable, uuid(8B042E24-6F87-11d3-B3C8-00805F8A6670)]
  16 interface nsITextToSubURI : nsISupports
  17 {
  18         string ConvertAndEscape(in string charset, in wstring text);
  19         wstring UnEscapeAndConvert(in string charset, in string text);
  20
  21   /**
  22    * Unescapes the given URI fragment (for UI purpose only)
  23    * Note:
  24    * <ul>
  25    *  <li> escaping back the result (unescaped string) is not guaranteed to
  26    *       give the original escaped string
  27    *  <li> In case of a conversion error, the URI fragment (escaped) is
  28    *       assumed to be in UTF-8 and converted to AString (UTF-16)
  29    *  <li> In case of successful conversion any resulting character listed
  30    *       in network.IDN.blacklist_chars (except space) is escaped
  31    *  <li> Always succeeeds (callers don't need to do error checking)
  32    * </ul>
  33    *
  34    * @param aCharset the charset to convert from
  35    * @param aURIFragment the URI (or URI fragment) to unescape
  36    * @return Unescaped aURIFragment  converted to unicode
  37    */
  38   AString unEscapeURIForUI(in ACString aCharset, in AUTF8String aURIFragment);
  39
  40   /**
  41    * Unescapes only non ASCII characters in the given URI fragment
  42    * note: this method assumes the URI as UTF-8 and fallbacks to the given
  43    * charset if the charset is an ASCII superset
  44    *
  45    * @param aCharset the charset to convert from
  46    * @param aURIFragment the URI (or URI fragment) to unescape
  47    * @return Unescaped aURIFragment  converted to unicode
  48    * @throws NS_ERROR_UCONV_NOCONV when there is no decoder for aCharset
  49    *         or error code of nsIUnicodeDecoder in case of conversion failure
  50    */
  51   AString unEscapeNonAsciiURI(in ACString aCharset, in AUTF8String aURIFragment);
  52 };