gecko-dev/toolkit/components/places/nsIBrowserHistory.idl

/* -*- 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(540aca25-1e01-467f-b24c-df89cbe40f8d)]
interface nsIBrowserHistory : nsIGlobalHistory2
{
    /**
     * addPageWithDetails
     *
     * Adds a page to history with specific time stamp information. This is used in
     * the History migrator. 
     */
    void addPageWithDetails(in nsIURI aURI, in wstring aTitle, in long long aLastVisited);

    /**
     * lastPageVisited
     *
     * The last page that was visited in a top-level window.
     */
    readonly attribute AUTF8String lastPageVisited;

    /**
     * count
     *
     * Indicate if there are entries in global history
     * For performance reasons this does not return the real number of entries
     */
    readonly attribute PRUint32 count;

    /**
     * removePage
     *
     * Remove a page from history
     */
    void removePage(in nsIURI aURI);

    /**
     * removePages
     *
     * Remove a bunch of pages from history
     * Notice that this does not call observers for performance reasons,
     * instead setting aDoBatchNotify true will send Begin/EndUpdateBatch
     */
    void removePages([array, size_is(aLength)] in nsIURI aURIs,
                     in unsigned long aLength, in boolean aDoBatchNotify);

    /**
     * removePagesFromHost
     *
     * Removes all history information about pages from a given host. If
     * aEntireDomain is set, we will also delete pages from sub hosts (so if
     * we are passed in "microsoft.com" we delete "www.microsoft.com",
     * "msdn.microsoft.com", etc.). An empty host name means local files and
     * anything else with no host name. 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.
     *
     * Note that this does not call observers for single deleted uris,
     * but will send Begin/EndUpdateBatch.
     */
    void removePagesFromHost(in AUTF8String aHost, in boolean aEntireDomain);

    /**
     * removePagesByTimeframe
     *
     * Remove all pages for a given timeframe.
     * Limits are included: aBeginTime <= timeframe <= aEndTime
     * Notice that this does not call observers for single deleted uris,
     * instead it will send Begin/EndUpdateBatch
     */
    void removePagesByTimeframe(in long long aBeginTime, in long long aEndTime);

    /**
     * removeVisitsByTimeframe
     *
     * Removes all visits in a given timeframe.  Limits are included:
     * aBeginTime <= timeframe <= aEndTime.  Any place that becomes unvisited
     * as a result will also be deleted.
     *
     * Note that removal is performed in batch, so observers will not be
     * notified of individual places that are deleted.  Instead they will be
     * notified onBeginUpdateBatch and onEndUpdateBatch.
     */
    void removeVisitsByTimeframe(in long long aBeginTime, in long long aEndTime);

    /**
     * removeAllPages
     *
     * Remove all pages from global history
     */
    void removeAllPages();

    /**
     * hidePage
     *
     * Hide the specified URL from being enumerated (and thus
     * displayed in the UI)
     * 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);

    /**
     * markPageAsTyped
     *
     * Designate the url as having been explicitly typed in by
     * the user, so it's okay to be an autocomplete result.
     */
    void markPageAsTyped(in nsIURI aURI);

    /**
     * markPageAsFollowedLink
     *
     * Designate the url as coming from a link explicitly followed by
     * the user (for example by clicking on it).
     */
    void markPageAsFollowedLink(in nsIURI aURI);

    /**
     * Mark a page as being currently open.
     *
     * @note Pages will not be automatically unregistered when Private Browsing
     *       mode is entered or exited.  Therefore, consumers MUST unregister or
     *       register themselves.
     *
     * @note This is just an alias for mozIPlacesAutoComplete::registerOpenPage.
     *
     * @status DEPRECATED
     */
    [deprecated] void registerOpenPage(in nsIURI aURI);

    /**
     * Mark a page as no longer being open (either by closing the window or tab,
     * or by navigating away from that page).
     *
     * @note Pages will not be automatically unregistered when Private Browsing
     *       mode is entered or exited.  Therefore, consumers MUST unregister or
     *       register themselves.
     *
     * @note This is just an alias for
     *       mozIPlacesAutoComplete::unregisterOpenPage.
     *
     * @status DEPRECATED
     */
    [deprecated] void unregisterOpenPage(in nsIURI aURI);
};