• file
• revisions
• annotate
• diff
• comparison
• raw

toolkit/components/places/mozIAsyncLivemarks.idl@b8a032363ba2 (annotated)

toolkit/components/places/mozIAsyncLivemarks.idl

Thu, 22 Jan 2015 13:21:57 +0100

author

Michael Schloh von Bennewitz <michael@schloh.com>

date

Thu, 22 Jan 2015 13:21:57 +0100

branch

TOR_BUG_9701

changeset 15

b8a032363ba2

permissions

-rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

michael@0	1	/* This Source Code Form is subject to the terms of the Mozilla Public
michael@0	2	* License, v. 2.0. If a copy of the MPL was not distributed with this file,
michael@0	3	* You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0	4
michael@0	5	#include "nsISupports.idl"
michael@0	6
michael@0	7	interface nsIURI;
michael@0	8
michael@0	9	interface mozILivemarkCallback;
michael@0	10	interface mozILivemarkInfo;
michael@0	11	interface mozILivemark;
michael@0	12
michael@0	13	interface nsINavHistoryResultObserver;
michael@0	14
michael@0	15	[scriptable, uuid(5B48E5A2-F07A-4E64-A935-C722A3D60B65)]
michael@0	16	interface mozIAsyncLivemarks : nsISupports
michael@0	17	{
michael@0	18	/**
michael@0	19	* Creates a new livemark
michael@0	20	*
michael@0	21	* @param aLivemarkInfo
michael@0	22	* mozILivemarkInfo object containing at least title, parentId,
michael@0	23	* index and feedURI of the livemark to create.
michael@0	24	* @param [optional] aCallback
michael@0	25	* Invoked when the creation process is done. In case of failure will
michael@0	26	* receive an error code.
michael@0	27	* @return {Promise}
michael@0	28	* @throws NS_ERROR_INVALID_ARG if the supplied information is insufficient
michael@0	29	* for the creation.
michael@0	30	* @deprecated passing a callback is deprecated. Moreover, for backwards
michael@0	31	* compatibility reasons, when a callback is provided this method
michael@0	32	* won't return a promise.
michael@0	33	*/
michael@0	34	jsval addLivemark(in jsval aLivemarkInfo,
michael@0	35	[optional] in mozILivemarkCallback aCallback);
michael@0	36
michael@0	37	/**
michael@0	38	* Removes an existing livemark.
michael@0	39	*
michael@0	40	* @param aLivemarkInfo
michael@0	41	* mozILivemarkInfo object containing either an id or a guid of the
michael@0	42	* livemark to remove.
michael@0	43	* @param [optional] aCallback
michael@0	44	* Invoked when the removal process is done. In case of failure will
michael@0	45	* receive an error code.
michael@0	46	*
michael@0	47	* @return {Promise}
michael@0	48	* @throws NS_ERROR_INVALID_ARG if the id/guid is invalid.
michael@0	49	* @deprecated passing a callback is deprecated. Moreover, for backwards
michael@0	50	* compatibility reasons, when a callback is provided this method
michael@0	51	* won't return a promise.
michael@0	52	*/
michael@0	53	jsval removeLivemark(in jsval aLivemarkInfo,
michael@0	54	[optional] in mozILivemarkCallback aCallback);
michael@0	55
michael@0	56	/**
michael@0	57	* Gets an existing livemark.
michael@0	58	*
michael@0	59	* @param aLivemarkInfo
michael@0	60	* mozILivemarkInfo object containing either an id or a guid of the
michael@0	61	* livemark to retrieve.
michael@0	62	* @param [optional] aCallback
michael@0	63	* Invoked when the fetching process is done. In case of failure will
michael@0	64	* receive an error code.
michael@0	65	*
michael@0	66	* @return {Promise}
michael@0	67	* @throws NS_ERROR_INVALID_ARG if the id/guid is invalid or an invalid
michael@0	68	* callback is provided.
michael@0	69	* @deprecated passing a callback is deprecated. Moreover, for backwards
michael@0	70	* compatibility reasons, when a callback is provided this method
michael@0	71	* won't return a promise.
michael@0	72	*/
michael@0	73	jsval getLivemark(in jsval aLivemarkInfo,
michael@0	74	[optional] in mozILivemarkCallback aCallback);
michael@0	75
michael@0	76	/**
michael@0	77	* Reloads all livemarks if they are expired or if forced to do so.
michael@0	78	*
michael@0	79	* @param [optional]aForceUpdate
michael@0	80	* If set to true forces a reload even if contents are still valid.
michael@0	81	*
michael@0	82	* @note The update process is asynchronous, observers registered through
michael@0	83	* registerForUpdates will be notified of updated contents.
michael@0	84	*/
michael@0	85	void reloadLivemarks([optional]in boolean aForceUpdate);
michael@0	86	};
michael@0	87
michael@0	88	[scriptable, function, uuid(62a426f9-39a6-42f0-ad48-b7404d48188f)]
michael@0	89	interface mozILivemarkCallback : nsISupports
michael@0	90	{
michael@0	91	/**
michael@0	92	* Invoked when a livemark is added, removed or retrieved.
michael@0	93	*
michael@0	94	* @param aStatus
michael@0	95	* Whether the request was completed successfully.
michael@0	96	* Use Components.isSuccessCode(aStatus) to check this.
michael@0	97	* @param aLivemark
michael@0	98	* A mozILivemark object representing the livemark, or null on removal.
michael@0	99	*/
michael@0	100	void onCompletion(in nsresult aStatus,
michael@0	101	in mozILivemark aLivemark);
michael@0	102	};
michael@0	103
michael@0	104	[scriptable, uuid(6e40d5b1-ce48-4458-8b68-6bee17d30ef3)]
michael@0	105	interface mozILivemarkInfo : nsISupports
michael@0	106	{
michael@0	107	/**
michael@0	108	* Id of the bookmarks folder representing this livemark.
michael@0	109	*/
michael@0	110	readonly attribute long long id;
michael@0	111
michael@0	112	/**
michael@0	113	* The globally unique identifier of this livemark.
michael@0	114	*/
michael@0	115	readonly attribute ACString guid;
michael@0	116
michael@0	117	/**
michael@0	118	* Title of this livemark.
michael@0	119	*/
michael@0	120	readonly attribute AString title;
michael@0	121
michael@0	122	/**
michael@0	123	* Id of the bookmarks parent folder containing this livemark.
michael@0	124	*/
michael@0	125	readonly attribute long long parentId;
michael@0	126
michael@0	127	/**
michael@0	128	* The position of this livemark in the bookmarks parent folder.
michael@0	129	*/
michael@0	130	readonly attribute long index;
michael@0	131
michael@0	132	/**
michael@0	133	* Time this livemark's details were last modified. Doesn't track changes to
michael@0	134	* the livemark contents.
michael@0	135	*/
michael@0	136	readonly attribute PRTime lastModified;
michael@0	137
michael@0	138	/**
michael@0	139	* The URI of the syndication feed associated with this livemark.
michael@0	140	*/
michael@0	141	readonly attribute nsIURI feedURI;
michael@0	142
michael@0	143	/**
michael@0	144	* The URI of the website associated with this livemark.
michael@0	145	*/
michael@0	146	readonly attribute nsIURI siteURI;
michael@0	147	};
michael@0	148
michael@0	149	[scriptable, uuid(9f6fdfae-db9a-4bd8-bde1-148758cf1b18)]
michael@0	150	interface mozILivemark : mozILivemarkInfo
michael@0	151	{
michael@0	152	// Indicates the livemark is inactive.
michael@0	153	const unsigned short STATUS_READY = 0;
michael@0	154	// Indicates the livemark is fetching new contents.
michael@0	155	const unsigned short STATUS_LOADING = 1;
michael@0	156	// Indicates the livemark failed to fetch new contents.
michael@0	157	const unsigned short STATUS_FAILED = 2;
michael@0	158
michael@0	159	/**
michael@0	160	* Status of this livemark. One of the STATUS_* constants above.
michael@0	161	*/
michael@0	162	readonly attribute unsigned short status;
michael@0	163
michael@0	164	/**
michael@0	165	* Reload livemark contents if they are expired or if forced to do so.
michael@0	166	*
michael@0	167	* @param [optional]aForceUpdate
michael@0	168	* If set to true forces a reload even if contents are still valid.
michael@0	169	*
michael@0	170	* @note The update process is asynchronous, it's possible to register a
michael@0	171	* result observer to be notified of updated contents through
michael@0	172	* registerForUpdates.
michael@0	173	*/
michael@0	174	void reload([optional]in boolean aForceUpdate);
michael@0	175
michael@0	176	/**
michael@0	177	* Returns an array of nsINavHistoryResultNode objects, representing children
michael@0	178	* of this livemark. The nodes will have aContainerNode as parent.
michael@0	179	*
michael@0	180	* @param aContainerNode
michael@0	181	* Object implementing nsINavHistoryContainerResultNode, to be used as
michael@0	182	* parent of the livemark nodes.
michael@0	183	*/
michael@0	184	jsval getNodesForContainer(in jsval aContainerNode);
michael@0	185
michael@0	186	/**
michael@0	187	* Registers a container node for updates on this livemark.
michael@0	188	* When the livemark contents change, an invalidateContainer(aContainerNode)
michael@0	189	* request is sent to aResultObserver.
michael@0	190	*
michael@0	191	* @param aContainerNode
michael@0	192	* Object implementing nsINavHistoryContainerResultNode, representing
michael@0	193	* this livemark.
michael@0	194	* @param aResultObserver
michael@0	195	* The nsINavHistoryResultObserver that should be notified of changes
michael@0	196	* to the livemark contents.
michael@0	197	*/
michael@0	198	void registerForUpdates(in jsval aContainerNode,
michael@0	199	in nsINavHistoryResultObserver aResultObserver);
michael@0	200
michael@0	201	/**
michael@0	202	* Unregisters a previously registered container node.
michael@0	203	*
michael@0	204	* @param aContainerNode
michael@0	205	* Object implementing nsINavHistoryContainerResultNode, representing
michael@0	206	* this livemark.
michael@0	207	*
michael@0	208	* @note it's suggested to always unregister containers that are no more used,
michael@0	209	* to free up the associated resources. A good time to do so is when
michael@0	210	* the container gets closed.
michael@0	211	*/
michael@0	212	void unregisterForUpdates(in jsval aContainerNode);
michael@0	213	};