DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (4a108e94d3e2)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIURI;
interface nsIDOMWindow;
interface nsIChannel;

/**
 * Utility functions for determining whether a given URI, channel, or window
 * hierarchy is third party with respect to a known URI.
 */
[scriptable, uuid(b711bd7f-0674-49be-ae77-f221db5f7b6c)]
interface mozIThirdPartyUtil : nsISupports
{
  /**
   * isThirdPartyURI
   *
   * Determine whether two URIs are third party with respect to each other.
   * This is determined by computing the base domain for both URIs. If they can
   * be determined, and the base domains match, the request is defined as first
   * party. If it cannot be determined because one or both URIs do not have a
   * base domain (for instance, in the case of IP addresses, host aliases such
   * as 'localhost', or a file:// URI), an exact string comparison on host is
   * performed.
   *
   * For example, the URI "http://mail.google.com/" is not third party with
   * respect to "http://images.google.com/", but "http://mail.yahoo.com/" and
   * "http://192.168.1.1/" are.
   *
   * @return true if aFirstURI is third party with respect to aSecondURI.
   *
   * @throws if either URI is null, has a malformed host, or has an empty host
   *         and is not a file:// URI.
   */
  boolean isThirdPartyURI(in nsIURI aFirstURI, in nsIURI aSecondURI);

  /**
   * isThirdPartyWindow
   *
   * Determine whether the given window hierarchy is third party. This is done
   * as follows:
   *
   * 1) Obtain the URI of the principal associated with 'aWindow'. Call this the
   *    'bottom URI'.
   * 2) If 'aURI' is provided, determine if it is third party with respect to
   *    the bottom URI. If so, return.
   * 3) Find the same-type parent window, if there is one, and its URI.
   *    Determine whether it is third party with respect to the bottom URI. If
   *    so, return.
   *
   * Therefore, each level in the window hierarchy is tested. (This means that
   * nested iframes with different base domains, even though the bottommost and
   * topmost URIs might be equal, will be considered third party.)
   *
   * @param aWindow
   *        The bottommost window in the hierarchy.
   * @param aURI
   *        A URI to test against. If null, the URI of the principal
   *        associated with 'aWindow' will be used.
   *
   * For example, if 'aURI' is "http://mail.google.com/", 'aWindow' has a URI
   * of "http://google.com/", and its parent is the topmost content window with
   * a URI of "http://mozilla.com", the result will be true.
   *
   * @return true if 'aURI' is third party with respect to any of the URIs
   *         associated with aWindow and its same-type parents.
   *
   * @throws if aWindow is null; the same-type parent of any window in the
   *         hierarchy cannot be determined; or the URI associated with any
   *         window in the hierarchy is null, has a malformed host, or has an
   *         empty host and is not a file:// URI.
   *
   * @see isThirdPartyURI
   */
  boolean isThirdPartyWindow(in nsIDOMWindow aWindow, [optional] in nsIURI aURI);

  /**
   * isThirdPartyChannel
   *
   * Determine whether the given channel and its content window hierarchy is
   * third party. This is done as follows:
   *
   * 1) If 'aChannel' is an nsIHttpChannel and has the
   *    'forceAllowThirdPartyCookie' property set, then:
   *    a) If 'aURI' is null, return false.
   *    b) Otherwise, find the URI of the channel, determine whether it is
   *       foreign with respect to 'aURI', and return.
   * 2) Find the URI of the channel and determine whether it is third party with
   *    respect to the URI of the channel. If so, return.
   * 3) Obtain the bottommost nsIDOMWindow, and its same-type parent if it
   *    exists, from the channel's notification callbacks. Then:
   *    a) If the parent is the same as the bottommost window, and the channel
   *       has the LOAD_DOCUMENT_URI flag set, return false. This represents the
   *       case where a toplevel load is occurring and the window's URI has not
   *       yet been updated. (We have already checked that 'aURI' is not foreign
   *       with respect to the channel URI.)
   *    b) Otherwise, return the result of isThirdPartyWindow with arguments
   *       of the channel's bottommost window and the channel URI, respectively.
   *
   * Therefore, both the channel's URI and each level in the window hierarchy
   * associated with the channel is tested.
   *
   * @param aChannel
   *        The channel associated with the load.
   * @param aURI
   *        A URI to test against. If null, the URI of the channel will be used.
   *
   * For example, if 'aURI' is "http://mail.google.com/", 'aChannel' has a URI
   * of "http://google.com/", and its parent is the topmost content window with
   * a URI of "http://mozilla.com", the result will be true.
   *
   * @return true if aURI is third party with respect to the channel URI or any
   *         of the URIs associated with the same-type window hierarchy of the
   *         channel.
   *
   * @throws if 'aChannel' is null; the channel has no notification callbacks or
   *         an associated window; or isThirdPartyWindow throws.
   *
   * @see isThirdPartyWindow
   */
  boolean isThirdPartyChannel(in nsIChannel aChannel, [optional] in nsIURI aURI);

  /**
   * getBaseDomain
   *
   * Get the base domain for aHostURI; e.g. for "www.bbc.co.uk", this would be
   * "bbc.co.uk". Only properly-formed URI's are tolerated, though a trailing
   * dot may be present. If aHostURI is an IP address, an alias such as
   * 'localhost', an eTLD such as 'co.uk', or the empty string, aBaseDomain will
   * be the exact host. The result of this function should only be used in exact
   * string comparisons, since substring comparisons will not be valid for the
   * special cases elided above.
   *
   * @param aHostURI
   *        The URI to analyze.
   *
   * @return the base domain.
   */
  AUTF8String getBaseDomain(in nsIURI aHostURI);

  /**
   * getURIFromWindow
   *
   * Returns the URI associated with the script object principal for the
   * window.
   */
  nsIURI getURIFromWindow(in nsIDOMWindow aWindow);

  /**
   * getTopWindowForChannel
   *
   * Returns the top-level window associated with the given channel.
   */
  nsIDOMWindow getTopWindowForChannel(in nsIChannel aChannel);
};

%{ C++
/**
 * The mozIThirdPartyUtil implementation is an XPCOM service registered
 * under the ContractID:
 */
#define THIRDPARTYUTIL_CONTRACTID "@mozilla.org/thirdpartyutil;1"
%}