/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* vim:expandtab:shiftwidth=4:tabstop=4:
 */
/* 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 "nsIIOService.idl"

interface nsIDOMNode;
interface nsIPrincipal;

/**
 * nsIIOService2 extends nsIIOService
 */
[scriptable, uuid(52c5804b-0d3c-4d4f-8654-1c36fd310e69)]
interface nsIIOService2 : nsIIOService
{
  /**
   * While this is set, IOService will monitor an nsINetworkLinkService
   * (if available) and set its offline status to "true" whenever
   * isLinkUp is false.
   *
   * Applications that want to control changes to the IOService's offline
   * status should set this to false, watch for network:link-status-changed
   * broadcasts, and change nsIIOService::offline as they see fit. Note
   * that this means during application startup, IOService may be offline
   * if there is no link, until application code runs and can turn off
   * this management.
   */
  attribute boolean manageOfflineStatus;

  /**
   * Creates a channel for a given URI.
   *
   * @param aURI
   *        nsIURI from which to make a channel
   * @param aProxyURI
   *        nsIURI to use for proxy resolution. Can be null in which
   *        case aURI is used
   * @param aProxyFlags flags from nsIProtocolProxyService to use
   *        when resolving proxies for this new channel
   * @param aLoadingNode
   *        The loadingDocument of the channel.
   *        The element or document where the result of this request will be
   *        used. This is the document/element that will get access to the
   *        result of this request. For example for an image load, it's the
   *        document in which the image will be loaded. And for a CSS
   *        stylesheet it's the document whose rendering will be affected by
   *        the stylesheet.
   *        If possible, pass in the element which is performing the load. But
   *        if the load is coming from a JS API (such as XMLHttpRequest) or if
   *        the load might be coalesced across multiple elements (such as
   *        for <img>) then pass in the Document node instead.
   *        For loads that are not related to any document, such as loads coming
   *        from addons or internal browser features, use null here.
   * @param aLoadingPrincipal
   *        The loadingPrincipal of the channel.
   *        The principal of the document where the result of this request will
   *        be used.
   *        This defaults to the principal of aLoadingNode, so when aLoadingNode
   *        is passed this can be left as null. However for loads where
   *        aLoadingNode is null this argument must be passed.
   *        For example for loads from a WebWorker, pass the principal
   *        of that worker. For loads from an addon or from internal browser
   *        features, pass the system principal.
   *        This principal should almost always be the system principal if
   *        aLoadingNode is null. The only exception to this is for loads
   *        from WebWorkers since they don't have any nodes to be passed as
   *        aLoadingNode.
   *        Please note, aLoadingPrincipal is *not* the principal of the
   *        resource being loaded. But rather the principal of the context
   *        where the resource will be used.
   * @param aTriggeringPrincipal
   *        The triggeringPrincipal of the load.
   *        The triggeringPrincipal is the principal of the resource that caused
   *        this particular URL to be loaded.
   *        Most likely the triggeringPrincipal and the loadingPrincipal are
   *        identical, in which case the triggeringPrincipal can be left out.
   *        In some cases the loadingPrincipal and the triggeringPrincipal are
   *        different however, e.g. a stylesheet may import a subresource. In
   *        that case the principal of the stylesheet which contains the
   *        import command is the triggeringPrincipal, and the principal of
   *        the document whose rendering is affected is the loadingPrincipal.
   * @param aSecurityFlags
   *        The securityFlags of the channel.
   *        Any of the securityflags defined in nsILoadInfo.idl
   * @param aContentPolicyType
   *        The contentPolicyType of the channel.
   *        Any of the content types defined in nsIContentPolicy.idl
   * @return reference to the new nsIChannel object
   *
   * Please note, if you provide both a loadingNode and a loadingPrincipal,
   * then loadingPrincipal must be equal to loadingNode->NodePrincipal().
   * But less error prone is to just supply a loadingNode.
   */
  nsIChannel newChannelFromURIWithProxyFlags2(in nsIURI aURI,
                                              in nsIURI aProxyURI,
                                              in unsigned long aProxyFlags,
                                              in nsIDOMNode aLoadingNode,
                                              in nsIPrincipal aLoadingPrincipal,
                                              in nsIPrincipal aTriggeringPrincipal,
                                              in unsigned long aSecurityFlags,
                                              in unsigned long aContentPolicyType);

  /**
   * Creates a channel for a given URI.
   *
   * @param aURI nsIURI from which to make a channel
   * @param aProxyURI nsIURI to use for proxy resolution. Can be null in which
   *        case aURI is used
   * @param aProxyFlags flags from nsIProtocolProxyService to use
   *        when resolving proxies for this new channel
   * @return reference to the new nsIChannel object
   */
  nsIChannel newChannelFromURIWithProxyFlags(in nsIURI aURI,
                                             in nsIURI aProxyURI,
                                             in unsigned long aProxyFlags);
};