/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 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/. */

/*
 * browser-specific interface to global history
 */

#include "nsISupports.idl"
#include "nsIGlobalHistory2.idl"

[scriptable, uuid(20d31479-38de-49f4-9300-566d6e834c66)]
interface nsIBrowserHistory : nsISupports
{
    /**
     * Removes a page from global history.
     *
     * @note It is preferrable to use this one rather then RemovePages when
     *       removing less than 10 pages, since it won't start a full batch
     *       operation.
     */
    void removePage(in nsIURI aURI);

    /**
     * Removes a list of pages from global history.
     *
     * @param aURIs
     *        Array of URIs to be removed.
     * @param aLength
     *        Length of the array.
     *
     * @note the removal happens in a batch.
     */
    void removePages([array, size_is(aLength)] in nsIURI aURIs,
                     in unsigned long aLength);

    /**
     * Removes all global history information about pages for a given host.
     *
     * @param aHost
     *        Hostname to be removed.
     *        An empty host name means local files and anything else with no
     *        hostname.  You can also pass in the localized "(local files)"
     *        title given to you from a history query to remove all
     *        history information from local files.
     * @param aEntireDomain
     *        If true, will also delete pages from sub hosts (so if
     *        passed in "microsoft.com" will delete "www.microsoft.com",
     *        "msdn.microsoft.com", etc.).
     *
     * @note The removal happens in a batch.
     */
    void removePagesFromHost(in AUTF8String aHost,
                             in boolean aEntireDomain);

    /**
     * Removes all pages for a given timeframe.
     * Limits are included: aBeginTime <= timeframe <= aEndTime
     *
     * @param aBeginTime
     *        Microseconds from epoch, representing the initial time.
     * @param aEndTime
     *        Microseconds from epoch, representing the final time.
     *
     * @note The removal happens in a batch.
     */
    void removePagesByTimeframe(in PRTime aBeginTime,
                                in PRTime aEndTime);
};