diff options
Diffstat (limited to 'netwerk/dns/nsIDNSService.idl')
| -rw-r--r-- | netwerk/dns/nsIDNSService.idl | 383 |
1 files changed, 383 insertions, 0 deletions
diff --git a/netwerk/dns/nsIDNSService.idl b/netwerk/dns/nsIDNSService.idl new file mode 100644 index 0000000000..c1aecccd8c --- /dev/null +++ b/netwerk/dns/nsIDNSService.idl @@ -0,0 +1,383 @@ +/* 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" +#include "nsIRequest.idl" +#include "nsITRRSkipReason.idl" + +%{ C++ +#include "mozilla/BasePrincipal.h" +#include "mozilla/TypedEnumBits.h" +%} + +interface nsICancelable; +interface nsIEventTarget; +interface nsIDNSRecord; +interface nsIDNSListener; +interface nsIDNSAdditionalInfo; + +%{C++ +#include "nsTArrayForwardDeclare.h" +namespace mozilla { namespace net { + struct DNSCacheEntries; +} } +%} + +[ptr] native EntriesArray(nsTArray<mozilla::net::DNSCacheEntries>); +[ref] native OriginAttributes(const mozilla::OriginAttributes); + +/** + * nsIDNSService + */ +[scriptable, builtinclass, uuid(de5642c6-61fc-4fcf-9a47-03226b0d4e21)] +interface nsIDNSService : nsISupports +{ + /** + * These are the dns request types that are currently supported. + * RESOLVE_TYPE_DEFAULT is standard A/AAAA lookup + */ + cenum ResolveType : 16 { + RESOLVE_TYPE_DEFAULT = 0, + RESOLVE_TYPE_TXT = 16, + RESOLVE_TYPE_HTTPSSVC = 65, + }; + + cenum ResolverMode : 32 { // 32 bits to allow this to be stored in an Atomic + MODE_NATIVEONLY = 0, // TRR OFF (by default) + MODE_RESERVED1 = 1, // Reserved value. Used to be parallel resolve. + MODE_TRRFIRST = 2, // fallback to native on TRR failure + MODE_TRRONLY = 3, // don't even fallback + MODE_RESERVED4 = 4, // Reserved value. Used to be race TRR with native. + MODE_TRROFF = 5 // identical to MODE_NATIVEONLY but explicitly selected + }; + + cenum DNSFlags : 32 { + RESOLVE_DEFAULT_FLAGS = 0, + // if set, this flag suppresses the internal DNS lookup cache. + RESOLVE_BYPASS_CACHE = (1 << 0), + // if set, the canonical name of the specified host will be queried. + RESOLVE_CANONICAL_NAME = (1 << 1), + // If PRIORITY flags are set, the query is given lower priority. + // Medium takes precedence if both MEDIUM and LOW are used. + RESOLVE_PRIORITY_MEDIUM = (1 << 2), + RESOLVE_PRIORITY_LOW = (1 << 3), + // if set, indicates request is speculative. Speculative requests + // return errors if prefetching is disabled by configuration. + RESOLVE_SPECULATE = (1 << 4), + // If set, only IPv4 addresses will be returned from resolve/asyncResolve. + RESOLVE_DISABLE_IPV6 = (1 << 5), + // If set, only literals and cached entries will be returned from resolve/asyncResolve. + RESOLVE_OFFLINE = (1 << 6), + // If set, only IPv6 addresses will be returned from resolve/asyncResolve. + RESOLVE_DISABLE_IPV4 = (1 << 7), + // If set, allow name collision results (127.0.53.53) which are normally filtered. + RESOLVE_ALLOW_NAME_COLLISION = (1 << 8), + // If set, do not use TRR for resolving the host name. + RESOLVE_DISABLE_TRR = (1 << 9), + // if set (together with RESOLVE_BYPASS_CACHE), invalidate the DNS + // existing cache entry first (if existing) then make a new resolve. + RESOLVE_REFRESH_CACHE = (1 << 10), + // These two bits encode the TRR mode of the request. + // Use the static helper methods GetFlagsFromTRRMode and + // GetTRRModeFromFlags to convert between the TRR mode and flags. + RESOLVE_TRR_MODE_MASK = (1 << 11) | (1 << 12), + RESOLVE_TRR_DISABLED_MODE = (1 << 11), + // Force resolution even when SOCKS proxy with DNS forwarding is configured. + // Only to be used for the proxy host resolution. + RESOLVE_IGNORE_SOCKS_DNS = (1 << 13), + // If set, only cached IP hint addresses will be returned from resolve/asyncResolve. + RESOLVE_IP_HINT = (1 << 14), + // If set, the DNS service will pass a DNS record to + // OnLookupComplete even when there was a resolution error. + RESOLVE_WANT_RECORD_ON_ERROR = (1 << 16), + + // Bitflag containing all possible flags. + ALL_DNSFLAGS_BITS = ((1 << 17) - 1), + }; + + cenum ConfirmationState : 8 { + CONFIRM_OFF = 0, + CONFIRM_TRYING_OK = 1, + CONFIRM_OK = 2, + CONFIRM_FAILED = 3, + CONFIRM_TRYING_FAILED = 4, + CONFIRM_DISABLED = 5, + }; + + /** + * kicks off an asynchronous host lookup. + * + * @param aHostName + * the hostname or IP-address-literal to resolve. + * @param aType + * one of RESOLVE_TYPE_*. + * @param aFlags + * a bitwise OR of the RESOLVE_ prefixed constants defined below. + * @param aInfo + * a AdditionalInfo object that holds information about: + * - the resolver to be used such as TRR URL + * - the port number that could be used to construct a QNAME + * for HTTPS RR + * If null we use the default configuration. + * @param aListener + * the listener to be notified when the result is available. + * @param aListenerTarget + * optional parameter (may be null). if non-null, this parameter + * specifies the nsIEventTarget of the thread on which the + * listener's onLookupComplete should be called. however, if this + * parameter is null, then onLookupComplete will be called on an + * unspecified thread (possibly recursively). + * @param aOriginAttributes + * the originAttribute for this resolving, the DNS cache will be + * separated according to this originAttributes. This attribute is + * optional to avoid breaking add-ons. + * + * @return An object that can be used to cancel the host lookup. + */ + [implicit_jscontext, optional_argc] + nsICancelable asyncResolve(in AUTF8String aHostName, + in nsIDNSService_ResolveType aType, + in nsIDNSService_DNSFlags aFlags, + in nsIDNSAdditionalInfo aInfo, + in nsIDNSListener aListener, + in nsIEventTarget aListenerTarget, + [optional] in jsval aOriginAttributes); + + [notxpcom] + nsresult asyncResolveNative(in AUTF8String aHostName, + in nsIDNSService_ResolveType aType, + in nsIDNSService_DNSFlags aFlags, + in nsIDNSAdditionalInfo aInfo, + in nsIDNSListener aListener, + in nsIEventTarget aListenerTarget, + in OriginAttributes aOriginAttributes, + out nsICancelable aResult); + + /** + * Returns a new nsIDNSAdditionalInfo object containing the URL we pass to it. + */ + nsIDNSAdditionalInfo newAdditionalInfo(in AUTF8String aTrrURL, + in int32_t aPort); + + /** + * Attempts to cancel a previously requested async DNS lookup + * + * @param aHostName + * the hostname or IP-address-literal to resolve. + * @param aType + * one of RESOLVE_TYPE_*. + * @param aFlags + * a bitwise OR of the RESOLVE_ prefixed constants defined below. + * @param aInfo + * a AdditionalInfo object that holds information about: + * - the resolver to be used such as TRR URL + * - the port number that could be used to construct a QNAME + * for HTTPS RR + * If null we use the default configuration. + * @param aListener + * the original listener which was to be notified about the host lookup + * result - used to match request information to requestor. + * @param aReason + * nsresult reason for the cancellation + * @param aOriginAttributes + * the originAttribute for this resolving. This attribute is optional + * to avoid breaking add-ons. + */ + [implicit_jscontext, optional_argc] + void cancelAsyncResolve(in AUTF8String aHostName, + in nsIDNSService_ResolveType aType, + in nsIDNSService_DNSFlags aFlags, + in nsIDNSAdditionalInfo aResolver, + in nsIDNSListener aListener, + in nsresult aReason, + [optional] in jsval aOriginAttributes); + + [notxpcom] + nsresult cancelAsyncResolveNative(in AUTF8String aHostName, + in nsIDNSService_ResolveType aType, + in nsIDNSService_DNSFlags aFlags, + in nsIDNSAdditionalInfo aResolver, + in nsIDNSListener aListener, + in nsresult aReason, + in OriginAttributes aOriginAttributes); + + /** + * called to synchronously resolve a hostname. + * + * Since this method may block the calling thread for a long period of + * time, it may not be accessed from the main thread. + * + * @param aHostName + * the hostname or IP-address-literal to resolve. + * @param aFlags + * a bitwise OR of the RESOLVE_ prefixed constants defined below. + * @param aOriginAttributes + * the originAttribute for this resolving, the DNS cache will be + * separated according to this originAttributes. This attribute is + * optional to avoid breaking add-ons. + * + * @return DNS record corresponding to the given hostname. + * @throws NS_ERROR_UNKNOWN_HOST if host could not be resolved. + * @throws NS_ERROR_NOT_AVAILABLE if accessed from the main thread. + */ + [implicit_jscontext, optional_argc] + nsIDNSRecord resolve(in AUTF8String aHostName, + in nsIDNSService_DNSFlags aFlags, + [optional] in jsval aOriginAttributes); + + [notxpcom] + nsresult resolveNative(in AUTF8String aHostName, + in nsIDNSService_DNSFlags aFlags, + in OriginAttributes aOriginAttributes, + out nsIDNSRecord aResult); + + /** + * The method takes a pointer to an nsTArray + * and fills it with cache entry data + * Called by the networking dashboard + */ + [noscript] void getDNSCacheEntries(in EntriesArray args); + + + /** + * Clears the DNS cache. + * @param aTrrToo + * If true we will clear TRR cached entries too. Since these + * are resolved remotely it's not necessary to clear them when + * the network status changes, but it's sometimes useful to do so + * for tests or other situations. + */ + void clearCache(in boolean aTrrToo); + + /** + * The method is used only for test purpose. We use this to recheck if + * parental control is enabled or not. + */ + void reloadParentalControlEnabled(); + + /** + * Notifies the TRR service of a TRR that was automatically detected based + * on network preferences. + */ + void setDetectedTrrURI(in AUTF8String aURI); + + /** + * Stores the result of the TRR heuristic detection. + * Will be TRR_OK if no heuristics failed. + */ + void setHeuristicDetectionResult(in nsITRRSkipReason_value value); + + /** + * Returns the result of the last TRR heuristic detection. + * Will be TRR_OK if no heuristics failed. + */ + readonly attribute nsITRRSkipReason_value heuristicDetectionResult; + + ACString getTRRSkipReasonName(in nsITRRSkipReason_value value); + + /** + * The channel status of the last TRR confirmation attempt. + * In strict mode it reflects the channel status of the last TRR request. + */ + readonly attribute nsresult lastConfirmationStatus; + + /** + * The TRR skip reason of the last TRR confirmation attempt. + * In strict mode it reflects the TRR skip reason of the last TRR request. + */ + readonly attribute nsITRRSkipReason_value lastConfirmationSkipReason; + + /** + * Notifies the DNS service that we failed to connect to this alternative + * endpoint. + * @param aOwnerName + * The owner name of this HTTPS RRs. + * @param aSVCDomainName + * The domain name of this alternative endpoint. + */ + [noscript] void ReportFailedSVCDomainName(in ACString aOwnerName, + in ACString aSVCDomainName); + + /** + * Check if the given domain name was failed to connect to before. + * @param aOwnerName + * The owner name of this HTTPS RRs. + * @param aSVCDomainName + * The domain name of this alternative endpoint. + */ + [noscript] boolean IsSVCDomainNameFailed(in ACString aOwnerName, + in ACString aSVCDomainName); + + /** + * Reset the exclusion list. + * @param aOwnerName + * The owner name of this HTTPS RRs. + */ + [noscript] void ResetExcludedSVCDomainName(in ACString aOwnerName); + + /** + * Returns a string containing the URI currently used by the TRR service. + */ + readonly attribute AUTF8String currentTrrURI; + + /** + * Returns the value of the TRR Service's current default mode. + */ + readonly attribute nsIDNSService_ResolverMode currentTrrMode; + + /** + * The TRRService's current confirmation state. + * This is mostly for testing purposes. + */ + readonly attribute unsigned long currentTrrConfirmationState; + + /** + * @return the hostname of the operating system. + */ + readonly attribute AUTF8String myHostName; + + /** + * returns the current TRR domain. + */ + readonly attribute ACString trrDomain; + + /** + * returns the telemetry key for current TRR domain. + */ + readonly attribute ACString TRRDomainKey; + + /************************************************************************* + * Listed below are the various flags that may be OR'd together to form + * the aFlags parameter passed to asyncResolve() and resolve(). + */ + +%{C++ + static nsIDNSService::DNSFlags GetFlagsFromTRRMode(nsIRequest::TRRMode aMode) { + return static_cast<nsIDNSService::DNSFlags>(static_cast<uint32_t>(aMode) << 11); + } + + static nsIRequest::TRRMode GetTRRModeFromFlags(nsIDNSService::DNSFlags aFlags) { + return static_cast<nsIRequest::TRRMode>((aFlags & RESOLVE_TRR_MODE_MASK) >> 11); + } +%} + +}; + +%{C++ + +/** + * An observer notification for this topic is sent whenever the URI that the + * TRR service is using has changed. + */ +#define NS_NETWORK_TRR_URI_CHANGED_TOPIC "network:trr-uri-changed" + +/** + * An observer notification for this topic is sent whenever the mode that the + * TRR service is using has changed. + */ +#define NS_NETWORK_TRR_MODE_CHANGED_TOPIC "network:trr-mode-changed" + +MOZ_MAKE_ENUM_CLASS_BITWISE_OPERATORS(nsIDNSService::DNSFlags) + +%} |