netwerk/dns/nsIDNSService.idl@b8a032363ba2
netwerk/dns/nsIDNSService.idl
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
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/. */
5 #include "nsISupports.idl"
7 interface nsICancelable;
8 interface nsIEventTarget;
9 interface nsIDNSRecord;
10 interface nsIDNSListener;
12 %{C++
13 template<class T> class nsTArray;
14 namespace mozilla { namespace net {
15 struct DNSCacheEntries;
16 } }
17 %}
19 [ptr] native EntriesArray(nsTArray<mozilla::net::DNSCacheEntries>);
21 /**
22 * nsIDNSService
23 */
24 [scriptable, uuid(f1971942-19db-44bf-81e8-d15df220a39f)]
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);
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);
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);
86 /**
87 * The method takes a pointer to an nsTArray
88 * and fills it with cache entry data
89 * Called by the networking dashboard
90 */
91 [noscript] void getDNSCacheEntries(in EntriesArray args);
93 /**
94 * @return the hostname of the operating system.
95 */
96 readonly attribute AUTF8String myHostName;
98 /*************************************************************************
99 * Listed below are the various flags that may be OR'd together to form
100 * the aFlags parameter passed to asyncResolve() and resolve().
101 */
103 /**
104 * if set, this flag suppresses the internal DNS lookup cache.
105 */
106 const unsigned long RESOLVE_BYPASS_CACHE = (1 << 0);
108 /**
109 * if set, the canonical name of the specified host will be queried.
110 */
111 const unsigned long RESOLVE_CANONICAL_NAME = (1 << 1);
113 /**
114 * if set, the query is given lower priority. Medium takes precedence
115 * if both are used.
116 */
117 const unsigned long RESOLVE_PRIORITY_MEDIUM = (1 << 2);
118 const unsigned long RESOLVE_PRIORITY_LOW = (1 << 3);
120 /**
121 * if set, indicates request is speculative. Speculative requests
122 * return errors if prefetching is disabled by configuration.
123 */
124 const unsigned long RESOLVE_SPECULATE = (1 << 4);
126 /**
127 * If set, only IPv4 addresses will be returned from resolve/asyncResolve.
128 */
129 const unsigned long RESOLVE_DISABLE_IPV6 = (1 << 5);
131 /**
132 * If set, only literals and cached entries will be returned from resolve/
133 * asyncResolve.
134 */
135 const unsigned long RESOLVE_OFFLINE = (1 << 6);
137 /**
138 * If set, only IPv6 addresses will be returned from resolve/asyncResolve.
139 */
140 const unsigned long RESOLVE_DISABLE_IPV4 = (1 << 7);
141 };
