Source code

Revision control

Other Tools

1
/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2
/* This Source Code Form is subject to the terms of the Mozilla Public
3
* License, v. 2.0. If a copy of the MPL was not distributed with this
4
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5
6
#include "nsISupports.idl"
7
8
interface nsIFile;
9
interface nsIURI;
10
interface nsITransaction;
11
interface nsINavHistoryBatchCallback;
12
13
/**
14
* Observer for bookmarks changes.
15
*/
16
[scriptable, uuid(4d00c221-2c4a-47ab-a617-abb324110492)]
17
interface nsINavBookmarkObserver : nsISupports
18
{
19
/*
20
* This observer should not be called for items that are tags.
21
*/
22
readonly attribute boolean skipTags;
23
24
/**
25
* Notifies that a batch transaction has started.
26
* Other notifications will be sent during the batch, but the observer is
27
* guaranteed that onEndUpdateBatch() will be called at its completion.
28
* During a batch the observer should do its best to reduce the work done to
29
* handle notifications, since multiple changes are going to happen in a short
30
* timeframe.
31
*/
32
void onBeginUpdateBatch();
33
34
/**
35
* Notifies that a batch transaction has ended.
36
*/
37
void onEndUpdateBatch();
38
39
/**
40
* Notifies that an item's information has changed. This will be called
41
* whenever any attributes like "title" are changed.
42
*
43
* @param aItemId
44
* The id of the item that was changed.
45
* @param aProperty
46
* The property which changed.
47
* @param aIsAnnotationProperty
48
* Obsolete and unused.
49
* @param aNewValue
50
* For certain properties, this is set to the new value of the
51
* property (see the list below).
52
* @param aLastModified
53
* The updated last-modified value.
54
* @param aItemType
55
* The type of the item to be removed (see TYPE_* constants below).
56
* @param aParentId
57
* The id of the folder containing the item.
58
* @param aGuid
59
* The unique ID associated with the item.
60
* @param aParentGuid
61
* The unique ID associated with the item's parent.
62
* @param aOldValue
63
* For certain properties, this is set to the new value of the
64
* property (see the list below).
65
* @param aSource
66
* A change source constant from nsINavBookmarksService::SOURCE_*,
67
* passed to the method that notifies the observer.
68
*
69
* @note List of values that may be associated with properties:
70
* aProperty | aNewValue
71
* =====================================================================
72
* guid | The new bookmark guid.
73
* cleartime | Empty string (all visits to this item were removed).
74
* title | The new title.
75
* favicon | The "moz-anno" URL of the new favicon.
76
* uri | new URL.
77
* tags | Empty string (tags for this item changed)
78
* dateAdded | PRTime (as string) when the item was first added.
79
* lastModified | PRTime (as string) when the item was last modified.
80
*
81
* aProperty | aOldValue
82
* =====================================================================
83
* guid | The old bookmark guid.
84
* cleartime | Empty string (currently unused).
85
* title | Empty string (currently unused).
86
* favicon | Empty string (currently unused).
87
* uri | old URL.
88
* tags | Empty string (currently unused).
89
* dateAdded | Empty string (currently unused).
90
* lastModified | Empty string (currently unused).
91
*/
92
void onItemChanged(in long long aItemId,
93
in ACString aProperty,
94
in boolean aIsAnnotationProperty,
95
in AUTF8String aNewValue,
96
in PRTime aLastModified,
97
in unsigned short aItemType,
98
in long long aParentId,
99
in ACString aGuid,
100
in ACString aParentGuid,
101
in AUTF8String aOldValue,
102
in unsigned short aSource);
103
104
/**
105
* Notifies that the item was visited. Can be invoked only for TYPE_BOOKMARK
106
* items.
107
*
108
* @param aItemId
109
* The id of the bookmark that was visited.
110
* @param aVisitId
111
* The id of the visit.
112
* @param aTime
113
* The time of the visit.
114
* @param aTransitionType
115
* The transition for the visit. See nsINavHistoryService::TRANSITION_*
116
* constants for a list of possible values.
117
* @param aURI
118
* The nsIURI for this bookmark.
119
* @param aParentId
120
* The id of the folder containing the item.
121
* @param aGuid
122
* The unique ID associated with the item.
123
* @param aParentGuid
124
* The unique ID associated with the item's parent.
125
*
126
* @see onItemChanged with property = "cleartime" for when all visits to an
127
* item are removed.
128
*
129
* @note The reported time is the time of the visit that was added, which may
130
* be well in the past since the visit time can be specified. This
131
* means that the visit the observer is told about may not be the most
132
* recent visit for that page.
133
*/
134
void onItemVisited(in long long aItemId,
135
in long long aVisitId,
136
in PRTime aTime,
137
in unsigned long aTransitionType,
138
in nsIURI aURI,
139
in long long aParentId,
140
in ACString aGuid,
141
in ACString aParentGuid);
142
143
/**
144
* Notifies that an item has been moved.
145
*
146
* @param aItemId
147
* The id of the item that was moved.
148
* @param aOldParentId
149
* The id of the old parent.
150
* @param aOldIndex
151
* The old index inside the old parent.
152
* @param aNewParentId
153
* The id of the new parent.
154
* @param aNewIndex
155
* The index inside the new parent.
156
* @param aItemType
157
* The type of the item to be removed (see TYPE_* constants below).
158
* @param aGuid
159
* The unique ID associated with the item.
160
* @param aOldParentGuid
161
* The unique ID associated with the old item's parent.
162
* @param aNewParentGuid
163
* The unique ID associated with the new item's parent.
164
* @param aSource
165
* A change source constant from nsINavBookmarksService::SOURCE_*,
166
* passed to the method that notifies the observer.
167
* @param aURI
168
* The URI for this bookmark.
169
*/
170
void onItemMoved(in long long aItemId,
171
in long long aOldParentId,
172
in long aOldIndex,
173
in long long aNewParentId,
174
in long aNewIndex,
175
in unsigned short aItemType,
176
in ACString aGuid,
177
in ACString aOldParentGuid,
178
in ACString aNewParentGuid,
179
in unsigned short aSource,
180
in AUTF8String aURI);
181
};
182
183
/**
184
* The BookmarksService interface provides methods for managing bookmarked
185
* history items. Bookmarks consist of a set of user-customizable
186
* folders. A URI in history can be contained in one or more such folders.
187
*/
188
189
[scriptable, uuid(24533891-afa6-4663-b72d-3143d03f1b04)]
190
interface nsINavBookmarksService : nsISupports
191
{
192
/**
193
* The item ID of the Places root.
194
*/
195
readonly attribute long long placesRoot;
196
197
/**
198
* The item ID of the bookmarks menu folder.
199
*/
200
readonly attribute long long bookmarksMenuFolder;
201
202
/**
203
* The item ID of the top-level folder that contain the tag "folders".
204
*/
205
readonly attribute long long tagsFolder;
206
207
/**
208
* The item ID of the personal toolbar folder.
209
*/
210
readonly attribute long long toolbarFolder;
211
212
/**
213
* The total number of Sync changes (inserts, updates, deletes, merges, and
214
* uploads) recorded since Places startup for all bookmarks.
215
*
216
* Note that this is *not* the number of bookmark syncs. It's a monotonically
217
* increasing counter incremented for every change that affects a bookmark's
218
* `syncChangeCounter`.
219
*
220
* The counter can be used to avoid keeping an exclusive transaction open for
221
* time-consuming work. One way to do that is to store the current value of
222
* the counter, do the work, start a transaction, check the current value
223
* again, and compare it to the stored value to determine if the database
224
* changed during the work.
225
*
226
* The bookmarks mirror does this to check for changes between building and
227
* applying a merged tree. This avoids blocking the main Places connection
228
* during the merge, and ensures that the new tree still applies cleanly.
229
*/
230
readonly attribute long long totalSyncChanges;
231
232
/**
233
* This value should be used for APIs that allow passing in an index
234
* where an index is not known, or not required to be specified.
235
* e.g.: When appending an item to a folder.
236
*/
237
const short DEFAULT_INDEX = -1;
238
239
const unsigned short TYPE_BOOKMARK = 1;
240
const unsigned short TYPE_FOLDER = 2;
241
const unsigned short TYPE_SEPARATOR = 3;
242
// Dynamic containers are deprecated and unsupported.
243
// This const exists just to avoid reusing the value.
244
const unsigned short TYPE_DYNAMIC_CONTAINER = 4;
245
246
// Change source constants. These are used to distinguish changes made by
247
// Sync and bookmarks import from other Places consumers, though they can
248
// be extended to support other callers. Sources are passed as optional
249
// parameters to methods used by Sync, and forwarded to observers.
250
const unsigned short SOURCE_DEFAULT = 0;
251
const unsigned short SOURCE_SYNC = 1;
252
const unsigned short SOURCE_IMPORT = 2;
253
const unsigned short SOURCE_SYNC_REPARENT_REMOVED_FOLDER_CHILDREN = 4;
254
const unsigned short SOURCE_RESTORE = 5;
255
const unsigned short SOURCE_RESTORE_ON_STARTUP = 6;
256
257
/**
258
* Sync status flags, stored in Places for each item. These affect conflict
259
* resolution, when an item is changed both locally and remotely; deduping,
260
* when a local item matches a remote item with similar contents and different
261
* GUIDs; and whether we write a tombstone when an item is deleted locally.
262
*
263
* Status | Description | Conflict | Can | Needs
264
* | | resolution | dedupe? | tombstone?
265
* -----------------------------------------------------------------------
266
* UNKNOWN | Automatically restored | Prefer | No | No
267
* | on startup to recover | deletion | |
268
* | from database corruption, | | |
269
* | or sync ID change on | | |
270
* | server. | | |
271
* -----------------------------------------------------------------------
272
* NEW | Item not uploaded to | Prefer | Yes | No
273
* | server yet, or Sync | newer | |
274
* | disconnected. | | |
275
* -----------------------------------------------------------------------
276
* NORMAL | Item uploaded to server. | Prefer | No | Yes
277
* | | newer | |
278
*/
279
const unsigned short SYNC_STATUS_UNKNOWN = 0;
280
const unsigned short SYNC_STATUS_NEW = 1;
281
const unsigned short SYNC_STATUS_NORMAL = 2;
282
283
/**
284
* Inserts a child bookmark into the given folder.
285
*
286
* @param aParentId
287
* The id of the parent folder
288
* @param aURI
289
* The URI to insert
290
* @param aIndex
291
* The index to insert at, or DEFAULT_INDEX to append
292
* @param aTitle
293
* The title for the new bookmark
294
* @param [optional] aGuid
295
* The GUID to be set for the new item. If not set, a new GUID is
296
* generated. Unless you've a very sound reason, such as an undo
297
* manager implementation, do not pass this argument.
298
* @param [optional] aSource
299
* The change source. This is forwarded to all bookmark observers,
300
* allowing them to distinguish between insertions from different
301
* callers. Defaults to SOURCE_DEFAULT if omitted.
302
* @return The ID of the newly-created bookmark.
303
*
304
* @note aTitle will be truncated to TITLE_LENGTH_MAX and
305
* aURI will be truncated to URI_LENGTH_MAX.
306
* @throws if aGuid is malformed.
307
*/
308
[can_run_script]
309
long long insertBookmark(in long long aParentId, in nsIURI aURI,
310
in long aIndex, in AUTF8String aTitle,
311
[optional] in ACString aGuid,
312
[optional] in unsigned short aSource);
313
314
/**
315
* Removes a child item. Used to delete a bookmark or separator.
316
* @param aItemId
317
* The child item to remove
318
* @param [optional] aSource
319
* The change source, forwarded to all bookmark observers. Defaults
320
* to SOURCE_DEFAULT.
321
*/
322
[can_run_script]
323
void removeItem(in long long aItemId, [optional] in unsigned short aSource);
324
325
/**
326
* Creates a new child folder and inserts it under the given parent.
327
* @param aParentFolder
328
* The id of the parent folder
329
* @param aName
330
* The name of the new folder
331
* @param aIndex
332
* The index to insert at, or DEFAULT_INDEX to append
333
* @param [optional] aGuid
334
* The GUID to be set for the new item. If not set, a new GUID is
335
* generated. Unless you've a very sound reason, such as an undo
336
* manager implementation, do not pass this argument.
337
* @param [optional] aSource
338
* The change source, forwarded to all bookmark observers. Defaults
339
* to SOURCE_DEFAULT.
340
* @return The ID of the newly-inserted folder.
341
* @throws if aGuid is malformed.
342
*/
343
[can_run_script]
344
long long createFolder(in long long aParentFolder, in AUTF8String name,
345
in long index,
346
[optional] in ACString aGuid,
347
[optional] in unsigned short aSource);
348
349
/**
350
* Set the title for an item.
351
* @param aItemId
352
* The id of the item whose title should be updated.
353
* @param aTitle
354
* The new title for the bookmark.
355
* @param [optional] aSource
356
* The change source, forwarded to all bookmark observers. Defaults
357
* to SOURCE_DEFAULT.
358
*
359
* @note aTitle will be truncated to TITLE_LENGTH_MAX.
360
*/
361
void setItemTitle(in long long aItemId, in AUTF8String aTitle,
362
[optional] in unsigned short aSource);
363
364
/**
365
* Get the title for an item.
366
*
367
* If no item title is available it will return a void string (null in JS).
368
*
369
* @param aItemId
370
* The id of the item whose title should be retrieved
371
* @return The title of the item.
372
*/
373
AUTF8String getItemTitle(in long long aItemId);
374
375
/**
376
* Set the last modified time for an item.
377
*
378
* @param aItemId
379
* the id of the item whose last modified time should be updated.
380
* @param aLastModified
381
* the new last modified value in microseconds. Note that it is
382
* rounded down to milliseconds precision.
383
* @param [optional] aSource
384
* The change source, forwarded to all bookmark observers. Defaults
385
* to SOURCE_DEFAULT.
386
*
387
* @note This is the only method that will send an itemChanged notification
388
* for the property. lastModified will still be updated in
389
* any other method that changes an item property, but we will send
390
* the corresponding itemChanged notification instead.
391
*/
392
void setItemLastModified(in long long aItemId,
393
in PRTime aLastModified,
394
[optional] in unsigned short aSource);
395
396
/**
397
* Get the parent folder's id for an item.
398
*/
399
long long getFolderIdForItem(in long long aItemId);
400
401
/**
402
* Adds a bookmark observer. If ownsWeak is false, the bookmark service will
403
* keep an owning reference to the observer. If ownsWeak is true, then
404
* aObserver must implement nsISupportsWeakReference, and the bookmark
405
* service will keep a weak reference to the observer.
406
*/
407
void addObserver(in nsINavBookmarkObserver observer,
408
[optional] in boolean ownsWeak);
409
410
/**
411
* Removes a bookmark observer.
412
*/
413
void removeObserver(in nsINavBookmarkObserver observer);
414
415
/**
416
* Gets an array of registered nsINavBookmarkObserver objects.
417
*/
418
Array<nsINavBookmarkObserver> getObservers();
419
};