/* 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"

[scriptable, uuid(4b731983-9542-49f4-b16b-de68ad1c2068)]
interface nsIPrivateBrowsingService : nsISupports
{
    // When read, determines whether the private browsing mode is currently
    // active.  Setting to true enters the private browsing mode, and setting
    // to false leaves the private browsing mode.
    // Setting this value while handling one of the notifications generated
    // by the private browsing service throws NS_ERROR_FAILURE.
    attribute boolean privateBrowsingEnabled;

    // Determine whether the private browsing mode has been started
    // automatically at application startup.
    // This value will never be true if privateBrowsingEnabled is false.
    readonly attribute boolean autoStarted;

    // Determine whether the last private browsing transition was performed through
    // the command line (using either the -private or -private-toggle switches).
    readonly attribute boolean lastChangedByCommandLine;

    /**
     * Removes all data stored for a given domain.  This includes all data for
     * subdomains of the given domain.
     *
     * @param aDomain
     *        The domain that will have its data removed.
     */
    void removeDataFromDomain(in AUTF8String aDomain);
};

%{C++
/**
 * Private Browsing service notifications:
 *
 * - NS_PRIVATE_BROWSING_REQUEST_TOPIC:
 *   The data parameter determines which kind of request this represents:
 * --- NS_PRIVATE_BROWSING_ENTER:
 *     We send this notification before switching to the private browsing mode.
 *     The subject parameter is set to a nsISupportsPRBool, which observers can
 *     set to true to prevent the switch to the private browsing mode.
 * --- NS_PRIVATE_BROWSING_LEAVE:
 *     We send this notification before leaving the private browsing mode.
 *     The subject parameter is set to a nsISupportsPRBool, which observers can
 *     set to true to prevent leaving the private browsing mode.
 *
 * - NS_PRIVATE_BROWSING_SWITCH_TOPIC:
 *   The data parameter determines which kind of switch this represents:
 * --- NS_PRIVATE_BROWSING_ENTER:
 *     We send this notification while switching to the private browsing mode.
 * --- NS_PRIVATE_BROWSING_LEAVE:
 *     We send this notification while leaving the private browsing mode.
 */
#define NS_PRIVATE_BROWSING_SWITCH_TOPIC  "private-browsing"
#define NS_PRIVATE_BROWSING_REQUEST_TOPIC "private-browsing-cancel-vote"
#define NS_PRIVATE_BROWSING_ENTER         "enter"
#define NS_PRIVATE_BROWSING_LEAVE         "exit"
%}