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