michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
michael@0:  * You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIURI;
michael@0: 
michael@0: interface mozILivemarkCallback;
michael@0: interface mozILivemarkInfo;
michael@0: interface mozILivemark;
michael@0: 
michael@0: interface nsINavHistoryResultObserver;
michael@0: 
michael@0: [scriptable, uuid(5B48E5A2-F07A-4E64-A935-C722A3D60B65)]
michael@0: interface mozIAsyncLivemarks : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Creates a new livemark
michael@0:    *
michael@0:    * @param aLivemarkInfo
michael@0:    *        mozILivemarkInfo object containing at least title, parentId,
michael@0:    *        index and feedURI of the livemark to create.
michael@0:    * @param [optional] aCallback
michael@0:    *        Invoked when the creation process is done.  In case of failure will
michael@0:    *        receive an error code.
michael@0:    * @return {Promise}
michael@0:    * @throws NS_ERROR_INVALID_ARG if the supplied information is insufficient
michael@0:    *         for the creation.
michael@0:    * @deprecated passing a callback is deprecated. Moreover, for backwards
michael@0:    *             compatibility reasons, when a callback is provided this method
michael@0:    *             won't return a promise.
michael@0:    */
michael@0:   jsval addLivemark(in jsval aLivemarkInfo,
michael@0:                     [optional] in mozILivemarkCallback aCallback);
michael@0: 
michael@0:   /**
michael@0:    * Removes an existing livemark.
michael@0:    *
michael@0:    * @param aLivemarkInfo
michael@0:    *        mozILivemarkInfo object containing either an id or a guid of the
michael@0:    *        livemark to remove.
michael@0:    * @param [optional] aCallback
michael@0:    *        Invoked when the removal process is done.  In case of failure will
michael@0:    *        receive an error code.
michael@0:    *
michael@0:    * @return {Promise}
michael@0:    * @throws NS_ERROR_INVALID_ARG if the id/guid is invalid.
michael@0:    * @deprecated passing a callback is deprecated. Moreover, for backwards
michael@0:    *             compatibility reasons, when a callback is provided this method
michael@0:    *             won't return a promise.
michael@0:    */
michael@0:   jsval removeLivemark(in jsval aLivemarkInfo,
michael@0:                        [optional] in mozILivemarkCallback aCallback);
michael@0: 
michael@0:   /**
michael@0:    * Gets an existing livemark.
michael@0:    *
michael@0:    * @param aLivemarkInfo
michael@0:    *        mozILivemarkInfo object containing either an id or a guid of the
michael@0:    *        livemark to retrieve.
michael@0:    * @param [optional] aCallback
michael@0:    *        Invoked when the fetching process is done.  In case of failure will
michael@0:    *        receive an error code.
michael@0:    *
michael@0:    * @return {Promise}
michael@0:    * @throws NS_ERROR_INVALID_ARG if the id/guid is invalid or an invalid
michael@0:    *         callback is provided.
michael@0:    * @deprecated passing a callback is deprecated. Moreover, for backwards
michael@0:    *             compatibility reasons, when a callback is provided this method
michael@0:    *             won't return a promise.
michael@0:    */
michael@0:   jsval getLivemark(in jsval aLivemarkInfo,
michael@0:                     [optional] in mozILivemarkCallback aCallback);
michael@0: 
michael@0:   /**
michael@0:    * Reloads all livemarks if they are expired or if forced to do so.
michael@0:    *
michael@0:    * @param [optional]aForceUpdate
michael@0:    *        If set to true forces a reload even if contents are still valid.
michael@0:    *
michael@0:    * @note The update process is asynchronous, observers registered through
michael@0:    *       registerForUpdates will be notified of updated contents.
michael@0:    */
michael@0:   void reloadLivemarks([optional]in boolean aForceUpdate);
michael@0: };
michael@0: 
michael@0: [scriptable, function, uuid(62a426f9-39a6-42f0-ad48-b7404d48188f)]
michael@0: interface mozILivemarkCallback : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Invoked when a livemark is added, removed or retrieved.
michael@0:    *
michael@0:    * @param aStatus
michael@0:    *        Whether the request was completed successfully.
michael@0:    *        Use Components.isSuccessCode(aStatus) to check this.
michael@0:    * @param aLivemark
michael@0:    *        A mozILivemark object representing the livemark, or null on removal.
michael@0:    */
michael@0:   void onCompletion(in nsresult aStatus,
michael@0:                     in mozILivemark aLivemark);
michael@0: };
michael@0: 
michael@0: [scriptable, uuid(6e40d5b1-ce48-4458-8b68-6bee17d30ef3)]
michael@0: interface mozILivemarkInfo : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Id of the bookmarks folder representing this livemark.
michael@0:    */
michael@0:   readonly attribute long long id;
michael@0: 
michael@0:   /**
michael@0:    * The globally unique identifier of this livemark.
michael@0:    */
michael@0:   readonly attribute ACString guid;
michael@0: 
michael@0:   /**
michael@0:    * Title of this livemark.
michael@0:    */
michael@0:   readonly attribute AString title;
michael@0: 
michael@0:   /**
michael@0:    * Id of the bookmarks parent folder containing this livemark.
michael@0:    */
michael@0:   readonly attribute long long parentId;
michael@0: 
michael@0:   /**
michael@0:    * The position of this livemark in the bookmarks parent folder.
michael@0:    */
michael@0:   readonly attribute long index;
michael@0: 
michael@0:   /**
michael@0:    * Time this livemark's details were last modified.  Doesn't track changes to
michael@0:    * the livemark contents.
michael@0:    */
michael@0:   readonly attribute PRTime lastModified;
michael@0: 
michael@0:   /**
michael@0:    * The URI of the syndication feed associated with this livemark.
michael@0:    */
michael@0:   readonly attribute nsIURI feedURI;
michael@0: 
michael@0:   /**
michael@0:    * The URI of the website associated with this livemark.
michael@0:    */
michael@0:   readonly attribute nsIURI siteURI;
michael@0: };
michael@0: 
michael@0: [scriptable, uuid(9f6fdfae-db9a-4bd8-bde1-148758cf1b18)]
michael@0: interface mozILivemark : mozILivemarkInfo
michael@0: {
michael@0:   // Indicates the livemark is inactive.
michael@0:   const unsigned short STATUS_READY = 0;
michael@0:   // Indicates the livemark is fetching new contents.
michael@0:   const unsigned short STATUS_LOADING = 1;
michael@0:   // Indicates the livemark failed to fetch new contents.
michael@0:   const unsigned short STATUS_FAILED = 2;
michael@0: 
michael@0:   /**
michael@0:    * Status of this livemark.  One of the STATUS_* constants above.
michael@0:    */
michael@0:   readonly attribute unsigned short status;
michael@0: 
michael@0:   /**
michael@0:    * Reload livemark contents if they are expired or if forced to do so.
michael@0:    *
michael@0:    * @param [optional]aForceUpdate
michael@0:    *        If set to true forces a reload even if contents are still valid.
michael@0:    *
michael@0:    * @note The update process is asynchronous, it's possible to register a
michael@0:    *       result observer to be notified of updated contents through
michael@0:    *       registerForUpdates.
michael@0:    */
michael@0:   void reload([optional]in boolean aForceUpdate);
michael@0: 
michael@0:   /**
michael@0:    * Returns an array of nsINavHistoryResultNode objects, representing children
michael@0:    * of this livemark.  The nodes will have aContainerNode as parent.
michael@0:    *
michael@0:    * @param aContainerNode
michael@0:    *        Object implementing nsINavHistoryContainerResultNode, to be used as
michael@0:    *        parent of the livemark nodes.
michael@0:    */
michael@0:   jsval getNodesForContainer(in jsval aContainerNode);
michael@0: 
michael@0:   /**
michael@0:    * Registers a container node for updates on this livemark.
michael@0:    * When the livemark contents change, an invalidateContainer(aContainerNode)
michael@0:    * request is sent to aResultObserver.
michael@0:    *
michael@0:    * @param aContainerNode
michael@0:    *        Object implementing nsINavHistoryContainerResultNode, representing
michael@0:    *        this livemark.
michael@0:    * @param aResultObserver
michael@0:    *        The nsINavHistoryResultObserver that should be notified of changes
michael@0:    *        to the livemark contents.
michael@0:    */
michael@0:   void registerForUpdates(in jsval aContainerNode,
michael@0:                           in nsINavHistoryResultObserver aResultObserver);
michael@0: 
michael@0:   /**
michael@0:    * Unregisters a previously registered container node.
michael@0:    *
michael@0:    * @param aContainerNode
michael@0:    *        Object implementing nsINavHistoryContainerResultNode, representing
michael@0:    *        this livemark.
michael@0:    *
michael@0:    * @note it's suggested to always unregister containers that are no more used,
michael@0:    *       to free up the associated resources.  A good time to do so is when
michael@0:    *       the container gets closed.
michael@0:    */
michael@0:   void unregisterForUpdates(in jsval aContainerNode);
michael@0: };