/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ /* ***** BEGIN LICENSE BLOCK ***** * Version: MPL 1.1/GPL 2.0/LGPL 2.1 * * The contents of this file are subject to the Mozilla Public License Version * 1.1 (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * http://www.mozilla.org/MPL/ * * Software distributed under the License is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License * for the specific language governing rights and limitations under the * License. * * The Original Code is Places. * * The Initial Developer of the Original Code is * Google Inc. * Portions created by the Initial Developer are Copyright (C) 2005 * the Initial Developer. All Rights Reserved. * * Contributor(s): * Brian Ryner (original author) * Joe Hughes * * Alternatively, the contents of this file may be used under the terms of * either the GNU General Public License Version 2 or later (the "GPL"), or * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), * in which case the provisions of the GPL or the LGPL are applicable instead * of those above. If you wish to allow use of your version of this file only * under the terms of either the GPL or the LGPL, and not to allow others to * use your version of this file under the terms of the MPL, indicate your * decision by deleting the provisions above and replace them with the notice * and other provisions required by the GPL or the LGPL. If you do not delete * the provisions above, a recipient may use your version of this file under * the terms of any one of the MPL, the GPL or the LGPL. * * ***** END LICENSE BLOCK ***** */ #include "nsISupports.idl" %{C++ #include "nsTArray.h" #include "prtypes.h" %} interface nsIFile; interface nsIURI; interface nsITransaction; [ptr] native PRInt64Array(nsTArray); /** * Observer for bookmark changes. */ [scriptable, uuid(224f8162-4da8-45eb-8187-a8ba3a3db8e5)] interface nsINavBookmarkObserver : nsISupports { /** * Notify this observer that a batch transaction has started. * Other notifications will be sent during the batch change, * but the observer is guaranteed that onEndUpdateBatch() will be called * at the completion of changes. */ void onBeginUpdateBatch(); /** * Notify this observer that a batch transaction has ended. */ void onEndUpdateBatch(); /** * Notify this observer that the bookmark was added. Called after the actual * add took place. The rest of the bookmarks will be shifted down, but no * additional notifications will be sent. * * @param bookmark The bookmark item that was added. * @param folder The folder that the item was added to. * @param index The item's index in the folder. */ void onItemAdded(in nsIURI bookmark, in PRInt64 folder, in PRInt32 index); /** * Notify this observer that the bookmark was removed. Called after the * actual remove took place. The bookmarks following the index will be * shifted up, but no additional notifications will be sent. * * @param bookmark The bookmark item will be removed. * @param folder The folder that the item was removed from. * @param index The bookmark's index in the folder. */ void onItemRemoved(in nsIURI bookmark, in PRInt64 folder, in PRInt32 index); /** * Notify this observer that a bookmark's information has changed. This * will be called whenever any attributes like "title" are changed. * * @param bookmark The bookmark which changed. * @param property The property which changed. * * property = "cleartime" (history was deleted, there is no last visit date): * value = none * property = "title": value = new title * property = "favicon": value = new "moz-anno" URL of favicon image */ void onItemChanged(in nsIURI bookmark, in ACString property, in AString value); /** * Notify that the item was visited. Normally in bookmarks we use the last * visit date, and normally the time will be a new visit that will be more * recent, but this is not guaranteed. You should check to see if it's * actually more recent before using this new time. * * @see onItemChanged properth = "cleartime" for when all visit dates are * deleted for the URI. */ void onItemVisited(in nsIURI bookmark, in PRInt64 aVisitID, in PRTime time); /** * Notify this observer that a bookmark has been replaced. * * @param folder The folder in which the bookmark was replaced * @param item The item which was replaced * @param newItem The new item which replaced item */ void onItemReplaced(in PRInt64 folder, in nsIURI item, in nsIURI newItem); /** * Notify this observer that a bookmark folder has been added. * @param folder The id of the folder that was added. * @param parent The id of the folder's parent. * @param index The folder's index inside its parent. */ void onFolderAdded(in PRInt64 folder, in PRInt64 parent, in PRInt32 index); /** * Notify this observer that a bookmark folder has been removed. * @param folder The id of the folder that was removed. * @param parent The id of the folder's old parent. * @param index The folder's old index in its parent. */ void onFolderRemoved(in PRInt64 folder, in PRInt64 parent, in PRInt32 index); /** * Notify this observer that a bookmark folder has been moved. * @param folder The id of the folder that was moved. * @param oldParent The id of the folder's old parent. * @param oldIndex The folder's old index inside oldParent. * @param newParent The id of the folder's new parent. * @param newIndex The folder's index inside newParent. */ void onFolderMoved(in PRInt64 folder, in PRInt64 oldParent, in PRInt32 oldIndex, in PRInt64 newParent, in PRInt32 newIndex); /** * Notify this observer that a bookmark folder's information has changed. * This will be called whenever any attributes like "title" are changed. * @param folder The id of the folder that was changed. * @param property The property that was changed. */ void onFolderChanged(in PRInt64 folder, in ACString property); /** * Notify this observer that a separator has been added. * @param parent The id of the separator's parent. * @param index The separator's index inside its parent. */ void onSeparatorAdded(in PRInt64 parent, in PRInt32 index); /** * Notify this observer that a separator has been removed. * @param parent The id of the separator's parent. * @param index The separator's old index in its parent. */ void onSeparatorRemoved(in PRInt64 parent, in PRInt32 index); }; /** * 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(860d786d-9bba-4011-a396-486a87af8f07)] interface nsINavBookmarksService : nsISupports { /** * The folder ID of the Places root. */ readonly attribute PRInt64 placesRoot; /** * The folder ID of the bookmarks root. */ readonly attribute PRInt64 bookmarksRoot; /** * The folder ID of the personal toolbar root. */ readonly attribute PRInt64 toolbarRoot; /** * The folder ID of the top-level folders that contain the tag "folders". * * NOTE: This isn't wired up yet, so don't try to use it for anything until * bug 329961 is marked resolved. */ readonly attribute PRInt64 tagRoot; /** * Inserts a child item into the given folder. If this item already exists in * the given folder, it will be moved to the new position. * @param folder The id of the parent folder * @param item The URI to insert * @param index The index to insert at, or -1 to append */ void insertItem(in PRInt64 folder, in nsIURI item, in PRInt32 index); /** * Removes a child item from the given folder. * @param folder The folder to remove the child from * @param item The child item to remove */ void removeItem(in PRInt64 folder, in nsIURI child); /** * Replace an item with a different item. * @param folder The folder which contains the item to replace * @param item The item which should be replaced * @param newItem The new item */ void replaceItem(in PRInt64 folder, in nsIURI item, in nsIURI newItem); /** * Creates a new child folder and inserts it under the given parent. * @param parent The id of the parent folder * @param name The name of the new folder * @param index The index to insert at, or -1 to append * @returns the ID of the newly-inserted folder */ PRInt64 createFolder(in PRInt64 parent, in AString name, in PRInt32 index); /** * Wrapper for container services. Creates a folder under the given * parent and sets the container type. * @param parent The id of the parent folder * @param name The name of the new folder * @param type The type of container to insert * @param index The index to insert at, or -1 to append * @returns the ID of the newly-inserted folder */ PRInt64 createContainer(in PRInt64 parent, in AString name, in AString type, in PRInt32 index); /** * Removes a folder from the bookmarks tree. * @param folder The id of the folder to remove. */ void removeFolder(in PRInt64 folder); /** * Gets an undo-able transaction for removing a folder from the bookmarks * tree. * @param folder The id of the folder to remove. * @returns 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 PRInt64 folder); /** * Convenience function for container services. Removes * all children of the given folder. * @param folder The id of the folder to remove children from. */ void removeFolderChildren(in PRInt64 folder); /** * Moves a folder to a different container, preserving its contents. * @param folder The folder to move * @param newParent The id of the folder's new parent * @param index The folder's index under newParent, or -1 to append */ void moveFolder(in PRInt64 folder, in PRInt64 newParent, in PRInt32 index); /** * Returns the ID of a child folder with the given name. This does not * recurse, you have to give it an immediate sibling of the given folder. * If the given subfolder doesn't exist, it will return 0. * @param folder Parent folder whose children we will search * @param subFolder Name of the folder to search for in folder */ PRInt64 getChildFolder(in PRInt64 folder, in AString subFolder); /** * Inserts a bookmark separator into the given folder at the given index. * The separator can be removed using removeChildAt(). * @param folder Parent folder of the separator * @param index The separator's index under folder, or -1 to append */ void insertSeparator(in PRInt64 folder, in PRInt32 index); /** * Removes any type of child (item, folder, or separator) at the given index. * @param folder The folder to remove a child from * @param index The index of the child to remove */ void removeChildAt(in PRInt64 folder, in PRInt32 index); /** * Set the history/bookmark title for a URI. The new title will be used * anywhere the URI is shown in bookmarks or history. * @param uri The URI whose name should be set * @param title The new title for the URI */ void setItemTitle(in nsIURI uri, in AString title); /** * Get the history/bookmark title for the URI. * * If no item title is available (for instance, if the URI doesn't appear * in the bookmarks or history), it will return a void string (null in JS). * * @param uri The URI whose title should be retrieved * @returns The title for the URI. */ AString getItemTitle(in nsIURI uri); /** * Set the title for a bookmark folder. * @param folder The folder whose title should be set * @param title The new title for the folder */ void setFolderTitle(in PRInt64 folder, in AString title); /** * Get the title for a bookmark folder. Throws an invalid argument * exception if it can't find a folder with the given ID. * * @param folder The folder whose title should be retrieved * @returns The title for the folder */ AString getFolderTitle(in PRInt64 folder); /** * Get the place: url for a bookmark folder. You can use this value to * get/set the icon for a folder or to associate other data with it using * the annotation service. Its important that you use this function instead * of just serializing the query/options for a given folder because you * may have different options or query parameters. This function will give * the canonical value. * @param folder The folder whose URI should be retrieved * @returns The URI for the folder */ nsIURI getFolderURI(in PRInt64 folder); /** * Checks whether a folder has read-only children. This property is * defined by the nsIBookmarsContainer for the folder, if one exists. * If this is set to true, UI should not allow the user to add, remove, * or reorder children in this folder. The default for all folders is false. */ boolean getFolderReadonly(in PRInt64 folder); /** * 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 uri); /** * 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. */ nsIURI getBookmarkedURIFor(in nsIURI uri); /** * "Changes" the URI of a bookmark. Since URIs are the unique * identifiers of bookmarks in this system, what this really means is * that all the metadata attached to oldURI will be copied onto newURI, * and oldURI will be deleted from the bookmark system. If newURI * is already bookmarked, the metadata from oldURI will overwrite * the corresponding metadata on newURI. Any annotations on oldURI * will be copied to newURI (a copy will remain on oldURI). */ void changeBookmarkURI(in nsIURI oldURI, in nsIURI newURI); /** * Returns the list of folder ids that contain the given URI. */ void getBookmarkFolders(in nsIURI uri, out PRUint32 count, [array, retval, size_is(count)] out PRInt64 folders); /** * TArray version of getBookmarkFolders for ease of use in C++ code. * Pass in a reference to a TArray; it will get cleared and filled with * the resulting list of folder IDs. */ [noscript] void getBookmarkFoldersTArray(in nsIURI aURI, in PRInt64Array aResult); /** * Returns the index of the given item in the given folder. * Returns -1 if the item is not present in the folder. */ PRInt32 indexOfItem(in PRInt64 folder, in nsIURI uri); /** * Returns the index of the given subfolder in its parent. * Returns -1 if the subfolder is not present in the parent folder. */ PRInt32 indexOfFolder(in PRInt64 parent, in PRInt64 folder); /** * Associates the given keyword with the given URI. * * Use an empty keyword to clear the keyword associated with the URI. Use an * empty URI to clear the URI associated with that keyword. In both of these * cases, succeeds but does nothing if the URL/keyword is not found. * * When setting a keyword (both URI and keyword are specified), the URI must * be bookmarked for the keyword to be persistent. */ void setKeywordForURI(in nsIURI uri, in AString keyword); /** * Retrieves the keyword for the given URI. Will be void string * (null in JS) if no such keyword is found. */ AString getKeywordForURI(in nsIURI uri); /** * Returns the URI associated with the given keyword. Empty if no such * keyword is found. */ 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); /** * Causes observers to be notified of a beginUpdateBatch when a lot of things * are about to change. Calls can be nested, observers will only be * notified when all batches begin/end. * * It is EXTREMELY IMPORTANT that you call EndUpdateBatch for each call to * beginUpdateBatch. If you don't do this, certain parts of the UI will not * get updated and any changes to bookmarks will not get written to disk. * From C++ code inside the places component, use nsBookmarksUpdateBatcher * defined in nsNavBookmarks.h to scope batches. For JS or from other * components, just please be very careful to close the batch, especially * when encountering an error and returning early. */ void beginUpdateBatch(); /** * Causes observers to be notified of an endUpdateBatch when a batch is * done changing. Should match beginUpdateBatch or bad things will happen. */ void endUpdateBatch(); /** * Loads the given bookmarks.html file and merges it with the current * bookmarks hierarchy. */ void importBookmarksHTML(in nsIURI url); /** * Loads the given bookmarks.html file and puts it in the given folder */ void importBookmarksHTMLToFolder(in nsIURI url, in PRInt64 folder); /** * Saves the current bookmarks hierarchy to a bookmarks.html file. */ void exportBookmarksHTML(in nsIFile file); };