nsIDNSService

netwerk/dns/nsIDNSService.idlScriptable

Provides domain name resolution service.

Inherits from: nsISupports Last changed in Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

Implemented by: @mozilla.org/network/dns-service;1. To access the service, use:

var dnsService = Components.classes["@mozilla.org/network/dns-service;1"]
                 .createInstance(Components.interfaces.nsIDNSService);

Note: Starting in Gecko 7.0, the "happy eyeballs" strategy is used to reduce lengthy timeouts when attempting backup connections during attempts to connect from clients that have broken IPv6 connectivity. This is done by disabling IPv6 on backup connections.

Method overview

nsICancelable asyncResolve(in AUTF8String aHostName, in unsigned long aFlags, in nsIDNSListener aListener, in nsIEventTarget aListenerTarget);

void init(); Obsolete since Gecko 1.8

nsIDNSRecord resolve(in AUTF8String aHostName, in unsigned long aFlags);

void shutdown(); Obsolete since Gecko 1.8

Attributes

Attribute	Type	Description
`myHostName`	`AUTF8String`	Read only.

Constants

Resolve flag constants

Various flags that may be ORed together to form the aFlags parameter passed to asyncResolve() and resolve().

Constant	Value	Description
`RESOLVE_BYPASS_CACHE`	`(1 << 0)`	This flag suppresses the internal DNS lookup cache.
`RESOLVE_CANONICAL_NAME`	`(1 << 1)`	The canonical name of the specified host will be queried.
`RESOLVE_PRIORITY_MEDIUM`	`(1 << 2)`	The query is given medium priority. If used with low, medium takes precedence.
`RESOLVE_PRIORITY_LOW`	`(1 << 3)`	The query is given lower priority. If used with medium, medium takes precedence.
`RESOLVE_SPECULATE`	`(1 << 4)`	Indicates request is speculative. Speculative requests return errors if prefetching is disabled by configuration.
`RESOLVE_DISABLE_IPV6`	`(1 << 5)`	If this flag is set, only IPv4 addresses will be returned by `asyncResolve()` and `resolve()`.

Methods

asyncResolve()

Begins off an asynchronous host lookup. A specified nsIDNSListener is invoked when the resolution process is completed.

nsICancelable asyncResolve(
  in AUTF8String aHostName,
  in unsigned long aFlags,
  in nsIDNSListener aListener,
  in nsIEventTarget aListenerTarget
);

Parameters

aHostName: The host name or IP-address-literal to resolve.
aFlags: A bitwise OR of the Resolve flag constants.
aListener: The listener to be notified when the result is available.
aListenerTarget: Optional parameter (may be null). If not null, this parameter specifies the nsIEventTarget of the thread on which the listener's onLookupComplete should be called. If this parameter is null, then onLookupComplete will be called on an unspecified thread (possibly recursively).

Return value

An object that can be used to cancel the host lookup.

init()

Obsolete since Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

Called to initialize the DNS service.

void init();

Parameters

None.

resolve()

Called to synchronously resolve a host name. Warning this method may block the calling thread for a long period of time. It is extremely unwise to call this function on the User Interface thread of an application.

nsIDNSRecord resolve(
  in AUTF8String aHostName,
  in unsigned long aFlags
);

Parameters

aHostName: The host name or IP-address-literal to resolve.
aFlags: A bitwise OR of the Resolve flag constants.

Return value

DNS record corresponding to the given host name.

Exceptions thrown

NS_ERROR_UNKNOWN_HOST: If host could not be resolved.

shutdown()

Obsolete since Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

Called to shutdown the DNS service. Any pending asynchronous requests will be canceled, and the local cache of DNS records will be cleared.

Note: The operating system may still have its own cache of DNS records, which would be unaffected by this method.

void shutdown();

Parameters

None.

Example

let DnsService = Components.classes["@mozilla.org/network/dns-service;1"]
                 .createInstance(Components.interfaces.nsIDNSService);

let Thread = Components.classes["@mozilla.org/thread-manager;1"]
             .getService(Components.interfaces.nsIThreadManager).currentThread;

let host = "www.mozilla.org";

let Listener = {
  onLookupComplete: function(request, record, status) {
    if (!Components.isSuccessCode(status)) {
      // Handle error here
      return;
    }
    let address = record.getNextAddrAsString();
    console.log(host + " = " + address);
  }
};

DnsService.asyncResolve(host, 0, Listener, Thread);