kamp/RetroZilla
1
0
Fork 0
mirror of https://github.com/rn10950/RetroZilla.git synced 2024-11-14 19:50:12 +01:00
Code Issues Packages Projects Releases Wiki Activity
b495767a90
RetroZilla/browser/components/places/public/nsINavBookmarksService.idl
Ryan Nematz 2f2ae146c0 first commit
2015-10-20 23:03:22 -04:00

508 lines
19 KiB
Plaintext
Raw Blame History

/* -*- 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 <bryner@brianryner.com> (original author)
* Joe Hughes <joe@retrovirus.com>
*
* Alternatively, the contents of this file may be used under the terms of
* either the GNU General Public License Version 2 or later (the "GPL"), or
* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
* in which case the provisions of the GPL or the LGPL are applicable instead
* of those above. If you wish to allow use of your version of this file only
* under the terms of either the GPL or the LGPL, and not to allow others to
* use your version of this file under the terms of the MPL, indicate your
* decision by deleting the provisions above and replace them with the notice
* and other provisions required by the GPL or the LGPL. If you do not delete
* the provisions above, a recipient may use your version of this file under
* the terms of any one of the MPL, the GPL or the LGPL.
*
* ***** END LICENSE BLOCK ***** */
#include "nsISupports.idl"
%{C++
#include "nsTArray.h"
#include "prtypes.h"
%}
interface nsIFile;
interface nsIURI;
interface nsITransaction;
[ptr] native PRInt64Array(nsTArray<PRInt64>);
/**
* 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);
};
Reference in New Issue View Git Blame Copy Permalink