1 /* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5 #include
"nsISupports.idl"
6 #include
"nsIRequest.idl"
7 #include
"nsITRRSkipReason.idl"
10 #include
"mozilla/BasePrincipal.h"
11 #include
"mozilla/TypedEnumBits.h"
14 interface nsICancelable
;
15 interface nsIEventTarget
;
16 interface nsIDNSRecord
;
17 interface nsIDNSListener
;
18 interface nsIDNSAdditionalInfo
;
21 #include
"nsTArrayForwardDeclare.h"
22 namespace mozilla
{ namespace net
{
23 struct DNSCacheEntries
;
27 [ptr] native EntriesArray
(nsTArray
<mozilla
::net
::DNSCacheEntries
>);
28 [ref] native OriginAttributes
(const mozilla
::OriginAttributes
);
33 [scriptable
, builtinclass
, uuid(de5642c6
-61fc
-4fcf
-9a47
-03226b0d4e21
)]
34 interface nsIDNSService
: nsISupports
37 * These are the dns request types that are currently supported.
38 * RESOLVE_TYPE_DEFAULT is standard A/AAAA lookup
40 cenum ResolveType
: 16 {
41 RESOLVE_TYPE_DEFAULT
= 0,
42 RESOLVE_TYPE_TXT
= 16,
43 RESOLVE_TYPE_HTTPSSVC
= 65,
46 cenum ResolverMode
: 32 { // 32 bits to allow this to be stored in an Atomic
47 MODE_NATIVEONLY
= 0, // TRR OFF (by default)
48 MODE_RESERVED1
= 1, // Reserved value. Used to be parallel resolve.
49 MODE_TRRFIRST
= 2, // fallback to native on TRR failure
50 MODE_TRRONLY
= 3, // don't even fallback
51 MODE_RESERVED4
= 4, // Reserved value. Used to be race TRR with native.
52 MODE_TRROFF
= 5 // identical to MODE_NATIVEONLY but explicitly selected
56 RESOLVE_DEFAULT_FLAGS
= 0,
57 // if set, this flag suppresses the internal DNS lookup cache.
58 RESOLVE_BYPASS_CACHE
= (1 << 0),
59 // if set, the canonical name of the specified host will be queried.
60 RESOLVE_CANONICAL_NAME
= (1 << 1),
61 // If PRIORITY flags are set, the query is given lower priority.
62 // Medium takes precedence if both MEDIUM and LOW are used.
63 RESOLVE_PRIORITY_MEDIUM
= (1 << 2),
64 RESOLVE_PRIORITY_LOW
= (1 << 3),
65 // if set, indicates request is speculative. Speculative requests
66 // return errors if prefetching is disabled by configuration.
67 RESOLVE_SPECULATE
= (1 << 4),
68 // If set, only IPv4 addresses will be returned from resolve/asyncResolve.
69 RESOLVE_DISABLE_IPV6
= (1 << 5),
70 // If set, only literals and cached entries will be returned from resolve/asyncResolve.
71 RESOLVE_OFFLINE
= (1 << 6),
72 // If set, only IPv6 addresses will be returned from resolve/asyncResolve.
73 RESOLVE_DISABLE_IPV4
= (1 << 7),
74 // If set, allow name collision results (127.0.53.53) which are normally filtered.
75 RESOLVE_ALLOW_NAME_COLLISION
= (1 << 8),
76 // If set, do not use TRR for resolving the host name.
77 RESOLVE_DISABLE_TRR
= (1 << 9),
78 // if set (together with RESOLVE_BYPASS_CACHE), invalidate the DNS
79 // existing cache entry first (if existing) then make a new resolve.
80 RESOLVE_REFRESH_CACHE
= (1 << 10),
81 // These two bits encode the TRR mode of the request.
82 // Use the static helper methods GetFlagsFromTRRMode and
83 // GetTRRModeFromFlags to convert between the TRR mode and flags.
84 RESOLVE_TRR_MODE_MASK
= (1 << 11) |
(1 << 12),
85 RESOLVE_TRR_DISABLED_MODE
= (1 << 11),
86 // Force resolution even when SOCKS proxy with DNS forwarding is configured.
87 // Only to be used for the proxy host resolution.
88 RESOLVE_IGNORE_SOCKS_DNS
= (1 << 13),
89 // If set, only cached IP hint addresses will be returned from resolve/asyncResolve.
90 RESOLVE_IP_HINT
= (1 << 14),
91 // If set, the DNS service will pass a DNS record to
92 // OnLookupComplete even when there was a resolution error.
93 RESOLVE_WANT_RECORD_ON_ERROR
= (1 << 16),
95 // Bitflag containing all possible flags.
96 ALL_DNSFLAGS_BITS
= ((1 << 17) - 1),
99 cenum ConfirmationState
: 8 {
101 CONFIRM_TRYING_OK
= 1,
104 CONFIRM_TRYING_FAILED
= 4,
105 CONFIRM_DISABLED
= 5,
109 * kicks off an asynchronous host lookup.
112 * the hostname or IP-address-literal to resolve.
114 * one of RESOLVE_TYPE_*.
116 * a bitwise OR of the RESOLVE_ prefixed constants defined below.
118 * a AdditionalInfo object that holds information about:
119 * - the resolver to be used such as TRR URL
120 * - the port number that could be used to construct a QNAME
122 * If null we use the default configuration.
124 * the listener to be notified when the result is available.
125 * @param aListenerTarget
126 * optional parameter (may be null). if non-null, this parameter
127 * specifies the nsIEventTarget of the thread on which the
128 * listener's onLookupComplete should be called. however, if this
129 * parameter is null, then onLookupComplete will be called on an
130 * unspecified thread (possibly recursively).
131 * @param aOriginAttributes
132 * the originAttribute for this resolving, the DNS cache will be
133 * separated according to this originAttributes. This attribute is
134 * optional to avoid breaking add-ons.
136 * @return An object that can be used to cancel the host lookup.
138 [implicit_jscontext
, optional_argc
]
139 nsICancelable asyncResolve
(in AUTF8String aHostName
,
140 in nsIDNSService_ResolveType aType
,
141 in nsIDNSService_DNSFlags aFlags
,
142 in nsIDNSAdditionalInfo aInfo
,
143 in nsIDNSListener aListener
,
144 in nsIEventTarget aListenerTarget
,
145 [optional] in jsval aOriginAttributes
);
148 nsresult asyncResolveNative
(in AUTF8String aHostName
,
149 in nsIDNSService_ResolveType aType
,
150 in nsIDNSService_DNSFlags aFlags
,
151 in nsIDNSAdditionalInfo aInfo
,
152 in nsIDNSListener aListener
,
153 in nsIEventTarget aListenerTarget
,
154 in OriginAttributes aOriginAttributes
,
155 out nsICancelable aResult
);
158 * Returns a new nsIDNSAdditionalInfo object containing the URL we pass to it.
160 nsIDNSAdditionalInfo newAdditionalInfo
(in AUTF8String aTrrURL
,
164 * Attempts to cancel a previously requested async DNS lookup
167 * the hostname or IP-address-literal to resolve.
169 * one of RESOLVE_TYPE_*.
171 * a bitwise OR of the RESOLVE_ prefixed constants defined below.
173 * a AdditionalInfo object that holds information about:
174 * - the resolver to be used such as TRR URL
175 * - the port number that could be used to construct a QNAME
177 * If null we use the default configuration.
179 * the original listener which was to be notified about the host lookup
180 * result - used to match request information to requestor.
182 * nsresult reason for the cancellation
183 * @param aOriginAttributes
184 * the originAttribute for this resolving. This attribute is optional
185 * to avoid breaking add-ons.
187 [implicit_jscontext
, optional_argc
]
188 void cancelAsyncResolve
(in AUTF8String aHostName
,
189 in nsIDNSService_ResolveType aType
,
190 in nsIDNSService_DNSFlags aFlags
,
191 in nsIDNSAdditionalInfo aResolver
,
192 in nsIDNSListener aListener
,
194 [optional] in jsval aOriginAttributes
);
197 nsresult cancelAsyncResolveNative
(in AUTF8String aHostName
,
198 in nsIDNSService_ResolveType aType
,
199 in nsIDNSService_DNSFlags aFlags
,
200 in nsIDNSAdditionalInfo aResolver
,
201 in nsIDNSListener aListener
,
203 in OriginAttributes aOriginAttributes
);
206 * called to synchronously resolve a hostname.
208 * Since this method may block the calling thread for a long period of
209 * time, it may not be accessed from the main thread.
212 * the hostname or IP-address-literal to resolve.
214 * a bitwise OR of the RESOLVE_ prefixed constants defined below.
215 * @param aOriginAttributes
216 * the originAttribute for this resolving, the DNS cache will be
217 * separated according to this originAttributes. This attribute is
218 * optional to avoid breaking add-ons.
220 * @return DNS record corresponding to the given hostname.
221 * @throws NS_ERROR_UNKNOWN_HOST if host could not be resolved.
222 * @throws NS_ERROR_NOT_AVAILABLE if accessed from the main thread.
224 [implicit_jscontext
, optional_argc
]
225 nsIDNSRecord resolve
(in AUTF8String aHostName
,
226 in nsIDNSService_DNSFlags aFlags
,
227 [optional] in jsval aOriginAttributes
);
230 nsresult resolveNative
(in AUTF8String aHostName
,
231 in nsIDNSService_DNSFlags aFlags
,
232 in OriginAttributes aOriginAttributes
,
233 out nsIDNSRecord aResult
);
236 * The method takes a pointer to an nsTArray
237 * and fills it with cache entry data
238 * Called by the networking dashboard
240 [noscript
] void getDNSCacheEntries
(in EntriesArray args
);
244 * Clears the DNS cache.
246 * If true we will clear TRR cached entries too. Since these
247 * are resolved remotely it's not necessary to clear them when
248 * the network status changes, but it's sometimes useful to do so
249 * for tests or other situations.
251 void clearCache
(in boolean aTrrToo
);
254 * The method is used only for test purpose. We use this to recheck if
255 * parental control is enabled or not.
257 void reloadParentalControlEnabled
();
260 * Notifies the TRR service of a TRR that was automatically detected based
261 * on network preferences.
263 void setDetectedTrrURI
(in AUTF8String aURI
);
266 * Stores the result of the TRR heuristic detection.
267 * Will be TRR_OK if no heuristics failed.
269 void setHeuristicDetectionResult
(in nsITRRSkipReason_value value
);
272 * Returns the result of the last TRR heuristic detection.
273 * Will be TRR_OK if no heuristics failed.
275 readonly attribute nsITRRSkipReason_value heuristicDetectionResult
;
277 ACString getTRRSkipReasonName
(in nsITRRSkipReason_value value
);
280 * The channel status of the last TRR confirmation attempt.
281 * In strict mode it reflects the channel status of the last TRR request.
283 readonly attribute nsresult lastConfirmationStatus
;
286 * The TRR skip reason of the last TRR confirmation attempt.
287 * In strict mode it reflects the TRR skip reason of the last TRR request.
289 readonly attribute nsITRRSkipReason_value lastConfirmationSkipReason
;
292 * Notifies the DNS service that we failed to connect to this alternative
295 * The owner name of this HTTPS RRs.
296 * @param aSVCDomainName
297 * The domain name of this alternative endpoint.
299 [noscript
] void ReportFailedSVCDomainName
(in ACString aOwnerName
,
300 in ACString aSVCDomainName
);
303 * Check if the given domain name was failed to connect to before.
305 * The owner name of this HTTPS RRs.
306 * @param aSVCDomainName
307 * The domain name of this alternative endpoint.
309 [noscript
] boolean IsSVCDomainNameFailed
(in ACString aOwnerName
,
310 in ACString aSVCDomainName
);
313 * Reset the exclusion list.
315 * The owner name of this HTTPS RRs.
317 [noscript
] void ResetExcludedSVCDomainName
(in ACString aOwnerName
);
320 * Returns a string containing the URI currently used by the TRR service.
322 readonly attribute AUTF8String currentTrrURI
;
325 * Returns the value of the TRR Service's current default mode.
327 readonly attribute nsIDNSService_ResolverMode currentTrrMode
;
330 * The TRRService's current confirmation state.
331 * This is mostly for testing purposes.
333 readonly attribute
unsigned long currentTrrConfirmationState
;
336 * @return the hostname of the operating system.
338 readonly attribute AUTF8String myHostName
;
341 * returns the current TRR domain.
343 readonly attribute ACString trrDomain
;
346 * returns the telemetry key for current TRR domain.
348 readonly attribute ACString TRRDomainKey
;
350 /*************************************************************************
351 * Listed below are the various flags that may be OR'd together to form
352 * the aFlags parameter passed to asyncResolve() and resolve().
356 static nsIDNSService
::DNSFlags GetFlagsFromTRRMode
(nsIRequest
::TRRMode aMode
) {
357 return static_cast
<nsIDNSService
::DNSFlags
>(static_cast
<uint32_t
>(aMode
) << 11);
360 static nsIRequest
::TRRMode GetTRRModeFromFlags
(nsIDNSService
::DNSFlags aFlags
) {
361 return static_cast
<nsIRequest
::TRRMode
>((aFlags
& RESOLVE_TRR_MODE_MASK
) >> 11);
370 * An observer notification for this topic is sent whenever the URI that the
371 * TRR service is using has changed.
373 #define NS_NETWORK_TRR_URI_CHANGED_TOPIC
"network:trr-uri-changed"
376 * An observer notification for this topic is sent whenever the mode that the
377 * TRR service is using has changed.
379 #define NS_NETWORK_TRR_MODE_CHANGED_TOPIC
"network:trr-mode-changed"
381 MOZ_MAKE_ENUM_CLASS_BITWISE_OPERATORS
(nsIDNSService
::DNSFlags
)