netwerk/dns/nsIIDNService.idl

   1 /* ***** BEGIN LICENSE BLOCK *****
   2  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3  *
   4  * The contents of this file are subject to the Mozilla Public License Version
   5  * 1.1 (the "License"); you may not use this file except in compliance with
   6  * the License. You may obtain a copy of the License at
   7  * http://www.mozilla.org/MPL/
   8  *
   9  * Software distributed under the License is distributed on an "AS IS" basis,
  10  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11  * for the specific language governing rights and limitations under the
  12  * License.
  13  *
  14  * The Original Code is i-DNS.net International, Inc. code.
  15  *
  16  * The Initial Developer of the Original Code is
  17  * i-DNS.net International.
  18  * Portions created by the Initial Developer are Copyright (C) 2001
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s): bobj@netscape.com,
  22  *                 brendan@mozilla.org,
  23  *                 darin@netscape.com,
  24  *                 ftang@netscape.com,
  25  *                 gagan@netscape.com,
  26  *                 nhotta@netscape.com,
  27  *                 william.tan@i-dns.net
  28  *                 dwitte@stanford.edu
  29  *
  30  *
  31  * Alternatively, the contents of this file may be used under the terms of
  32  * either the GNU General Public License Version 2 or later (the "GPL"), or
  33  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  34  * in which case the provisions of the GPL or the LGPL are applicable instead
  35  * of those above. If you wish to allow use of your version of this file only
  36  * under the terms of either the GPL or the LGPL, and not to allow others to
  37  * use your version of this file under the terms of the MPL, indicate your
  38  * decision by deleting the provisions above and replace them with the notice
  39  * and other provisions required by the GPL or the LGPL. If you do not delete
  40  * the provisions above, a recipient may use your version of this file under
  41  * the terms of any one of the MPL, the GPL or the LGPL.
  42  *
  43  * ***** END LICENSE BLOCK ***** */
  44
  45 #include "nsISupports.idl"
  46
  47 /**
  48  * nsIIDNService interface.
  49  *
  50  * IDN (Internationalized Domain Name) support. Provides facilities
  51  * for manipulating IDN hostnames according to the specification set
  52  * forth by the IETF.
  53  *
  54  * IDN effort:
  55  * http://www.ietf.org/html.characters/idn-charter.html
  56  * http://www.i-dns.net
  57  *
  58  * IDNA specification:
  59  * http://search.ietf.org/internet-drafts/draft-ietf-idn-idna-06.txt
  60  */
  61
  62 [scriptable, uuid(a592a60e-3621-4f19-a318-2bf233cfad3e)]
  63 interface nsIIDNService : nsISupports
  64 {
  65     /**
  66      * Prepares the input hostname according to IDNA ToASCII operation,
  67      * the input hostname is assumed to be UTF8-encoded.
  68      */
  69     ACString convertUTF8toACE(in AUTF8String input);
  70
  71
  72     /**
  73      * This is the ToUnicode operation as specified in the IDNA proposal,
  74      * with an additional step to encode the result in UTF-8.
  75      * It takes an ACE-encoded hostname and performs ToUnicode to it, then
  76      * encodes the resulting string into UTF8.
  77      */
  78     AUTF8String convertACEtoUTF8(in ACString input);
  79
  80     /**
  81      * Checks if the input string is ACE encoded or not.
  82      */
  83     boolean isACE(in ACString input);
  84
  85     /**
  86      * Performs the unicode normalization needed for hostnames in IDN,
  87      * for callers that want early normalization.
  88      */
  89     AUTF8String normalize(in AUTF8String input);
  90
  91     /**
  92      * Normalizes and converts a host to UTF-8 if the host is in the IDN
  93      * whitelist, otherwise converts it to ACE. This is useful for display
  94      * purposes and to ensure an encoding consistent with nsIURI::GetHost().
  95      * If the result is ASCII or ACE encoded, |isASCII| will be true.
  96      */
  97     AUTF8String convertToDisplayIDN(in AUTF8String input, out boolean isASCII);
  98 };