/Users/dietrich/moz/trunk/mozilla/toolkit/components/places/public/nsINavHistoryService.idl

Go to the documentation of this file.

/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* ***** 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 Places code.
 *
 * The Initial Developer of the Original Code is
 * Google Inc.
 * Portions created by the Initial Developer are Copyright (C) 2005
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   Brett Wilson <brett@gmail.com>
 *
 * 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 ***** */

#include "nsISupports.idl"
#include "nsIArray.idl"
#include "nsIURI.idl"

interface nsIFile;
interface nsINavHistoryContainerResultNode;
interface nsINavHistoryQueryResultNode;
interface nsINavHistoryQuery;
interface nsINavHistoryQueryOptions;
interface nsINavHistoryResult;
interface nsINavHistoryBatchCallback;
interface nsITreeColumn;
interface nsIWritablePropertyBag;

[scriptable, uuid(47cf89e3-4777-46bf-9677-21793870ce62)]
interface nsINavHistoryResultNode : nsISupports
{
  readonly attribute nsINavHistoryContainerResultNode parent;

  readonly attribute nsINavHistoryResult parentResult;

  readonly attribute AUTF8String uri;

  const unsigned long RESULT_TYPE_URI = 0;               // nsINavHistoryResultNode
  const unsigned long RESULT_TYPE_VISIT = 1;             // nsINavHistoryVisitResultNode
  const unsigned long RESULT_TYPE_FULL_VISIT = 2;        // nsINavHistoryFullVisitResultNode
  const unsigned long RESULT_TYPE_DYNAMIC_CONTAINER = 4; // nsINavHistoryContainerResultNode
  const unsigned long RESULT_TYPE_QUERY = 5;             // nsINavHistoryQueryResultNode
  const unsigned long RESULT_TYPE_FOLDER = 6;            // nsINavHistoryQueryResultNode
  const unsigned long RESULT_TYPE_SEPARATOR = 7;         // nsINavHistoryResultNode
  const unsigned long RESULT_TYPE_FOLDER_SHORTCUT = 9;   // nsINavHistoryQueryResultNode
  readonly attribute unsigned long type;

  readonly attribute AUTF8String title;

  readonly attribute unsigned long accessCount;

  readonly attribute PRTime time;

  readonly attribute nsIURI icon;

  readonly attribute long indentLevel;

  attribute long viewIndex;

  readonly attribute nsIWritablePropertyBag propertyBag;

  readonly attribute long bookmarkIndex;

  readonly attribute long long itemId;

  readonly attribute PRTime dateAdded;

  readonly attribute PRTime lastModified;

  readonly attribute AString tags;
};


[scriptable, uuid(8e2c5a86-b33d-4fa6-944b-559af7e95fcd)]
interface nsINavHistoryVisitResultNode : nsINavHistoryResultNode
{
  readonly attribute long long sessionId;
};


[scriptable, uuid(c49fd9d5-56e2-43eb-932c-f933f28cba85)]
interface nsINavHistoryFullVisitResultNode : nsINavHistoryVisitResultNode
{
  readonly attribute long long visitId;

  readonly attribute long long referringVisitId;

  readonly attribute long transitionType;
};


[scriptable, uuid(f9c8e1c1-e701-44ad-893c-8504c3956929)]
interface nsINavHistoryContainerResultNode : nsINavHistoryResultNode
{

  attribute boolean containerOpen;

  readonly attribute boolean hasChildren;

  readonly attribute unsigned long childCount;
  nsINavHistoryResultNode getChild(in unsigned long aIndex);

  readonly attribute boolean childrenReadOnly;

  // --------------------------------------------------------------------------
  // Dynamic container

  readonly attribute AUTF8String dynamicContainerType;

  nsINavHistoryResultNode appendURINode(
      in AUTF8String aURI, in AUTF8String aTitle, in PRUint32 aAccessCount,
      in PRTime aTime, in AUTF8String aIconURI);

  /*nsINavHistoryVisitResultNode appendVisitNode(
      in AUTF8String aURI, in AUTF8String aTitle, in PRUint32 aAccessCount,
      in PRTime aTime, in AUTF8String aIconURI, in PRInt64 aSession);*/

  /*nsINavHistoryFullVisitResultNode appendFullVisitNode(
      in AUTF8String aURI, in AUTF8String aTitle, in PRUint32 aAccessCount,
      in PRTime aTime, in AUTF8String aIconURI, in PRInt64 aSession,
      in PRInt64 aVisitId, in PRInt64 aReferringVisitId,
      in PRInt32 aTransitionType);*/

  /*nsINavHistoryContainerResultNode appendContainerNode(
      in AUTF8String aTitle, in AUTF8String aIconURI, in PRUint32 aContainerType,
      in AUTF8String aDynamicContainerType);*/

  /*nsINavHistoryQueryResultNode appendQueryNode(
      in AUTF8String aQueryURI, in AUTF8String aTitle, in AUTF8String aIconURI);*/

  nsINavHistoryContainerResultNode appendFolderNode(in PRInt64 aFolderId);

  /*void clearContents();*/
};


[scriptable, uuid(ea17745a-1852-4155-a98f-d1dd1763b3df)]
interface nsINavHistoryQueryResultNode : nsINavHistoryContainerResultNode
{
  void getQueries(out unsigned long queryCount,
                  [retval,array,size_is(queryCount)] out nsINavHistoryQuery queries);

  readonly attribute nsINavHistoryQueryOptions queryOptions;

  readonly attribute long long folderItemId;
};


[scriptable, uuid(e60f4429-3787-45c8-a8c0-18ef52621bbf)]
interface nsINavHistoryResultViewer : nsISupports
{
  void itemInserted(in nsINavHistoryContainerResultNode aParent,
                    in nsINavHistoryResultNode aItem,
                    in unsigned long aNewIndex);

  void itemRemoved(in nsINavHistoryContainerResultNode aParent,
                   in nsINavHistoryResultNode aItem,
                   in unsigned long aOldIndex);

  void itemMoved(in nsINavHistoryResultNode aItem,
                 in nsINavHistoryContainerResultNode aOldParent,
                 in unsigned long aOldIndex,
                 in nsINavHistoryContainerResultNode aNewParent,
                 in unsigned long aNewIndex);

  void itemChanged(in nsINavHistoryResultNode item);

  void itemReplaced(in nsINavHistoryContainerResultNode parent,
                    in nsINavHistoryResultNode oldItem,
                    in nsINavHistoryResultNode newItem,
                    in unsigned long index);

  void containerOpened(in nsINavHistoryContainerResultNode item);

  void containerClosed(in nsINavHistoryContainerResultNode item);

  void invalidateContainer(in nsINavHistoryContainerResultNode item);

  void invalidateAll();

  void sortingChanged(in unsigned short sortingMode);

  attribute nsINavHistoryResult result;
};


[scriptable, uuid(fa77e4e9-9fc8-45d2-9507-0fe4f0602505)]
interface nsINavHistoryResultTreeViewer : nsINavHistoryResultViewer
{
  nsINavHistoryResultNode nodeForTreeIndex(in unsigned long aIndex);

  const unsigned long INDEX_INVISIBLE = 0xffffffff;
  unsigned long treeIndexForNode(in nsINavHistoryResultNode aNode);
};


[scriptable, uuid(d1562f6f-8d5a-4042-8524-72f747a51b18)]
interface nsINavHistoryResult : nsISupports
{
  attribute unsigned short sortingMode;

  attribute AUTF8String sortingAnnotation;

  attribute nsINavHistoryResultViewer viewer;

  readonly attribute nsINavHistoryContainerResultNode root;
};


[scriptable, uuid(eacb76eb-3eeb-419b-a963-9b3a9d65f356)]
interface nsINavHistoryObserver : nsISupports
{
  void onBeginUpdateBatch();

  void onEndUpdateBatch();

  void onVisit(in nsIURI aURI, in long long aVisitID, in PRTime aTime,
               in long long aSessionID, in long long aReferringID,
               in unsigned long aTransitionType, out unsigned long aAdded);

  void onTitleChanged(in nsIURI aURI, in AString aPageTitle);

  void onDeleteURI(in nsIURI aURI);

  void onClearHistory();

  const unsigned long ATTRIBUTE_FAVICON = 3; // favicon updated, aString = favicon annotation URI
  void onPageChanged(in nsIURI aURI, in unsigned long aWhat, in AString aValue);

  void onPageExpired(in nsIURI aURI, in PRTime aVisitTime, in boolean aWholeEntry);
};


[scriptable, uuid(53B51AFE-9DE8-40AD-9C81-F2CC1701F1FF)]
interface nsINavHistoryQuery : nsISupports
{
  const unsigned long TIME_RELATIVE_EPOCH = 0;
  const unsigned long TIME_RELATIVE_TODAY = 1;
  const unsigned long TIME_RELATIVE_NOW = 2;

  attribute PRTime beginTime;
  attribute unsigned long beginTimeReference;
  readonly attribute boolean hasBeginTime;
  readonly attribute PRTime absoluteBeginTime;

  attribute PRTime endTime;
  attribute unsigned long endTimeReference;
  readonly attribute boolean hasEndTime;
  readonly attribute PRTime absoluteEndTime;

  attribute AString searchTerms;
  readonly attribute boolean hasSearchTerms;

  attribute long minVisits;
  attribute long maxVisits;

  attribute boolean onlyBookmarked;

  attribute boolean domainIsHost;

  attribute AUTF8String domain;
  readonly attribute boolean hasDomain;

  attribute boolean uriIsPrefix;

  attribute nsIURI uri;
  readonly attribute boolean hasUri;

  attribute boolean annotationIsNot;
  attribute AUTF8String annotation;
  readonly attribute boolean hasAnnotation;

  void getFolders(out unsigned long count,
                  [retval,array,size_is(count)] out long long folders);
  readonly attribute unsigned long folderCount;

  void setFolders([const,array, size_is(folderCount)] in long long folders,
                  in unsigned long folderCount);

  nsINavHistoryQuery clone();
};

[scriptable, uuid(a46c132e-35f3-4e1e-bb3d-4e3043657248)]
interface nsINavHistoryQueryOptions : nsISupports
{
  const unsigned short SORT_BY_NONE = 0;
  const unsigned short SORT_BY_TITLE_ASCENDING = 1;
  const unsigned short SORT_BY_TITLE_DESCENDING = 2;
  const unsigned short SORT_BY_DATE_ASCENDING = 3;
  const unsigned short SORT_BY_DATE_DESCENDING = 4;
  const unsigned short SORT_BY_URI_ASCENDING = 5;
  const unsigned short SORT_BY_URI_DESCENDING = 6;
  const unsigned short SORT_BY_VISITCOUNT_ASCENDING = 7;
  const unsigned short SORT_BY_VISITCOUNT_DESCENDING = 8;
  const unsigned short SORT_BY_KEYWORD_ASCENDING = 9;
  const unsigned short SORT_BY_KEYWORD_DESCENDING = 10;
  const unsigned short SORT_BY_DATEADDED_ASCENDING = 11;
  const unsigned short SORT_BY_DATEADDED_DESCENDING = 12;
  const unsigned short SORT_BY_LASTMODIFIED_ASCENDING = 13;
  const unsigned short SORT_BY_LASTMODIFIED_DESCENDING = 14;
  const unsigned short SORT_BY_TAGS_ASCENDING = 17;
  const unsigned short SORT_BY_TAGS_DESCENDING = 18;
  const unsigned short SORT_BY_ANNOTATION_ASCENDING = 19;
  const unsigned short SORT_BY_ANNOTATION_DESCENDING = 20;


  const unsigned short RESULTS_AS_URI = 0;

  const unsigned short RESULTS_AS_VISIT = 1;

  const unsigned short RESULTS_AS_FULL_VISIT = 2;

  const unsigned short RESULTS_AS_DATE_QUERY = 3;

  const unsigned short RESULTS_AS_SITE_QUERY = 4;

  const unsigned short RESULTS_AS_DATE_SITE_QUERY = 5;

  const unsigned short RESULTS_AS_TAG_QUERY = 6;

  const unsigned short RESULTS_AS_TAG_CONTENTS = 7;

  attribute unsigned short sortingMode;

  attribute AUTF8String sortingAnnotation;

  attribute unsigned short resultType;

  attribute boolean excludeItems;

  attribute boolean excludeQueries;

  attribute boolean excludeReadOnlyFolders;

  attribute AUTF8String excludeItemIfParentHasAnnotation;

  attribute boolean expandQueries;

  attribute boolean includeHidden;

  attribute boolean showSessions;

  attribute unsigned long maxResults;

  const unsigned short QUERY_TYPE_HISTORY = 0;
  const unsigned short QUERY_TYPE_BOOKMARKS = 1;
  const unsigned short QUERY_TYPE_UNIFIED = 2;
  
  attribute unsigned short queryType;

  nsINavHistoryQueryOptions clone();
};

[scriptable, uuid(437f539b-d541-4a0f-a200-6f9a6d45cce2)]
interface nsINavHistoryService : nsISupports
{
  const unsigned long TRANSITION_LINK = 1;

  const unsigned long TRANSITION_TYPED = 2;

  const unsigned long TRANSITION_BOOKMARK = 3;

  const unsigned long TRANSITION_EMBED = 4;

  const unsigned long TRANSITION_REDIRECT_PERMANENT = 5;

  const unsigned long TRANSITION_REDIRECT_TEMPORARY = 6;

  const unsigned long TRANSITION_DOWNLOAD = 7;

  const unsigned short DATABASE_STATUS_OK = 0;

  const unsigned short DATABASE_STATUS_CREATE = 1;

  const unsigned short DATABASE_STATUS_CORRUPT = 2;

  const unsigned short DATABASE_STATUS_UPGRADED = 3;

  readonly attribute unsigned short databaseStatus;

  readonly attribute boolean hasHistoryEntries;

  AString getPageTitle(in nsIURI aURI);

  void markPageAsFollowedBookmark(in nsIURI aURI);

  AString getCharsetForURI(in nsIURI aURI);

  void setCharsetForURI(in nsIURI aURI, in AString aCharset);

  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);

  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);

  readonly attribute boolean historyDisabled;

  void importHistory(in nsIFile file);
};

[scriptable, uuid(5143f2bb-be0a-4faf-9acb-b0ed3f82952c)]
interface nsINavHistoryBatchCallback : nsISupports {
  void runBatched(in nsISupports aUserData);
};

---