michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsICancelable;
michael@0: interface nsIEventTarget;
michael@0: interface nsIDNSRecord;
michael@0: interface nsIDNSListener;
michael@0: 
michael@0: %{C++
michael@0: template<class T> class nsTArray;
michael@0: namespace mozilla { namespace net {
michael@0:     struct DNSCacheEntries;
michael@0: } }
michael@0: %}
michael@0: 
michael@0: [ptr] native EntriesArray(nsTArray<mozilla::net::DNSCacheEntries>);
michael@0: 
michael@0: /**
michael@0:  * nsIDNSService
michael@0:  */
michael@0: [scriptable, uuid(f1971942-19db-44bf-81e8-d15df220a39f)]
michael@0: interface nsIDNSService : nsISupports
michael@0: {
michael@0:     /**
michael@0:      * kicks off an asynchronous host lookup.
michael@0:      *
michael@0:      * @param aHostName
michael@0:      *        the hostname or IP-address-literal to resolve.
michael@0:      * @param aFlags
michael@0:      *        a bitwise OR of the RESOLVE_ prefixed constants defined below.
michael@0:      * @param aListener
michael@0:      *        the listener to be notified when the result is available.
michael@0:      * @param aListenerTarget
michael@0:      *        optional parameter (may be null).  if non-null, this parameter
michael@0:      *        specifies the nsIEventTarget of the thread on which the
michael@0:      *        listener's onLookupComplete should be called.  however, if this
michael@0:      *        parameter is null, then onLookupComplete will be called on an
michael@0:      *        unspecified thread (possibly recursively).
michael@0:      *
michael@0:      * @return An object that can be used to cancel the host lookup.
michael@0:      */
michael@0:     nsICancelable asyncResolve(in AUTF8String       aHostName,
michael@0:                                in unsigned long     aFlags,
michael@0:                                in nsIDNSListener    aListener,
michael@0:                                in nsIEventTarget    aListenerTarget);
michael@0: 
michael@0:     /**
michael@0:      * Attempts to cancel a previously requested async DNS lookup
michael@0:      *
michael@0:      * @param aHostName
michael@0:      *        the hostname or IP-address-literal to resolve.
michael@0:      * @param aFlags
michael@0:      *        a bitwise OR of the RESOLVE_ prefixed constants defined below.
michael@0:      * @param aListener
michael@0:      *        the original listener which was to be notified about the host lookup
michael@0:      *        result - used to match request information to requestor.
michael@0:      * @param aReason
michael@0:      *        nsresult reason for the cancellation
michael@0:      *
michael@0:      * @return An object that can be used to cancel the host lookup.
michael@0:      */
michael@0:     void cancelAsyncResolve(in AUTF8String       aHostName,
michael@0:                             in unsigned long     aFlags,
michael@0:                             in nsIDNSListener    aListener,
michael@0:                             in nsresult          aReason);
michael@0:     
michael@0:     /**
michael@0:      * called to synchronously resolve a hostname.  warning this method may
michael@0:      * block the calling thread for a long period of time.  it is extremely
michael@0:      * unwise to call this function on the UI thread of an application.
michael@0:      *
michael@0:      * @param aHostName
michael@0:      *        the hostname or IP-address-literal to resolve.
michael@0:      * @param aFlags
michael@0:      *        a bitwise OR of the RESOLVE_ prefixed constants defined below.
michael@0:      *
michael@0:      * @return DNS record corresponding to the given hostname.
michael@0:      * @throws NS_ERROR_UNKNOWN_HOST if host could not be resolved.
michael@0:      */
michael@0:     nsIDNSRecord resolve(in AUTF8String   aHostName,
michael@0:                          in unsigned long aFlags);
michael@0: 
michael@0:     /**
michael@0:      * The method takes a pointer to an nsTArray
michael@0:      * and fills it with cache entry data
michael@0:      * Called by the networking dashboard
michael@0:      */
michael@0:     [noscript] void getDNSCacheEntries(in EntriesArray args);
michael@0: 
michael@0:     /**
michael@0:      * @return the hostname of the operating system.
michael@0:      */
michael@0:     readonly attribute AUTF8String myHostName;
michael@0: 
michael@0:     /*************************************************************************
michael@0:      * Listed below are the various flags that may be OR'd together to form
michael@0:      * the aFlags parameter passed to asyncResolve() and resolve().
michael@0:      */
michael@0: 
michael@0:     /**
michael@0:      * if set, this flag suppresses the internal DNS lookup cache.
michael@0:      */
michael@0:     const unsigned long RESOLVE_BYPASS_CACHE = (1 << 0);
michael@0: 
michael@0:     /**
michael@0:      * if set, the canonical name of the specified host will be queried.
michael@0:      */
michael@0:     const unsigned long RESOLVE_CANONICAL_NAME = (1 << 1);
michael@0: 
michael@0:     /**
michael@0:      * if set, the query is given lower priority. Medium takes precedence
michael@0:      * if both are used.
michael@0:      */
michael@0:     const unsigned long RESOLVE_PRIORITY_MEDIUM = (1 << 2);
michael@0:     const unsigned long RESOLVE_PRIORITY_LOW    = (1 << 3);
michael@0: 
michael@0:     /**
michael@0:      * if set, indicates request is speculative. Speculative requests 
michael@0:      * return errors if prefetching is disabled by configuration.
michael@0:      */
michael@0:     const unsigned long RESOLVE_SPECULATE = (1 << 4);
michael@0: 
michael@0:     /**
michael@0:      * If set, only IPv4 addresses will be returned from resolve/asyncResolve.
michael@0:      */
michael@0:     const unsigned long RESOLVE_DISABLE_IPV6 = (1 << 5);
michael@0: 
michael@0:     /**
michael@0:      * If set, only literals and cached entries will be returned from resolve/
michael@0:      * asyncResolve.
michael@0:      */
michael@0:     const unsigned long RESOLVE_OFFLINE = (1 << 6);
michael@0: 
michael@0:     /**
michael@0:      * If set, only IPv6 addresses will be returned from resolve/asyncResolve.
michael@0:      */
michael@0:     const unsigned long RESOLVE_DISABLE_IPV4 = (1 << 7);
michael@0: };