summaryrefslogtreecommitdiffstats
path: root/toolkit/components/places/mozIAsyncLivemarks.idl
diff options
context:
space:
mode:
Diffstat (limited to 'toolkit/components/places/mozIAsyncLivemarks.idl')
-rw-r--r--toolkit/components/places/mozIAsyncLivemarks.idl190
1 files changed, 190 insertions, 0 deletions
diff --git a/toolkit/components/places/mozIAsyncLivemarks.idl b/toolkit/components/places/mozIAsyncLivemarks.idl
new file mode 100644
index 000000000..e84ecca8e
--- /dev/null
+++ b/toolkit/components/places/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);
+};