/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 * vim: ft=cpp tw=78 sw=2 et ts=2 sts=2 cin
 * 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 nsIDOMWindow;
interface nsIURI;

/**
 * An nsILoadContext represents the context of a load.  This interface
 * can be queried for various information about where the load is
 * happening.
 */
[scriptable, uuid(386806c3-c4cb-4b3d-b05d-c08ea10f5585)]
interface nsILoadContext : nsISupports
{
  /**
   * associatedWindow is the window with which the load is associated, if any.
   * Note that the load may be triggered by a document which is different from
   * the document in associatedWindow, and in fact the source of the load need
   * not be same-origin with the document in associatedWindow.  This attribute
   * may be null if there is no associated window.
   */
  readonly attribute nsIDOMWindow associatedWindow;

  /**
   * topWindow is the top window which is of same type as associatedWindow.
   * This is equivalent to associatedWindow.top, but is provided here as a
   * convenience.  All the same caveats as associatedWindow of apply, of
   * course.  This attribute may be null if there is no associated window.
   */
  readonly attribute nsIDOMWindow topWindow;

  /**
   * Check whether the load is happening in a particular type of application.
   *
   * @param an application type.  For now, the constants to be passed here are
   *        the nsIDocShell APP_TYPE_* constants.
   *
   * @return whether there is some ancestor of the associatedWindow that is of
   *         the given app type.
   */
  boolean isAppOfType(in unsigned long appType);

  /**
   * True if the load context is content (as opposed to chrome).  This is
   * determined based on the type of window the load is performed in, NOT based
   * on any URIs that might be around.
   */
  readonly attribute boolean isContent;

  /*
   * Attribute that determines if private browsing should be used.
   */
  attribute boolean usePrivateBrowsing;

%{C++
  /**
   * De-XPCOMed getter to make call-sites cleaner.
   */
  bool UsePrivateBrowsing() {
    bool usingPB;
    GetUsePrivateBrowsing(&usingPB);
    return usingPB;
  }
%}

  /**
   * Returns true iif the load is occurring inside a browser element.
   */
  readonly attribute boolean isInBrowserElement;

  /**
   * Returns the app id of the app the load is occurring is in. Returns
   * nsIScriptSecurityManager::NO_APP_ID if the load is not part of an app.
   */
  readonly attribute unsigned long appId;

  /**
   * Get the extended origin of a channel in this load context.
   * The extended origin is a string that has more information than the origin
   * and can be used to isolate data or permissions between different
   * principals while taking into account parameters like the app id or the
   * fact that the load is taking place in a mozbrowser.
   *
   * In some cases this function will simply return the origin for the
   * channel's URI.
   *
   * The extendedOrigin is intended to be an opaque identifier. It is
   * currently "human-readable" but no callers should assume it will stay
   * as-is and it might be crypto-hashed at some point.
   */
  AUTF8String GetExtendedOrigin(in nsIURI channel);
};