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
   7 interface nsICancelable;
   8 interface nsIEventTarget;
   9 interface nsIDNSRecord;
  10 interface nsIDNSListener;
  11
  12 %{C++
  13 template<class T> class nsTArray;
  14 namespace mozilla { namespace net {
  15     struct DNSCacheEntries;
  16 } }
  17 %}
  18
  19 [ptr] native EntriesArray(nsTArray<mozilla::net::DNSCacheEntries>);
  20
  21 /**
  22  * nsIDNSService
  23  */
  24 [scriptable, uuid(de5642c6-61fc-4fcf-9a47-03226b0d4e21)]
  25 interface nsIDNSService : nsISupports
  26 {
  27     /**
  28      * kicks off an asynchronous host lookup.
  29      *
  30      * @param aHostName
  31      *        the hostname or IP-address-literal to resolve.
  32      * @param aFlags
  33      *        a bitwise OR of the RESOLVE_ prefixed constants defined below.
  34      * @param aListener
  35      *        the listener to be notified when the result is available.
  36      * @param aListenerTarget
  37      *        optional parameter (may be null).  if non-null, this parameter
  38      *        specifies the nsIEventTarget of the thread on which the
  39      *        listener's onLookupComplete should be called.  however, if this
  40      *        parameter is null, then onLookupComplete will be called on an
  41      *        unspecified thread (possibly recursively).
  42      *
  43      * @return An object that can be used to cancel the host lookup.
  44      */
  45     nsICancelable asyncResolve(in AUTF8String       aHostName,
  46                                in unsigned long     aFlags,
  47                                in nsIDNSListener    aListener,
  48                                in nsIEventTarget    aListenerTarget);
  49
  50     /**
  51      * Attempts to cancel a previously requested async DNS lookup
  52      *
  53      * @param aHostName
  54      *        the hostname or IP-address-literal to resolve.
  55      * @param aFlags
  56      *        a bitwise OR of the RESOLVE_ prefixed constants defined below.
  57      * @param aListener
  58      *        the original listener which was to be notified about the host lookup
  59      *        result - used to match request information to requestor.
  60      * @param aReason
  61      *        nsresult reason for the cancellation
  62      *
  63      * @return An object that can be used to cancel the host lookup.
  64      */
  65     void cancelAsyncResolve(in AUTF8String       aHostName,
  66                             in unsigned long     aFlags,
  67                             in nsIDNSListener    aListener,
  68                             in nsresult          aReason);
  69
  70     /**
  71      * called to synchronously resolve a hostname.  warning this method may
  72      * block the calling thread for a long period of time.  it is extremely
  73      * unwise to call this function on the UI thread of an application.
  74      *
  75      * @param aHostName
  76      *        the hostname or IP-address-literal to resolve.
  77      * @param aFlags
  78      *        a bitwise OR of the RESOLVE_ prefixed constants defined below.
  79      *
  80      * @return DNS record corresponding to the given hostname.
  81      * @throws NS_ERROR_UNKNOWN_HOST if host could not be resolved.
  82      */
  83     nsIDNSRecord resolve(in AUTF8String   aHostName,
  84                          in unsigned long aFlags);
  85
  86     /**
  87      * kicks off an asynchronous host lookup.
  88      *
  89      * This function is identical to asyncResolve except an additional
  90      * parameter aNetwortInterface. If parameter aNetworkInterface is an empty
  91      * string function will return the same result as asyncResolve.
  92      * Setting aNetworkInterface value make only sense for gonk,because it
  93      * an per networking interface query is possible.
  94      */
  95     nsICancelable asyncResolveExtended(in AUTF8String       aHostName,
  96                                        in unsigned long     aFlags,
  97                                        in AUTF8String       aNetworkInterface,
  98                                        in nsIDNSListener    aListener,
  99                                        in nsIEventTarget    aListenerTarget);
 100
 101     /**
 102      * Attempts to cancel a previously requested async DNS lookup
 103      * This is an extended versin with a additional parameter aNetworkInterface
 104      */
 105     void cancelAsyncResolveExtended(in AUTF8String       aHostName,
 106                                     in unsigned long     aFlags,
 107                                     in AUTF8String       aNetworkInterface,
 108                                     in nsIDNSListener    aListener,
 109                                     in nsresult          aReason);
 110
 111     /**
 112      * The method takes a pointer to an nsTArray
 113      * and fills it with cache entry data
 114      * Called by the networking dashboard
 115      */
 116     [noscript] void getDNSCacheEntries(in EntriesArray args);
 117
 118     /**
 119      * @return the hostname of the operating system.
 120      */
 121     readonly attribute AUTF8String myHostName;
 122
 123     /*************************************************************************
 124      * Listed below are the various flags that may be OR'd together to form
 125      * the aFlags parameter passed to asyncResolve() and resolve().
 126      */
 127
 128     /**
 129      * if set, this flag suppresses the internal DNS lookup cache.
 130      */
 131     const unsigned long RESOLVE_BYPASS_CACHE = (1 << 0);
 132
 133     /**
 134      * if set, the canonical name of the specified host will be queried.
 135      */
 136     const unsigned long RESOLVE_CANONICAL_NAME = (1 << 1);
 137
 138     /**
 139      * if set, the query is given lower priority. Medium takes precedence
 140      * if both are used.
 141      */
 142     const unsigned long RESOLVE_PRIORITY_MEDIUM = (1 << 2);
 143     const unsigned long RESOLVE_PRIORITY_LOW    = (1 << 3);
 144
 145     /**
 146      * if set, indicates request is speculative. Speculative requests
 147      * return errors if prefetching is disabled by configuration.
 148      */
 149     const unsigned long RESOLVE_SPECULATE = (1 << 4);
 150
 151     /**
 152      * If set, only IPv4 addresses will be returned from resolve/asyncResolve.
 153      */
 154     const unsigned long RESOLVE_DISABLE_IPV6 = (1 << 5);
 155
 156     /**
 157      * If set, only literals and cached entries will be returned from resolve/
 158      * asyncResolve.
 159      */
 160     const unsigned long RESOLVE_OFFLINE = (1 << 6);
 161
 162     /**
 163      * If set, only IPv6 addresses will be returned from resolve/asyncResolve.
 164      */
 165     const unsigned long RESOLVE_DISABLE_IPV4 = (1 << 7);
 166 };