1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/toolkit/components/places/nsINavBookmarksService.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,585 @@
1.4 +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIFile;
1.12 +interface nsIURI;
1.13 +interface nsITransaction;
1.14 +interface nsINavHistoryBatchCallback;
1.15 +
1.16 +/**
1.17 + * Observer for bookmarks changes.
1.18 + */
1.19 +[scriptable, uuid(8ab925f8-af9b-4837-afa0-ffed507212ce)]
1.20 +interface nsINavBookmarkObserver : nsISupports
1.21 +{
1.22 + /**
1.23 + * Notifies that a batch transaction has started.
1.24 + * Other notifications will be sent during the batch, but the observer is
1.25 + * guaranteed that onEndUpdateBatch() will be called at its completion.
1.26 + * During a batch the observer should do its best to reduce the work done to
1.27 + * handle notifications, since multiple changes are going to happen in a short
1.28 + * timeframe.
1.29 + */
1.30 + void onBeginUpdateBatch();
1.31 +
1.32 + /**
1.33 + * Notifies that a batch transaction has ended.
1.34 + */
1.35 + void onEndUpdateBatch();
1.36 +
1.37 + /**
1.38 + * Notifies that an item (any type) was added. Called after the actual
1.39 + * addition took place.
1.40 + * When a new item is created, all the items following it in the same folder
1.41 + * will have their index shifted down, but no additional notifications will
1.42 + * be sent.
1.43 + *
1.44 + * @param aItemId
1.45 + * The id of the item that was added.
1.46 + * @param aParentId
1.47 + * The id of the folder to which the item was added.
1.48 + * @param aIndex
1.49 + * The item's index in the folder.
1.50 + * @param aItemType
1.51 + * The type of the added item (see TYPE_* constants below).
1.52 + * @param aURI
1.53 + * The URI of the added item if it was TYPE_BOOKMARK, null otherwise.
1.54 + * @param aTitle
1.55 + * The title of the added item.
1.56 + * @param aDateAdded
1.57 + * The stored date added value, in microseconds from the epoch.
1.58 + * @param aGUID
1.59 + * The unique ID associated with the item.
1.60 + * @param aParentGUID
1.61 + * The unique ID associated with the item's parent.
1.62 + */
1.63 + void onItemAdded(in long long aItemId,
1.64 + in long long aParentId,
1.65 + in long aIndex,
1.66 + in unsigned short aItemType,
1.67 + in nsIURI aURI,
1.68 + in AUTF8String aTitle,
1.69 + in PRTime aDateAdded,
1.70 + in ACString aGUID,
1.71 + in ACString aParentGUID);
1.72 +
1.73 + /**
1.74 + * Notifies that an item was removed. Called after the actual remove took
1.75 + * place.
1.76 + * When an item is removed, all the items following it in the same folder
1.77 + * will have their index shifted down, but no additional notifications will
1.78 + * be sent.
1.79 + *
1.80 + * @param aItemId
1.81 + * The id of the item that was removed.
1.82 + * @param aParentId
1.83 + * The id of the folder from which the item was removed.
1.84 + * @param aIndex
1.85 + * The bookmark's index in the folder.
1.86 + * @param aItemType
1.87 + * The type of the item to be removed (see TYPE_* constants below).
1.88 + * @param aURI
1.89 + * The URI of the added item if it was TYPE_BOOKMARK, null otherwise.
1.90 + * @param aGUID
1.91 + * The unique ID associated with the item.
1.92 + * @param aParentGUID
1.93 + * The unique ID associated with the item's parent.
1.94 + */
1.95 + void onItemRemoved(in long long aItemId,
1.96 + in long long aParentId,
1.97 + in long aIndex,
1.98 + in unsigned short aItemType,
1.99 + in nsIURI aURI,
1.100 + in ACString aGUID,
1.101 + in ACString aParentGUID);
1.102 +
1.103 + /**
1.104 + * Notifies that an item's information has changed. This will be called
1.105 + * whenever any attributes like "title" are changed.
1.106 + *
1.107 + * @param aItemId
1.108 + * The id of the item that was changed.
1.109 + * @param aProperty
1.110 + * The property which changed. Can be null for the removal of all of
1.111 + * the annotations, in this case aIsAnnotationProperty is true.
1.112 + * @param aIsAnnotationProperty
1.113 + * Whether or not aProperty is the name of an annotation. If true
1.114 + * aNewValue is always an empty string.
1.115 + * @param aNewValue
1.116 + * For certain properties, this is set to the new value of the
1.117 + * property (see the list below).
1.118 + * @param aLastModified
1.119 + * If lastModified changed, this parameter is the new value, otherwise
1.120 + * it's set to 0.
1.121 + * @param aItemType
1.122 + * The type of the item to be removed (see TYPE_* constants below).
1.123 + * @param aParentId
1.124 + * The id of the folder containing the item.
1.125 + * @param aGUID
1.126 + * The unique ID associated with the item.
1.127 + * @param aParentGUID
1.128 + * The unique ID associated with the item's parent.
1.129 + *
1.130 + * @note List of values that may be associated with properties:
1.131 + * aProperty | aNewValue
1.132 + * =====================================================================
1.133 + * cleartime | Empty string (all visits to this item were removed).
1.134 + * title | The new title.
1.135 + * favicon | The "moz-anno" URL of the new favicon.
1.136 + * uri | new URL.
1.137 + * tags | Empty string (tags for this item changed)
1.138 + * dateAdded | PRTime (as string) when the item was first added.
1.139 + * lastModified | PRTime (as string) when the item was last modified.
1.140 + */
1.141 + void onItemChanged(in long long aItemId,
1.142 + in ACString aProperty,
1.143 + in boolean aIsAnnotationProperty,
1.144 + in AUTF8String aNewValue,
1.145 + in PRTime aLastModified,
1.146 + in unsigned short aItemType,
1.147 + in long long aParentId,
1.148 + in ACString aGUID,
1.149 + in ACString aParentGUID);
1.150 +
1.151 + /**
1.152 + * Notifies that the item was visited. Can be invoked only for TYPE_BOOKMARK
1.153 + * items.
1.154 + *
1.155 + * @param aItemId
1.156 + * The id of the bookmark that was visited.
1.157 + * @param aVisitId
1.158 + * The id of the visit.
1.159 + * @param aTime
1.160 + * The time of the visit.
1.161 + * @param aTransitionType
1.162 + * The transition for the visit. See nsINavHistoryService::TRANSITION_*
1.163 + * constants for a list of possible values.
1.164 + * @param aURI
1.165 + * The nsIURI for this bookmark.
1.166 + * @param aParentId
1.167 + * The id of the folder containing the item.
1.168 + * @param aGUID
1.169 + * The unique ID associated with the item.
1.170 + * @param aParentGUID
1.171 + * The unique ID associated with the item's parent.
1.172 + *
1.173 + * @see onItemChanged with property = "cleartime" for when all visits to an
1.174 + * item are removed.
1.175 + *
1.176 + * @note The reported time is the time of the visit that was added, which may
1.177 + * be well in the past since the visit time can be specified. This
1.178 + * means that the visit the observer is told about may not be the most
1.179 + * recent visit for that page.
1.180 + */
1.181 + void onItemVisited(in long long aItemId,
1.182 + in long long aVisitId,
1.183 + in PRTime aTime,
1.184 + in unsigned long aTransitionType,
1.185 + in nsIURI aURI,
1.186 + in long long aParentId,
1.187 + in ACString aGUID,
1.188 + in ACString aParentGUID);
1.189 +
1.190 + /**
1.191 + * Notifies that an item has been moved.
1.192 + *
1.193 + * @param aItemId
1.194 + * The id of the item that was moved.
1.195 + * @param aOldParentId
1.196 + * The id of the old parent.
1.197 + * @param aOldIndex
1.198 + * The old index inside the old parent.
1.199 + * @param aNewParentId
1.200 + * The id of the new parent.
1.201 + * @param aNewIndex
1.202 + * The index inside the new parent.
1.203 + * @param aItemType
1.204 + * The type of the item to be removed (see TYPE_* constants below).
1.205 + * @param aGUID
1.206 + * The unique ID associated with the item.
1.207 + * @param aOldParentGUID
1.208 + * The unique ID associated with the old item's parent.
1.209 + * @param aNewParentGUID
1.210 + * The unique ID associated with the new item's parent.
1.211 + */
1.212 + void onItemMoved(in long long aItemId,
1.213 + in long long aOldParentId,
1.214 + in long aOldIndex,
1.215 + in long long aNewParentId,
1.216 + in long aNewIndex,
1.217 + in unsigned short aItemType,
1.218 + in ACString aGUID,
1.219 + in ACString aOldParentGUID,
1.220 + in ACString aNewParentGUID);
1.221 +};
1.222 +
1.223 +/**
1.224 + * The BookmarksService interface provides methods for managing bookmarked
1.225 + * history items. Bookmarks consist of a set of user-customizable
1.226 + * folders. A URI in history can be contained in one or more such folders.
1.227 + */
1.228 +
1.229 +[scriptable, uuid(A78EA368-E28E-462E-897A-26606D4DDCE6)]
1.230 +interface nsINavBookmarksService : nsISupports
1.231 +{
1.232 + /**
1.233 + * The item ID of the Places root.
1.234 + */
1.235 + readonly attribute long long placesRoot;
1.236 +
1.237 + /**
1.238 + * The item ID of the bookmarks menu folder.
1.239 + */
1.240 + readonly attribute long long bookmarksMenuFolder;
1.241 +
1.242 + /**
1.243 + * The item ID of the top-level folder that contain the tag "folders".
1.244 + */
1.245 + readonly attribute long long tagsFolder;
1.246 +
1.247 + /**
1.248 + * The item ID of the unfiled-bookmarks folder.
1.249 + */
1.250 + readonly attribute long long unfiledBookmarksFolder;
1.251 +
1.252 + /**
1.253 + * The item ID of the personal toolbar folder.
1.254 + */
1.255 + readonly attribute long long toolbarFolder;
1.256 +
1.257 + /**
1.258 + * This value should be used for APIs that allow passing in an index
1.259 + * where an index is not known, or not required to be specified.
1.260 + * e.g.: When appending an item to a folder.
1.261 + */
1.262 + const short DEFAULT_INDEX = -1;
1.263 +
1.264 + const unsigned short TYPE_BOOKMARK = 1;
1.265 + const unsigned short TYPE_FOLDER = 2;
1.266 + const unsigned short TYPE_SEPARATOR = 3;
1.267 + // Dynamic containers are deprecated and unsupported.
1.268 + // This const exists just to avoid reusing the value.
1.269 + const unsigned short TYPE_DYNAMIC_CONTAINER = 4;
1.270 +
1.271 + /**
1.272 + * Inserts a child bookmark into the given folder.
1.273 + *
1.274 + * @param aParentId
1.275 + * The id of the parent folder
1.276 + * @param aURI
1.277 + * The URI to insert
1.278 + * @param aIndex
1.279 + * The index to insert at, or DEFAULT_INDEX to append
1.280 + * @param aTitle
1.281 + * The title for the new bookmark
1.282 + * @param [optional] aGUID
1.283 + * The GUID to be set for the new item. If not set, a new GUID is
1.284 + * generated. Unless you've a very sound reason, such as an undo
1.285 + * manager implementation, do not pass this argument.
1.286 + * @return The ID of the newly-created bookmark.
1.287 + *
1.288 + * @note aTitle will be truncated to TITLE_LENGTH_MAX and
1.289 + * aURI will be truncated to URI_LENGTH_MAX.
1.290 + * @throws if aGUID is malformed.
1.291 + */
1.292 + long long insertBookmark(in long long aParentId, in nsIURI aURI,
1.293 + in long aIndex, in AUTF8String aTitle,
1.294 + [optional] in ACString aGUID);
1.295 +
1.296 + /**
1.297 + * Removes a child item. Used to delete a bookmark or separator.
1.298 + * @param aItemId
1.299 + * The child item to remove
1.300 + */
1.301 + void removeItem(in long long aItemId);
1.302 +
1.303 + /**
1.304 + * Creates a new child folder and inserts it under the given parent.
1.305 + * @param aParentFolder
1.306 + * The id of the parent folder
1.307 + * @param aName
1.308 + * The name of the new folder
1.309 + * @param aIndex
1.310 + * The index to insert at, or DEFAULT_INDEX to append
1.311 + * @param [optional] aGUID
1.312 + * The GUID to be set for the new item. If not set, a new GUID is
1.313 + * generated. Unless you've a very sound reason, such as an undo
1.314 + * manager implementation, do not pass this argument.
1.315 + * @return The ID of the newly-inserted folder.
1.316 + * @throws if aGUID is malformed.
1.317 + */
1.318 + long long createFolder(in long long aParentFolder, in AUTF8String name,
1.319 + in long index,
1.320 + [optional] in ACString aGUID);
1.321 +
1.322 + /**
1.323 + * Gets an undo-able transaction for removing a folder from the bookmarks
1.324 + * tree.
1.325 + * @param aItemId
1.326 + * The id of the folder to remove.
1.327 + * @return An object implementing nsITransaction that can be used to undo
1.328 + * or redo the action.
1.329 + *
1.330 + * This method exists because complex delete->undo operations rely on
1.331 + * recreated folders to have the same ID they had before they were deleted,
1.332 + * so that any other items deleted in different transactions can be
1.333 + * re-inserted correctly. This provides a safe encapsulation of this
1.334 + * functionality without exposing the ability to recreate folders with
1.335 + * specific IDs (potentially dangerous if abused by other code!) in the
1.336 + * public API.
1.337 + */
1.338 + nsITransaction getRemoveFolderTransaction(in long long aItemId);
1.339 +
1.340 + /**
1.341 + * Convenience function for container services. Removes
1.342 + * all children of the given folder.
1.343 + * @param aItemId
1.344 + * The id of the folder to remove children from.
1.345 + */
1.346 + void removeFolderChildren(in long long aItemId);
1.347 +
1.348 + /**
1.349 + * Moves an item to a different container, preserving its contents.
1.350 + * @param aItemId
1.351 + * The id of the item to move
1.352 + * @param aNewParentId
1.353 + * The id of the new parent
1.354 + * @param aIndex
1.355 + * The index under aNewParent, or DEFAULT_INDEX to append
1.356 + *
1.357 + * NOTE: When moving down in the same container we take into account the
1.358 + * removal of the original item. If you want to move from index X to
1.359 + * index Y > X you must use moveItem(id, folder, Y + 1)
1.360 + */
1.361 + void moveItem(in long long aItemId, in long long aNewParentId, in long aIndex);
1.362 +
1.363 + /**
1.364 + * Inserts a bookmark separator into the given folder at the given index.
1.365 + * The separator can be removed using removeChildAt().
1.366 + * @param aParentId
1.367 + * The id of the parent folder
1.368 + * @param aIndex
1.369 + * The separator's index under folder, or DEFAULT_INDEX to append
1.370 + * @param [optional] aGUID
1.371 + * The GUID to be set for the new item. If not set, a new GUID is
1.372 + * generated. Unless you've a very sound reason, such as an undo
1.373 + * manager implementation, do not pass this argument.
1.374 + * @return The ID of the new separator.
1.375 + * @throws if aGUID is malformed.
1.376 + */
1.377 + long long insertSeparator(in long long aParentId, in long aIndex,
1.378 + [optional] in ACString aGUID);
1.379 +
1.380 + /**
1.381 + * Get the itemId given the containing folder and the index.
1.382 + * @param aParentId
1.383 + * The id of the diret parent folder of the item
1.384 + * @param aIndex
1.385 + * The index of the item within the parent folder.
1.386 + * Pass DEFAULT_INDEX for the last item.
1.387 + * @return The ID of the found item, -1 if the item does not exists.
1.388 + */
1.389 + long long getIdForItemAt(in long long aParentId, in long aIndex);
1.390 +
1.391 + /**
1.392 + * Set the title for an item.
1.393 + * @param aItemId
1.394 + * The id of the item whose title should be updated.
1.395 + * @param aTitle
1.396 + * The new title for the bookmark.
1.397 + *
1.398 + * @note aTitle will be truncated to TITLE_LENGTH_MAX.
1.399 + */
1.400 + void setItemTitle(in long long aItemId, in AUTF8String aTitle);
1.401 +
1.402 + /**
1.403 + * Get the title for an item.
1.404 + *
1.405 + * If no item title is available it will return a void string (null in JS).
1.406 + *
1.407 + * @param aItemId
1.408 + * The id of the item whose title should be retrieved
1.409 + * @return The title of the item.
1.410 + */
1.411 + AUTF8String getItemTitle(in long long aItemId);
1.412 +
1.413 + /**
1.414 + * Set the date added time for an item.
1.415 + */
1.416 + void setItemDateAdded(in long long aItemId, in PRTime aDateAdded);
1.417 + /**
1.418 + * Get the date added time for an item.
1.419 + */
1.420 + PRTime getItemDateAdded(in long long aItemId);
1.421 +
1.422 + /**
1.423 + * Set the last modified time for an item.
1.424 + *
1.425 + * @note This is the only method that will send an itemChanged notification
1.426 + * for the property. lastModified will still be updated in
1.427 + * any other method that changes an item property, but we will send
1.428 + * the corresponding itemChanged notification instead.
1.429 + */
1.430 + void setItemLastModified(in long long aItemId, in PRTime aLastModified);
1.431 + /**
1.432 + * Get the last modified time for an item.
1.433 + *
1.434 + * @note When an item is added lastModified is set to the same value as
1.435 + * dateAdded.
1.436 + */
1.437 + PRTime getItemLastModified(in long long aItemId);
1.438 +
1.439 + /**
1.440 + * Get the URI for a bookmark item.
1.441 + */
1.442 + nsIURI getBookmarkURI(in long long aItemId);
1.443 +
1.444 + /**
1.445 + * Get the index for an item.
1.446 + */
1.447 + long getItemIndex(in long long aItemId);
1.448 +
1.449 + /**
1.450 + * Changes the index for a item. This method does not change the indices of
1.451 + * any other items in the same folder, so ensure that the new index does not
1.452 + * already exist, or change the index of other items accordingly, otherwise
1.453 + * the indices will become corrupted.
1.454 + *
1.455 + * WARNING: This is API is intended for scenarios such as folder sorting,
1.456 + * where the caller manages the indices of *all* items in the folder.
1.457 + * You must always ensure each index is unique after a reordering.
1.458 + *
1.459 + * @param aItemId The id of the item to modify
1.460 + * @param aNewIndex The new index
1.461 + *
1.462 + * @throws If aNewIndex is out of bounds.
1.463 + */
1.464 + void setItemIndex(in long long aItemId, in long aNewIndex);
1.465 +
1.466 + /**
1.467 + * Get an item's type (bookmark, separator, folder).
1.468 + * The type is one of the TYPE_* constants defined above.
1.469 + */
1.470 + unsigned short getItemType(in long long aItemId);
1.471 +
1.472 + /**
1.473 + * Checks whether a folder is marked as read-only.
1.474 + * If this is set to true, UI will not allow the user to add, remove,
1.475 + * or reorder children in this folder. The default for all folders is false.
1.476 + * Note: This does not restrict API calls, only UI actions.
1.477 + *
1.478 + * @param aItemId
1.479 + * the item-id of the folder.
1.480 + */
1.481 + boolean getFolderReadonly(in long long aItemId);
1.482 +
1.483 + /**
1.484 + * Sets or unsets the readonly flag from a folder.
1.485 + * If this is set to true, UI will not allow the user to add, remove,
1.486 + * or reorder children in this folder. The default for all folders is false.
1.487 + * Note: This does not restrict API calls, only UI actions.
1.488 + *
1.489 + * @param aFolder
1.490 + * the item-id of the folder.
1.491 + * @param aReadOnly
1.492 + * the read-only state (boolean).
1.493 + */
1.494 + void setFolderReadonly(in long long aFolder, in boolean aReadOnly);
1.495 +
1.496 + /**
1.497 + * Returns true if the given URI is in any bookmark folder. If you want the
1.498 + * results to be redirect-aware, use getBookmarkedURIFor()
1.499 + */
1.500 + boolean isBookmarked(in nsIURI aURI);
1.501 +
1.502 + /**
1.503 + * Used to see if the given URI is bookmarked, or any page that redirected to
1.504 + * it is bookmarked. For example, if I bookmark "mozilla.org" by manually
1.505 + * typing it in, and follow the bookmark, I will get redirected to
1.506 + * "www.mozilla.org". Logically, this new page is also bookmarked. This
1.507 + * function, if given "www.mozilla.org", will return the URI of the bookmark,
1.508 + * in this case "mozilla.org".
1.509 + *
1.510 + * If there is no bookmarked page found, it will return NULL.
1.511 + *
1.512 + * @note The function will only return bookmarks in the first 2 levels of
1.513 + * redirection (1 -> 2 -> aURI).
1.514 + */
1.515 + nsIURI getBookmarkedURIFor(in nsIURI aURI);
1.516 +
1.517 + /**
1.518 + * Change the bookmarked URI for a bookmark.
1.519 + * This changes which "place" the bookmark points at,
1.520 + * which means all annotations, etc are carried along.
1.521 + */
1.522 + void changeBookmarkURI(in long long aItemId, in nsIURI aNewURI);
1.523 +
1.524 + /**
1.525 + * Get the parent folder's id for an item.
1.526 + */
1.527 + long long getFolderIdForItem(in long long aItemId);
1.528 +
1.529 + /**
1.530 + * Returns the list of bookmark ids that contain the given URI.
1.531 + */
1.532 + void getBookmarkIdsForURI(in nsIURI aURI, [optional] out unsigned long count,
1.533 + [array, retval, size_is(count)] out long long bookmarks);
1.534 +
1.535 + /**
1.536 + * Associates the given keyword with the given bookmark.
1.537 + *
1.538 + * Use an empty keyword to clear the keyword associated with the URI.
1.539 + * In both of these cases, succeeds but does nothing if the URL/keyword is not found.
1.540 + */
1.541 + void setKeywordForBookmark(in long long aItemId, in AString aKeyword);
1.542 +
1.543 + /**
1.544 + * Retrieves the keyword for the given URI. Will be void string
1.545 + * (null in JS) if no such keyword is found.
1.546 + */
1.547 + AString getKeywordForURI(in nsIURI aURI);
1.548 +
1.549 + /**
1.550 + * Retrieves the keyword for the given bookmark. Will be void string
1.551 + * (null in JS) if no such keyword is found.
1.552 + */
1.553 + AString getKeywordForBookmark(in long long aItemId);
1.554 +
1.555 + /**
1.556 + * Returns the URI associated with the given keyword. Empty if no such
1.557 + * keyword is found.
1.558 + */
1.559 + nsIURI getURIForKeyword(in AString keyword);
1.560 +
1.561 + /**
1.562 + * Adds a bookmark observer. If ownsWeak is false, the bookmark service will
1.563 + * keep an owning reference to the observer. If ownsWeak is true, then
1.564 + * aObserver must implement nsISupportsWeakReference, and the bookmark
1.565 + * service will keep a weak reference to the observer.
1.566 + */
1.567 + void addObserver(in nsINavBookmarkObserver observer, in boolean ownsWeak);
1.568 +
1.569 + /**
1.570 + * Removes a bookmark observer.
1.571 + */
1.572 + void removeObserver(in nsINavBookmarkObserver observer);
1.573 +
1.574 + /**
1.575 + * Runs the passed callback inside of a database transaction.
1.576 + * Use this when a lot of things are about to change, for example
1.577 + * adding or deleting a large number of bookmark items. Calls can
1.578 + * be nested. Observers are notified when batches begin and end, via
1.579 + * nsINavBookmarkObserver.onBeginUpdateBatch/onEndUpdateBatch.
1.580 + *
1.581 + * @param aCallback
1.582 + * nsINavHistoryBatchCallback interface to call.
1.583 + * @param aUserData
1.584 + * Opaque parameter passed to nsINavBookmarksBatchCallback
1.585 + */
1.586 + void runInBatchMode(in nsINavHistoryBatchCallback aCallback,
1.587 + in nsISupports aUserData);
1.588 +};
