tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

nsIIDNService.idl (3091B)

      1 /* This Source Code Form is subject to the terms of the Mozilla Public
      2 * License, v. 2.0. If a copy of the MPL was not distributed with this
      3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
      4 
      5 #include "nsISupports.idl"
      6 
      7 /**
      8 * IDN (Internationalized Domain Name) support. Provides facilities
      9 * for manipulating IDN hostnames according to UTS #46 as parametrized
     10 * by the WHATWG URL Standard.
     11 *
     12 * UTS #46: https://www.unicode.org/reports/tr46/
     13 *
     14 * URL Standard: https://url.spec.whatwg.org/
     15 */
     16 
     17 [scriptable, uuid(a592a60e-3621-4f19-a318-2bf233cfad3e)]
     18 interface nsIIDNService : nsISupports
     19 {
     20    /**
     21     * The UTS #46 ToASCII operation as parametrized by the WHATWG URL Standard
     22     *
     23     * Use this function to prepare a host name for network protocols.
     24     *
     25     * Do not try to optimize and avoid calling this function if you already
     26     * have ASCII. This function optimizes internally, and calling it is
     27     * required for correctness!
     28     *
     29     * The function is available to C++ callers as `NS_DomainToASCII`.
     30     *
     31     * Rust callers that don't happen to be using XPCOM strings are better
     32     * off using the `idna` crate directly.
     33     */
     34    ACString domainToASCII(in AUTF8String input);
     35 
     36    /**
     37     * Legacy variant of `domainToASCII` that allows allows any ASCII character that has a glyph.
     38     *
     39     * The function is available to C++ callers as `NS_DomainToASCIIAllowAnyGlyphfulASCII`.
     40     */
     41    ACString convertUTF8toACE(in AUTF8String input);
     42 
     43    /**
     44     * The UTS #46 ToUnicode operation as parametrized by the WHATWG URL Standard,
     45     * except potentially misleading labels are treated according to ToASCII instead.
     46     *
     47     * Use this function to prepare a host name for display to the user.
     48     *
     49     * The function is available to C++ callers as `NS_DomainToDisplay`.
     50     *
     51     * Rust callers that don't happen to be using XPCOM strings are better
     52     * off using the `idna` crate directly. (See `idna_glue` for what policy
     53     * closure to use.)
     54     */
     55    AUTF8String domainToDisplay(in AUTF8String input);
     56 
     57    /**
     58     * Legacy variant of `domainToDisplay` that allows allows any ASCII character that has a glyph.
     59     *
     60     * The function is available to C++ callers as `NS_DomainToDisplayAllowAnyGlyphfulASCII`.
     61     */
     62    AUTF8String convertToDisplayIDN(in AUTF8String input);
     63 
     64    /**
     65     * The UTS #46 ToUnicode operation as parametrized by the WHATWG URL Standard,
     66     * except allows any ASCII character that has a glyph.
     67     *
     68     * It's most likely INCORRECT to call this function, and `domainToDisplay`
     69     * should typically be called instead. Please avoid adding new callers, so
     70     * that this conversion could be removed entirely!
     71     *
     72     * There is no `domainToUnicode` to discourage new callers.
     73     *
     74     * The function is available to C++ callers as `NS_DomainToUnicodeAllowAnyGlyphfulASCII`.
     75     *
     76     * Rust callers that don't happen to be using XPCOM strings are better
     77     * off using the `idna` crate directly.
     78     */
     79    AUTF8String convertACEtoUTF8(in ACString input);
     80 };