nsIEffectiveTLDService.idl (10556B)
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* This Source Code Form is subject to the terms of the Mozilla Public 3 * License, v. 2.0. If a copy of the MPL was not distributed with this 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 5 6 #include "nsISupports.idl" 7 8 interface nsIURI; 9 10 [scriptable, uuid(68067eb5-ad8d-43cb-a043-1cc85ebe06e7)] 11 interface nsIEffectiveTLDService : nsISupports 12 { 13 /** 14 * Returns the public suffix of a URI. A public suffix is the highest-level domain 15 * under which individual domains may be registered; it may therefore contain one 16 * or more dots. For example, the public suffix for "www.bbc.co.uk" is "co.uk", 17 * because the .uk TLD does not allow the registration of domains at the 18 * second level ("bbc.uk" is forbidden). 19 * 20 * The public suffix will be returned encoded in ASCII/ACE and will be normalized 21 * according to RFC 3454, i.e. the same encoding returned by nsIURI::GetAsciiHost(). 22 * If consumers wish to compare the result of this method against the host from 23 * another nsIURI, the host should be obtained using nsIURI::GetAsciiHost(). 24 * In the case of nested URIs, the innermost URI will be used. 25 * 26 * @param aURI The URI to be analyzed 27 * 28 * @returns the public suffix 29 * 30 * @throws NS_ERROR_UNEXPECTED 31 * or other error returned by nsIIDNService::normalize when 32 * the hostname contains characters disallowed in URIs 33 * @throws NS_ERROR_HOST_IS_IP_ADDRESS 34 * if the host is a numeric IPv4 or IPv6 address (as determined by 35 * the success of a call to PR_StringToNetAddr()). 36 */ 37 ACString getPublicSuffix(in nsIURI aURI); 38 39 /** 40 * Similar to getPublicSuffix, but the suffix is validated against 41 * the Public Suffix List. If the suffix is unknown this will return 42 * an empty string. 43 * 44 * If you only need to know if the host ends in a valid suffix, and not the 45 * actual public suffix, consider the more performant hasKnownPublicSuffix() 46 * instead. 47 * 48 * @param aURI The URI to be analyzed 49 * @returns the public suffix if known, an empty string otherwise 50 * @see getPublicSuffixFromHost() 51 */ 52 ACString getKnownPublicSuffix(in nsIURI aURI); 53 54 /** 55 * Returns the base domain of a URI; that is, the public suffix with a given 56 * number of additional domain name parts. For example, the result of this method 57 * for "www.bbc.co.uk", depending on the value of aAdditionalParts parameter, will 58 * be: 59 * 60 * 0 (default) -> bbc.co.uk 61 * 1 -> www.bbc.co.uk 62 * 63 * Similarly, the public suffix for "www.developer.mozilla.org" is "org", and the base 64 * domain will be: 65 * 66 * 0 (default) -> mozilla.org 67 * 1 -> developer.mozilla.org 68 * 2 -> www.developer.mozilla.org 69 * 70 * The base domain will be returned encoded in ASCII/ACE and will be normalized 71 * according to RFC 3454, i.e. the same encoding returned by nsIURI::GetAsciiHost(). 72 * If consumers wish to compare the result of this method against the host from 73 * another nsIURI, the host should be obtained using nsIURI::GetAsciiHost(). 74 * In the case of nested URIs, the innermost URI will be used. 75 * 76 * @param aURI The URI to be analyzed 77 * @param aAdditionalParts Number of domain name parts to be 78 * returned in addition to the public suffix 79 * 80 * @returns the base domain (public suffix plus the requested number of additional parts) 81 * 82 * @throws NS_ERROR_UNEXPECTED 83 * or other error returned by nsIIDNService::normalize when 84 * the hostname contains characters disallowed in URIs 85 * @throws NS_ERROR_INSUFFICIENT_DOMAIN_LEVELS 86 * when there are insufficient subdomain levels in the hostname to satisfy the 87 * requested aAdditionalParts value. 88 * @throws NS_ERROR_HOST_IS_IP_ADDRESS 89 * if aHost is a numeric IPv4 or IPv6 address (as determined by 90 * the success of a call to PR_StringToNetAddr()). 91 * 92 * @see getPublicSuffix() 93 */ 94 ACString getBaseDomain(in nsIURI aURI, [optional] in uint32_t aAdditionalParts); 95 96 /** 97 * Get the Site without the scheme for the origin of aURI; e.g. for 98 * "https://www.bbc.co.uk/index.html", this would be "bbc.co.uk". 99 * This uses getBaseDomain() internally. This is appropriately permissive, 100 * and will return a schemeless site for aliased hostnames and IP addresses 101 * and will therefore not throw NS_ERROR_INSUFFICIENT_DOMAIN_LEVELS or 102 * NS_ERROR_HOST_IS_IP_ADDRESS, e.g. "http://localhost/index.html" will 103 * return "localhost" successfully, rather than throwing an error. 104 * 105 * @param aHostURI 106 * The URI to analyze. 107 * 108 * @return the Site. 109 * 110 * @throws NS_ERROR_UNEXPECTED 111 * or other error returned by nsIIDNService::normalize when 112 * the hostname contains characters disallowed in URIs 113 * 114 * @see getBaseDomain() 115 * @see getSite() 116 * 117 * @warning This function should not be used without good reason. Please 118 * use getSite() or the Origin if you are not absolutely certain. 119 */ 120 ACString getSchemelessSite(in nsIURI aURI); 121 122 /** 123 * Same as getSchemelessSite but takes a host string. Prefer the URI variant 124 * if possible. 125 * 126 * @param aHost 127 * The host to analyze. 128 * 129 * @return the Site. 130 * 131 * @throws NS_ERROR_UNEXPECTED 132 * or other error returned by nsIIDNService::normalize when 133 * the hostname contains characters disallowed in URIs 134 * 135 * @see getSchemelessSite() 136 * @see getBaseDomain() 137 * @see getSite() 138 * 139 * @warning This function should not be used without good reason. Please 140 * use getSite() or the Origin if you are not absolutely certain. 141 */ 142 ACString getSchemelessSiteFromHost(in AUTF8String aHost); 143 144 /** 145 * Get the Site for the origin of aURI; e.g. for 146 * "https://www.bbc.co.uk/index.html", this would be "https://bbc.co.uk". 147 * This uses getBaseDomain() internally. This is appropriately permissive, 148 * and will return a scheme for alaised hostnames and IP addresses and will 149 * therefore not throw NS_ERROR_INSUFFICIENT_DOMAIN_LEVELS or 150 * NS_ERROR_HOST_IS_IP_ADDRESS, e.g. "http://localhost/index.html" will 151 * return "http://localhost" successfully, rather than throwing an error. 152 * 153 * @param aHostURI 154 * The URI to analyze. 155 * 156 * @return the Site. 157 * 158 * @throws NS_ERROR_UNEXPECTED 159 * or other error returned by nsIIDNService::normalize when 160 * the hostname contains characters disallowed in URIs 161 * 162 * @see getBaseDomain() 163 */ 164 ACString getSite(in nsIURI aURI); 165 166 /** 167 * NOTE: It is strongly recommended to use getPublicSuffix() above if a suitable 168 * nsIURI is available. Only use this method if this is not the case. 169 * 170 * Returns the public suffix of a host string. Otherwise identical to getPublicSuffix(). 171 * 172 * @param aHost The host to be analyzed. Any additional parts (e.g. scheme, 173 * port, or path) will cause this method to throw. ASCII/ACE and 174 * UTF8 encodings are acceptable as input; normalization will 175 * be performed as specified in getBaseDomain(). 176 * 177 * @see getPublicSuffix() 178 */ 179 ACString getPublicSuffixFromHost(in AUTF8String aHost); 180 181 /** 182 * Similar to getPublicSuffixFromHost, but the suffix is validated against 183 * the Public Suffix List. If the suffix is unknown this will return 184 * an empty string. 185 * 186 * @param aHost The host to be analyzed. 187 * @returns the public suffix if known, an empty string otherwise 188 * @see getPublicSuffixFromHost() 189 */ 190 ACString getKnownPublicSuffixFromHost(in AUTF8String aHost); 191 192 /** 193 * NOTE: It is strongly recommended to use getBaseDomain() above if a suitable 194 * nsIURI is available. Only use this method if this is not the case. 195 * 196 * Returns the base domain of a host string. Otherwise identical to getBaseDomain(). 197 * 198 * @param aHost The host to be analyzed. Any additional parts (e.g. scheme, 199 * port, or path) will cause this method to throw. ASCII/ACE and 200 * UTF8 encodings are acceptable as input; normalization will 201 * be performed as specified in getBaseDomain(). 202 * 203 * @see getBaseDomain() 204 */ 205 ACString getBaseDomainFromHost(in AUTF8String aHost, [optional] in uint32_t aAdditionalParts); 206 207 /** 208 * Returns the parent sub-domain of a host string. If the host is a base 209 * domain, it will throw NS_ERROR_INSUFFICIENT_DOMAIN_LEVELS. 210 * 211 * For example: "player.bbc.co.uk" would return "bbc.co.uk" and 212 * "bbc.co.uk" would throw NS_ERROR_INSUFFICIENT_DOMAIN_LEVELS. 213 * 214 * @param aHost The host to be analyzed. Any additional parts (e.g. scheme, 215 * port, or path) will cause this method to throw. ASCII/ACE and 216 * UTF8 encodings are acceptable as input; normalization will 217 * be performed as specified in getBaseDomain(). 218 */ 219 ACString getNextSubDomain(in AUTF8String aHost); 220 221 /** 222 * Returns true if the |aInput| in is part of the root domain of |aHost|. 223 * For example, if |aInput| is "www.mozilla.org", and we pass in 224 * "mozilla.org" as |aHost|, this will return true. It would return false 225 * the other way around. 226 * 227 * @param aInput The host to be analyzed. 228 * @param aHost The host to compare to. 229 */ 230 boolean hasRootDomain(in AUTF8String aInput, in AUTF8String aHost); 231 232 /** 233 * Returns true if the host of |aURI| ends with, or is, a suffix that is on 234 * the public suffix list. 235 * 236 * @param aURI The URI to be checked 237 */ 238 boolean hasKnownPublicSuffix(in nsIURI aURI); 239 240 /** 241 * Returns true if |aHost| ends with, or is, a suffix that is on the public 242 * suffix list. 243 * 244 * @param aHost The hostname to be checked 245 * @see hasKnownPublicSuffix() 246 */ 247 boolean hasKnownPublicSuffixFromHost(in AUTF8String aHost); 248 };