netwerk/dns/nsIDNSService.idl

   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 %}