gecko/toolkit/components/places/mozIAsyncLivemarks.idl
Nicholas Nethercote b89a8ac1c0 Bug 905017 (part 1) - Minimize inclusions of JS engine headers in .h and .idl files. r=billm.
--HG--
extra : rebase_source : 984c61ab12f46be0509b1ce0d458d9a6e5841c64
2013-08-17 15:50:18 -07:00

203 lines
6.3 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 mozILivemarkCallback;
interface mozILivemarkInfo;
interface mozILivemark;
interface nsINavHistoryResultObserver;
[scriptable, uuid(1dbf174c-696e-4d9b-af0f-350da50d2249)]
interface mozIAsyncLivemarks : nsISupports
{
/**
* Creates a new livemark
*
* @param aLivemarkInfo
* mozILivemarkInfo object containing at least title, parentId,
* index and feedURI of the livemark to create.
* @param [optional] aCallback
* Invoked when the creation process is done. In case of failure will
* receive an error code.
*
* @throws NS_ERROR_INVALID_ARG if the supplied information is insufficient
* for the creation.
*/
void addLivemark(in jsval aLivemarkInfo,
[optional]in mozILivemarkCallback aCallback);
/**
* Removes an existing livemark.
*
* @param aLivemarkInfo
* mozILivemarkInfo object containing either an id or a guid of the
* livemark to remove.
* @param [optional] aCallback
* Invoked when the removal process is done. In case of failure will
* receive an error code.
*
* @throws NS_ERROR_INVALID_ARG if the id/guid is invalid.
*/
void removeLivemark(in jsval aLivemarkInfo,
[optional]in mozILivemarkCallback aCallback);
/**
* Gets an existing livemark.
*
* @param aLivemarkInfo
* mozILivemarkInfo object containing either an id or a guid of the
* livemark to retrieve.
* @param aCallback
* Invoked when the fetching process is done. In case of failure will
* receive an error code.
*
* @throws NS_ERROR_INVALID_ARG if the id/guid is invalid or an invalid
* callback is provided.
*/
void getLivemark(in jsval aLivemarkInfo,
in mozILivemarkCallback aCallback);
/**
* 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, function, uuid(62a426f9-39a6-42f0-ad48-b7404d48188f)]
interface mozILivemarkCallback : nsISupports
{
/**
* Invoked when a livemark is added, removed or retrieved.
*
* @param aStatus
* Whether the request was completed successfully.
* Use Components.isSuccessCode(aStatus) to check this.
* @param aLivemark
* A mozILivemark object representing the livemark, or null on removal.
*/
void onCompletion(in nsresult aStatus,
in mozILivemark aLivemark);
};
[scriptable, uuid(6e40d5b1-ce48-4458-8b68-6bee17d30ef3)]
interface mozILivemarkInfo : nsISupports
{
/**
* Id of the bookmarks folder representing this livemark.
*/
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.
*/
readonly attribute long long parentId;
/**
* The position of this livemark in the bookmarks parent folder.
*/
readonly attribute long index;
/**
* 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);
};