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 #define NS_ITEXTTOSUBURI_CONTRACTID "@mozilla.org/intl/texttosuburi;1"
  11 %}
  12
  13 [scriptable, uuid(8B042E24-6F87-11d3-B3C8-00805F8A6670)]
  14 interface nsITextToSubURI : nsISupports
  15 {
  16   ACString ConvertAndEscape(in ACString charset, in AString text);
  17   AString UnEscapeAndConvert(in ACString charset, in ACString text);
  18
  19   /**
  20    * Unescapes the given URI fragment (for UI purpose only)
  21    * Note:
  22    * <ul>
  23    *  <li> escaping back the result (unescaped string) is not guaranteed to
  24    *       give the original escaped string
  25    *  <li> The URI fragment (escaped) is assumed to be in UTF-8 and converted
  26    *       to AString (UTF-16)
  27    *  <li> In case of successful conversion any resulting character listed
  28    *       in netwerk/dns/IDNCharacterBlocklist.inc (except space) is escaped
  29    *  <li> Always succeeeds (callers don't need to do error checking)
  30    * </ul>
  31    *
  32    * @param aURIFragment the URI (or URI fragment) to unescape
  33    * @param aDontEscape whether to escape IDN blocklisted characters
  34    * @return Unescaped aURIFragment  converted to unicode
  35    */
  36   AString unEscapeURIForUI(in AUTF8String aURIFragment,
  37                            [optional] in boolean aDontEscape);
  38 %{C++
  39   nsresult UnEscapeURIForUI(const nsACString& aURIFragment,
  40                             nsAString& _retval) {
  41     return UnEscapeURIForUI(aURIFragment, false, _retval);
  42   }
  43 %}
  44
  45   /**
  46    * Unescapes only non ASCII characters in the given URI fragment
  47    * note: this method assumes the URI as UTF-8 and fallbacks to the given
  48    * charset if the charset is an ASCII superset
  49    *
  50    * @param aCharset the charset to convert from
  51    * @param aURIFragment the URI (or URI fragment) to unescape
  52    * @return Unescaped aURIFragment  converted to unicode
  53    * @throws NS_ERROR_UCONV_NOCONV when there is no decoder for aCharset
  54    *         or NS_ERROR_UDEC_ILLEGALINPUT in case of conversion failure
  55    */
  56   [binaryname(UnEscapeNonAsciiURIJS)]
  57   AString unEscapeNonAsciiURI(in ACString aCharset, in AUTF8String aURIFragment);
  58 };