intl/uconv/nsITextToSubURI.idl
author Carsten "Tomcat" Book <cbook@mozilla.com>
Wed, 28 Oct 2015 14:28:37 +0100
changeset 269997 929a872c1f15ef81d7730d366d95983b2e287602
parent 218171 be23ef5730dce08c3d636fc670a5bf85c56b3f3b
child 363728 e155fa765af299f0e8cfb42e0a1709e5b04928b9
permissions -rw-r--r--
Backed out changeset 2284c3e8c336 (bug 1215092)

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"


%{C++
// {8B042E22-6F87-11d3-B3C8-00805F8A6670}
#define NS_TEXTTOSUBURI_CID { 0x8b042e22, 0x6f87, 0x11d3, { 0xb3, 0xc8, 0x0, 0x80, 0x5f, 0x8a, 0x66, 0x70 } }
#define NS_ITEXTTOSUBURI_CONTRACTID "@mozilla.org/intl/texttosuburi;1"
%}

[scriptable, uuid(8B042E24-6F87-11d3-B3C8-00805F8A6670)]
interface nsITextToSubURI : nsISupports
{
	string ConvertAndEscape(in string charset, in wstring text);
	wstring UnEscapeAndConvert(in string charset, in string text);

  /**
   * Unescapes the given URI fragment (for UI purpose only)
   * Note: 
   * <ul>
   *  <li> escaping back the result (unescaped string) is not guaranteed to 
   *       give the original escaped string
   *  <li> In case of a conversion error, the URI fragment (escaped) is 
   *       assumed to be in UTF-8 and converted to AString (UTF-16)
   *  <li> In case of successful conversion any resulting character listed
   *       in network.IDN.blacklist_chars (except space) is escaped
   *  <li> Always succeeeds (callers don't need to do error checking)
   * </ul>
   *
   * @param aCharset the charset to convert from
   * @param aURIFragment the URI (or URI fragment) to unescape
   * @return Unescaped aURIFragment  converted to unicode
   */
  AString unEscapeURIForUI(in ACString aCharset, in AUTF8String aURIFragment);

  /**
   * Unescapes only non ASCII characters in the given URI fragment 
   * note: this method assumes the URI as UTF-8 and fallbacks to the given 
   * charset if the charset is an ASCII superset 
   *
   * @param aCharset the charset to convert from
   * @param aURIFragment the URI (or URI fragment) to unescape
   * @return Unescaped aURIFragment  converted to unicode
   * @throws NS_ERROR_UCONV_NOCONV when there is no decoder for aCharset
   *         or error code of nsIUnicodeDecoder in case of conversion failure
   */
  AString unEscapeNonAsciiURI(in ACString aCharset, in AUTF8String aURIFragment);
};