/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 1998
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

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

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

[scriptable, uuid(d092f5a5-33a8-456c-ac89-6ae6f880bd04)]
interface nsIBrowserHistory : nsIGlobalHistory2
{
    /**
     * Used by the History migrator to add a page to global history, with a
     * specific title and last visit time.
     *
     * @param aURI
     *        URI of the page to be added.
     * @param aTitle
     *        Title of the page.
     * @param aLastvisited
     *        Microseconds from epoch representing the last visit time.
     */
    void addPageWithDetails(in nsIURI aURI,
                            in wstring aTitle,
                            in long long aLastVisited);

    /**
     * Indicates if there are entries in global history.
     *
     * @note For performance reasons this is not the real number of entries.
     *       It will instead evaluate to 0 for no entries, 1 otherwise.
     */
    readonly attribute PRUint32 count;

    /**
     * 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 long long aBeginTime,
                                in long long aEndTime);

    /**
     * Removes all visits in a given timeframe.
     * Limits are included: aBeginTime <= timeframe <= aEndTime.
     * Any pages that becomes unvisited as a result will also be deleted.
     *
     * @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 removeVisitsByTimeframe(in long long aBeginTime,
                                 in long long aEndTime);

    /**
     * Removes all existing pages from global history.
     * Visits are removed synchronously, but pages are expired asynchronously
     * off the main-thread.
     *
     * @note The removal happens in a batch. Single removals are not notified,
     *       instead an onClearHistory notification is sent to
     *       nsINavHistoryObserver implementers.
     */
    void removeAllPages();

    /**
     * Hides the specified URL from being enumerated (and thus displayed in
     * the UI).
     *
     * @param aURI
     *        URI of the page to be marked.
     *
     * @note If the page hasn't been visited yet, then it will be added
     *       as if it was visited, and then marked as hidden
     */
    void hidePage(in nsIURI aURI);

    /**
     * Designates the url as having been explicitly typed in by the user.
     *
     * @param aURI
     *        URI of the page to be marked.
     */
    void markPageAsTyped(in nsIURI aURI);

    /**
     * Designates the url as coming from a link explicitly followed by
     * the user (for example by clicking on it).
     *
     * @param aURI
     *        URI of the page to be marked.
     */
    void markPageAsFollowedLink(in nsIURI aURI);
};