/* 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);
};
