netwerk/dns/nsIDNSRecord.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 #include "nsIRequest.idl"
   7 #include "nsITRRSkipReason.idl"
   8
   9 %{ C++
  10 namespace mozilla {
  11 namespace net {
  12 union NetAddr;
  13 }
  14 }
  15 #include "nsTArrayForwardDeclare.h"
  16 %}
  17 native NetAddr(mozilla::net::NetAddr);
  18 [ref] native nsNetAddrTArrayRef(nsTArray<mozilla::net::NetAddr>);
  19 interface nsINetAddr;
  20
  21 /**
  22  * nsIDNSRecord
  23  *
  24  * this interface represents the result of a DNS lookup.  since a DNS
  25  * query may return more than one resolved IP address, the record acts
  26  * like an enumerator, allowing the caller to easily step through the
  27  * list of IP addresses.
  28  */
  29 [scriptable, uuid(f92228ae-c417-4188-a604-0830a95e7eb9)]
  30 interface nsIDNSRecord : nsISupports
  31 {
  32 };
  33
  34 [scriptable, uuid(cb260e20-943f-4309-953b-78c90d3a7638)]
  35 interface nsIDNSAddrRecord : nsIDNSRecord
  36 {
  37     /**
  38      * @return the canonical hostname for this record.  this value is empty if
  39      * the record was not fetched with the RESOLVE_CANONICAL_NAME flag.
  40      *
  41      * e.g., www.mozilla.org --> rheet.mozilla.org
  42      *
  43      * That the result, if IDN will be returned as punycode.
  44      * e.g., élève.w3c-test.org --> xn--lve-6lad.w3c-test.org
  45      */
  46     readonly attribute ACString canonicalName;
  47
  48     /**
  49      * this function copies the value of the next IP address into the
  50      * given NetAddr struct and increments the internal address iterator.
  51      *
  52      * @param aPort
  53      *        A port number to initialize the NetAddr with.
  54      *
  55      * @throws NS_ERROR_NOT_AVAILABLE if there is not another IP address in
  56      * the record.
  57      */
  58     [noscript] NetAddr getNextAddr(in uint16_t aPort);
  59
  60     /**
  61      * this function copies the value of all working members of the RR
  62      * set into the output array.
  63      *
  64      * @param aAddressArray
  65      *        The result set
  66      */
  67     [noscript] void getAddresses(out nsNetAddrTArrayRef aAddressArray);
  68
  69     /**
  70      * this function returns the value of the next IP address as a
  71      * scriptable address and increments the internal address iterator.
  72      *
  73      * @param aPort
  74      *        A port number to initialize the nsINetAddr with.
  75      *
  76      * @throws NS_ERROR_NOT_AVAILABLE if there is not another IP address in
  77      * the record.
  78      */
  79     nsINetAddr getScriptableNextAddr(in uint16_t aPort);
  80
  81     /**
  82      * this function returns the value of the next IP address as a
  83      * string and increments the internal address iterator.
  84      *
  85      * @throws NS_ERROR_NOT_AVAILABLE if there is not another IP address in
  86      * the record.
  87      */
  88     ACString getNextAddrAsString();
  89
  90     /**
  91      * this function returns true if there is another address in the record.
  92      */
  93     boolean hasMore();
  94
  95     /**
  96      * this function resets the internal address iterator to the first
  97      * address in the record.
  98      */
  99     void rewind();
 100
 101     /**
 102      * This function indicates that the last address obtained via getNextAddr*()
 103      * was not usuable and should be skipped in future uses of this
 104      * record if other addresses are available.
 105      *
 106      * @param aPort is the port number associated with the failure, if any.
 107      *        It may be zero if not applicable.
 108      */
 109     void reportUnusable(in uint16_t aPort);
 110
 111     /**
 112      * Record retreived with TRR.
 113      */
 114     bool IsTRR();
 115
 116     /**
 117      * Record is resolved in socket process.
 118      */
 119     bool resolvedInSocketProcess();
 120
 121     /**
 122      * This attribute is only set if TRR is used and it measures time between
 123      * asyncOpen on a channel and the time parsing of response if done.
 124      * Thee time is measured in milliseconds.
 125      */
 126     readonly attribute double trrFetchDuration;
 127
 128     /**
 129      * This attribute is only set if TRR is used and it measures time between
 130      * sending a request and the time response is received from the network.
 131      * This time is similat to the time above, but exludes a time needed to
 132      * make a connection and a time neededto parse results (this also does not
 133      * include delays that may be introduce because parsing is perform on the main
 134      * thread).
 135      * Thee time is measured in milliseconds.
 136      */
 137     readonly attribute double trrFetchDurationNetworkOnly;
 138
 139     /**
 140      * The TRR mode this record is used.
 141      */
 142     readonly attribute nsIRequest_TRRMode effectiveTRRMode;
 143
 144     /**
 145      * If the DNS request didn't use TRR, this value
 146      * contains the reason why that was skipped.
 147      */
 148     readonly attribute nsITRRSkipReason_value trrSkipReason;
 149
 150     /**
 151      * Returns the ttl of this record.
 152      */
 153     readonly attribute uint32_t ttl;
 154 };