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