path: root/netwerk/dns/nsIDNSService.idl

/* 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)

%}