nsIDNSService.idl (15326B)
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/. */ 4 5 #include "nsISupports.idl" 6 #include "nsIRequest.idl" 7 #include "nsITRRSkipReason.idl" 8 9 %{ C++ 10 #include "mozilla/BasePrincipal.h" 11 #include "mozilla/TypedEnumBits.h" 12 %} 13 14 interface nsICancelable; 15 interface nsIEventTarget; 16 interface nsIDNSRecord; 17 interface nsIDNSListener; 18 interface nsIDNSAdditionalInfo; 19 20 %{C++ 21 #include "nsTArrayForwardDeclare.h" 22 namespace mozilla { namespace net { 23 struct DNSCacheEntries; 24 } } 25 %} 26 27 [ptr] native EntriesArray(nsTArray<mozilla::net::DNSCacheEntries>); 28 [ref] native OriginAttributes(const mozilla::OriginAttributes); 29 30 /** 31 * nsIDNSService 32 */ 33 [scriptable, builtinclass, uuid(de5642c6-61fc-4fcf-9a47-03226b0d4e21)] 34 interface nsIDNSService : nsISupports 35 { 36 /** 37 * These are the dns request types that are currently supported. 38 * RESOLVE_TYPE_DEFAULT is standard A/AAAA lookup 39 */ 40 cenum ResolveType : 16 { 41 RESOLVE_TYPE_DEFAULT = 0, 42 RESOLVE_TYPE_TXT = 16, 43 RESOLVE_TYPE_HTTPSSVC = 65, 44 }; 45 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 53 }; 54 55 cenum DNSFlags : 32 { 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), 94 // If set, the native HTTPS query is not allowed. 95 RESOLVE_DISABLE_NATIVE_HTTPS_QUERY = (1 << 17), 96 // For testing purposes only. If set, create a mock HTTPS RR and use it. 97 RESOLVE_CREATE_MOCK_HTTPS_RR = (1 << 18), 98 99 // Bitflag containing all possible flags. 100 ALL_DNSFLAGS_BITS = ((1 << 19) - 1), 101 }; 102 103 cenum ConfirmationState : 8 { 104 CONFIRM_OFF = 0, 105 CONFIRM_TRYING_OK = 1, 106 CONFIRM_OK = 2, 107 CONFIRM_FAILED = 3, 108 CONFIRM_TRYING_FAILED = 4, 109 CONFIRM_DISABLED = 5, 110 }; 111 112 /** 113 * kicks off an asynchronous host lookup. 114 * 115 * @param aHostName 116 * the hostname or IP-address-literal to resolve. 117 * @param aType 118 * one of RESOLVE_TYPE_*. 119 * @param aFlags 120 * a bitwise OR of the RESOLVE_ prefixed constants defined below. 121 * @param aInfo 122 * a AdditionalInfo object that holds information about: 123 * - the resolver to be used such as TRR URL 124 * - the port number that could be used to construct a QNAME 125 * for HTTPS RR 126 * If null we use the default configuration. 127 * @param aListener 128 * the listener to be notified when the result is available. 129 * @param aListenerTarget 130 * optional parameter (may be null). if non-null, this parameter 131 * specifies the nsIEventTarget of the thread on which the 132 * listener's onLookupComplete should be called. however, if this 133 * parameter is null, then onLookupComplete will be called on an 134 * unspecified thread (possibly recursively). 135 * @param aOriginAttributes 136 * the originAttribute for this resolving, the DNS cache will be 137 * separated according to this originAttributes. This attribute is 138 * optional to avoid breaking add-ons. 139 * 140 * @return An object that can be used to cancel the host lookup. 141 */ 142 [implicit_jscontext, optional_argc] 143 nsICancelable asyncResolve(in AUTF8String aHostName, 144 in nsIDNSService_ResolveType aType, 145 in nsIDNSService_DNSFlags aFlags, 146 in nsIDNSAdditionalInfo aInfo, 147 in nsIDNSListener aListener, 148 in nsIEventTarget aListenerTarget, 149 [optional] in jsval aOriginAttributes); 150 151 [notxpcom] 152 nsresult asyncResolveNative(in AUTF8String aHostName, 153 in nsIDNSService_ResolveType aType, 154 in nsIDNSService_DNSFlags aFlags, 155 in nsIDNSAdditionalInfo aInfo, 156 in nsIDNSListener aListener, 157 in nsIEventTarget aListenerTarget, 158 in OriginAttributes aOriginAttributes, 159 out nsICancelable aResult); 160 161 /** 162 * Returns a new nsIDNSAdditionalInfo object containing the URL we pass to it. 163 */ 164 nsIDNSAdditionalInfo newAdditionalInfo(in AUTF8String aTrrURL, 165 in int32_t aPort); 166 167 /** 168 * Attempts to cancel a previously requested async DNS lookup 169 * 170 * @param aHostName 171 * the hostname or IP-address-literal to resolve. 172 * @param aType 173 * one of RESOLVE_TYPE_*. 174 * @param aFlags 175 * a bitwise OR of the RESOLVE_ prefixed constants defined below. 176 * @param aInfo 177 * a AdditionalInfo object that holds information about: 178 * - the resolver to be used such as TRR URL 179 * - the port number that could be used to construct a QNAME 180 * for HTTPS RR 181 * If null we use the default configuration. 182 * @param aListener 183 * the original listener which was to be notified about the host lookup 184 * result - used to match request information to requestor. 185 * @param aReason 186 * nsresult reason for the cancellation 187 * @param aOriginAttributes 188 * the originAttribute for this resolving. This attribute is optional 189 * to avoid breaking add-ons. 190 */ 191 [implicit_jscontext, optional_argc] 192 void cancelAsyncResolve(in AUTF8String aHostName, 193 in nsIDNSService_ResolveType aType, 194 in nsIDNSService_DNSFlags aFlags, 195 in nsIDNSAdditionalInfo aResolver, 196 in nsIDNSListener aListener, 197 in nsresult aReason, 198 [optional] in jsval aOriginAttributes); 199 200 [notxpcom] 201 nsresult cancelAsyncResolveNative(in AUTF8String aHostName, 202 in nsIDNSService_ResolveType aType, 203 in nsIDNSService_DNSFlags aFlags, 204 in nsIDNSAdditionalInfo aResolver, 205 in nsIDNSListener aListener, 206 in nsresult aReason, 207 in OriginAttributes aOriginAttributes); 208 209 /** 210 * called to synchronously resolve a hostname. 211 * 212 * Since this method may block the calling thread for a long period of 213 * time, it may not be accessed from the main thread. 214 * 215 * @param aHostName 216 * the hostname or IP-address-literal to resolve. 217 * @param aFlags 218 * a bitwise OR of the RESOLVE_ prefixed constants defined below. 219 * @param aOriginAttributes 220 * the originAttribute for this resolving, the DNS cache will be 221 * separated according to this originAttributes. This attribute is 222 * optional to avoid breaking add-ons. 223 * 224 * @return DNS record corresponding to the given hostname. 225 * @throws NS_ERROR_UNKNOWN_HOST if host could not be resolved. 226 * @throws NS_ERROR_NOT_AVAILABLE if accessed from the main thread. 227 */ 228 [implicit_jscontext, optional_argc] 229 nsIDNSRecord resolve(in AUTF8String aHostName, 230 in nsIDNSService_DNSFlags aFlags, 231 [optional] in jsval aOriginAttributes); 232 233 [notxpcom] 234 nsresult resolveNative(in AUTF8String aHostName, 235 in nsIDNSService_DNSFlags aFlags, 236 in OriginAttributes aOriginAttributes, 237 out nsIDNSRecord aResult); 238 239 /** 240 * The method takes a pointer to an nsTArray 241 * and fills it with cache entry data 242 * Called by the networking dashboard 243 */ 244 [noscript] void getDNSCacheEntries(in EntriesArray args); 245 246 247 /** 248 * Clears the DNS cache. 249 * @param aTrrToo 250 * If true we will clear TRR cached entries too. Since these 251 * are resolved remotely it's not necessary to clear them when 252 * the network status changes, but it's sometimes useful to do so 253 * for tests or other situations. 254 */ 255 void clearCache(in boolean aTrrToo); 256 257 /** 258 * The method is used only for test purpose. We use this to recheck if 259 * parental control is enabled or not. 260 */ 261 void reloadParentalControlEnabled(); 262 263 /** 264 * Notifies the TRR service of a TRR that was automatically detected based 265 * on network preferences. 266 */ 267 void setDetectedTrrURI(in AUTF8String aURI); 268 269 /** 270 * Stores the result of the TRR heuristic detection. 271 * Will be TRR_OK if no heuristics failed. 272 */ 273 void setHeuristicDetectionResult(in nsITRRSkipReason_value value); 274 275 /** 276 * Returns the result of the last TRR heuristic detection. 277 * Will be TRR_OK if no heuristics failed. 278 */ 279 readonly attribute nsITRRSkipReason_value heuristicDetectionResult; 280 281 ACString getTRRSkipReasonName(in nsITRRSkipReason_value value); 282 283 /** 284 * The channel status of the last TRR confirmation attempt. 285 * In strict mode it reflects the channel status of the last TRR request. 286 */ 287 readonly attribute nsresult lastConfirmationStatus; 288 289 /** 290 * The TRR skip reason of the last TRR confirmation attempt. 291 * In strict mode it reflects the TRR skip reason of the last TRR request. 292 */ 293 readonly attribute nsITRRSkipReason_value lastConfirmationSkipReason; 294 295 /** 296 * Notifies the DNS service that we failed to connect to this alternative 297 * endpoint. 298 * @param aOwnerName 299 * The owner name of this HTTPS RRs. 300 * @param aSVCDomainName 301 * The domain name of this alternative endpoint. 302 */ 303 [noscript] void ReportFailedSVCDomainName(in ACString aOwnerName, 304 in ACString aSVCDomainName); 305 306 /** 307 * Check if the given domain name was failed to connect to before. 308 * @param aOwnerName 309 * The owner name of this HTTPS RRs. 310 * @param aSVCDomainName 311 * The domain name of this alternative endpoint. 312 */ 313 [noscript] boolean IsSVCDomainNameFailed(in ACString aOwnerName, 314 in ACString aSVCDomainName); 315 316 /** 317 * Reset the exclusion list. 318 * @param aOwnerName 319 * The owner name of this HTTPS RRs. 320 */ 321 [noscript] void ResetExcludedSVCDomainName(in ACString aOwnerName); 322 323 /** 324 * Returns a string containing the URI currently used by the TRR service. 325 */ 326 readonly attribute AUTF8String currentTrrURI; 327 328 /** 329 * Returns the value of the TRR Service's current default mode. 330 */ 331 readonly attribute nsIDNSService_ResolverMode currentTrrMode; 332 333 /** 334 * The TRRService's current confirmation state. 335 * This is mostly for testing purposes. 336 */ 337 readonly attribute unsigned long currentTrrConfirmationState; 338 339 /** 340 * @return the hostname of the operating system. 341 */ 342 readonly attribute AUTF8String myHostName; 343 344 /** 345 * returns the current TRR domain. 346 */ 347 readonly attribute ACString trrDomain; 348 349 /** 350 * returns the telemetry key for current TRR domain. 351 */ 352 readonly attribute ACString TRRDomainKey; 353 354 /************************************************************************* 355 * Listed below are the various flags that may be OR'd together to form 356 * the aFlags parameter passed to asyncResolve() and resolve(). 357 */ 358 359 %{C++ 360 static nsIDNSService::DNSFlags GetFlagsFromTRRMode(nsIRequest::TRRMode aMode) { 361 return static_cast<nsIDNSService::DNSFlags>(static_cast<uint32_t>(aMode) << 11); 362 } 363 364 static nsIRequest::TRRMode GetTRRModeFromFlags(nsIDNSService::DNSFlags aFlags) { 365 return static_cast<nsIRequest::TRRMode>((aFlags & RESOLVE_TRR_MODE_MASK) >> 11); 366 } 367 %} 368 369 }; 370 371 %{C++ 372 373 /** 374 * An observer notification for this topic is sent whenever the URI that the 375 * TRR service is using has changed. 376 */ 377 #define NS_NETWORK_TRR_URI_CHANGED_TOPIC "network:trr-uri-changed" 378 379 /** 380 * An observer notification for this topic is sent whenever the mode that the 381 * TRR service is using has changed. 382 */ 383 #define NS_NETWORK_TRR_MODE_CHANGED_TOPIC "network:trr-mode-changed" 384 385 MOZ_MAKE_ENUM_CLASS_BITWISE_OPERATORS(nsIDNSService::DNSFlags) 386 387 %}