diff options
Diffstat (limited to 'components/places/public')
| -rw-r--r-- | components/places/public/mozIAsyncFavicons.idl | 174 | ||||
| -rw-r--r-- | components/places/public/mozIAsyncHistory.idl | 188 | ||||
| -rw-r--r-- | components/places/public/mozIAsyncLivemarks.idl | 190 | ||||
| -rw-r--r-- | components/places/public/mozIColorAnalyzer.idl | 52 | ||||
| -rw-r--r-- | components/places/public/mozIPlacesAutoComplete.idl | 134 | ||||
| -rw-r--r-- | components/places/public/mozIPlacesPendingOperation.idl | 14 | ||||
| -rw-r--r-- | components/places/public/nsIAnnotationService.idl | 422 | ||||
| -rw-r--r-- | components/places/public/nsIBrowserHistory.idl | 70 | ||||
| -rw-r--r-- | components/places/public/nsIFaviconService.idl | 145 | ||||
| -rw-r--r-- | components/places/public/nsINavBookmarksService.idl | 697 | ||||
| -rw-r--r-- | components/places/public/nsINavHistoryService.idl | 1451 | ||||
| -rw-r--r-- | components/places/public/nsITaggingService.idl | 95 | ||||
| -rw-r--r-- | components/places/public/nsPIPlacesDatabase.idl | 52 |
13 files changed, 3684 insertions, 0 deletions
diff --git a/components/places/public/mozIAsyncFavicons.idl b/components/places/public/mozIAsyncFavicons.idl new file mode 100644 index 000000000..f1be18278 --- /dev/null +++ b/components/places/public/mozIAsyncFavicons.idl @@ -0,0 +1,174 @@ +/* -*- 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/. */ + +#include "nsISupports.idl" + +interface nsIURI; +interface nsIFaviconDataCallback; +interface nsIPrincipal; +interface mozIPlacesPendingOperation; + +[scriptable, uuid(a9c81797-9133-4823-b55f-3646e67cfd41)] +interface mozIAsyncFavicons : nsISupports +{ + /** + * Declares that a given page uses a favicon with the given URI and + * attempts to fetch and save the icon data by loading the favicon URI + * through an async network request. + * + * If the icon data already exists, we won't try to reload the icon unless + * aForceReload is true. Similarly, if the icon is in the failed favicon + * cache we won't do anything unless aForceReload is true, in which case + * we'll try to reload the favicon. + * + * This function will only save favicons for pages that are already stored in + * the database, like visited pages or bookmarks. For any other URIs, it + * will succeed but do nothing. This function will also ignore the error + * page favicon URI (see FAVICON_ERRORPAGE_URL below). + * + * Icons that fail to load will automatically be added to the failed favicon + * cache, and this function will not save favicons for non-bookmarked URIs + * when history is disabled. + * + * @note This function is identical to + * nsIFaviconService::setAndLoadFaviconForPage. + * + * @param aPageURI + * URI of the page whose favicon is being set. + * @param aFaviconURI + * URI of the favicon to associate with the page. + * @param aForceReload + * If aForceReload is false, we try to reload the favicon only if we + * don't have it or it has expired from the cache. Setting + * aForceReload to true causes us to reload the favicon even if we + * have a usable copy. + * @param aFaviconLoadType + * Set to FAVICON_LOAD_PRIVATE if the favicon is loaded from a private + * browsing window. Set to FAVICON_LOAD_NON_PRIVATE otherwise. + * @param aCallback + * Once we're done setting and/or fetching the favicon, we invoke this + * callback. + * @param aLoadingPrincipal + * Principal of the page whose favicon is being set. If this argument + * is omitted, the loadingPrincipal defaults to the nullPrincipal. + * + * @see nsIFaviconDataCallback in nsIFaviconService.idl. + */ + mozIPlacesPendingOperation setAndFetchFaviconForPage( + in nsIURI aPageURI, + in nsIURI aFaviconURI, + in boolean aForceReload, + in unsigned long aFaviconLoadType, + [optional] in nsIFaviconDataCallback aCallback, + [optional] in nsIPrincipal aLoadingPrincipal); + /** + * Sets the data for a given favicon URI either by replacing existing data in + * the database or taking the place of otherwise fetched icon data when + * calling setAndFetchFaviconForPage later. + * + * Favicon data for favicon URIs that are not associated with a page URI via + * setAndFetchFaviconForPage will be stored in memory, but may be expired at + * any time, so you should make an effort to associate favicon URIs with page + * URIs as soon as possible. + * + * It's better to not use this function for chrome: icon URIs since you can + * reference the chrome image yourself. getFaviconLinkForIcon/Page will ignore + * any associated data if the favicon URI is "chrome:" and just return the + * same chrome URI. + * + * This function does NOT send out notifications that the data has changed. + * Pages using this favicons that are visible in history or bookmarks views + * will keep the old icon until they have been refreshed by other means. + * + * This function tries to optimize the favicon size, if it is bigger + * than a defined limit we will try to convert it to a 16x16 png image. + * If the conversion fails and favicon is still bigger than our max accepted + * size it won't be saved. + * + * @param aFaviconURI + * URI of the favicon whose data is being set. + * @param aData + * Binary contents of the favicon to save + * @param aDataLength + * Length of binary data + * @param aMimeType + * MIME type of the data to store. This is important so that we know + * what to report when the favicon is used. You should always set this + * param unless you are clearing an icon. + * @param aExpiration + * Time in microseconds since the epoch when this favicon expires. + * Until this time, we won't try to load it again. + * @throws NS_ERROR_FAILURE + * Thrown if the favicon is overbloated and won't be saved to the db. + */ + void replaceFaviconData(in nsIURI aFaviconURI, + [const,array,size_is(aDataLen)] in octet aData, + in unsigned long aDataLen, + in AUTF8String aMimeType, + [optional] in PRTime aExpiration); + + /** + * Same as replaceFaviconData but the data is provided by a string + * containing a data URL. + * + * @see replaceFaviconData + * + * @param aFaviconURI + * URI of the favicon whose data is being set. + * @param aDataURL + * string containing a data URL that represents the contents of + * the favicon to save + * @param aExpiration + * Time in microseconds since the epoch when this favicon expires. + * Until this time, we won't try to load it again. + * @param aLoadingPrincipal + * Principal of the page whose favicon is being set. If this argument + * is omitted, the loadingPrincipal defaults to the nullPrincipal. + * @throws NS_ERROR_FAILURE + * Thrown if the favicon is overbloated and won't be saved to the db. + */ + void replaceFaviconDataFromDataURL(in nsIURI aFaviconURI, + in AString aDataURL, + [optional] in PRTime aExpiration, + [optional] in nsIPrincipal aLoadingPrincipal); + + /** + * Retrieves the favicon URI associated to the given page, if any. + * + * @param aPageURI + * URI of the page whose favicon URI we're looking up. + * @param aCallback + * This callback is always invoked to notify the result of the lookup. + * The aURI parameter will be the favicon URI, or null when no favicon + * is associated with the page or an error occurred while fetching it. + * + * @note When the callback is invoked, aDataLen will be always 0, aData will + * be an empty array, and aMimeType will be an empty string, regardless + * of whether a favicon is associated with the page. + * + * @see nsIFaviconDataCallback in nsIFaviconService.idl. + */ + void getFaviconURLForPage(in nsIURI aPageURI, + in nsIFaviconDataCallback aCallback); + + /** + * Retrieves the favicon URI and data associated to the given page, if any. + * + * @param aPageURI + * URI of the page whose favicon URI and data we're looking up. + * @param aCallback + * This callback is always invoked to notify the result of the lookup. The aURI + * parameter will be the favicon URI, or null when no favicon is + * associated with the page or an error occurred while fetching it. If + * aURI is not null, the other parameters may contain the favicon data. + * However, if no favicon data is currently associated with the favicon + * URI, aDataLen will be 0, aData will be an empty array, and aMimeType + * will be an empty string. + * + * @see nsIFaviconDataCallback in nsIFaviconService.idl. + */ + void getFaviconDataForPage(in nsIURI aPageURI, + in nsIFaviconDataCallback aCallback); +}; diff --git a/components/places/public/mozIAsyncHistory.idl b/components/places/public/mozIAsyncHistory.idl new file mode 100644 index 000000000..35c8cc3a6 --- /dev/null +++ b/components/places/public/mozIAsyncHistory.idl @@ -0,0 +1,188 @@ +/* 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/. */ + +#include "nsISupports.idl" + +interface nsIURI; +interface nsIVariant; + +[scriptable, uuid(41e4ccc9-f0c8-4cd7-9753-7a38514b8488)] +interface mozIVisitInfo : nsISupports +{ + /** + * The machine-local (internal) id of the visit. + */ + readonly attribute long long visitId; + + /** + * The time the visit occurred. + */ + readonly attribute PRTime visitDate; + + /** + * The transition type used to get to this visit. One of the TRANSITION_TYPE + * constants on nsINavHistory. + * + * @see nsINavHistory.idl + */ + readonly attribute unsigned long transitionType; + + /** + * The referring URI of this visit. This may be null. + */ + readonly attribute nsIURI referrerURI; +}; + +[scriptable, uuid(ad83e137-c92a-4b7b-b67e-0a318811f91e)] +interface mozIPlaceInfo : nsISupports +{ + /** + * The machine-local (internal) id of the place. + */ + readonly attribute long long placeId; + + /** + * The globally unique id of the place. + */ + readonly attribute ACString guid; + + /** + * The URI of the place. + */ + readonly attribute nsIURI uri; + + /** + * The title associated with the place. + */ + readonly attribute AString title; + + /** + * The frecency of the place. + */ + readonly attribute long long frecency; + + /** + * An array of mozIVisitInfo objects for the place. + */ + [implicit_jscontext] + readonly attribute jsval visits; +}; + +/** + * Shared Callback interface for mozIAsyncHistory methods. The semantics + * for each method are detailed in mozIAsyncHistory. + */ +[scriptable, uuid(1f266877-2859-418b-a11b-ec3ae4f4f93d)] +interface mozIVisitInfoCallback : nsISupports +{ + /** + * Called when the given place could not be processed. + * + * @param aResultCode + * nsresult indicating the failure reason. + * @param aPlaceInfo + * The information that was given to the caller for the place. + */ + void handleError(in nsresult aResultCode, + in mozIPlaceInfo aPlaceInfo); + + /** + * Called for each place processed successfully. + * + * @param aPlaceInfo + * The current info stored for the place. + */ + void handleResult(in mozIPlaceInfo aPlaceInfo); + + /** + * Called when all records were processed. + */ + void handleCompletion(); + +}; + +[scriptable, function, uuid(994092bf-936f-449b-8dd6-0941e024360d)] +interface mozIVisitedStatusCallback : nsISupports +{ + /** + * Notifies whether a certain URI has been visited. + * + * @param aURI + * URI being notified about. + * @param aVisitedStatus + * The visited status of aURI. + */ + void isVisited(in nsIURI aURI, + in boolean aVisitedStatus); +}; + +[scriptable, uuid(1643EFD2-A329-4733-A39D-17069C8D3B2D)] +interface mozIAsyncHistory : nsISupports +{ + /** + * Gets the available information for the given array of places, each + * identified by either nsIURI or places GUID (string). + * + * The retrieved places info objects DO NOT include the visits data (the + * |visits| attribute is set to null). + * + * If a given place does not exist in the database, aCallback.handleError is + * called for it with NS_ERROR_NOT_AVAILABLE result code. + * + * @param aPlaceIdentifiers + * The place[s] for which to retrieve information, identified by either + * a single place GUID, a single URI, or a JS array of URIs and/or GUIDs. + * @param aCallback + * A mozIVisitInfoCallback object which consists of callbacks to be + * notified for successful or failed retrievals. + * If there's no information available for a given place, aCallback + * is called with a stub place info object, containing just the provided + * data (GUID or URI). + * + * @throws NS_ERROR_INVALID_ARG + * - Passing in NULL for aPlaceIdentifiers or aCallback. + * - Not providing at least one valid GUID or URI. + */ + [implicit_jscontext] + void getPlacesInfo(in jsval aPlaceIdentifiers, + in mozIVisitInfoCallback aCallback); + + /** + * Adds a set of visits for one or more mozIPlaceInfo objects, and updates + * each mozIPlaceInfo's title or guid. + * + * aCallback.handleResult is called for each visit added. + * + * @param aPlaceInfo + * The mozIPlaceInfo object[s] containing the information to store or + * update. This can be a single object, or an array of objects. + * @param [optional] aCallback + * A mozIVisitInfoCallback object which consists of callbacks to be + * notified for successful and/or failed changes. + * + * @throws NS_ERROR_INVALID_ARG + * - Passing in NULL for aPlaceInfo. + * - Not providing at least one valid guid, or uri for all + * mozIPlaceInfo object[s]. + * - Not providing an array or nothing for the visits property of + * mozIPlaceInfo. + * - Not providing a visitDate and transitionType for each + * mozIVisitInfo. + * - Providing an invalid transitionType for a mozIVisitInfo. + */ + [implicit_jscontext] + void updatePlaces(in jsval aPlaceInfo, + [optional] in mozIVisitInfoCallback aCallback); + + /** + * Checks if a given URI has been visited. + * + * @param aURI + * The URI to check for. + * @param aCallback + * A mozIVisitStatusCallback object which receives the visited status. + */ + void isURIVisited(in nsIURI aURI, + in mozIVisitedStatusCallback aCallback); +}; diff --git a/components/places/public/mozIAsyncLivemarks.idl b/components/places/public/mozIAsyncLivemarks.idl new file mode 100644 index 000000000..e84ecca8e --- /dev/null +++ b/components/places/public/mozIAsyncLivemarks.idl @@ -0,0 +1,190 @@ +/* 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/. */ + +#include "nsISupports.idl" + +interface nsIURI; + +interface mozILivemarkInfo; +interface mozILivemark; + +interface nsINavHistoryResultObserver; + +[scriptable, uuid(672387b7-a75d-4e8f-9b49-5c1dcbfff46b)] +interface mozIAsyncLivemarks : nsISupports +{ + /** + * Creates a new livemark + * + * @param aLivemarkInfo + * mozILivemarkInfo object containing at least title, parentId, + * index and feedURI of the livemark to create. + * + * @return {Promise} + * @throws NS_ERROR_INVALID_ARG if the supplied information is insufficient + * for the creation. + */ + jsval addLivemark(in jsval aLivemarkInfo); + + /** + * Removes an existing livemark. + * + * @param aLivemarkInfo + * mozILivemarkInfo object containing either an id or a guid of the + * livemark to remove. + * + * @return {Promise} + * @throws NS_ERROR_INVALID_ARG if the id/guid is invalid. + */ + jsval removeLivemark(in jsval aLivemarkInfo); + + /** + * Gets an existing livemark. + * + * @param aLivemarkInfo + * mozILivemarkInfo object containing either an id or a guid of the + * livemark to retrieve. + * + * @return {Promise} + * @throws NS_ERROR_INVALID_ARG if the id/guid is invalid or an invalid + * callback is provided. + */ + jsval getLivemark(in jsval aLivemarkInfo); + + /** + * Reloads all livemarks if they are expired or if forced to do so. + * + * @param [optional]aForceUpdate + * If set to true forces a reload even if contents are still valid. + * + * @note The update process is asynchronous, observers registered through + * registerForUpdates will be notified of updated contents. + */ + void reloadLivemarks([optional]in boolean aForceUpdate); +}; + +[scriptable, uuid(3a3c5e8f-ec4a-4086-ae0a-d16420d30c9f)] +interface mozILivemarkInfo : nsISupports +{ + /** + * Id of the bookmarks folder representing this livemark. + * + * @deprecated Use guid instead. + */ + readonly attribute long long id; + + /** + * The globally unique identifier of this livemark. + */ + readonly attribute ACString guid; + + /** + * Title of this livemark. + */ + readonly attribute AString title; + + /** + * Id of the bookmarks parent folder containing this livemark. + * + * @deprecated Use parentGuid instead. + */ + readonly attribute long long parentId; + + /** + * Guid of the bookmarks parent folder containing this livemark. + */ + readonly attribute long long parentGuid; + + /** + * The position of this livemark in the bookmarks parent folder. + */ + readonly attribute long index; + + /** + * Time this livemark was created. + */ + readonly attribute PRTime dateAdded; + + /** + * Time this livemark's details were last modified. Doesn't track changes to + * the livemark contents. + */ + readonly attribute PRTime lastModified; + + /** + * The URI of the syndication feed associated with this livemark. + */ + readonly attribute nsIURI feedURI; + + /** + * The URI of the website associated with this livemark. + */ + readonly attribute nsIURI siteURI; +}; + +[scriptable, uuid(9f6fdfae-db9a-4bd8-bde1-148758cf1b18)] +interface mozILivemark : mozILivemarkInfo +{ + // Indicates the livemark is inactive. + const unsigned short STATUS_READY = 0; + // Indicates the livemark is fetching new contents. + const unsigned short STATUS_LOADING = 1; + // Indicates the livemark failed to fetch new contents. + const unsigned short STATUS_FAILED = 2; + + /** + * Status of this livemark. One of the STATUS_* constants above. + */ + readonly attribute unsigned short status; + + /** + * Reload livemark contents if they are expired or if forced to do so. + * + * @param [optional]aForceUpdate + * If set to true forces a reload even if contents are still valid. + * + * @note The update process is asynchronous, it's possible to register a + * result observer to be notified of updated contents through + * registerForUpdates. + */ + void reload([optional]in boolean aForceUpdate); + + /** + * Returns an array of nsINavHistoryResultNode objects, representing children + * of this livemark. The nodes will have aContainerNode as parent. + * + * @param aContainerNode + * Object implementing nsINavHistoryContainerResultNode, to be used as + * parent of the livemark nodes. + */ + jsval getNodesForContainer(in jsval aContainerNode); + + /** + * Registers a container node for updates on this livemark. + * When the livemark contents change, an invalidateContainer(aContainerNode) + * request is sent to aResultObserver. + * + * @param aContainerNode + * Object implementing nsINavHistoryContainerResultNode, representing + * this livemark. + * @param aResultObserver + * The nsINavHistoryResultObserver that should be notified of changes + * to the livemark contents. + */ + void registerForUpdates(in jsval aContainerNode, + in nsINavHistoryResultObserver aResultObserver); + + /** + * Unregisters a previously registered container node. + * + * @param aContainerNode + * Object implementing nsINavHistoryContainerResultNode, representing + * this livemark. + * + * @note it's suggested to always unregister containers that are no more used, + * to free up the associated resources. A good time to do so is when + * the container gets closed. + */ + void unregisterForUpdates(in jsval aContainerNode); +}; diff --git a/components/places/public/mozIColorAnalyzer.idl b/components/places/public/mozIColorAnalyzer.idl new file mode 100644 index 000000000..368958cbb --- /dev/null +++ b/components/places/public/mozIColorAnalyzer.idl @@ -0,0 +1,52 @@ +/* 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/. */ + +#include "nsISupports.idl" + +interface nsIURI; + +[function, scriptable, uuid(e4089e21-71b6-40af-b546-33c21b90e874)] +interface mozIRepresentativeColorCallback : nsISupports +{ + /** + * Will be called when color analysis finishes. + * + * @param success + * True if analysis was successful, false otherwise. + * Analysis can fail if the image is transparent, imageURI doesn't + * resolve to a valid image, or the image is too big. + * + * @param color + * The representative color as an integer in RGB form. + * e.g. 0xFF0102 == rgb(255,1,2) + * If success is false, color is not provided. + */ + void onComplete(in boolean success, [optional] in unsigned long color); +}; + +[scriptable, uuid(d056186c-28a0-494e-aacc-9e433772b143)] +interface mozIColorAnalyzer : nsISupports +{ + /** + * Given an image URI, find the most representative color for that image + * based on the frequency of each color. Preference is given to colors that + * are more interesting. Avoids the background color if it can be + * discerned. Ignores sufficiently transparent colors. + * + * This is intended to be used on favicon images. Larger images take longer + * to process, especially those with a larger number of unique colors. If + * imageURI points to an image that has more than 128^2 pixels, this method + * will fail before analyzing it for performance reasons. + * + * @param imageURI + * A URI pointing to the image - ideally a data: URI, but any scheme + * that will load when setting the src attribute of a DOM img element + * should work. + * @param callback + * Function to call when the representative color is found or an + * error occurs. + */ + void findRepresentativeColor(in nsIURI imageURI, + in mozIRepresentativeColorCallback callback); +}; diff --git a/components/places/public/mozIPlacesAutoComplete.idl b/components/places/public/mozIPlacesAutoComplete.idl new file mode 100644 index 000000000..6ff82e667 --- /dev/null +++ b/components/places/public/mozIPlacesAutoComplete.idl @@ -0,0 +1,134 @@ +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- + * vim: sw=2 ts=2 sts=2 + * 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/. */ + +#include "nsISupports.idl" + +interface nsIURI; + +/** + * This interface provides some constants used by the Places AutoComplete + * search provider as well as methods to track opened pages for AutoComplete + * purposes. + */ +[scriptable, uuid(61b6348a-09e1-4810-8057-f8cb3cec6ef8)] +interface mozIPlacesAutoComplete : nsISupports +{ + ////////////////////////////////////////////////////////////////////////////// + //// Matching Constants + + /** + * Match anywhere in each searchable term. + */ + const long MATCH_ANYWHERE = 0; + + /** + * Match first on word boundaries, and if we do not get enough results, then + * match anywhere in each searchable term. + */ + const long MATCH_BOUNDARY_ANYWHERE = 1; + + /** + * Match on word boundaries in each searchable term. + */ + const long MATCH_BOUNDARY = 2; + + /** + * Match only the beginning of each search term. + */ + const long MATCH_BEGINNING = 3; + + /** + * Match anywhere in each searchable term without doing any transformation + * or stripping on the underlying data. + */ + const long MATCH_ANYWHERE_UNMODIFIED = 4; + + /** + * Match only the beginning of each search term using a case sensitive + * comparator. + */ + const long MATCH_BEGINNING_CASE_SENSITIVE = 5; + + ////////////////////////////////////////////////////////////////////////////// + //// Search Behavior Constants + + /** + * Search through history. + */ + const long BEHAVIOR_HISTORY = 1 << 0; + + /** + * Search though bookmarks. + */ + const long BEHAVIOR_BOOKMARK = 1 << 1; + + /** + * Search through tags. + */ + const long BEHAVIOR_TAG = 1 << 2; + + /** + * Search the title of pages. + */ + const long BEHAVIOR_TITLE = 1 << 3; + + /** + * Search the URL of pages. + */ + const long BEHAVIOR_URL = 1 << 4; + + /** + * Search for typed pages. + */ + const long BEHAVIOR_TYPED = 1 << 5; + + /** + * Search javascript: URLs. + */ + const long BEHAVIOR_JAVASCRIPT = 1 << 6; + + /** + * Search for pages that have been marked as being opened, such as a tab + * in a tabbrowser. + */ + const long BEHAVIOR_OPENPAGE = 1 << 7; + + /** + * Use intersection between history, typed, bookmark, tag and openpage + * instead of union, when the restrict bit is set. + */ + const long BEHAVIOR_RESTRICT = 1 << 8; + + /** + * Include search suggestions from the currently selected search provider. + */ + const long BEHAVIOR_SEARCHES = 1 << 9; + + /** + * 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. + * + * @param aURI + * The URI to register as an open page. + */ + 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. + * + * @param aURI + * The URI to unregister as an open page. + */ + void unregisterOpenPage(in nsIURI aURI); +}; diff --git a/components/places/public/mozIPlacesPendingOperation.idl b/components/places/public/mozIPlacesPendingOperation.idl new file mode 100644 index 000000000..678a90870 --- /dev/null +++ b/components/places/public/mozIPlacesPendingOperation.idl @@ -0,0 +1,14 @@ +/* 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/. */ + +#include "nsISupports.idl" + +[scriptable, uuid(ebd31374-3808-40e4-9e73-303bf70467c3)] +interface mozIPlacesPendingOperation : nsISupports { + /** + * Cancels a pending operation, if possible. This will only fail if you try + * to cancel more than once. + */ + void cancel(); +}; diff --git a/components/places/public/nsIAnnotationService.idl b/components/places/public/nsIAnnotationService.idl new file mode 100644 index 000000000..bdd417ece --- /dev/null +++ b/components/places/public/nsIAnnotationService.idl @@ -0,0 +1,422 @@ +/* -*- 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/. */ + +#include "nsISupports.idl" + +interface nsIURI; +interface nsIVariant; +interface mozIAnnotatedResult; + +[scriptable, uuid(63fe98e0-6889-4c2c-ac9f-703e4bc25027)] +interface nsIAnnotationObserver : nsISupports +{ + /** + * Called when an annotation value is set. It could be a new annotation, + * or it could be a new value for an existing annotation. + */ + void onPageAnnotationSet(in nsIURI aPage, + in AUTF8String aName); + void onItemAnnotationSet(in long long aItemId, + in AUTF8String aName, + in unsigned short aSource); + + /** + * Called when an annotation is deleted. If aName is empty, then ALL + * annotations for the given URI have been deleted. This is not called when + * annotations are expired (normally happens when the app exits). + */ + void onPageAnnotationRemoved(in nsIURI aURI, + in AUTF8String aName); + void onItemAnnotationRemoved(in long long aItemId, + in AUTF8String aName, + in unsigned short aSource); +}; + +[scriptable, uuid(D4CDAAB1-8EEC-47A8-B420-AD7CB333056A)] +interface nsIAnnotationService : nsISupports +{ + /** + * Valid values for aExpiration, which sets the expiration policy for your + * annotation. The times for the days, weeks and months policies are + * measured since the last visit date of the page in question. These + * will not expire so long as the user keeps visiting the page from time + * to time. + */ + + // For temporary data that can be discarded when the user exits. + // Removed at application exit. + const unsigned short EXPIRE_SESSION = 0; + + // NOTE: 1 is skipped due to its temporary use as EXPIRE_NEVER in bug #319455. + + // For general page settings, things the user is interested in seeing + // if they come back to this page some time in the near future. + // Removed at 30 days. + const unsigned short EXPIRE_WEEKS = 2; + + // Something that the user will be interested in seeing in their + // history like favicons. If they haven't visited a page in a couple + // of months, they probably aren't interested in many other annotations, + // the positions of things, or other stuff you create, so put that in + // the weeks policy. + // Removed at 180 days. + const unsigned short EXPIRE_MONTHS = 3; + + // For annotations that only live as long as the URI is in the database. + // A page annotation will expire if the page has no visits + // and is not bookmarked. + // An item annotation will expire when the item is deleted. + const unsigned short EXPIRE_NEVER = 4; + + // For annotations that only live as long as the URI has visits. + // Valid only for page annotations. + const unsigned short EXPIRE_WITH_HISTORY = 5; + + // For short-lived temporary data that you still want to outlast a session. + // Removed at 7 days. + const unsigned short EXPIRE_DAYS = 6; + + // type constants + const unsigned short TYPE_INT32 = 1; + const unsigned short TYPE_DOUBLE = 2; + const unsigned short TYPE_STRING = 3; + const unsigned short TYPE_INT64 = 5; + + /** + * Sets an annotation, overwriting any previous annotation with the same + * URL/name. IT IS YOUR JOB TO NAMESPACE YOUR ANNOTATION NAMES. + * Use the form "namespace/value", so your name would be like + * "bills_extension/page_state" or "history/thumbnail". + * + * Do not use characters that are not valid in URLs such as spaces, ":", + * commas, or most other symbols. You should stick to ASCII letters and + * numbers plus "_", "-", and "/". + * + * aExpiration is one of EXPIRE_* above. aFlags should be 0 for now, some + * flags will be defined in the future. + * + * NOTE: ALL PAGE ANNOTATIONS WILL GET DELETED WHEN THE PAGE IS REMOVED FROM + * HISTORY IF THE PAGE IS NOT BOOKMARKED. This means that if you create an + * annotation on an unvisited URI, it will get deleted when the browser + * shuts down. Otherwise, URIs can exist in history as annotations but the + * user has no way of knowing it, potentially violating their privacy + * expectations about actions such as "Clear history". + * If there is an important annotation that the user or extension wants to + * keep, you should add a bookmark for the page and use an EXPIRE_NEVER + * annotation. This will ensure the annotation exists until the item is + * removed by the user. + * See EXPIRE_* constants above for further information. + * + * For item annotations, aSource should be a change source constant from + * nsINavBookmarksService::SOURCE_*, and defaults to SOURCE_DEFAULT if + * omitted. + * + * The annotation "favicon" is special. Favicons are stored in the favicon + * service, but are special cased in the protocol handler so they look like + * annotations. Do not set favicons using this service, it will not work. + * + * Only C++ consumers may use the type-specific methods. + * + * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist. + */ + void setPageAnnotation(in nsIURI aURI, + in AUTF8String aName, + in nsIVariant aValue, + in long aFlags, + in unsigned short aExpiration); + void setItemAnnotation(in long long aItemId, + in AUTF8String aName, + in nsIVariant aValue, + in long aFlags, + in unsigned short aExpiration, + [optional] in unsigned short aSource); + + /** + * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist. + */ + [noscript] void setPageAnnotationString(in nsIURI aURI, + in AUTF8String aName, + in AString aValue, + in long aFlags, + in unsigned short aExpiration); + [noscript] void setItemAnnotationString(in long long aItemId, + in AUTF8String aName, + in AString aValue, + in long aFlags, + in unsigned short aExpiration, + [optional] in unsigned short aSource); + + /** + * Sets an annotation just like setAnnotationString, but takes an Int32 as + * input. + * + * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist. + */ + [noscript] void setPageAnnotationInt32(in nsIURI aURI, + in AUTF8String aName, + in long aValue, + in long aFlags, + in unsigned short aExpiration); + [noscript] void setItemAnnotationInt32(in long long aItemId, + in AUTF8String aName, + in long aValue, + in long aFlags, + in unsigned short aExpiration, + [optional] in unsigned short aSource); + + /** + * Sets an annotation just like setAnnotationString, but takes an Int64 as + * input. + * + * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist. + */ + [noscript] void setPageAnnotationInt64(in nsIURI aURI, + in AUTF8String aName, + in long long aValue, + in long aFlags, + in unsigned short aExpiration); + [noscript] void setItemAnnotationInt64(in long long aItemId, + in AUTF8String aName, + in long long aValue, + in long aFlags, + in unsigned short aExpiration, + [optional] in unsigned short aSource); + + /** + * Sets an annotation just like setAnnotationString, but takes a double as + * input. + * + * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist. + */ + [noscript] void setPageAnnotationDouble(in nsIURI aURI, + in AUTF8String aName, + in double aValue, + in long aFlags, + in unsigned short aExpiration); + [noscript] void setItemAnnotationDouble(in long long aItemId, + in AUTF8String aName, + in double aValue, + in long aFlags, + in unsigned short aExpiration, + [optional] in unsigned short aSource); + + /** + * Retrieves the value of a given annotation. Throws an error if the + * annotation does not exist. C++ consumers may use the type-specific + * methods. + * + * The type-specific methods throw if the given annotation is set in + * a different type. + */ + nsIVariant getPageAnnotation(in nsIURI aURI, + in AUTF8String aName); + nsIVariant getItemAnnotation(in long long aItemId, + in AUTF8String aName); + + /** + * @see getPageAnnotation + */ + [noscript] AString getPageAnnotationString(in nsIURI aURI, + in AUTF8String aName); + [noscript] AString getItemAnnotationString(in long long aItemId, + in AUTF8String aName); + + /** + * @see getPageAnnotation + */ + [noscript] long getPageAnnotationInt32(in nsIURI aURI, + in AUTF8String aName); + [noscript] long getItemAnnotationInt32(in long long aItemId, + in AUTF8String aName); + + /** + * @see getPageAnnotation + */ + [noscript] long long getPageAnnotationInt64(in nsIURI aURI, + in AUTF8String aName); + [noscript] long long getItemAnnotationInt64(in long long aItemId, + in AUTF8String aName); + + /** + * @see getPageAnnotation + */ + [noscript] double getPageAnnotationDouble(in nsIURI aURI, + in AUTF8String aName); + [noscript] double getItemAnnotationDouble(in long long aItemId, + in AUTF8String aName); + + /** + * Retrieves info about an existing annotation. + * + * aType will be one of TYPE_* constansts above + * + * example JS: + * var flags = {}, exp = {}, type = {}; + * annotator.getAnnotationInfo(myURI, "foo", flags, exp, type); + * // now you can use 'exp.value' and 'flags.value' + */ + void getPageAnnotationInfo(in nsIURI aURI, + in AUTF8String aName, + out int32_t aFlags, + out unsigned short aExpiration, + out unsigned short aType); + void getItemAnnotationInfo(in long long aItemId, + in AUTF8String aName, + out long aFlags, + out unsigned short aExpiration, + out unsigned short aType); + + /** + * Retrieves the type of an existing annotation + * Use getAnnotationInfo if you need this along with the mime-type etc. + * + * @param aURI + * the uri on which the annotation is set + * @param aName + * the annotation name + * @return one of the TYPE_* constants above + * @throws if the annotation is not set + */ + uint16_t getPageAnnotationType(in nsIURI aURI, + in AUTF8String aName); + uint16_t getItemAnnotationType(in long long aItemId, + in AUTF8String aName); + + /** + * Returns a list of all URIs having a given annotation. + */ + void getPagesWithAnnotation( + in AUTF8String name, + [optional] out unsigned long resultCount, + [retval, array, size_is(resultCount)] out nsIURI results); + void getItemsWithAnnotation( + in AUTF8String name, + [optional] out unsigned long resultCount, + [retval, array, size_is(resultCount)] out long long results); + + /** + * Returns a list of mozIAnnotation(s), having a given annotation name. + * + * @param name + * The annotation to search for. + * @return list of mozIAnnotation objects. + */ + void getAnnotationsWithName( + in AUTF8String name, + [optional] out unsigned long count, + [retval, array, size_is(count)] out mozIAnnotatedResult results); + + /** + * Get the names of all annotations for this URI. + * + * example JS: + * var annotations = annotator.getPageAnnotations(myURI, {}); + */ + void getPageAnnotationNames( + in nsIURI aURI, + [optional] out unsigned long count, + [retval, array, size_is(count)] out nsIVariant result); + void getItemAnnotationNames( + in long long aItemId, + [optional] out unsigned long count, + [retval, array, size_is(count)] out nsIVariant result); + + /** + * Test for annotation existence. + */ + boolean pageHasAnnotation(in nsIURI aURI, + in AUTF8String aName); + boolean itemHasAnnotation(in long long aItemId, + in AUTF8String aName); + + /** + * Removes a specific annotation. Succeeds even if the annotation is + * not found. + */ + void removePageAnnotation(in nsIURI aURI, + in AUTF8String aName); + void removeItemAnnotation(in long long aItemId, + in AUTF8String aName, + [optional] in unsigned short aSource); + + /** + * Removes all annotations for the given page/item. + * We may want some other similar functions to get annotations with given + * flags (once we have flags defined). + */ + void removePageAnnotations(in nsIURI aURI); + void removeItemAnnotations(in long long aItemId, + [optional] in unsigned short aSource); + + /** + * Copies all annotations from the source to the destination URI/item. If + * the destination already has an annotation with the same name as one on + * the source, it will be overwritten if aOverwriteDest is set. Otherwise, + * the original annotation will be preferred. + * + * All the source annotations will stay as-is. If you don't want them + * any more, use removePageAnnotations on that URI. + */ + void copyPageAnnotations(in nsIURI aSourceURI, + in nsIURI aDestURI, + in boolean aOverwriteDest); + void copyItemAnnotations(in long long aSourceItemId, + in long long aDestItemId, + in boolean aOverwriteDest, + [optional] in unsigned short aSource); + + /** + * Adds an annotation observer. The annotation service will keep an owning + * reference to the observer object. + */ + void addObserver(in nsIAnnotationObserver aObserver); + + + /** + * Removes an annotaton observer previously registered by addObserver. + */ + void removeObserver(in nsIAnnotationObserver aObserver); +}; + +/** + * Represents a place annotated with a given annotation. If a place has + * multiple annotations, it can be represented by multiple + * mozIAnnotatedResult(s). + */ +[scriptable, uuid(81fd0188-db6a-492e-80b6-f6414913b396)] +interface mozIAnnotatedResult : nsISupports +{ + /** + * The globally unique identifier of the place with this annotation. + * + * @note if itemId is valid this is the guid of the bookmark, otherwise + * of the page. + */ + readonly attribute AUTF8String guid; + + /** + * The URI of the place with this annotation, if available, null otherwise. + */ + readonly attribute nsIURI uri; + + /** + * The bookmark id of the place with this annotation, if available, + * -1 otherwise. + * + * @note if itemId is -1, it doesn't mean the page is not bookmarked, just + * that this annotation is relative to the page, not to the bookmark. + */ + readonly attribute long long itemId; + + /** + * Name of the annotation. + */ + readonly attribute AUTF8String annotationName; + + /** + * Value of the annotation. + */ + readonly attribute nsIVariant annotationValue; +}; diff --git a/components/places/public/nsIBrowserHistory.idl b/components/places/public/nsIBrowserHistory.idl new file mode 100644 index 000000000..8f3265972 --- /dev/null +++ b/components/places/public/nsIBrowserHistory.idl @@ -0,0 +1,70 @@ +/* -*- 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); +}; diff --git a/components/places/public/nsIFaviconService.idl b/components/places/public/nsIFaviconService.idl new file mode 100644 index 000000000..25339d64b --- /dev/null +++ b/components/places/public/nsIFaviconService.idl @@ -0,0 +1,145 @@ +/* -*- 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/. */ + +#include "nsISupports.idl" + +interface nsIURI; + +[scriptable, uuid(e81e0b0c-b9f1-4c2e-8f3c-b809933cf73c)] +interface nsIFaviconService : nsISupports +{ + // The favicon is being loaded from a private browsing window + const unsigned long FAVICON_LOAD_PRIVATE = 1; + // The favicon is being loaded from a non-private browsing window + const unsigned long FAVICON_LOAD_NON_PRIVATE = 2; + + /** + * The limit in bytes of the size of favicons in memory and passed via the + * favicon protocol. + */ + const unsigned long MAX_FAVICON_BUFFER_SIZE = 10240; + + /** + * For a given icon URI, this will return a URI that will result in the image. + * In most cases, this is an annotation URI. For chrome URIs, this will do + * nothing but returning the input URI. + * + * No validity checking is done. If you pass an icon URI that we've never + * seen, you'll get back a URI that references an invalid icon. The moz-anno + * protocol handler's special case for "favicon" annotations will resolve + * invalid icons to the default icon, although without caching. + * For invalid chrome URIs, you'll get a broken image. + * + * @param aFaviconURI + * The URI of an icon in the favicon service. + * @return A URI that will give you the icon image. This is NOT the URI of + * the icon as set on the page, but a URI that will give you the + * data out of the favicon service. For a normal page with a + * favicon we've stored, this will be an annotation URI which will + * then cause the corresponding favicon data to be loaded async from + * this service. For pages where we don't have a favicon, this will + * be a chrome URI of the default icon. For chrome URIs, the + * output will be the same as the input. + */ + nsIURI getFaviconLinkForIcon(in nsIURI aFaviconURI); + + /** + * Expire all known favicons from the database. + * + * @note This is an async method. + * On successful completion a "places-favicons-expired" notification is + * dispatched through observer's service. + */ + void expireAllFavicons(); + + /** + * Adds a given favicon's URI to the failed favicon cache. + * + * The lifespan of the favicon cache is up to the caching system. This cache + * will also be written when setAndLoadFaviconForPage hits an error while + * fetching an icon. + * + * @param aFaviconURI + * The URI of an icon in the favicon service. + */ + void addFailedFavicon(in nsIURI aFaviconURI); + + /** + * Removes the given favicon from the failed favicon cache. If the icon is + * not in the cache, it will silently succeed. + * + * @param aFaviconURI + * The URI of an icon in the favicon service. + */ + void removeFailedFavicon(in nsIURI aFaviconURI); + + /** + * Checks to see if a favicon is in the failed favicon cache. + * A positive return value means the icon is in the failed cache and you + * probably shouldn't try to load it. A false return value means that it's + * worth trying to load it. + * This allows you to avoid trying to load "foo.com/favicon.ico" for every + * page on a site that doesn't have a favicon. + * + * @param aFaviconURI + * The URI of an icon in the favicon service. + */ + boolean isFailedFavicon(in nsIURI aFaviconURI); + + /** + * The default favicon URI + */ + readonly attribute nsIURI defaultFavicon; +}; + +[scriptable, function, uuid(c85e5c82-b70f-4621-9528-beb2aa47fb44)] +interface nsIFaviconDataCallback : nsISupports +{ + /** + * Called when the required favicon's information is available. + * + * It's up to the invoking method to state if the callback is always invoked, + * or called on success only. Check the method documentation to ensure that. + * + * The caller will receive the most information we can gather on the icon, + * but it's not guaranteed that all of them will be set. For some method + * we could not know the favicon's data (it could just be too expensive to + * get it, or the method does not require we actually have any data). + * It's up to the caller to check aDataLen > 0 before using any data-related + * information like mime-type or data itself. + * + * @param aFaviconURI + * Receives the "favicon URI" (not the "favicon link URI") associated + * to the requested page. This can be null if there is no associated + * favicon URI, or the callback is notifying a failure. + * @param aDataLen + * Size of the icon data in bytes. Notice that a value of 0 does not + * necessarily mean that we don't have an icon. + * @param aData + * Icon data, or an empty array if aDataLen is 0. + * @param aMimeType + * Mime type of the icon, or an empty string if aDataLen is 0. + * + * @note If you want to open a network channel to access the favicon, it's + * recommended that you call the getFaviconLinkForIcon method to convert + * the "favicon URI" into a "favicon link URI". + */ + void onComplete(in nsIURI aFaviconURI, + in unsigned long aDataLen, + [const,array,size_is(aDataLen)] in octet aData, + in AUTF8String aMimeType); +}; + +%{C++ + +/** + * Notification sent when all favicons are expired. + */ +#define NS_PLACES_FAVICONS_EXPIRED_TOPIC_ID "places-favicons-expired" + +#define FAVICON_DEFAULT_URL "chrome://mozapps/skin/places/defaultFavicon.png" +#define FAVICON_ERRORPAGE_URL "chrome://global/skin/icons/warning-16.png" + +%} diff --git a/components/places/public/nsINavBookmarksService.idl b/components/places/public/nsINavBookmarksService.idl new file mode 100644 index 000000000..e9e49a4f4 --- /dev/null +++ b/components/places/public/nsINavBookmarksService.idl @@ -0,0 +1,697 @@ +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* 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/. */ + +#include "nsISupports.idl" + +interface nsIFile; +interface nsIURI; +interface nsITransaction; +interface nsINavHistoryBatchCallback; + +/** + * Observer for bookmarks changes. + */ +[scriptable, uuid(c06b4e7d-15b1-4d4f-bdf7-147d2be9084a)] +interface nsINavBookmarkObserver : nsISupports +{ + /* + * This observer should not be called for items that are tags. + */ + readonly attribute boolean skipTags; + + /* + * This observer should not be called for descendants when the parent is removed. + * For example when revmoing a folder containing bookmarks. + */ + readonly attribute boolean skipDescendantsOnItemRemoval; + + /** + * Notifies that a batch transaction has started. + * Other notifications will be sent during the batch, but the observer is + * guaranteed that onEndUpdateBatch() will be called at its completion. + * During a batch the observer should do its best to reduce the work done to + * handle notifications, since multiple changes are going to happen in a short + * timeframe. + */ + void onBeginUpdateBatch(); + + /** + * Notifies that a batch transaction has ended. + */ + void onEndUpdateBatch(); + + /** + * Notifies that an item (any type) was added. Called after the actual + * addition took place. + * When a new item is created, all the items following it in the same folder + * will have their index shifted down, but no additional notifications will + * be sent. + * + * @param aItemId + * The id of the item that was added. + * @param aParentId + * The id of the folder to which the item was added. + * @param aIndex + * The item's index in the folder. + * @param aItemType + * The type of the added item (see TYPE_* constants below). + * @param aURI + * The URI of the added item if it was TYPE_BOOKMARK, null otherwise. + * @param aTitle + * The title of the added item. + * @param aDateAdded + * The stored date added value, in microseconds from the epoch. + * @param aGuid + * The unique ID associated with the item. + * @param aParentGuid + * The unique ID associated with the item's parent. + * @param aSource + * A change source constant from nsINavBookmarksService::SOURCE_*, + * passed to the method that notifies the observer. + */ + void onItemAdded(in long long aItemId, + in long long aParentId, + in long aIndex, + in unsigned short aItemType, + in nsIURI aURI, + in AUTF8String aTitle, + in PRTime aDateAdded, + in ACString aGuid, + in ACString aParentGuid, + in unsigned short aSource); + + /** + * Notifies that an item was removed. Called after the actual remove took + * place. + * When an item is removed, all the items following it in the same folder + * will have their index shifted down, but no additional notifications will + * be sent. + * + * @param aItemId + * The id of the item that was removed. + * @param aParentId + * The id of the folder from which the item was removed. + * @param aIndex + * The bookmark's index in the folder. + * @param aItemType + * The type of the item to be removed (see TYPE_* constants below). + * @param aURI + * The URI of the added item if it was TYPE_BOOKMARK, null otherwise. + * @param aGuid + * The unique ID associated with the item. + * @param aParentGuid + * The unique ID associated with the item's parent. + * @param aSource + * A change source constant from nsINavBookmarksService::SOURCE_*, + * passed to the method that notifies the observer. + */ + void onItemRemoved(in long long aItemId, + in long long aParentId, + in long aIndex, + in unsigned short aItemType, + in nsIURI aURI, + in ACString aGuid, + in ACString aParentGuid, + in unsigned short aSource); + + /** + * Notifies that an item's information has changed. This will be called + * whenever any attributes like "title" are changed. + * + * @param aItemId + * The id of the item that was changed. + * @param aProperty + * The property which changed. Can be null for the removal of all of + * the annotations, in this case aIsAnnotationProperty is true. + * @param aIsAnnotationProperty + * Whether or not aProperty is the name of an annotation. If true + * aNewValue is always an empty string. + * @param aNewValue + * For certain properties, this is set to the new value of the + * property (see the list below). + * @param aLastModified + * The updated last-modified value. + * @param aItemType + * The type of the item to be removed (see TYPE_* constants below). + * @param aParentId + * The id of the folder containing the item. + * @param aGuid + * The unique ID associated with the item. + * @param aParentGuid + * The unique ID associated with the item's parent. + * @param aOldValue + * For certain properties, this is set to the new value of the + * property (see the list below). + * @param aSource + * A change source constant from nsINavBookmarksService::SOURCE_*, + * passed to the method that notifies the observer. + * + * @note List of values that may be associated with properties: + * aProperty | aNewValue + * ===================================================================== + * cleartime | Empty string (all visits to this item were removed). + * title | The new title. + * favicon | The "moz-anno" URL of the new favicon. + * uri | new URL. + * tags | Empty string (tags for this item changed) + * dateAdded | PRTime (as string) when the item was first added. + * lastModified | PRTime (as string) when the item was last modified. + * + * aProperty | aOldValue + * ===================================================================== + * cleartime | Empty string (currently unused). + * title | Empty string (currently unused). + * favicon | Empty string (currently unused). + * uri | old URL. + * tags | Empty string (currently unused). + * dateAdded | Empty string (currently unused). + * lastModified | Empty string (currently unused). + */ + void onItemChanged(in long long aItemId, + in ACString aProperty, + in boolean aIsAnnotationProperty, + in AUTF8String aNewValue, + in PRTime aLastModified, + in unsigned short aItemType, + in long long aParentId, + in ACString aGuid, + in ACString aParentGuid, + in AUTF8String aOldValue, + in unsigned short aSource); + + /** + * Notifies that the item was visited. Can be invoked only for TYPE_BOOKMARK + * items. + * + * @param aItemId + * The id of the bookmark that was visited. + * @param aVisitId + * The id of the visit. + * @param aTime + * The time of the visit. + * @param aTransitionType + * The transition for the visit. See nsINavHistoryService::TRANSITION_* + * constants for a list of possible values. + * @param aURI + * The nsIURI for this bookmark. + * @param aParentId + * The id of the folder containing the item. + * @param aGuid + * The unique ID associated with the item. + * @param aParentGuid + * The unique ID associated with the item's parent. + * + * @see onItemChanged with property = "cleartime" for when all visits to an + * item are removed. + * + * @note The reported time is the time of the visit that was added, which may + * be well in the past since the visit time can be specified. This + * means that the visit the observer is told about may not be the most + * recent visit for that page. + */ + void onItemVisited(in long long aItemId, + in long long aVisitId, + in PRTime aTime, + in unsigned long aTransitionType, + in nsIURI aURI, + in long long aParentId, + in ACString aGuid, + in ACString aParentGuid); + + /** + * Notifies that an item has been moved. + * + * @param aItemId + * The id of the item that was moved. + * @param aOldParentId + * The id of the old parent. + * @param aOldIndex + * The old index inside the old parent. + * @param aNewParentId + * The id of the new parent. + * @param aNewIndex + * The index inside the new parent. + * @param aItemType + * The type of the item to be removed (see TYPE_* constants below). + * @param aGuid + * The unique ID associated with the item. + * @param aOldParentGuid + * The unique ID associated with the old item's parent. + * @param aNewParentGuid + * The unique ID associated with the new item's parent. + * @param aSource + * A change source constant from nsINavBookmarksService::SOURCE_*, + * passed to the method that notifies the observer. + */ + void onItemMoved(in long long aItemId, + in long long aOldParentId, + in long aOldIndex, + in long long aNewParentId, + in long aNewIndex, + in unsigned short aItemType, + in ACString aGuid, + in ACString aOldParentGuid, + in ACString aNewParentGuid, + in unsigned short aSource); +}; + +/** + * The BookmarksService interface provides methods for managing bookmarked + * history items. Bookmarks consist of a set of user-customizable + * folders. A URI in history can be contained in one or more such folders. + */ + +[scriptable, uuid(24533891-afa6-4663-b72d-3143d03f1b04)] +interface nsINavBookmarksService : nsISupports +{ + /** + * The item ID of the Places root. + */ + readonly attribute long long placesRoot; + + /** + * The item ID of the bookmarks menu folder. + */ + readonly attribute long long bookmarksMenuFolder; + + /** + * The item ID of the top-level folder that contain the tag "folders". + */ + readonly attribute long long tagsFolder; + + /** + * The item ID of the unfiled-bookmarks folder. + */ + readonly attribute long long unfiledBookmarksFolder; + + /** + * The item ID of the personal toolbar folder. + */ + readonly attribute long long toolbarFolder; + + /** + * The item ID of the mobile bookmarks folder. + */ + readonly attribute long long mobileFolder; + + /** + * This value should be used for APIs that allow passing in an index + * where an index is not known, or not required to be specified. + * e.g.: When appending an item to a folder. + */ + const short DEFAULT_INDEX = -1; + + const unsigned short TYPE_BOOKMARK = 1; + const unsigned short TYPE_FOLDER = 2; + const unsigned short TYPE_SEPARATOR = 3; + // Dynamic containers are deprecated and unsupported. + // This const exists just to avoid reusing the value. + const unsigned short TYPE_DYNAMIC_CONTAINER = 4; + + // Change source constants. These are used to distinguish changes made by + // Sync and bookmarks import from other Places consumers, though they can + // be extended to support other callers. Sources are passed as optional + // parameters to methods used by Sync, and forwarded to observers. + const unsigned short SOURCE_DEFAULT = 0; + const unsigned short SOURCE_SYNC = 1; + const unsigned short SOURCE_IMPORT = 2; + const unsigned short SOURCE_IMPORT_REPLACE = 3; + + /** + * Inserts a child bookmark into the given folder. + * + * @param aParentId + * The id of the parent folder + * @param aURI + * The URI to insert + * @param aIndex + * The index to insert at, or DEFAULT_INDEX to append + * @param aTitle + * The title for the new bookmark + * @param [optional] aGuid + * The GUID to be set for the new item. If not set, a new GUID is + * generated. Unless you've a very sound reason, such as an undo + * manager implementation, do not pass this argument. + * @param [optional] aSource + * The change source. This is forwarded to all bookmark observers, + * allowing them to distinguish between insertions from different + * callers. Defaults to SOURCE_DEFAULT if omitted. + * @return The ID of the newly-created bookmark. + * + * @note aTitle will be truncated to TITLE_LENGTH_MAX and + * aURI will be truncated to URI_LENGTH_MAX. + * @throws if aGuid is malformed. + */ + long long insertBookmark(in long long aParentId, in nsIURI aURI, + in long aIndex, in AUTF8String aTitle, + [optional] in ACString aGuid, + [optional] in unsigned short aSource); + + /** + * Removes a child item. Used to delete a bookmark or separator. + * @param aItemId + * The child item to remove + * @param [optional] aSource + * The change source, forwarded to all bookmark observers. Defaults + * to SOURCE_DEFAULT. + */ + void removeItem(in long long aItemId, [optional] in unsigned short aSource); + + /** + * Creates a new child folder and inserts it under the given parent. + * @param aParentFolder + * The id of the parent folder + * @param aName + * The name of the new folder + * @param aIndex + * The index to insert at, or DEFAULT_INDEX to append + * @param [optional] aGuid + * The GUID to be set for the new item. If not set, a new GUID is + * generated. Unless you've a very sound reason, such as an undo + * manager implementation, do not pass this argument. + * @param [optional] aSource + * The change source, forwarded to all bookmark observers. Defaults + * to SOURCE_DEFAULT. + * @return The ID of the newly-inserted folder. + * @throws if aGuid is malformed. + */ + long long createFolder(in long long aParentFolder, in AUTF8String name, + in long index, + [optional] in ACString aGuid, + [optional] in unsigned short aSource); + + /** + * Gets an undo-able transaction for removing a folder from the bookmarks + * tree. + * @param aItemId + * The id of the folder to remove. + * @param [optional] aSource + * The change source, forwarded to all bookmark observers. Defaults + * to SOURCE_DEFAULT. + * @return An object implementing nsITransaction that can be used to undo + * or redo the action. + * + * This method exists because complex delete->undo operations rely on + * recreated folders to have the same ID they had before they were deleted, + * so that any other items deleted in different transactions can be + * re-inserted correctly. This provides a safe encapsulation of this + * functionality without exposing the ability to recreate folders with + * specific IDs (potentially dangerous if abused by other code!) in the + * public API. + */ + nsITransaction getRemoveFolderTransaction(in long long aItemId, + [optional] in unsigned short aSource); + + /** + * Convenience function for container services. Removes + * all children of the given folder. + * @param aItemId + * The id of the folder to remove children from. + * @param [optional] aSource + * The change source, forwarded to all bookmark observers. Defaults + * to SOURCE_DEFAULT. + */ + void removeFolderChildren(in long long aItemId, + [optional] in unsigned short aSource); + + /** + * Moves an item to a different container, preserving its contents. + * @param aItemId + * The id of the item to move + * @param aNewParentId + * The id of the new parent + * @param aIndex + * The index under aNewParent, or DEFAULT_INDEX to append + * @param [optional] aSource + * The change source, forwarded to all bookmark observers. Defaults + * to SOURCE_DEFAULT. + * + * NOTE: When moving down in the same container we take into account the + * removal of the original item. If you want to move from index X to + * index Y > X you must use moveItem(id, folder, Y + 1) + */ + void moveItem(in long long aItemId, + in long long aNewParentId, + in long aIndex, + [optional] in unsigned short aSource); + + /** + * Inserts a bookmark separator into the given folder at the given index. + * The separator can be removed using removeChildAt(). + * @param aParentId + * The id of the parent folder + * @param aIndex + * The separator's index under folder, or DEFAULT_INDEX to append + * @param [optional] aGuid + * The GUID to be set for the new item. If not set, a new GUID is + * generated. Unless you've a very sound reason, such as an undo + * manager implementation, do not pass this argument. + * @param [optional] aSource + * The change source, forwarded to all bookmark observers. Defaults + * to SOURCE_DEFAULT. + * @return The ID of the new separator. + * @throws if aGuid is malformed. + */ + long long insertSeparator(in long long aParentId, in long aIndex, + [optional] in ACString aGuid, + [optional] in unsigned short aSource); + + /** + * Get the itemId given the containing folder and the index. + * @param aParentId + * The id of the diret parent folder of the item + * @param aIndex + * The index of the item within the parent folder. + * Pass DEFAULT_INDEX for the last item. + * @return The ID of the found item, -1 if the item does not exists. + */ + long long getIdForItemAt(in long long aParentId, in long aIndex); + + /** + * Set the title for an item. + * @param aItemId + * The id of the item whose title should be updated. + * @param aTitle + * The new title for the bookmark. + * @param [optional] aSource + * The change source, forwarded to all bookmark observers. Defaults + * to SOURCE_DEFAULT. + * + * @note aTitle will be truncated to TITLE_LENGTH_MAX. + */ + void setItemTitle(in long long aItemId, in AUTF8String aTitle, + [optional] in unsigned short aSource); + + /** + * Get the title for an item. + * + * If no item title is available it will return a void string (null in JS). + * + * @param aItemId + * The id of the item whose title should be retrieved + * @return The title of the item. + */ + AUTF8String getItemTitle(in long long aItemId); + + /** + * Set the date added time for an item. + * + * @param aItemId + * the id of the item whose date added time should be updated. + * @param aDateAdded + * the new date added value in microseconds. Note that it is rounded + * down to milliseconds precision. + * @param [optional] aSource + * The change source, forwarded to all bookmark observers. Defaults + * to SOURCE_DEFAULT. + */ + void setItemDateAdded(in long long aItemId, + in PRTime aDateAdded, + [optional] in unsigned short aSource); + + /** + * Get the date added time for an item. + * + * @param aItemId + * the id of the item whose date added time should be retrieved. + * + * @return the date added value in microseconds. + */ + PRTime getItemDateAdded(in long long aItemId); + + /** + * Set the last modified time for an item. + * + * @param aItemId + * the id of the item whose last modified time should be updated. + * @param aLastModified + * the new last modified value in microseconds. Note that it is + * rounded down to milliseconds precision. + * @param [optional] aSource + * The change source, forwarded to all bookmark observers. Defaults + * to SOURCE_DEFAULT. + * + * @note This is the only method that will send an itemChanged notification + * for the property. lastModified will still be updated in + * any other method that changes an item property, but we will send + * the corresponding itemChanged notification instead. + */ + void setItemLastModified(in long long aItemId, + in PRTime aLastModified, + [optional] in unsigned short aSource); + + /** + * Get the last modified time for an item. + * + * @param aItemId + * the id of the item whose last modified time should be retrieved. + * + * @return the date added value in microseconds. + * + * @note When an item is added lastModified is set to the same value as + * dateAdded. + */ + PRTime getItemLastModified(in long long aItemId); + + /** + * Get the URI for a bookmark item. + */ + nsIURI getBookmarkURI(in long long aItemId); + + /** + * Get the index for an item. + */ + long getItemIndex(in long long aItemId); + + /** + * Changes the index for a item. This method does not change the indices of + * any other items in the same folder, so ensure that the new index does not + * already exist, or change the index of other items accordingly, otherwise + * the indices will become corrupted. + * + * WARNING: This is API is intended for scenarios such as folder sorting, + * where the caller manages the indices of *all* items in the folder. + * You must always ensure each index is unique after a reordering. + * + * @param aItemId The id of the item to modify + * @param aNewIndex The new index + * @param aSource The optional change source, forwarded to all bookmark + * observers. Defaults to SOURCE_DEFAULT. + * + * @throws If aNewIndex is out of bounds. + */ + void setItemIndex(in long long aItemId, + in long aNewIndex, + [optional] in unsigned short aSource); + + /** + * Get an item's type (bookmark, separator, folder). + * The type is one of the TYPE_* constants defined above. + */ + unsigned short getItemType(in long long aItemId); + + /** + * Returns true if the given URI is in any bookmark folder. If you want the + * results to be redirect-aware, use getBookmarkedURIFor() + */ + boolean isBookmarked(in nsIURI aURI); + + /** + * Used to see if the given URI is bookmarked, or any page that redirected to + * it is bookmarked. For example, if I bookmark "mozilla.org" by manually + * typing it in, and follow the bookmark, I will get redirected to + * "www.mozilla.org". Logically, this new page is also bookmarked. This + * function, if given "www.mozilla.org", will return the URI of the bookmark, + * in this case "mozilla.org". + * + * If there is no bookmarked page found, it will return NULL. + * + * @note The function will only return bookmarks in the first 2 levels of + * redirection (1 -> 2 -> aURI). + */ + nsIURI getBookmarkedURIFor(in nsIURI aURI); + + /** + * Change the bookmarked URI for a bookmark. + * This changes which "place" the bookmark points at, + * which means all annotations, etc are carried along. + */ + void changeBookmarkURI(in long long aItemId, + in nsIURI aNewURI, + [optional] in unsigned short aSource); + + /** + * Get the parent folder's id for an item. + */ + long long getFolderIdForItem(in long long aItemId); + + /** + * Returns the list of bookmark ids that contain the given URI. + */ + void getBookmarkIdsForURI(in nsIURI aURI, [optional] out unsigned long count, + [array, retval, size_is(count)] out long long bookmarks); + + /** + * Associates the given keyword with the given bookmark. + * + * Use an empty keyword to clear the keyword associated with the URI. + * In both of these cases, succeeds but does nothing if the URL/keyword is not found. + * + * @deprecated Use PlacesUtils.keywords.insert() API instead. + */ + void setKeywordForBookmark(in long long aItemId, + in AString aKeyword, + [optional] in unsigned short aSource); + + /** + * Retrieves the keyword for the given bookmark. Will be void string + * (null in JS) if no such keyword is found. + * + * @deprecated Use PlacesUtils.keywords.fetch() API instead. + */ + AString getKeywordForBookmark(in long long aItemId); + + /** + * Returns the URI associated with the given keyword. Empty if no such + * keyword is found. + * + * @deprecated Use PlacesUtils.keywords.fetch() API instead. + */ + nsIURI getURIForKeyword(in AString keyword); + + /** + * Adds a bookmark observer. If ownsWeak is false, the bookmark service will + * keep an owning reference to the observer. If ownsWeak is true, then + * aObserver must implement nsISupportsWeakReference, and the bookmark + * service will keep a weak reference to the observer. + */ + void addObserver(in nsINavBookmarkObserver observer, in boolean ownsWeak); + + /** + * Removes a bookmark observer. + */ + void removeObserver(in nsINavBookmarkObserver observer); + + /** + * Gets an array of registered nsINavBookmarkObserver objects. + */ + void getObservers([optional] out unsigned long count, + [retval, array, size_is(count)] out nsINavBookmarkObserver observers); + + /** + * Runs the passed callback inside of a database transaction. + * Use this when a lot of things are about to change, for example + * adding or deleting a large number of bookmark items. Calls can + * be nested. Observers are notified when batches begin and end, via + * nsINavBookmarkObserver.onBeginUpdateBatch/onEndUpdateBatch. + * + * @param aCallback + * nsINavHistoryBatchCallback interface to call. + * @param aUserData + * Opaque parameter passed to nsINavBookmarksBatchCallback + */ + void runInBatchMode(in nsINavHistoryBatchCallback aCallback, + in nsISupports aUserData); +}; diff --git a/components/places/public/nsINavHistoryService.idl b/components/places/public/nsINavHistoryService.idl new file mode 100644 index 000000000..3fd851870 --- /dev/null +++ b/components/places/public/nsINavHistoryService.idl @@ -0,0 +1,1451 @@ +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* 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/. */ + +/** + * Using Places services after quit-application is not reliable, so make + * sure to do any shutdown work on quit-application, or history + * synchronization could fail, losing latest changes. + */ + +#include "nsISupports.idl" + +interface nsIArray; +interface nsIURI; +interface nsIVariant; +interface nsIFile; + +interface nsINavHistoryContainerResultNode; +interface nsINavHistoryQueryResultNode; +interface nsINavHistoryQuery; +interface nsINavHistoryQueryOptions; +interface nsINavHistoryResult; +interface nsINavHistoryBatchCallback; + +[scriptable, uuid(91d104bb-17ef-404b-9f9a-d9ed8de6824c)] +interface nsINavHistoryResultNode : nsISupports +{ + /** + * Indentifies the parent result node in the result set. This is null for + * top level nodes. + */ + readonly attribute nsINavHistoryContainerResultNode parent; + + /** + * The history-result to which this node belongs. + */ + readonly attribute nsINavHistoryResult parentResult; + + /** + * URI of the resource in question. For visits and URLs, this is the URL of + * the page. For folders and queries, this is the place: URI of the + * corresponding folder or query. This may be empty for other types of + * objects like host containers. + */ + readonly attribute AUTF8String uri; + + /** + * Identifies the type of this node. This node can then be QI-ed to the + * corresponding specialized result node interface. + */ + const unsigned long RESULT_TYPE_URI = 0; // nsINavHistoryResultNode + + // Visit nodes are deprecated and unsupported. + // This line exists just to avoid reusing the value: + // const unsigned long RESULT_TYPE_VISIT = 1; + + // Full visit nodes are deprecated and unsupported. + // This line exists just to avoid reusing the value: + // const unsigned long RESULT_TYPE_FULL_VISIT = 2; + + // Dynamic containers are deprecated and unsupported. + // This const exists just to avoid reusing the value: + // 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; + + /** + * Title of the web page, or of the node's query (day, host, folder, etc) + */ + readonly attribute AUTF8String title; + + /** + * Total number of times the URI has ever been accessed. For hosts, this + * is the total of the children under it, NOT the total times the host has + * been accessed (this would require an additional query, so is not given + * by default when most of the time it is never needed). + */ + readonly attribute unsigned long accessCount; + + /** + * This is the time the user accessed the page. + * + * If this is a visit, it is the exact time that the page visit occurred. + * + * If this is a URI, it is the most recent time that the URI was visited. + * Even if you ask for all URIs for a given date range long ago, this might + * contain today's date if the URI was visited today. + * + * For hosts, or other node types with children, this is the most recent + * access time for any of the children. + * + * For days queries this is the respective endTime - a maximum possible + * visit time to fit in the day range. + */ + readonly attribute PRTime time; + + /** + * This URI can be used as an image source URI and will give you the favicon + * for the page. It is *not* the URI of the favicon, but rather something + * that will resolve to the actual image. + * + * In most cases, this is an annotation URI that will query the favicon + * service. If the entry has no favicon, this is the chrome URI of the + * default favicon. If the favicon originally lived in chrome, this will + * be the original chrome URI of the icon. + */ + readonly attribute AUTF8String icon; + + /** + * This is the number of levels between this node and the top of the + * hierarchy. The members of result.children have indentLevel = 0, their + * children have indentLevel = 1, etc. The indent level of the root node is + * set to -1. + */ + readonly attribute long indentLevel; + + /** + * When this item is in a bookmark folder (parent is of type folder), this is + * the index into that folder of this node. These indices start at 0 and + * increase in the order that they appear in the bookmark folder. For items + * that are not in a bookmark folder, this value is -1. + */ + readonly attribute long bookmarkIndex; + + /** + * If the node is an item (bookmark, folder or a separator) this value is the + * row ID of that bookmark in the database. For other nodes, this value is + * set to -1. + */ + readonly attribute long long itemId; + + /** + * If the node is an item (bookmark, folder or a separator) this value is the + * time that the item was created. For other nodes, this value is 0. + */ + readonly attribute PRTime dateAdded; + + /** + * If the node is an item (bookmark, folder or a separator) this value is the + * time that the item was last modified. For other nodes, this value is 0. + * + * @note When an item is added lastModified is set to the same value as + * dateAdded. + */ + readonly attribute PRTime lastModified; + + /** + * For uri nodes, this is a sorted list of the tags, delimited with commans, + * for the uri represented by this node. Otherwise this is an empty string. + */ + readonly attribute AString tags; + + /** + * The unique ID associated with the page. It my return an empty string + * if the result node is a non-URI node. + */ + readonly attribute ACString pageGuid; + + /** + * The unique ID associated with the bookmark. It returns an empty string + * if the result node is not associated with a bookmark, a folder or a + * separator. + */ + readonly attribute ACString bookmarkGuid; + + /** + * The unique ID associated with the history visit. For node types other than + * history visit nodes, this value is -1. + */ + readonly attribute long long visitId; + + /** + * The unique ID associated with visit node which was the referrer of this + * history visit. For node types other than history visit nodes, or visits + * without any known referrer, this value is -1. + */ + readonly attribute long long fromVisitId; + + /** + * The transition type associated with this visit. For node types other than + * history visit nodes, this value is 0. + */ + readonly attribute unsigned long visitType; +}; + + +/** + * Base class for container results. This includes all types of groupings. + * Bookmark folders and places queries will be QueryResultNodes which extends + * these items. + */ +[scriptable, uuid(3E9CC95F-0D93-45F1-894F-908EEB9866D7)] +interface nsINavHistoryContainerResultNode : nsINavHistoryResultNode +{ + + /** + * Set this to allow descent into the container. When closed, attempting + * to call getChildren or childCount will result in an error. You should + * set this to false when you are done reading. + * + * For HOST and DAY groupings, doing this is free since the children have + * been precomputed. For queries and bookmark folders, being open means they + * will keep themselves up-to-date by listening for updates and re-querying + * as needed. + */ + attribute boolean containerOpen; + + /** + * Indicates whether the container is closed, loading, or opened. Loading + * implies that the container has been opened asynchronously and has not yet + * fully opened. + */ + readonly attribute unsigned short state; + const unsigned short STATE_CLOSED = 0; + const unsigned short STATE_LOADING = 1; + const unsigned short STATE_OPENED = 2; + + /** + * This indicates whether this node "may" have children, and can be used + * when the container is open or closed. When the container is closed, it + * will give you an exact answer if the node can easily be populated (for + * example, a bookmark folder). If not (for example, a complex history query), + * it will return true. When the container is open, it will always be + * accurate. It is intended to be used to see if we should draw the "+" next + * to a tree item. + */ + readonly attribute boolean hasChildren; + + /** + * This gives you the children of the nodes. It is preferrable to use this + * interface over the array one, since it avoids creating an nsIArray object + * and the interface is already the correct type. + * + * @throws NS_ERROR_NOT_AVAILABLE if containerOpen is false. + */ + readonly attribute unsigned long childCount; + nsINavHistoryResultNode getChild(in unsigned long aIndex); + + /** + * Get the index of a direct child in this container. + * + * @param aNode + * a result node. + * + * @return aNode's index in this container. + * @throws NS_ERROR_NOT_AVAILABLE if containerOpen is false. + * @throws NS_ERROR_INVALID_ARG if aNode isn't a direct child of this + * container. + */ + unsigned long getChildIndex(in nsINavHistoryResultNode aNode); + + /** + * Look for a node in the container by some of its details. Does not search + * closed containers. + * + * @param aURI + * the node's uri attribute value + * @param aTime + * the node's time attribute value. + * @param aItemId + * the node's itemId attribute value. + * @param aRecursive + * whether or not to search recursively. + * + * @throws NS_ERROR_NOT_AVAILABLE if this container is closed. + * @return a result node that matches the given details if any, null + * otherwise. + */ + nsINavHistoryResultNode findNodeByDetails(in AUTF8String aURIString, + in PRTime aTime, + in long long aItemId, + in boolean aRecursive); +}; + + +/** + * Used for places queries and as a base for bookmark folders. + * + * Note that if you request places to *not* be expanded in the options that + * generated this node, this item will report it has no children and never try + * to populate itself. + */ +[scriptable, uuid(62817759-4FEE-44A3-B58C-3E2F5AFC9D0A)] +interface nsINavHistoryQueryResultNode : nsINavHistoryContainerResultNode +{ + /** + * Get the queries which build this node's children. + * Only valid for RESULT_TYPE_QUERY nodes. + */ + void getQueries([optional] out unsigned long queryCount, + [retval,array,size_is(queryCount)] out nsINavHistoryQuery queries); + + /** + * Get the options which group this node's children. + * Only valid for RESULT_TYPE_QUERY nodes. + */ + readonly attribute nsINavHistoryQueryOptions queryOptions; + + /** + * For both simple folder queries and folder shortcut queries, this is set to + * the concrete itemId of the folder (i.e. for folder shortcuts it's the + * target folder id). Otherwise, this is set to -1. + */ + readonly attribute long long folderItemId; + + /** + * For both simple folder queries and folder shortcut queries, this is set to + * the concrete guid of the folder (i.e. for folder shortcuts it's the target + * folder guid). Otherwise, this is set to an empty string. + */ + readonly attribute ACString targetFolderGuid; +}; + + +/** + * Allows clients to observe what is happening to a result as it updates itself + * according to history and bookmark system events. Register this observer on a + * result using nsINavHistoryResult::addObserver. + */ +[scriptable, uuid(f62d8b6b-3c4e-4a9f-a897-db605d0b7a0f)] +interface nsINavHistoryResultObserver : nsISupports +{ + /** + * Called when 'aItem' is inserted into 'aParent' at index 'aNewIndex'. + * The item previously at index (if any) and everything below it will have + * been shifted down by one. The item may be a container or a leaf. + */ + void nodeInserted(in nsINavHistoryContainerResultNode aParent, + in nsINavHistoryResultNode aNode, + in unsigned long aNewIndex); + + /** + * Called whan 'aItem' is removed from 'aParent' at 'aOldIndex'. The item + * may be a container or a leaf. This function will be called after the item + * has been removed from its parent list, but before anything else (including + * NULLing out the item's parent) has happened. + */ + void nodeRemoved(in nsINavHistoryContainerResultNode aParent, + in nsINavHistoryResultNode aItem, + in unsigned long aOldIndex); + + /** + * Called whan 'aItem' is moved from 'aOldParent' at 'aOldIndex' to + * aNewParent at aNewIndex. The item may be a container or a leaf. + * + * XXX: at the moment, this method is called only when an item is moved + * within the same container. When an item is moved between containers, + * a new node is created for the item, and the itemRemoved/itemAdded methods + * are used. + */ + void nodeMoved(in nsINavHistoryResultNode aNode, + in nsINavHistoryContainerResultNode aOldParent, + in unsigned long aOldIndex, + in nsINavHistoryContainerResultNode aNewParent, + in unsigned long aNewIndex); + + /** + * Called right after aNode's title has changed. + * + * @param aNode + * a result node + * @param aNewTitle + * the new title + */ + void nodeTitleChanged(in nsINavHistoryResultNode aNode, + in AUTF8String aNewTitle); + + /** + * Called right after aNode's uri property has changed. + * + * @param aNode + * a result node + * @param aNewURI + * the new uri + */ + void nodeURIChanged(in nsINavHistoryResultNode aNode, + in AUTF8String aNewURI); + + /** + * Called right after aNode's icon property has changed. + * + * @param aNode + * a result node + * + * @note: The new icon is accessible through aNode.icon. + */ + void nodeIconChanged(in nsINavHistoryResultNode aNode); + + /** + * Called right after aNode's time property or accessCount property, or both, + * have changed. + * + * @param aNode + * a uri result node + * @param aNewVisitDate + * the new visit date + * @param aNewAccessCount + * the new access-count + */ + void nodeHistoryDetailsChanged(in nsINavHistoryResultNode aNode, + in PRTime aNewVisitDate, + in unsigned long aNewAccessCount); + + /** + * Called when the tags set on the uri represented by aNode have changed. + * + * @param aNode + * a uri result node + * + * @note: The new tags list is accessible through aNode.tags. + */ + void nodeTagsChanged(in nsINavHistoryResultNode aNode); + + /** + * Called right after the aNode's keyword property has changed. + * + * @param aNode + * a uri result node + * @param aNewKeyword + * the new keyword + */ + void nodeKeywordChanged(in nsINavHistoryResultNode aNode, + in AUTF8String aNewKeyword); + + /** + * Called right after an annotation of aNode's has changed (set, altered, or + * unset). + * + * @param aNode + * a result node + * @param aAnnoName + * the name of the annotation that changed + */ + void nodeAnnotationChanged(in nsINavHistoryResultNode aNode, + in AUTF8String aAnnoName); + + /** + * Called right after aNode's dateAdded property has changed. + * + * @param aNode + * a result node + * @param aNewValue + * the new value of the dateAdded property + */ + void nodeDateAddedChanged(in nsINavHistoryResultNode aNode, + in PRTime aNewValue); + + /** + * Called right after aNode's dateModified property has changed. + * + * @param aNode + * a result node + * @param aNewValue + * the new value of the dateModified property + */ + void nodeLastModifiedChanged(in nsINavHistoryResultNode aNode, + in PRTime aNewValue); + + /** + * Called after a container changes state. + * + * @param aContainerNode + * The container that has changed state. + * @param aOldState + * The state that aContainerNode has transitioned out of. + * @param aNewState + * The state that aContainerNode has transitioned into. + */ + void containerStateChanged(in nsINavHistoryContainerResultNode aContainerNode, + in unsigned long aOldState, + in unsigned long aNewState); + + /** + * Called when something significant has happened within the container. The + * contents of the container should be re-built. + * + * @param aContainerNode + * the container node to invalidate + */ + void invalidateContainer(in nsINavHistoryContainerResultNode aContainerNode); + + /** + * This is called to indicate to the UI that the sort has changed to the + * given mode. For trees, for example, this would update the column headers + * to reflect the sorting. For many other types of views, this won't be + * applicable. + * + * @param sortingMode One of nsINavHistoryQueryOptions.SORT_BY_* that + * indicates the new sorting mode. + * + * This only is expected to update the sorting UI. invalidateAll() will also + * get called if the sorting changes to update everything. + */ + void sortingChanged(in unsigned short sortingMode); + + /** + * This is called to indicate that a batch operation is about to start or end. + * The observer could want to disable some events or updates during batches, + * since multiple operations are packed in a short time. + * For example treeviews could temporarily suppress select notifications. + * + * @param aToggleMode + * true if a batch is starting, false if it's ending. + */ + void batching(in boolean aToggleMode); + + /** + * Called by the result when this observer is added. + */ + attribute nsINavHistoryResult result; +}; + + +/** + * TODO: Bug 517719. + * + * A predefined view adaptor for interfacing results with an nsITree. This + * object will remove itself from its associated result when the tree has been + * detached. This prevents circular references. Users should be aware of this, + * if you want to re-use the same viewer, you will need to keep your own + * reference to it and re-initialize it when the tree changes. If you use this + * object, attach it to a result, never attach it to a tree, and forget about + * it, it will leak! + */ +[scriptable, uuid(f8b518c0-1faf-11df-8a39-0800200c9a66)] +interface nsINavHistoryResultTreeViewer : nsINavHistoryResultObserver +{ + /** + * This allows you to get at the real node for a given row index. This is + * only valid when a tree is attached. + */ + nsINavHistoryResultNode nodeForTreeIndex(in unsigned long aIndex); + + /** + * Reverse of nodeForFlatIndex, returns the row index for a given result node. + * Returns INDEX_INVISIBLE if the item is not visible (for example, its + * parent is collapsed). This is only valid when a tree is attached. The + * the result will always be INDEX_INVISIBLE if not. + * + * Note: This sounds sort of obvious, but it got me: aNode must be a node + * retrieved from the same result that this viewer is for. If you + * execute another query and get a node from a _different_ result, this + * function will always return the index of that node in the tree that + * is attached to that result. + */ + const unsigned long INDEX_INVISIBLE = 0xffffffff; + unsigned long treeIndexForNode(in nsINavHistoryResultNode aNode); +}; + + +/** + * The result of a history/bookmark query. + */ +[scriptable, uuid(c2229ce3-2159-4001-859c-7013c52f7619)] +interface nsINavHistoryResult : nsISupports +{ + /** + * Sorts all nodes recursively by the given parameter, one of + * nsINavHistoryQueryOptions.SORT_BY_* This will update the corresponding + * options for this result, so that re-using the current options/queries will + * always give you the current view. + */ + attribute unsigned short sortingMode; + + /** + * The annotation to use in SORT_BY_ANNOTATION_* sorting modes, set this + * before setting the sortingMode attribute. + */ + attribute AUTF8String sortingAnnotation; + + /** + * Whether or not notifications on result changes are suppressed. + * Initially set to false. + * + * Use this to avoid flickering and to improve performance when you + * do temporary changes to the result structure (e.g. when searching for a + * node recursively). + */ + attribute boolean suppressNotifications; + + /** + * Adds an observer for changes done in the result. + * + * @param aObserver + * a result observer. + * @param aOwnsWeak + * If false, the result will keep an owning reference to the observer, + * which must be removed using removeObserver. + * If true, the result will keep a weak reference to the observer, which + * must implement nsISupportsWeakReference. + * + * @see nsINavHistoryResultObserver + */ + void addObserver(in nsINavHistoryResultObserver aObserver, in boolean aOwnsWeak); + + /** + * Removes an observer that was added by addObserver. + * + * @param aObserver + * a result observer that was added by addObserver. + */ + void removeObserver(in nsINavHistoryResultObserver aObserver); + + /** + * This is the root of the results. Remember that you need to open all + * containers for their contents to be valid. + * + * When a result goes out of scope it will continue to observe changes till + * it is cycle collected. While the result waits to be collected it will stay + * in memory, and continue to update itself, potentially causing unwanted + * additional work. When you close the root node the result will stop + * observing changes, so it is good practice to close the root node when you + * are done with a result, since that will avoid unwanted performance hits. + */ + readonly attribute nsINavHistoryContainerResultNode root; +}; + + +/** + * Similar to nsIRDFObserver for history. Note that we don't pass the data + * source since that is always the global history. + * + * DANGER! If you are in the middle of a batch transaction, there may be a + * database transaction active. You can still access the DB, but be careful. + */ +[scriptable, uuid(0f0f45b0-13a1-44ae-a0ab-c6046ec6d4da)] +interface nsINavHistoryObserver : nsISupports +{ + /** + * Notifies you that a bunch of things are about to change, don't do any + * heavy-duty processing until onEndUpdateBatch is called. + */ + void onBeginUpdateBatch(); + + /** + * Notifies you that we are done doing a bunch of things and you should go + * ahead and update UI, etc. + */ + void onEndUpdateBatch(); + + /** + * Called everytime a URI is visited. + * + * @note TRANSITION_EMBED visits (corresponding to images in a page, for + * example) are not displayed in history results. Most observers can + * ignore TRANSITION_EMBED visit notifications (which will comprise the + * majority of visit notifications) to save work. + * + * @param aVisitId + * Id of the visit that was just created. + * @param aTime + * Time of the visit. + * @param aSessionId + * No longer supported and always set to 0. + * @param aReferrerVisitId + * The id of the visit the user came from, defaults to 0 for no referrer. + * @param aTransitionType + * One of nsINavHistory.TRANSITION_* + * @param aGuid + * The unique id associated with the page. + * @param aHidden + * Whether the visited page is marked as hidden. + * @param aVisitCount + * Number of visits (included this one) for this URI. + * @param aTyped + * Whether the URI has been typed or not. + * TODO (Bug 1271801): This will become a count, rather than a boolean. + * For future compatibility, always compare it with "> 0". + */ + void onVisit(in nsIURI aURI, + in long long aVisitId, + in PRTime aTime, + in long long aSessionId, + in long long aReferrerVisitId, + in unsigned long aTransitionType, + in ACString aGuid, + in boolean aHidden, + in unsigned long aVisitCount, + in unsigned long aTyped); + + /** + * Called whenever either the "real" title or the custom title of the page + * changed. BOTH TITLES ARE ALWAYS INCLUDED in this notification, even though + * only one will change at a time. Often, consumers will want to display the + * user title if it is available, and fall back to the page title (the one + * specified in the <title> tag of the page). + * + * Note that there is a difference between an empty title and a NULL title. + * An empty string means that somebody specifically set the title to be + * nothing. NULL means nobody set it. From C++: use IsVoid() and SetIsVoid() + * to see whether an empty string is "null" or not (it will always be an + * empty string in either case). + * + * @param aURI + * The URI of the page. + * @param aPageTitle + * The new title of the page. + * @param aGUID + * The unique ID associated with the page. + */ + void onTitleChanged(in nsIURI aURI, + in AString aPageTitle, + in ACString aGUID); + + /** + * Called when an individual page's frecency has changed. + * + * This is not called for pages whose frecencies change as the result of some + * large operation where some large or unknown number of frecencies change at + * once. Use onManyFrecenciesChanged to detect such changes. + * + * @param aURI + * The page's URI. + * @param aNewFrecency + * The page's new frecency. + * @param aGUID + * The page's GUID. + * @param aHidden + * True if the page is marked as hidden. + * @param aVisitDate + * The page's last visit date. + */ + void onFrecencyChanged(in nsIURI aURI, + in long aNewFrecency, + in ACString aGUID, + in boolean aHidden, + in PRTime aVisitDate); + + /** + * Called when the frecencies of many pages have changed at once. + * + * onFrecencyChanged is not called for each of those pages. + */ + void onManyFrecenciesChanged(); + + /** + * Removed by the user. + */ + const unsigned short REASON_DELETED = 0; + /** + * Removed by automatic expiration. + */ + const unsigned short REASON_EXPIRED = 1; + + /** + * This page and all of its visits are being deleted. Note: the page may not + * necessarily have actually existed for this function to be called. + * + * Delete notifications are only 99.99% accurate. Batch delete operations + * must be done in two steps, so first come notifications, then a bulk + * delete. If there is some error in the middle (for example, out of memory) + * then you'll get a notification and it won't get deleted. There's no easy + * way around this. + * + * @param aURI + * The URI that was deleted. + * @param aGUID + * The unique ID associated with the page. + * @param aReason + * Indicates the reason for the removal. see REASON_* constants. + */ + void onDeleteURI(in nsIURI aURI, + in ACString aGUID, + in unsigned short aReason); + + /** + * Notification that all of history is being deleted. + */ + void onClearHistory(); + + /** + * onPageChanged attribute indicating that favicon has been updated. + * aNewValue parameter will be set to the new favicon URI string. + */ + const unsigned long ATTRIBUTE_FAVICON = 3; + + /** + * An attribute of this page changed. + * + * @param aURI + * The URI of the page on which an attribute changed. + * @param aChangedAttribute + * The attribute whose value changed. See ATTRIBUTE_* constants. + * @param aNewValue + * The attribute's new value. + * @param aGUID + * The unique ID associated with the page. + */ + void onPageChanged(in nsIURI aURI, + in unsigned long aChangedAttribute, + in AString aNewValue, + in ACString aGUID); + + /** + * Called when some visits of an history entry are expired. + * + * @param aURI + * The page whose visits have been expired. + * @param aVisitTime + * The largest visit time in microseconds that has been expired. We + * guarantee that we don't have any visit older than this date. + * @param aGUID + * The unique ID associated with the page. + * + * @note: when all visits for a page are expired and also the full page entry + * is expired, you will only get an onDeleteURI notification. If a + * page entry is removed, then you can be sure that we don't have + * anymore visits for it. + * @param aReason + * Indicates the reason for the removal. see REASON_* constants. + * @param aTransitionType + * If it's a valid TRANSITION_* value, all visits of the specified type + * have been removed. + */ + void onDeleteVisits(in nsIURI aURI, + in PRTime aVisitTime, + in ACString aGUID, + in unsigned short aReason, + in unsigned long aTransitionType); +}; + + +/** + * This object encapsulates all the query parameters you're likely to need + * when building up history UI. All parameters are ANDed together. + * + * This is not intended to be a super-general query mechanism. This was designed + * so that most queries can be done in only one SQL query. This is important + * because, if the user has their profile on a networked drive, query latency + * can be non-negligible. + */ + +[scriptable, uuid(dc87ae79-22f1-4dcf-975b-852b01d210cb)] +interface nsINavHistoryQuery : nsISupports +{ + /** + * Time range for results (INCLUSIVE). The *TimeReference is one of the + * constants TIME_RELATIVE_* which indicates how to interpret the + * corresponding time value. + * TIME_RELATIVE_EPOCH (default): + * The time is relative to Jan 1 1970 GMT, (this is a normal PRTime) + * TIME_RELATIVE_TODAY: + * The time is relative to this morning at midnight. Normally used for + * queries relative to today. For example, a "past week" query would be + * today-6 days -> today+1 day + * TIME_RELATIVE_NOW: + * The time is relative to right now. + * + * Note: PRTime is in MICROseconds since 1 Jan 1970. Javascript date objects + * are expressed in MILLIseconds since 1 Jan 1970. + * + * As a special case, a 0 time relative to TIME_RELATIVE_EPOCH indicates that + * the time is not part of the query. This is the default, so an empty query + * will match any time. The has* functions return whether the corresponding + * time is considered. + * + * You can read absolute*Time to get the time value that the currently loaded + * reference points + offset resolve to. + */ + 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; + + /** + * Text search terms. + */ + attribute AString searchTerms; + readonly attribute boolean hasSearchTerms; + + /** + * Set lower or upper limits for how many times an item has been + * visited. The default is -1, and in that case all items are + * matched regardless of their visit count. + */ + attribute long minVisits; + attribute long maxVisits; + + /** + * When the set of transitions is nonempty, results are limited to pages which + * have at least one visit for each of the transition types. + * @note: For searching on more than one transition this can be very slow. + * + * Limit results to the specified list of transition types. + */ + void setTransitions([const,array, size_is(count)] in unsigned long transitions, + in unsigned long count); + + /** + * Get the transitions set for this query. + */ + void getTransitions([optional] out unsigned long count, + [retval,array,size_is(count)] out unsigned long transitions); + + /** + * Get the count of the set query transitions. + */ + readonly attribute unsigned long transitionCount; + + /** + * When set, returns only bookmarked items, when unset, returns anything. Setting this + * is equivalent to listing all bookmark folders in the 'folders' parameter. + */ + attribute boolean onlyBookmarked; + + /** + * This controls the meaning of 'domain', and whether it is an exact match + * 'domainIsHost' = true, or hierarchical (= false). + */ + attribute boolean domainIsHost; + + /** + * This is the host or domain name (controlled by domainIsHost). When + * domainIsHost, domain only does exact matching on host names. Otherwise, + * it will return anything whose host name ends in 'domain'. + * + * This one is a little different than most. Setting it to an empty string + * is a real query and will match any URI that has no host name (local files + * and such). Set this to NULL (in C++ use SetIsVoid) if you don't want + * domain matching. + */ + attribute AUTF8String domain; + readonly attribute boolean hasDomain; + + /** + * This is a URI to match, to, for example, find out every time you visited + * a given URI. This is an exact match. + */ + attribute nsIURI uri; + readonly attribute boolean hasUri; + + /** + * Test for existence or non-existence of a given annotation. We don't + * currently support >1 annotation name per query. If 'annotationIsNot' is + * true, we test for the non-existence of the specified annotation. + * + * Testing for not annotation will do the same thing as a normal query and + * remove everything that doesn't have that annotation. Asking for things + * that DO have a given annotation is a little different. It also includes + * things that have never been visited. This allows place queries to be + * returned as well as anything else that may have been tagged with an + * annotation. This will only work for RESULTS_AS_URI since there will be + * no visits for these items. + */ + attribute boolean annotationIsNot; + attribute AUTF8String annotation; + readonly attribute boolean hasAnnotation; + + /** + * Limit results to items that are tagged with all of the given tags. This + * attribute must be set to an array of strings. When called as a getter it + * will return an array of strings sorted ascending in lexicographical order. + * The array may be empty in either case. Duplicate tags may be specified + * when setting the attribute, but the getter returns only unique tags. + * + * To search for items that are tagged with any given tags rather than all, + * multiple queries may be passed to nsINavHistoryService.executeQueries(). + */ + attribute nsIVariant tags; + + /** + * If 'tagsAreNot' is true, the results are instead limited to items that + * are not tagged with any of the given tags. This attribute is used in + * conjunction with the 'tags' attribute. + */ + attribute boolean tagsAreNot; + + /** + * Limit results to items that are in all of the given folders. + */ + void getFolders([optional] out unsigned long count, + [retval,array,size_is(count)] out long long folders); + readonly attribute unsigned long folderCount; + + /** + * For the special result type RESULTS_AS_TAG_CONTENTS we can define only + * one folder that must be a tag folder. This is not recursive so results + * will be returned from the first level of that folder. + */ + void setFolders([const,array, size_is(folderCount)] in long long folders, + in unsigned long folderCount); + + /** + * Creates a new query item with the same parameters of this one. + */ + nsINavHistoryQuery clone(); +}; + +/** + * This object represents the global options for executing a query. + */ +[scriptable, uuid(8198dfa7-8061-4766-95cb-fa86b3c00a47)] +interface nsINavHistoryQueryOptions : nsISupports +{ + /** + * You can ask for the results to be pre-sorted. Since the DB has indices + * of many items, it can produce sorted results almost for free. These should + * be self-explanatory. + * + * Note: re-sorting is slower, as is sorting by title or when you have a + * host name. + * + * For bookmark items, SORT_BY_NONE means sort by the natural bookmark order. + */ + 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 SORT_BY_FRECENCY_ASCENDING = 21; + const unsigned short SORT_BY_FRECENCY_DESCENDING = 22; + + /** + * "URI" results, one for each URI visited in the range. Individual result + * nodes will be of type "URI". + */ + const unsigned short RESULTS_AS_URI = 0; + + /** + * "Visit" results, with one for each time a page was visited (this will + * often give you multiple results for one URI). Individual result nodes will + * have type "Visit" + * + * @note This result type is only supported by QUERY_TYPE_HISTORY. + */ + const unsigned short RESULTS_AS_VISIT = 1; + + /** + * This is identical to RESULT_TYPE_VISIT except that individual result nodes + * will have type "FullVisit". This is used for the attributes that are not + * commonly accessed to save space in the common case (the lists can be very + * long). + * + * @note Not yet implemented. See bug 409662. + * @note This result type is only supported by QUERY_TYPE_HISTORY. + */ + const unsigned short RESULTS_AS_FULL_VISIT = 2; + + /** + * This returns query nodes for each predefined date range where we + * had visits. The node contains information how to load its content: + * - visits for the given date range will be loaded. + * + * @note This result type is only supported by QUERY_TYPE_HISTORY. + */ + const unsigned short RESULTS_AS_DATE_QUERY = 3; + + /** + * This returns nsINavHistoryQueryResultNode nodes for each site where we + * have visits. The node contains information how to load its content: + * - last visit for each url in the given host will be loaded. + * + * @note This result type is only supported by QUERY_TYPE_HISTORY. + */ + const unsigned short RESULTS_AS_SITE_QUERY = 4; + + /** + * This returns nsINavHistoryQueryResultNode nodes for each day where we + * have visits. The node contains information how to load its content: + * - list of hosts visited in the given period will be loaded. + * + * @note This result type is only supported by QUERY_TYPE_HISTORY. + */ + const unsigned short RESULTS_AS_DATE_SITE_QUERY = 5; + + /** + * This returns nsINavHistoryQueryResultNode nodes for each tag. + * The node contains information how to load its content: + * - list of bookmarks with the given tag will be loaded. + * + * @note Setting this resultType will force queryType to QUERY_TYPE_BOOKMARKS. + */ + const unsigned short RESULTS_AS_TAG_QUERY = 6; + + /** + * This is a container with an URI result type that contains the last + * modified bookmarks for the given tag. + * Tag folder id must be defined in the query. + * + * @note Setting this resultType will force queryType to QUERY_TYPE_BOOKMARKS. + */ + const unsigned short RESULTS_AS_TAG_CONTENTS = 7; + + /** + * The sorting mode to be used for this query. + * mode is one of SORT_BY_* + */ + attribute unsigned short sortingMode; + + /** + * The annotation to use in SORT_BY_ANNOTATION_* sorting modes. + */ + attribute AUTF8String sortingAnnotation; + + /** + * Sets the result type. One of RESULT_TYPE_* which includes how URIs are + * represented. + */ + attribute unsigned short resultType; + + /** + * This option excludes all URIs and separators from a bookmarks query. + * This would be used if you just wanted a list of bookmark folders and + * queries (such as the left pane of the places page). + * Defaults to false. + */ + attribute boolean excludeItems; + + /** + * Set to true to exclude queries ("place:" URIs) from the query results. + * Simple folder queries (bookmark folder symlinks) will still be included. + * Defaults to false. + */ + attribute boolean excludeQueries; + + /** + * DO NOT USE THIS API. IT'LL BE REMOVED IN BUG 1072833. + * + * Set to true to exclude live bookmarks from the query results. + */ + attribute boolean excludeReadOnlyFolders; + + /** + * When set, allows items with "place:" URIs to appear as containers, + * with the container's contents filled in from the stored query. + * If not set, these will appear as normal items. Doesn't do anything if + * excludeQueries is set. Defaults to false. + * + * Note that this has no effect on folder links, which are place: URIs + * returned by nsINavBookmarkService.GetFolderURI. These are always expanded + * and will appear as bookmark folders. + */ + attribute boolean expandQueries; + + /** + * Some pages in history are marked "hidden" and thus don't appear by default + * in queries. These include automatic framed visits and redirects. Setting + * this attribute will return all pages, even hidden ones. Does nothing for + * bookmark queries. Defaults to false. + */ + attribute boolean includeHidden; + + /** + * This is the maximum number of results that you want. The query is exeucted, + * the results are sorted, and then the top 'maxResults' results are taken + * and returned. Set to 0 (the default) to get all results. + * + * THIS DOES NOT WORK IN CONJUNCTION WITH SORTING BY TITLE. This is because + * sorting by title requires us to sort after using locale-sensetive sorting + * (as opposed to letting the database do it for us). + * + * Instead, we get the result ordered by date, pick the maxResult most recent + * ones, and THEN sort by title. + */ + attribute unsigned long maxResults; + + const unsigned short QUERY_TYPE_HISTORY = 0; + const unsigned short QUERY_TYPE_BOOKMARKS = 1; + /* Unified queries are not yet implemented. See bug 378798 */ + const unsigned short QUERY_TYPE_UNIFIED = 2; + + /** + * The type of search to use when querying the DB; This attribute is only + * honored by query nodes. It is silently ignored for simple folder queries. + */ + attribute unsigned short queryType; + + /** + * When this is true, the root container node generated by these options and + * its descendant containers will be opened asynchronously if they support it. + * This is false by default. + * + * @note Currently only bookmark folder containers support being opened + * asynchronously. + */ + attribute boolean asyncEnabled; + + /** + * Creates a new options item with the same parameters of this one. + */ + nsINavHistoryQueryOptions clone(); +}; + +[scriptable, uuid(8a1f527e-c9d7-4a51-bf0c-d86f0379b701)] +interface nsINavHistoryService : nsISupports +{ + /** + * System Notifications: + * + * places-init-complete - Sent once the History service is completely + * initialized successfully. + * places-database-locked - Sent if initialization of the History service + * failed due to the inability to open the places.sqlite + * for access reasons. + */ + + /** + * This transition type means the user followed a link and got a new toplevel + * window. + */ + const unsigned long TRANSITION_LINK = 1; + + /** + * This transition type means that the user typed the page's URL in the + * URL bar or selected it from URL bar autocomplete results, clicked on + * it from a history query (from the History sidebar, History menu, + * or history query in the personal toolbar or Places organizer. + */ + const unsigned long TRANSITION_TYPED = 2; + + /** + * This transition is set when the user followed a bookmark to get to the + * page. + */ + const unsigned long TRANSITION_BOOKMARK = 3; + + /** + * 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 if the user did not explicitly follow + * a link to get there. + */ + const unsigned long TRANSITION_EMBED = 4; + + /** + * Set when the transition was a permanent redirect. + */ + const unsigned long TRANSITION_REDIRECT_PERMANENT = 5; + + /** + * Set when the transition was a temporary redirect. + */ + const unsigned long TRANSITION_REDIRECT_TEMPORARY = 6; + + /** + * Set when the transition is a download. + */ + const unsigned long TRANSITION_DOWNLOAD = 7; + + /** + * This transition type means the user followed a link and got a visit in + * a frame. + */ + const unsigned long TRANSITION_FRAMED_LINK = 8; + + /** + * This transition type means the page has been reloaded. + */ + const unsigned long TRANSITION_RELOAD = 9; + + /** + * Set when database is coherent + */ + const unsigned short DATABASE_STATUS_OK = 0; + + /** + * Set when database did not exist and we created a new one + */ + const unsigned short DATABASE_STATUS_CREATE = 1; + + /** + * Set when database was corrupt and we replaced it + */ + const unsigned short DATABASE_STATUS_CORRUPT = 2; + + /** + * Set when database schema has been upgraded + */ + const unsigned short DATABASE_STATUS_UPGRADED = 3; + + /** + * Returns the current database status + */ + readonly attribute unsigned short databaseStatus; + + /** + * 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. + */ + readonly attribute boolean hasHistoryEntries; + + /** + * Gets the original title of the page. + * @deprecated use mozIAsyncHistory.getPlacesInfo instead. + */ + AString getPageTitle(in nsIURI aURI); + + /** + * This 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); + + /** + * 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); + + /** + * Returns true if this URI would be added to the history. You don't have to + * worry about calling this, adding a visit 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 (i.e. for + * annotations). + */ + boolean canAddURI(in nsIURI aURI); + + /** + * This returns a new query object that you can pass to executeQuer[y/ies]. + * It will be initialized to all empty (so using it will give you all history). + */ + nsINavHistoryQuery getNewQuery(); + + /** + * This returns a new options object that you can pass to executeQuer[y/ies] + * after setting the desired options. + */ + nsINavHistoryQueryOptions getNewQueryOptions(); + + /** + * Executes a single query. + */ + nsINavHistoryResult executeQuery(in nsINavHistoryQuery aQuery, + in nsINavHistoryQueryOptions options); + + /** + * 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. See executeQuery() + */ + nsINavHistoryResult executeQueries( + [array,size_is(aQueryCount)] in nsINavHistoryQuery aQueries, + in unsigned long aQueryCount, + in nsINavHistoryQueryOptions options); + + /** + * Converts a query URI-like string to an array of actual query objects for + * use to executeQueries(). 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); + + /** + * Converts a query into an equivalent string that can be persisted. Inverse + * of queryStringToQueries() + */ + AUTF8String queriesToQueryString( + [array, size_is(aQueryCount)] in nsINavHistoryQuery aQueries, + in unsigned long aQueryCount, + in nsINavHistoryQueryOptions options); + + /** + * 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); + + /** + * Removes a history observer. + */ + void removeObserver(in nsINavHistoryObserver observer); + + /** + * Gets an array of registered nsINavHistoryObserver objects. + */ + void getObservers([optional] out unsigned long count, + [retval, array, size_is(count)] out nsINavHistoryObserver observers); + + /** + * 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. + * + * @param aCallback + * nsINavHistoryBatchCallback interface to call. + * @param aUserData + * Opaque parameter passed to nsINavBookmarksBatchCallback + */ + void runInBatchMode(in nsINavHistoryBatchCallback aCallback, + in nsISupports aClosure); + + /** + * True if history is disabled. currently, + * history is disabled if the places.history.enabled pref is false. + */ + readonly attribute boolean historyDisabled; + + /** + * Clear all TRANSITION_EMBED visits. + */ + void clearEmbedVisits(); +}; + +/** + * @see runInBatchMode of nsINavHistoryService/nsINavBookmarksService + */ +[scriptable, function, uuid(5a5a9154-95ac-4e3d-90df-558816297407)] +interface nsINavHistoryBatchCallback : nsISupports { + void runBatched(in nsISupports aUserData); +}; diff --git a/components/places/public/nsITaggingService.idl b/components/places/public/nsITaggingService.idl new file mode 100644 index 000000000..f3731feb6 --- /dev/null +++ b/components/places/public/nsITaggingService.idl @@ -0,0 +1,95 @@ +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* 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/. */ + +#include "nsISupports.idl" + +interface nsIURI; +interface nsIVariant; + +[scriptable, uuid(9759bd0e-78e2-4421-9ed1-c676e1af3513)] +interface nsITaggingService : nsISupports +{ + + /** + * Defines the maximal length of a tag. Related to the bug 407821 + * (https://bugzilla.mozilla.org/show_bug.cgi?id=407821) + */ + const unsigned long MAX_TAG_LENGTH = 100; + + /** + * Tags a URL with the given set of tags. Current tags set for the URL + * persist. Tags in aTags which are already set for the given URL are + * ignored. + * + * @param aURI + * the URL to tag. + * @param aTags + * Array of tags to set for the given URL. Each element within the + * array can be either a tag name (non-empty string) or a concrete + * itemId of a tag container. + * @param [optional] aSource + * A change source constant from nsINavBookmarksService::SOURCE_*. + * Defaults to SOURCE_DEFAULT if omitted. + */ + void tagURI(in nsIURI aURI, + in nsIVariant aTags, + [optional] in unsigned short aSource); + + /** + * Removes tags from a URL. Tags from aTags which are not set for the + * given URL are ignored. + * + * @param aURI + * the URL to un-tag. + * @param aTags + * Array of tags to unset. Pass null to remove all tags from the given + * url. Each element within the array can be either a tag name + * (non-empty string) or a concrete itemId of a tag container. + * @param [optional] aSource + * A change source constant from nsINavBookmarksService::SOURCE_*. + * Defaults to SOURCE_DEFAULT if omitted. + */ + void untagURI(in nsIURI aURI, + in nsIVariant aTags, + [optional] in unsigned short aSource); + + /** + * Retrieves all URLs tagged with the given tag. + * + * @param aTag + * tag name + * @returns Array of uris tagged with aTag. + */ + nsIVariant getURIsForTag(in AString aTag); + + /** + * Retrieves all tags set for the given URL. + * + * @param aURI + * a URL. + * @returns array of tags (sorted by name). + */ + void getTagsForURI(in nsIURI aURI, + [optional] out unsigned long length, + [retval, array, size_is(length)] out wstring aTags); + + /** + * Retrieves all tags used to tag URIs in the data-base (sorted by name). + */ + readonly attribute nsIVariant allTags; + + /** + * Whether any tags exist. + * + * @note This is faster than allTags.length, since doesn't need to sort tags. + */ + readonly attribute boolean hasTags; +}; + +%{C++ + +#define TAGGING_SERVICE_CID "@mozilla.org/browser/tagging-service;1" + +%} diff --git a/components/places/public/nsPIPlacesDatabase.idl b/components/places/public/nsPIPlacesDatabase.idl new file mode 100644 index 000000000..5511b1be6 --- /dev/null +++ b/components/places/public/nsPIPlacesDatabase.idl @@ -0,0 +1,52 @@ +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- + * vim: sw=2 ts=2 sts=2 + * 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/. */ + +#include "nsISupports.idl" + +interface mozIStorageConnection; +interface nsINavHistoryQuery; +interface nsINavHistoryQueryOptions; +interface mozIStorageStatementCallback; +interface mozIStoragePendingStatement; +interface nsIAsyncShutdownClient; + +/** + * This is a private interface used by Places components to get access to the + * database. If outside consumers wish to use this, they should only read from + * the database so they do not break any internal invariants. + */ +[scriptable, uuid(366ee63e-a413-477d-9ad6-8d6863e89401)] +interface nsPIPlacesDatabase : nsISupports +{ + /** + * The database connection used by Places. + */ + readonly attribute mozIStorageConnection DBConnection; + + /** + * Asynchronously executes the statement created from queries. + * + * @see nsINavHistoryService::executeQueries + * @note THIS IS A TEMPORARY API. Don't rely on it, since it will be replaced + * in future versions by a real async querying API. + * @note Results obtained from this method differ from results obtained from + * executeQueries, because there is additional filtering and sorting + * done by the latter. Thus you should use executeQueries, unless you + * are absolutely sure that the returned results are fine for + * your use-case. + */ + mozIStoragePendingStatement asyncExecuteLegacyQueries( + [array, size_is(aQueryCount)] in nsINavHistoryQuery aQueries, + in unsigned long aQueryCount, + in nsINavHistoryQueryOptions aOptions, + in mozIStorageStatementCallback aCallback); + + /** + * Hook for clients who need to perform actions during/by the end of + * the shutdown of the database. + */ + readonly attribute nsIAsyncShutdownClient shutdownClient; +}; |