gecko-dev/netwerk/dns/nsIDNSService.idl

149 lines
5.7 KiB
Plaintext

/* ***** BEGIN LICENSE BLOCK *****
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
* for the specific language governing rights and limitations under the
* License.
*
* The Original Code is Mozilla.
*
* The Initial Developer of the Original Code is
* Netscape Communications Corporation.
* Portions created by the Initial Developer are Copyright (C) 2003
* the Initial Developer. All Rights Reserved.
*
* Contributor(s):
* Gordon Sheridan <gordon@netscape.com>
* IBM Corp.
*
* Alternatively, the contents of this file may be used under the terms of
* either the GNU General Public License Version 2 or later (the "GPL"), or
* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
* in which case the provisions of the GPL or the LGPL are applicable instead
* of those above. If you wish to allow use of your version of this file only
* under the terms of either the GPL or the LGPL, and not to allow others to
* use your version of this file under the terms of the MPL, indicate your
* decision by deleting the provisions above and replace them with the notice
* and other provisions required by the GPL or the LGPL. If you do not delete
* the provisions above, a recipient may use your version of this file under
* the terms of any one of the MPL, the GPL or the LGPL.
*
* ***** END LICENSE BLOCK ***** */
#include "nsISupports.idl"
interface nsICancelable;
interface nsIEventTarget;
interface nsIDNSRecord;
interface nsIDNSListener;
/**
* nsIDNSService
*/
[scriptable, uuid(F6E05CC3-8A13-463D-877F-D59B20B59724)]
interface nsIDNSService : nsISupports
{
/**
* kicks off an asynchronous host lookup.
*
* @param aHostName
* the hostname or IP-address-literal to resolve.
* @param aFlags
* a bitwise OR of the RESOLVE_ prefixed constants defined below.
* @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).
*
* @return An object that can be used to cancel the host lookup.
*/
nsICancelable asyncResolve(in AUTF8String aHostName,
in unsigned long aFlags,
in nsIDNSListener aListener,
in nsIEventTarget aListenerTarget);
/**
* Attempts to cancel a previously requested async DNS lookup
*
* @param aHostName
* the hostname or IP-address-literal to resolve.
* @param aFlags
* a bitwise OR of the RESOLVE_ prefixed constants defined below.
* @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
*
* @return An object that can be used to cancel the host lookup.
*/
void cancelAsyncResolve(in AUTF8String aHostName,
in unsigned long aFlags,
in nsIDNSListener aListener,
in nsresult aReason);
/**
* called to synchronously resolve a hostname. warning this method may
* block the calling thread for a long period of time. it is extremely
* unwise to call this function on the UI thread of an application.
*
* @param aHostName
* the hostname or IP-address-literal to resolve.
* @param aFlags
* a bitwise OR of the RESOLVE_ prefixed constants defined below.
*
* @return DNS record corresponding to the given hostname.
* @throws NS_ERROR_UNKNOWN_HOST if host could not be resolved.
*/
nsIDNSRecord resolve(in AUTF8String aHostName,
in unsigned long aFlags);
/**
* @return the hostname of the operating system.
*/
readonly attribute AUTF8String myHostName;
/*************************************************************************
* Listed below are the various flags that may be OR'd together to form
* the aFlags parameter passed to asyncResolve() and resolve().
*/
/**
* if set, this flag suppresses the internal DNS lookup cache.
*/
const unsigned long RESOLVE_BYPASS_CACHE = (1 << 0);
/**
* if set, the canonical name of the specified host will be queried.
*/
const unsigned long RESOLVE_CANONICAL_NAME = (1 << 1);
/**
* if set, the query is given lower priority. Medium takes precedence
* if both are used.
*/
const unsigned long RESOLVE_PRIORITY_MEDIUM = (1 << 2);
const unsigned long RESOLVE_PRIORITY_LOW = (1 << 3);
/**
* if set, indicates request is speculative. Speculative requests
* return errors if prefetching is disabled by configuration.
*/
const unsigned long RESOLVE_SPECULATE = (1 << 4);
/**
* If set, only IPv4 addresses will be returned from resolve/asyncResolve.
*/
const unsigned long RESOLVE_DISABLE_IPV6 = (1 << 5);
};