/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* 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 nsIRequest;

/**
 * NetworkZonePolicy is used to permit or deny nsIRequests loading from private
 * IP addresses. Private in this case means RFC1918-like addresses and
 * localhost. Primarily, this is to protect resources held on private
 * networks from being loaded by documents which were loaded from the public
 * internet.
 */

[scriptable, uuid(639a0797-7870-4a37-9110-57ea9f14783f)]
interface nsINetworkZonePolicy : nsISupports
{
  /**
   * Returns true if aRequest can connect to private, RFC1918-like addresses.
   * Implementing classes should query the loadgroup of the request, along with
   * the loadgroup's owning/parent hierarchy, to determine if permission is
   * granted. This should result in requests generated by a public document
   * being restricted to public loads only.
   *
   * @param aRequest  The nsIRequest which is trying to load from a private IP
   *                  address.
   * @returns         True if aRequest has permission to load from a private IP
   *                  address; false if it does not.
   */
  bool checkPrivateNetworkPermission(in nsIRequest aRequest);

  /**
   * Tries to set permission in the loadgroup of aRequest with respect to
   * loading from private IP addresses. Permission will only be set if the
   * loadgroup's ancestors (parent-, owning- and docshell parent loadgroups) all
   * allow private network loads. If permission cannot be set, the function
   * returns silently.
   * Note: only documents should be allowed to set permission for other
   * resource loads in the loadgroup, so aRequest should represent a document
   * load. Non document loads will be ignored and the function will return
   * silently.
   *
   * @param aRequest  The request which is trying to set private load
   *                  permission for its loadgroup.
   * @param aAllowed  True if permission is to be granted; false if not.
   */
  void setPrivateNetworkPermission(in nsIRequest aRequest,
                                   in bool aAllowed);
};
