/* 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"

/**
 * IDN (Internationalized Domain Name) support. Provides facilities
 * for manipulating IDN hostnames according to UTS #46 as parametrized
 * by the WHATWG URL Standard.
 *
 * UTS #46: https://www.unicode.org/reports/tr46/
 *
 * URL Standard: https://url.spec.whatwg.org/
 */

[scriptable, uuid(a592a60e-3621-4f19-a318-2bf233cfad3e)]
interface nsIIDNService : nsISupports
{
    /**
     * The UTS #46 ToASCII operation as parametrized by the WHATWG URL Standard
     *
     * Use this function to prepare a host name for network protocols.
     *
     * Do not try to optimize and avoid calling this function if you already
     * have ASCII. This function optimizes internally, and calling it is
     * required for correctness!
     *
     * The function is available to C++ callers as `NS_DomainToASCII`.
     *
     * Rust callers that don't happen to be using XPCOM strings are better
     * off using the `idna` crate directly.
     */
    ACString domainToASCII(in AUTF8String input);

    /**
     * Legacy variant of `domainToASCII` that allows allows any ASCII character that has a glyph.
     *
     * The function is available to C++ callers as `NS_DomainToASCIIAllowAnyGlyphfulASCII`.
     */
    ACString convertUTF8toACE(in AUTF8String input);

    /**
     * The UTS #46 ToUnicode operation as parametrized by the WHATWG URL Standard,
     * except potentially misleading labels are treated according to ToASCII instead.
     *
     * Use this function to prepare a host name for display to the user.
     *
     * The function is available to C++ callers as `NS_DomainToDisplay`.
     *
     * Rust callers that don't happen to be using XPCOM strings are better
     * off using the `idna` crate directly. (See `idna_glue` for what policy
     * closure to use.)
     */
    AUTF8String domainToDisplay(in AUTF8String input);

    /**
     * Legacy variant of `domainToDisplay` that allows allows any ASCII character that has a glyph.
     *
     * The function is available to C++ callers as `NS_DomainToDisplayAllowAnyGlyphfulASCII`.
     */
    AUTF8String convertToDisplayIDN(in AUTF8String input);

    /**
     * The UTS #46 ToUnicode operation as parametrized by the WHATWG URL Standard,
     * except allows any ASCII character that has a glyph.
     *
     * It's most likely INCORRECT to call this function, and `domainToDisplay`
     * should typically be called instead. Please avoid adding new callers, so
     * that this conversion could be removed entirely!
     *
     * There is no `domainToUnicode` to discourage new callers.
     *
     * The function is available to C++ callers as `NS_DomainToUnicodeAllowAnyGlyphfulASCII`.
     *
     * Rust callers that don't happen to be using XPCOM strings are better
     * off using the `idna` crate directly.
     */
    AUTF8String convertACEtoUTF8(in ACString input);
};