mozilla
Your Search Results

    nsINavHistoryService

    This interface provides complex query functions, more fine-grained getters and setters.
    1.0
    28
    Introduced
    Gecko 1.8
    Inherits from: nsISupports Last changed in Gecko 22 (Firefox 22 / Thunderbird 22 / SeaMonkey 2.19)

    Implemented by: "@mozilla.org/browser/nav-history-service;1". To use this service, use:

    var historyService = Components.classes["@mozilla.org/browser/nav-history-service;1"]
                                   .getService(Components.interfaces.nsINavHistoryService);
    

    Method overview

    AString getPageTitle(in nsIURI aURI);
    void markPageAsFollowedBookmark(in nsIURI aURI);
    void markPageAsFollowedLink(in nsIURI aURI); Requires Gecko 22.0
    void markPageAsTyped(in nsIURI aURI); Requires Gecko 22.0
    boolean canAddURI(in nsIURI aURI);
    long long addVisit(in nsIURI aURI, in PRTime aTime, in nsIURI aReferringURI, in long aTransitionType, in boolean aIsRedirect, in long long aSessionID); Obsolete since Gecko 22.0
    nsINavHistoryQuery getNewQuery();
    nsINavHistoryQueryOptions getNewQueryOptions();
    nsINavHistoryResult executeQuery(in nsINavHistoryQuery aQuery, in nsINavHistoryQueryOptions options);
    nsINavHistoryResult executeQueries([array,size_is(aQueryCount)] in nsINavHistoryQuery aQueries, in unsigned long aQueryCount, in nsINavHistoryQueryOptions options);
    void queryStringToQueries(in AUTF8String aQueryString, [array, size_is(aResultCount)] out nsINavHistoryQuery aQueries, out unsigned long aResultCount, out nsINavHistoryQueryOptions options);
    AUTF8String queriesToQueryString([array, size_is(aQueryCount)] in nsINavHistoryQuery aQueries, in unsigned long aQueryCount, in nsINavHistoryQueryOptions options);
    void addObserver(in nsINavHistoryObserver observer, in boolean ownsWeak);
    void removeObserver(in nsINavHistoryObserver observer);
    void runInBatchMode(in nsINavHistoryBatchCallback aCallback, in nsISupports aClosure);
    void importHistory(in nsIFile file);
    AString getCharsetForURI(in nsIURI aURI);
    AString setCharsetForURI(in nsIURI aURI, in AString aCharset);

    Attributes

    Attribute Type Description
    hasHistoryEntries boolean True if there is any history. This can be used in UI to determine whether the "clear history" button should be enabled or not. This is much better than using BrowserHistory.count since that can be very slow if there is a lot of history (it must enumerate each item). This is pretty fast.
    historyDisabled boolean True if history is disabled. currently, history is disabled if the browser.history_expire_days pref is "0".

    Constants

    Transition type constants

    Constant Value Description
    TRANSITION_LINK 1 This transition type means the user followed a link and got a new toplevel window.
    TRANSITION_TYPED 2 This transition type is set when the user typed the URL to get to the page.
    TRANSITION_BOOKMARK 3 This transition type is set when the user followed a bookmark to get to the page.
    TRANSITION_EMBED 4 This transition type is set when some inner content is loaded. This is true of all images on a page, and the contents of the iframe. It is also true of any content in a frame, regardless if whether or not the user clicked something to get there.
    TRANSITION_REDIRECT_PERMANENT 5 This transition type is set when the transition was a permanent redirect.
    TRANSITION_REDIRECT_TEMPORARY 6 This transition type is set when the transition was a temporary redirect.
    TRANSITION_DOWNLOAD 7 This transition type is set when the transition is a download.
    TRANSITION_FRAMED_LINK 8 This transition type is set when the user followed a link that loaded a page in a frame.

    Methods

    getPageTitle()

    This method retrieves the original title of the page.

    AString getPageTitle(
      in nsIURI aURI
    );
    
    Parameters
    aURI
    The page whose title needs to be retrieved.
    Return value

    Returns the original title of the page.

    markPageAsFollowedBookmark()

    This method is just like markPageAsTyped (in nsIBrowserHistory, also implemented by the history service), but for bookmarks. It declares that the given URI is being opened as a result of following a bookmark. If this URI is loaded soon after this message has been received, that transition will be marked as following a bookmark.

    void markPageAsFollowedBookmark(
      in nsIURI aURI
    );
    
    Parameters
    aURI
    The page that is to be marked as followed by a bookmark.

    Requires Gecko 22.0 (Firefox 22.0 / Thunderbird 22.0 / SeaMonkey 2.19)

    markPageAsTyped()

    This method designates the URL as having been explicitly typed in by the user, so it can be used as an autocomplete result. It is called by the URL bar when the user types in a URL. This can be and is called before the page is actually added to history, since the page isn't added until it actually starts loading. The typed flag affects the URL bar autocomplete. This will cause the transition type of the next visit of the URL to be marked as "typed."

    void markPageAsTyped(
      in nsIURI aURI
    );
    
    Parameters
    aURI
    The page that is to be marked as typed by the user.

    Requires Gecko 22.0 (Firefox 22.0 / Thunderbird 22.0 / SeaMonkey 2.19)

    markPageAsFollowedLink()

    Designates the specified URL as coming from a link explicitly followed by the user (for example by clicking on it).

    void markPageAsFollowedLink(
      in nsIURI aURI
    );
    
    Parameters
    aURI
    The URL that is to be marked as explicitly followed by the user.

    canAddURI()

    This method checks if the given URI would be added to the history or not. Many types of URIs, such as "chrome:" URIs, are not stored when addURI is called. This function allows you to determine whether it will be or not.

    You don't have to worry about calling this, addPageToSession/addURI will always check before actually adding the page. This function is public because some components may want to check if this page would go in the history (That is for annotations).

    boolean canAddURI(
      in nsIURI aURI
    );
    
    Parameters
    aURI
    The URI that needs to be added to the history system.
    Return value

    Returns true if this URI would be added to the history, otherwise returns false.

    Obsolete since Gecko 22.0 (Firefox 22.0 / Thunderbird 22.0 / SeaMonkey 2.19)

    addVisit()

    Note: This method was removed in Gecko 22.0. You should use the new async API mozIAsyncHistory.updatePlaces() instead. See this code for how a function to add visits and handle errors using the new API could look like.

    This method adds a visit for a specific page. This will probably not be commonly used other than for backup/restore type operations. If the URI does not have an entry in the history database already, one will be created with no visits, no title, hidden, not typed. Adding a visit will automatically increment the visit count for the visited page and will unhide it and/or mark it typed according to the transition type.

    long long addVisit(
      in nsIURI aURI, 
      in PRTime aTime,
      in nsIURI aReferringURI,
      in long aTransitionType,
      in boolean aIsRedirect,
      in long long aSessionID ); 
    Parameters
    aURI
    The visited page.
    aTime
    The time page was visited (microseconds).
    aReferringURI
    The URI of the visit that generated this one. Use null for no referrer.
    aTransitionType
    The type of transition: one of TRANSITION_* defined above.
    aIsRedirect
    True if the given visit redirects to somewhere else (That is you will create a visit out of here that is a redirect transition). This causes this page to be hidden in normal history views (unless it has been unhidden by visiting it with a non-redirect).
    aSessionID
    The session ID that this page belongs to. Use "0" for no session.
    Return value

    Returns the ID of the created visit. This will be "0" if the URI is not valid for adding to history (canAddURI = false).

    getNewQuery()

    This method returns a new query object that you can pass to executeQuery/ies methods. It will be initialized to all empty (so using it will give you all history).

    nsINavHistoryQuery getNewQuery();
    
    Parameters

    None.

    Return value

    Returns a new query object.

    getNewQueryOptions()

    This method returns a new options object that you can pass to executeQuery/ies methods after setting the desired options.

    nsINavHistoryQueryOptions getNewQueryOptions();
    
    Parameters

    None.

    Return value

    Returns a new options object.

    executeQuery()

    This method executes a query with a single query object and options. All the parameters set on the query object will be ANDed together.

    nsINavHistoryResult executeQuery(
      in nsINavHistoryQuery aQuery,
      in nsINavHistoryQueryOptions options
    );
    
    Parameters
    aQuery
    The query object.
    options
    The options object.
    Return value

    Returns a new result object.

    executeQueries()

    This method is similar to executeQuery method. It executes an array of queries. All of the query objects are ORed together. Within a query, all the terms are ANDed together as in executeQuery method.

    nsINavHistoryResult executeQueries(
      [array,size_is(aQueryCount)] in nsINavHistoryQuery aQueries,
      in unsigned long aQueryCount,
      in nsINavHistoryQueryOptions options
    );
    
    Parameters
    aQueries
    The queries object.
    aQueryCount
    The count of queries.
    options
    The options object.
    Return value

    Returns a new result object.

    queryStringToQueries()

    This method converts a query URI-like string to an array of actual query objects for use to executeQueries method. The output query array may be empty if there is no information. However, there will always be an options structure returned (if nothing is defined, it will just have the default values).

    void queryStringToQueries(
      in AUTF8String aQueryString,
      [array, size_is(aResultCount)] out nsINavHistoryQuery aQueries,
      out unsigned long aResultCount,
      out nsINavHistoryQueryOptions options
    );
    
    Parameters
    aQueryString
    The query URI-like string.
    aQueries
    The queries object.
    aResultCount
    The count of converted queries.
    options
    The options object.

    queriesToQueryString()

    This method converts a query into an equivalent string that can be persisted. Inverse of queryStringToQueries method.

    AUTF8String queriesToQueryString(
      [array, size_is(aQueryCount)] in nsINavHistoryQuery aQueries,
      in unsigned long aQueryCount,
      in nsINavHistoryQueryOptions options
    );
    
    Parameters
    aQueries
    The queries object.
    aQueryCount
    The count queries.
    options
    The options object.
    Return value

    Returns the converted query into an equivalent string query.

    addObserver()

    This method adds a history observer. If ownsWeak is false, the history service will keep an owning reference to the observer. If ownsWeak is true, then aObserver must implement nsISupportsWeakReference, and the history service will keep a weak reference to the observer.

    void addObserver(
      in nsINavHistoryObserver observer, 
      in boolean ownsWeak
    );
    
    Parameters
    observer
    The history observer to be added.
    ownsWeak
    The owning reference state (boolean).

    removeObserver()

    This method removes a history observer.

    void removeObserver(
      in nsINavHistoryObserver observer
    );
    
    Parameters
    observer
    The history observer to be removed.

    runInBatchMode()

    This method runs the passed callback in batch mode. Use this when a lot of things are about to change. Calls can be nested, observers will only be notified when all batches begin/end.

    void runInBatchMode(
      in nsINavHistoryBatchCallback aCallback,
      in nsISupports aClosure
    );
    
    Parameters
    aCallback
    nsINavHistoryBatchCallback interface to call.
    aClosure
    Opaque parameter passed to nsINavBookmarksBatchCallback.

    importHistory()

    This method imports the given Mork history file.

    void importHistory(
      in nsIFile file
    );
    
    Parameters
    file
    The Mork history file to import.

    getCharsetForURI()

    Gets the stored character-set for an URI.

    void getCharsetForURI(
      in nsIURI aURI 
    );
    
    Parameters
    aURI
    URI to retrieve character-set for
    Returns

    Returns the character-set, empty string if not found

     

    setCharsetForURI()

    Gets the stored character-set for an URI.

    void getCharsetForURI(
      in nsIURI aURI,
      in AString aCharset
    );
    
    Parameters
    aURI
    URI to set character-set for
    aCharacterSet
    character-set to be set

    See also


    Document Tags and Contributors

    Last updated by: Sheppy,