gecko/toolkit/components/places/mozIAsyncLivemarks.idl

191 lines
5.5 KiB
Plaintext

/* 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);
};