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
/**
7
* Using Places services after quit-application is not reliable, so make
8
* sure to do any shutdown work on quit-application, or history
9
* synchronization could fail, losing latest changes.
10
*/
11
12
#include "nsISupports.idl"
13
14
interface nsIArray;
15
interface nsIFile;
16
interface nsIObserver;
17
interface nsIVariant;
18
interface nsIURI;
19
20
interface mozIStorageConnection;
21
interface mozIStorageStatementCallback;
22
interface mozIStoragePendingStatement;
23
interface nsIAsyncShutdownClient;
24
25
interface nsINavHistoryContainerResultNode;
26
interface nsINavHistoryQueryResultNode;
27
interface nsINavHistoryQuery;
28
interface nsINavHistoryQueryOptions;
29
interface nsINavHistoryResult;
30
interface nsINavHistoryBatchCallback;
31
32
[scriptable, uuid(91d104bb-17ef-404b-9f9a-d9ed8de6824c)]
33
interface nsINavHistoryResultNode : nsISupports
34
{
35
/**
36
* Indentifies the parent result node in the result set. This is null for
37
* top level nodes.
38
*/
39
readonly attribute nsINavHistoryContainerResultNode parent;
40
41
/**
42
* The history-result to which this node belongs.
43
*/
44
readonly attribute nsINavHistoryResult parentResult;
45
46
/**
47
* URI of the resource in question. For visits and URLs, this is the URL of
48
* the page. For folders and queries, this is the place: URI of the
49
* corresponding folder or query. This may be empty for other types of
50
* objects like host containers.
51
*/
52
readonly attribute AUTF8String uri;
53
54
/**
55
* Identifies the type of this node. This node can then be QI-ed to the
56
* corresponding specialized result node interface.
57
*/
58
const unsigned long RESULT_TYPE_URI = 0; // nsINavHistoryResultNode
59
60
// Visit nodes are deprecated and unsupported.
61
// This line exists just to avoid reusing the value:
62
// const unsigned long RESULT_TYPE_VISIT = 1;
63
64
// Full visit nodes are deprecated and unsupported.
65
// This line exists just to avoid reusing the value:
66
// const unsigned long RESULT_TYPE_FULL_VISIT = 2;
67
68
// Dynamic containers are deprecated and unsupported.
69
// This const exists just to avoid reusing the value:
70
// const unsigned long RESULT_TYPE_DYNAMIC_CONTAINER = 4; // nsINavHistoryContainerResultNode
71
72
const unsigned long RESULT_TYPE_QUERY = 5; // nsINavHistoryQueryResultNode
73
const unsigned long RESULT_TYPE_FOLDER = 6; // nsINavHistoryQueryResultNode
74
const unsigned long RESULT_TYPE_SEPARATOR = 7; // nsINavHistoryResultNode
75
const unsigned long RESULT_TYPE_FOLDER_SHORTCUT = 9; // nsINavHistoryQueryResultNode
76
readonly attribute unsigned long type;
77
78
/**
79
* Title of the web page, or of the node's query (day, host, folder, etc)
80
*/
81
readonly attribute AUTF8String title;
82
83
/**
84
* Total number of times the URI has ever been accessed. For hosts, this
85
* is the total of the children under it, NOT the total times the host has
86
* been accessed (this would require an additional query, so is not given
87
* by default when most of the time it is never needed).
88
*/
89
readonly attribute unsigned long accessCount;
90
91
/**
92
* This is the time the user accessed the page.
93
*
94
* If this is a visit, it is the exact time that the page visit occurred.
95
*
96
* If this is a URI, it is the most recent time that the URI was visited.
97
* Even if you ask for all URIs for a given date range long ago, this might
98
* contain today's date if the URI was visited today.
99
*
100
* For hosts, or other node types with children, this is the most recent
101
* access time for any of the children.
102
*
103
* For days queries this is the respective endTime - a maximum possible
104
* visit time to fit in the day range.
105
*/
106
readonly attribute PRTime time;
107
108
/**
109
* This URI can be used as an image source URI and will give you the favicon
110
* for the page. It is *not* the URI of the favicon, but rather something
111
* that will resolve to the actual image.
112
*
113
* In most cases, this is an annotation URI that will query the favicon
114
* service. If the entry has no favicon, this is the chrome URI of the
115
* default favicon. If the favicon originally lived in chrome, this will
116
* be the original chrome URI of the icon.
117
*/
118
readonly attribute AUTF8String icon;
119
120
/**
121
* This is the number of levels between this node and the top of the
122
* hierarchy. The members of result.children have indentLevel = 0, their
123
* children have indentLevel = 1, etc. The indent level of the root node is
124
* set to -1.
125
*/
126
readonly attribute long indentLevel;
127
128
/**
129
* When this item is in a bookmark folder (parent is of type folder), this is
130
* the index into that folder of this node. These indices start at 0 and
131
* increase in the order that they appear in the bookmark folder. For items
132
* that are not in a bookmark folder, this value is -1.
133
*/
134
readonly attribute long bookmarkIndex;
135
136
/**
137
* If the node is an item (bookmark, folder or a separator) this value is the
138
* row ID of that bookmark in the database. For other nodes, this value is
139
* set to -1.
140
*/
141
readonly attribute long long itemId;
142
143
/**
144
* If the node is an item (bookmark, folder or a separator) this value is the
145
* time that the item was created. For other nodes, this value is 0.
146
*/
147
readonly attribute PRTime dateAdded;
148
149
/**
150
* If the node is an item (bookmark, folder or a separator) this value is the
151
* time that the item was last modified. For other nodes, this value is 0.
152
*
153
* @note When an item is added lastModified is set to the same value as
154
* dateAdded.
155
*/
156
readonly attribute PRTime lastModified;
157
158
/**
159
* For uri nodes, this is a sorted list of the tags, delimited with commans,
160
* for the uri represented by this node. Otherwise this is an empty string.
161
*/
162
readonly attribute AString tags;
163
164
/**
165
* The unique ID associated with the page. It my return an empty string
166
* if the result node is a non-URI node.
167
*/
168
readonly attribute ACString pageGuid;
169
170
/**
171
* The unique ID associated with the bookmark. It returns an empty string
172
* if the result node is not associated with a bookmark, a folder or a
173
* separator.
174
*/
175
readonly attribute ACString bookmarkGuid;
176
177
/**
178
* The unique ID associated with the history visit. For node types other than
179
* history visit nodes, this value is -1.
180
*/
181
readonly attribute long long visitId;
182
183
/**
184
* The unique ID associated with visit node which was the referrer of this
185
* history visit. For node types other than history visit nodes, or visits
186
* without any known referrer, this value is -1.
187
*/
188
readonly attribute long long fromVisitId;
189
190
/**
191
* The transition type associated with this visit. For node types other than
192
* history visit nodes, this value is 0.
193
*/
194
readonly attribute unsigned long visitType;
195
};
196
197
198
/**
199
* Base class for container results. This includes all types of groupings.
200
* Bookmark folders and places queries will be QueryResultNodes which extends
201
* these items.
202
*/
203
[scriptable, uuid(3E9CC95F-0D93-45F1-894F-908EEB9866D7)]
204
interface nsINavHistoryContainerResultNode : nsINavHistoryResultNode
205
{
206
207
/**
208
* Set this to allow descent into the container. When closed, attempting
209
* to call getChildren or childCount will result in an error. You should
210
* set this to false when you are done reading.
211
*
212
* For HOST and DAY groupings, doing this is free since the children have
213
* been precomputed. For queries and bookmark folders, being open means they
214
* will keep themselves up-to-date by listening for updates and re-querying
215
* as needed.
216
*/
217
attribute boolean containerOpen;
218
219
/**
220
* Indicates whether the container is closed, loading, or opened. Loading
221
* implies that the container has been opened asynchronously and has not yet
222
* fully opened.
223
*/
224
readonly attribute unsigned short state;
225
const unsigned short STATE_CLOSED = 0;
226
const unsigned short STATE_LOADING = 1;
227
const unsigned short STATE_OPENED = 2;
228
229
/**
230
* This indicates whether this node "may" have children, and can be used
231
* when the container is open or closed. When the container is closed, it
232
* will give you an exact answer if the node can easily be populated (for
233
* example, a bookmark folder). If not (for example, a complex history query),
234
* it will return true. When the container is open, it will always be
235
* accurate. It is intended to be used to see if we should draw the "+" next
236
* to a tree item.
237
*/
238
readonly attribute boolean hasChildren;
239
240
/**
241
* This gives you the children of the nodes. It is preferrable to use this
242
* interface over the array one, since it avoids creating an nsIArray object
243
* and the interface is already the correct type.
244
*
245
* @throws NS_ERROR_NOT_AVAILABLE if containerOpen is false.
246
*/
247
readonly attribute unsigned long childCount;
248
nsINavHistoryResultNode getChild(in unsigned long aIndex);
249
250
/**
251
* Get the index of a direct child in this container.
252
*
253
* @param aNode
254
* a result node.
255
*
256
* @return aNode's index in this container.
257
* @throws NS_ERROR_NOT_AVAILABLE if containerOpen is false.
258
* @throws NS_ERROR_INVALID_ARG if aNode isn't a direct child of this
259
* container.
260
*/
261
unsigned long getChildIndex(in nsINavHistoryResultNode aNode);
262
};
263
264
265
/**
266
* Used for places queries and as a base for bookmark folders.
267
*
268
* Note that if you request places to *not* be expanded in the options that
269
* generated this node, this item will report it has no children and never try
270
* to populate itself.
271
*/
272
[scriptable, uuid(62817759-4FEE-44A3-B58C-3E2F5AFC9D0A)]
273
interface nsINavHistoryQueryResultNode : nsINavHistoryContainerResultNode
274
{
275
/**
276
* Get the query which builds this node's children.
277
* Only valid for RESULT_TYPE_QUERY nodes.
278
*/
279
readonly attribute nsINavHistoryQuery query;
280
281
/**
282
* Get the options which group this node's children.
283
* Only valid for RESULT_TYPE_QUERY nodes.
284
*/
285
readonly attribute nsINavHistoryQueryOptions queryOptions;
286
287
/**
288
* For both simple folder queries and folder shortcut queries, this is set to
289
* the concrete itemId of the folder (i.e. for folder shortcuts it's the
290
* target folder id). Otherwise, this is set to -1.
291
*/
292
readonly attribute long long folderItemId;
293
294
/**
295
* For both simple folder queries and folder shortcut queries, this is set to
296
* the concrete guid of the folder (i.e. for folder shortcuts it's the target
297
* folder guid). Otherwise, this is set to an empty string.
298
*/
299
readonly attribute ACString targetFolderGuid;
300
};
301
302
303
/**
304
* Allows clients to observe what is happening to a result as it updates itself
305
* according to history and bookmark system events. Register this observer on a
306
* result using nsINavHistoryResult::addObserver.
307
*/
308
[scriptable, uuid(f62d8b6b-3c4e-4a9f-a897-db605d0b7a0f)]
309
interface nsINavHistoryResultObserver : nsISupports
310
{
311
/**
312
* Called when 'aItem' is inserted into 'aParent' at index 'aNewIndex'.
313
* The item previously at index (if any) and everything below it will have
314
* been shifted down by one. The item may be a container or a leaf.
315
*/
316
void nodeInserted(in nsINavHistoryContainerResultNode aParent,
317
in nsINavHistoryResultNode aNode,
318
in unsigned long aNewIndex);
319
320
/**
321
* Called whan 'aItem' is removed from 'aParent' at 'aOldIndex'. The item
322
* may be a container or a leaf. This function will be called after the item
323
* has been removed from its parent list, but before anything else (including
324
* NULLing out the item's parent) has happened.
325
*/
326
void nodeRemoved(in nsINavHistoryContainerResultNode aParent,
327
in nsINavHistoryResultNode aItem,
328
in unsigned long aOldIndex);
329
330
/**
331
* Called whan 'aItem' is moved from 'aOldParent' at 'aOldIndex' to
332
* aNewParent at aNewIndex. The item may be a container or a leaf.
333
*
334
* XXX: at the moment, this method is called only when an item is moved
335
* within the same container. When an item is moved between containers,
336
* a new node is created for the item, and the itemRemoved/itemAdded methods
337
* are used.
338
*/
339
void nodeMoved(in nsINavHistoryResultNode aNode,
340
in nsINavHistoryContainerResultNode aOldParent,
341
in unsigned long aOldIndex,
342
in nsINavHistoryContainerResultNode aNewParent,
343
in unsigned long aNewIndex);
344
345
/**
346
* Called right after aNode's title has changed.
347
*
348
* @param aNode
349
* a result node
350
* @param aNewTitle
351
* the new title
352
*/
353
void nodeTitleChanged(in nsINavHistoryResultNode aNode,
354
in AUTF8String aNewTitle);
355
356
/**
357
* Called right after aNode's uri property has changed.
358
*
359
* @param aNode
360
* a result node
361
* @param aNewURI
362
* the old uri
363
*/
364
void nodeURIChanged(in nsINavHistoryResultNode aNode,
365
in AUTF8String aOldURI);
366
367
/**
368
* Called right after aNode's icon property has changed.
369
*
370
* @param aNode
371
* a result node
372
*
373
* @note: The new icon is accessible through aNode.icon.
374
*/
375
void nodeIconChanged(in nsINavHistoryResultNode aNode);
376
377
/**
378
* Called right after aNode's time property or accessCount property, or both,
379
* have changed.
380
*
381
* @param aNode
382
* a uri result node
383
* @param aOldVisitDate
384
* the old visit date
385
* @param aOldAccessCount
386
* the old access-count
387
*/
388
void nodeHistoryDetailsChanged(in nsINavHistoryResultNode aNode,
389
in PRTime aOldVisitDate,
390
in unsigned long aOldAccessCount);
391
392
/**
393
* Called when the tags set on the uri represented by aNode have changed.
394
*
395
* @param aNode
396
* a uri result node
397
*
398
* @note: The new tags list is accessible through aNode.tags.
399
*/
400
void nodeTagsChanged(in nsINavHistoryResultNode aNode);
401
402
/**
403
* Called right after the aNode's keyword property has changed.
404
*
405
* @param aNode
406
* a uri result node
407
* @param aNewKeyword
408
* the new keyword
409
*/
410
void nodeKeywordChanged(in nsINavHistoryResultNode aNode,
411
in AUTF8String aNewKeyword);
412
413
/**
414
* Called right after aNode's dateAdded property has changed.
415
*
416
* @param aNode
417
* a result node
418
* @param aNewValue
419
* the new value of the dateAdded property
420
*/
421
void nodeDateAddedChanged(in nsINavHistoryResultNode aNode,
422
in PRTime aNewValue);
423
424
/**
425
* Called right after aNode's dateModified property has changed.
426
*
427
* @param aNode
428
* a result node
429
* @param aNewValue
430
* the new value of the dateModified property
431
*/
432
void nodeLastModifiedChanged(in nsINavHistoryResultNode aNode,
433
in PRTime aNewValue);
434
435
/**
436
* Called after a container changes state.
437
*
438
* @param aContainerNode
439
* The container that has changed state.
440
* @param aOldState
441
* The state that aContainerNode has transitioned out of.
442
* @param aNewState
443
* The state that aContainerNode has transitioned into.
444
*/
445
void containerStateChanged(in nsINavHistoryContainerResultNode aContainerNode,
446
in unsigned long aOldState,
447
in unsigned long aNewState);
448
449
/**
450
* Called when something significant has happened within the container. The
451
* contents of the container should be re-built.
452
*
453
* @param aContainerNode
454
* the container node to invalidate
455
*/
456
void invalidateContainer(in nsINavHistoryContainerResultNode aContainerNode);
457
458
/**
459
* This is called to indicate to the UI that the sort has changed to the
460
* given mode. For trees, for example, this would update the column headers
461
* to reflect the sorting. For many other types of views, this won't be
462
* applicable.
463
*
464
* @param sortingMode One of nsINavHistoryQueryOptions.SORT_BY_* that
465
* indicates the new sorting mode.
466
*
467
* This only is expected to update the sorting UI. invalidateAll() will also
468
* get called if the sorting changes to update everything.
469
*/
470
void sortingChanged(in unsigned short sortingMode);
471
472
/**
473
* This is called to indicate that a batch operation is about to start or end.
474
* The observer could want to disable some events or updates during batches,
475
* since multiple operations are packed in a short time.
476
* For example treeviews could temporarily suppress select notifications.
477
*
478
* @param aToggleMode
479
* true if a batch is starting, false if it's ending.
480
*/
481
void batching(in boolean aToggleMode);
482
483
/**
484
* Called by the result when this observer is added.
485
*/
486
attribute nsINavHistoryResult result;
487
};
488
489
490
/**
491
* The result of a history/bookmark query.
492
*/
493
[scriptable, uuid(c2229ce3-2159-4001-859c-7013c52f7619)]
494
interface nsINavHistoryResult : nsISupports
495
{
496
/**
497
* Sorts all nodes recursively by the given parameter, one of
498
* nsINavHistoryQueryOptions.SORT_BY_* This will update the corresponding
499
* options for this result, so that re-using the current options/queries will
500
* always give you the current view.
501
*/
502
attribute unsigned short sortingMode;
503
504
/**
505
* Whether or not notifications on result changes are suppressed.
506
* Initially set to false.
507
*
508
* Use this to avoid flickering and to improve performance when you
509
* do temporary changes to the result structure (e.g. when searching for a
510
* node recursively).
511
*/
512
attribute boolean suppressNotifications;
513
514
/**
515
* Adds an observer for changes done in the result.
516
*
517
* @param aObserver
518
* a result observer.
519
* @param aOwnsWeak
520
* If false, the result will keep an owning reference to the observer,
521
* which must be removed using removeObserver.
522
* If true, the result will keep a weak reference to the observer, which
523
* must implement nsISupportsWeakReference.
524
*
525
* @see nsINavHistoryResultObserver
526
*/
527
void addObserver(in nsINavHistoryResultObserver aObserver,
528
[optional] in boolean aOwnsWeak);
529
530
/**
531
* Removes an observer that was added by addObserver.
532
*
533
* @param aObserver
534
* a result observer that was added by addObserver.
535
*/
536
void removeObserver(in nsINavHistoryResultObserver aObserver);
537
538
/**
539
* This is the root of the results. Remember that you need to open all
540
* containers for their contents to be valid.
541
*
542
* When a result goes out of scope it will continue to observe changes till
543
* it is cycle collected. While the result waits to be collected it will stay
544
* in memory, and continue to update itself, potentially causing unwanted
545
* additional work. When you close the root node the result will stop
546
* observing changes, so it is good practice to close the root node when you
547
* are done with a result, since that will avoid unwanted performance hits.
548
*/
549
readonly attribute nsINavHistoryContainerResultNode root;
550
};
551
552
553
/**
554
* DANGER! If you are in the middle of a batch transaction, there may be a
555
* database transaction active. You can still access the DB, but be careful.
556
*/
557
[scriptable, uuid(0f0f45b0-13a1-44ae-a0ab-c6046ec6d4da)]
558
interface nsINavHistoryObserver : nsISupports
559
{
560
/**
561
* Notifies you that a bunch of things are about to change, don't do any
562
* heavy-duty processing until onEndUpdateBatch is called.
563
*/
564
void onBeginUpdateBatch();
565
566
/**
567
* Notifies you that we are done doing a bunch of things and you should go
568
* ahead and update UI, etc.
569
*/
570
void onEndUpdateBatch();
571
572
/**
573
* Called whenever either the "real" title or the custom title of the page
574
* changed. BOTH TITLES ARE ALWAYS INCLUDED in this notification, even though
575
* only one will change at a time. Often, consumers will want to display the
576
* user title if it is available, and fall back to the page title (the one
577
* specified in the <title> tag of the page).
578
*
579
* Note that there is a difference between an empty title and a NULL title.
580
* An empty string means that somebody specifically set the title to be
581
* nothing. NULL means nobody set it. From C++: use IsVoid() and SetIsVoid()
582
* to see whether an empty string is "null" or not (it will always be an
583
* empty string in either case).
584
*
585
* @param aURI
586
* The URI of the page.
587
* @param aPageTitle
588
* The new title of the page.
589
* @param aGUID
590
* The unique ID associated with the page.
591
*/
592
void onTitleChanged(in nsIURI aURI,
593
in AString aPageTitle,
594
in ACString aGUID);
595
596
/**
597
* Called when an individual page's frecency has changed.
598
*
599
* This is not called for pages whose frecencies change as the result of some
600
* large operation where some large or unknown number of frecencies change at
601
* once. Use onManyFrecenciesChanged to detect such changes.
602
*
603
* @param aURI
604
* The page's URI.
605
* @param aNewFrecency
606
* The page's new frecency.
607
* @param aGUID
608
* The page's GUID.
609
* @param aHidden
610
* True if the page is marked as hidden.
611
* @param aVisitDate
612
* The page's last visit date.
613
*/
614
void onFrecencyChanged(in nsIURI aURI,
615
in long aNewFrecency,
616
in ACString aGUID,
617
in boolean aHidden,
618
in PRTime aVisitDate);
619
620
/**
621
* Called when the frecencies of many pages have changed at once.
622
*
623
* onFrecencyChanged is not called for each of those pages.
624
*/
625
void onManyFrecenciesChanged();
626
627
/**
628
* Removed by the user.
629
*/
630
const unsigned short REASON_DELETED = 0;
631
/**
632
* Removed by automatic expiration.
633
*/
634
const unsigned short REASON_EXPIRED = 1;
635
636
/**
637
* This page and all of its visits are being deleted. Note: the page may not
638
* necessarily have actually existed for this function to be called.
639
*
640
* Delete notifications are only 99.99% accurate. Batch delete operations
641
* must be done in two steps, so first come notifications, then a bulk
642
* delete. If there is some error in the middle (for example, out of memory)
643
* then you'll get a notification and it won't get deleted. There's no easy
644
* way around this.
645
*
646
* @param aURI
647
* The URI that was deleted.
648
* @param aGUID
649
* The unique ID associated with the page.
650
* @param aReason
651
* Indicates the reason for the removal. see REASON_* constants.
652
*/
653
void onDeleteURI(in nsIURI aURI,
654
in ACString aGUID,
655
in unsigned short aReason);
656
657
/**
658
* Notification that all of history is being deleted.
659
*/
660
void onClearHistory();
661
662
/**
663
* onPageChanged attribute indicating that favicon has been updated.
664
* aNewValue parameter will be set to the new favicon URI string.
665
*/
666
const unsigned long ATTRIBUTE_FAVICON = 3;
667
668
/**
669
* An attribute of this page changed.
670
*
671
* @param aURI
672
* The URI of the page on which an attribute changed.
673
* @param aChangedAttribute
674
* The attribute whose value changed. See ATTRIBUTE_* constants.
675
* @param aNewValue
676
* The attribute's new value.
677
* @param aGUID
678
* The unique ID associated with the page.
679
*/
680
void onPageChanged(in nsIURI aURI,
681
in unsigned long aChangedAttribute,
682
in AString aNewValue,
683
in ACString aGUID);
684
685
/**
686
* Called when some visits of an history entry are expired.
687
*
688
* @param aURI
689
* The page whose visits have been expired.
690
* @param aPartialRemoval
691
* Set to true if only some of the visits for the page have been removed.
692
* @param aGUID
693
* The unique ID associated with the page.
694
*
695
* @note: when all visits for a page are expired and also the full page entry
696
* is expired, you will only get an onDeleteURI notification. If a
697
* page entry is removed, then you can be sure that we don't have
698
* anymore visits for it.
699
* @param aReason
700
* Indicates the reason for the removal. see REASON_* constants.
701
* @param aTransitionType
702
* If it's a valid TRANSITION_* value, all visits of the specified type
703
* have been removed.
704
*/
705
void onDeleteVisits(in nsIURI aURI,
706
in boolean aPartialRemoval,
707
in ACString aGUID,
708
in unsigned short aReason,
709
in unsigned long aTransitionType);
710
};
711
712
713
/**
714
* This object encapsulates all the query parameters you're likely to need
715
* when building up history UI. All parameters are ANDed together.
716
*
717
* This is not intended to be a super-general query mechanism. This was designed
718
* so that most queries can be done in only one SQL query. This is important
719
* because, if the user has their profile on a networked drive, query latency
720
* can be non-negligible.
721
*/
722
723
[scriptable, uuid(dc87ae79-22f1-4dcf-975b-852b01d210cb)]
724
interface nsINavHistoryQuery : nsISupports
725
{
726
/**
727
* Time range for results (INCLUSIVE). The *TimeReference is one of the
728
* constants TIME_RELATIVE_* which indicates how to interpret the
729
* corresponding time value.
730
* TIME_RELATIVE_EPOCH (default):
731
* The time is relative to Jan 1 1970 GMT, (this is a normal PRTime)
732
* TIME_RELATIVE_TODAY:
733
* The time is relative to this morning at midnight. Normally used for
734
* queries relative to today. For example, a "past week" query would be
735
* today-6 days -> today+1 day
736
* TIME_RELATIVE_NOW:
737
* The time is relative to right now.
738
*
739
* Note: PRTime is in MICROseconds since 1 Jan 1970. Javascript date objects
740
* are expressed in MILLIseconds since 1 Jan 1970.
741
*
742
* As a special case, a 0 time relative to TIME_RELATIVE_EPOCH indicates that
743
* the time is not part of the query. This is the default, so an empty query
744
* will match any time. The has* functions return whether the corresponding
745
* time is considered.
746
*
747
* You can read absolute*Time to get the time value that the currently loaded
748
* reference points + offset resolve to.
749
*/
750
const unsigned long TIME_RELATIVE_EPOCH = 0;
751
const unsigned long TIME_RELATIVE_TODAY = 1;
752
const unsigned long TIME_RELATIVE_NOW = 2;
753
754
attribute PRTime beginTime;
755
attribute unsigned long beginTimeReference;
756
readonly attribute boolean hasBeginTime;
757
readonly attribute PRTime absoluteBeginTime;
758
759
attribute PRTime endTime;
760
attribute unsigned long endTimeReference;
761
readonly attribute boolean hasEndTime;
762
readonly attribute PRTime absoluteEndTime;
763
764
/**
765
* Text search terms.
766
*/
767
attribute AString searchTerms;
768
readonly attribute boolean hasSearchTerms;
769
770
/**
771
* Set lower or upper limits for how many times an item has been
772
* visited. The default is -1, and in that case all items are
773
* matched regardless of their visit count.
774
*/
775
attribute long minVisits;
776
attribute long maxVisits;
777
778
/**
779
* When the set of transitions is nonempty, results are limited to pages which
780
* have at least one visit for each of the transition types.
781
* @note: For searching on more than one transition this can be very slow.
782
*
783
* Limit results to the specified list of transition types.
784
*/
785
void setTransitions(in Array<unsigned long> transitions);
786
787
/**
788
* Get the transitions set for this query.
789
*/
790
Array<unsigned long> getTransitions();
791
792
/**
793
* Get the count of the set query transitions.
794
*/
795
readonly attribute unsigned long transitionCount;
796
797
/**
798
* When set, returns only bookmarked items, when unset, returns anything. Setting this
799
* is equivalent to listing all bookmark folders in the 'folders' parameter.
800
*/
801
attribute boolean onlyBookmarked;
802
803
/**
804
* This controls the meaning of 'domain', and whether it is an exact match
805
* 'domainIsHost' = true, or hierarchical (= false).
806
*/
807
attribute boolean domainIsHost;
808
809
/**
810
* This is the host or domain name (controlled by domainIsHost). When
811
* domainIsHost, domain only does exact matching on host names. Otherwise,
812
* it will return anything whose host name ends in 'domain'.
813
*
814
* This one is a little different than most. Setting it to an empty string
815
* is a real query and will match any URI that has no host name (local files
816
* and such). Set this to NULL (in C++ use SetIsVoid) if you don't want
817
* domain matching.
818
*/
819
attribute AUTF8String domain;
820
readonly attribute boolean hasDomain;
821
822
/**
823
* This is a URI to match, to, for example, find out every time you visited
824
* a given URI. This is an exact match.
825
*/
826
attribute nsIURI uri;
827
readonly attribute boolean hasUri;
828
829
/**
830
* Test for existence or non-existence of a given annotation. We don't
831
* currently support >1 annotation name per query. If 'annotationIsNot' is
832
* true, we test for the non-existence of the specified annotation.
833
*
834
* Testing for not annotation will do the same thing as a normal query and
835
* remove everything that doesn't have that annotation. Asking for things
836
* that DO have a given annotation is a little different. It also includes
837
* things that have never been visited. This allows place queries to be
838
* returned as well as anything else that may have been tagged with an
839
* annotation. This will only work for RESULTS_AS_URI since there will be
840
* no visits for these items.
841
*/
842
attribute boolean annotationIsNot;
843
attribute AUTF8String annotation;
844
readonly attribute boolean hasAnnotation;
845
846
/**
847
* Limit results to items that are tagged with all of the given tags. This
848
* attribute must be set to an array of strings. When called as a getter it
849
* will return an array of strings sorted ascending in lexicographical order.
850
* The array may be empty in either case. Duplicate tags may be specified
851
* when setting the attribute, but the getter returns only unique tags.
852
*/
853
attribute nsIVariant tags;
854
855
/**
856
* If 'tagsAreNot' is true, the results are instead limited to items that
857
* are not tagged with any of the given tags. This attribute is used in
858
* conjunction with the 'tags' attribute.
859
*/
860
attribute boolean tagsAreNot;
861
862
/**
863
* Limit results to items that are in all of the given folders.
864
*/
865
Array<ACString> getParents();
866
readonly attribute unsigned long parentCount;
867
868
/**
869
* This is not recursive so results will be returned from the first level of
870
* that folder.
871
*/
872
void setParents(in Array<ACString> aGuids);
873
874
/**
875
* Creates a new query item with the same parameters of this one.
876
*/
877
nsINavHistoryQuery clone();
878
};
879
880
/**
881
* This object represents the global options for executing a query.
882
*/
883
[scriptable, uuid(8198dfa7-8061-4766-95cb-fa86b3c00a47)]
884
interface nsINavHistoryQueryOptions : nsISupports
885
{
886
/**
887
* You can ask for the results to be pre-sorted. Since the DB has indices
888
* of many items, it can produce sorted results almost for free. These should
889
* be self-explanatory.
890
*
891
* Note: re-sorting is slower, as is sorting by title or when you have a
892
* host name.
893
*
894
* For bookmark items, SORT_BY_NONE means sort by the natural bookmark order.
895
*/
896
const unsigned short SORT_BY_NONE = 0;
897
const unsigned short SORT_BY_TITLE_ASCENDING = 1;
898
const unsigned short SORT_BY_TITLE_DESCENDING = 2;
899
const unsigned short SORT_BY_DATE_ASCENDING = 3;
900
const unsigned short SORT_BY_DATE_DESCENDING = 4;
901
const unsigned short SORT_BY_URI_ASCENDING = 5;
902
const unsigned short SORT_BY_URI_DESCENDING = 6;
903
const unsigned short SORT_BY_VISITCOUNT_ASCENDING = 7;
904
const unsigned short SORT_BY_VISITCOUNT_DESCENDING = 8;
905
const unsigned short SORT_BY_DATEADDED_ASCENDING = 11;
906
const unsigned short SORT_BY_DATEADDED_DESCENDING = 12;
907
const unsigned short SORT_BY_LASTMODIFIED_ASCENDING = 13;
908
const unsigned short SORT_BY_LASTMODIFIED_DESCENDING = 14;
909
const unsigned short SORT_BY_TAGS_ASCENDING = 17;
910
const unsigned short SORT_BY_TAGS_DESCENDING = 18;
911
const unsigned short SORT_BY_FRECENCY_ASCENDING = 21;
912
const unsigned short SORT_BY_FRECENCY_DESCENDING = 22;
913
914
/**
915
* "URI" results, one for each URI visited in the range. Individual result
916
* nodes will be of type "URI".
917
*/
918
const unsigned short RESULTS_AS_URI = 0;
919
920
/**
921
* "Visit" results, with one for each time a page was visited (this will
922
* often give you multiple results for one URI). Individual result nodes will
923
* have type "Visit"
924
*
925
* @note This result type is only supported by QUERY_TYPE_HISTORY.
926
*/
927
const unsigned short RESULTS_AS_VISIT = 1;
928
929
/**
930
* This returns query nodes for each predefined date range where we
931
* had visits. The node contains information how to load its content:
932
* - visits for the given date range will be loaded.
933
*
934
* @note This result type is only supported by QUERY_TYPE_HISTORY.
935
*/
936
const unsigned short RESULTS_AS_DATE_QUERY = 3;
937
938
/**
939
* This returns nsINavHistoryQueryResultNode nodes for each site where we
940
* have visits. The node contains information how to load its content:
941
* - last visit for each url in the given host will be loaded.
942
*
943
* @note This result type is only supported by QUERY_TYPE_HISTORY.
944
*/
945
const unsigned short RESULTS_AS_SITE_QUERY = 4;
946
947
/**
948
* This returns nsINavHistoryQueryResultNode nodes for each day where we
949
* have visits. The node contains information how to load its content:
950
* - list of hosts visited in the given period will be loaded.
951
*
952
* @note This result type is only supported by QUERY_TYPE_HISTORY.
953
*/
954
const unsigned short RESULTS_AS_DATE_SITE_QUERY = 5;
955
956
/**
957
* This returns nsINavHistoryQueryResultNode nodes for each tag.
958
* The node contains information how to load its content:
959
* - list of bookmarks with the given tag will be loaded.
960
*
961
* @note Setting this resultType will force queryType to QUERY_TYPE_BOOKMARKS.
962
*/
963
const unsigned short RESULTS_AS_TAGS_ROOT = 6;
964
965
/**
966
* DEPRECATED: This exists for Sync and also to avoid reusing this number.
967
*/
968
const unsigned short RESULTS_AS_TAG_CONTENTS = 7;
969
970
/**
971
* This returns nsINavHistoryQueryResultNode nodes for each top-level bookmark
972
* root.
973
*
974
* @note Setting this resultType will force queryType to QUERY_TYPE_BOOKMARKS.
975
*/
976
const unsigned short RESULTS_AS_ROOTS_QUERY = 8;
977
978
/**
979
* This returns nsINavHistoryQueryResultNode for each left-pane root.
980
*/
981
const unsigned short RESULTS_AS_LEFT_PANE_QUERY = 9;
982
983
/**
984
* The sorting mode to be used for this query.
985
* mode is one of SORT_BY_*
986
*/
987
attribute unsigned short sortingMode;
988
989
/**
990
* Sets the result type. One of RESULT_TYPE_* which includes how URIs are
991
* represented.
992
*/
993
attribute unsigned short resultType;
994
995
/**
996
* This option excludes all URIs and separators from a bookmarks query.
997
* This would be used if you just wanted a list of bookmark folders and
998
* queries (such as the left pane of the places page).
999
* Defaults to false.
1000
*/
1001
attribute boolean excludeItems;
1002
1003
/**
1004
* Set to true to exclude queries ("place:" URIs) from the query results.
1005
* Simple folder queries (bookmark folder symlinks) will still be included.
1006
* Defaults to false.
1007
*/
1008
attribute boolean excludeQueries;
1009
1010
/**
1011
* When set, allows items with "place:" URIs to appear as containers,
1012
* with the container's contents filled in from the stored query.
1013
* If not set, these will appear as normal items. Doesn't do anything if
1014
* excludeQueries is set. Defaults to false.
1015
*
1016
* Note that this has no effect on folder links, which are place: URIs
1017
* returned by nsINavBookmarkService.GetFolderURI. These are always expanded
1018
* and will appear as bookmark folders.
1019
*/
1020
attribute boolean expandQueries;
1021
1022
/**
1023
* Some pages in history are marked "hidden" and thus don't appear by default
1024
* in queries. These include automatic framed visits and redirects. Setting
1025
* this attribute will return all pages, even hidden ones. Does nothing for
1026
* bookmark queries. Defaults to false.
1027
*/
1028
attribute boolean includeHidden;
1029
1030
/**
1031
* This is the maximum number of results that you want. The query is executed,
1032
* the results are sorted, and then the top 'maxResults' results are taken
1033
* and returned. Set to 0 (the default) to get all results.
1034
*
1035
* THIS DOES NOT WORK IN CONJUNCTION WITH SORTING BY TITLE. This is because
1036
* sorting by title requires us to sort after using locale-sensetive sorting
1037
* (as opposed to letting the database do it for us).
1038
*
1039
* Instead, we get the result ordered by date, pick the maxResult most recent
1040
* ones, and THEN sort by title.
1041
*/
1042
attribute unsigned long maxResults;
1043
1044
const unsigned short QUERY_TYPE_HISTORY = 0;
1045
const unsigned short QUERY_TYPE_BOOKMARKS = 1;
1046
/* Unified queries are not yet implemented. See bug 378798 */
1047
const unsigned short QUERY_TYPE_UNIFIED = 2;
1048
1049
/**
1050
* The type of search to use when querying the DB; This attribute is only
1051
* honored by query nodes. It is silently ignored for simple folder queries.
1052
*/
1053
attribute unsigned short queryType;
1054
1055
/**
1056
* When this is true, the root container node generated by these options and
1057
* its descendant containers will be opened asynchronously if they support it.
1058
* This is false by default.
1059
*
1060
* @note Currently only bookmark folder containers support being opened
1061
* asynchronously.
1062
*/
1063
attribute boolean asyncEnabled;
1064
1065
/**
1066
* Creates a new options item with the same parameters of this one.
1067
*/
1068
nsINavHistoryQueryOptions clone();
1069
};
1070
1071
[scriptable, uuid(20c974ff-ee16-4828-9326-1b7c9e036622)]
1072
interface nsINavHistoryService : nsISupports
1073
{
1074
/**
1075
* System Notifications:
1076
*
1077
* places-init-complete - Sent once the History service is completely
1078
* initialized successfully.
1079
* places-database-locked - Sent if initialization of the History service
1080
* failed due to the inability to open the places.sqlite
1081
* for access reasons.
1082
*/
1083
1084
/**
1085
* This transition type means the user followed a link and got a new toplevel
1086
* window.
1087
*/
1088
const unsigned long TRANSITION_LINK = 1;
1089
1090
/**
1091
* This transition type means that the user typed the page's URL in the
1092
* URL bar or selected it from URL bar autocomplete results, clicked on
1093
* it from a history query (from the History sidebar, History menu,
1094
* or history query in the personal toolbar or Places organizer.
1095
*/
1096
const unsigned long TRANSITION_TYPED = 2;
1097
1098
/**
1099
* This transition is set when the user followed a bookmark to get to the
1100
* page.
1101
*/
1102
const unsigned long TRANSITION_BOOKMARK = 3;
1103
1104
/**
1105
* This transition type is set when some inner content is loaded. This is
1106
* true of all images on a page, and the contents of the iframe. It is also
1107
* true of any content in a frame if the user did not explicitly follow
1108
* a link to get there.
1109
*/
1110
const unsigned long TRANSITION_EMBED = 4;
1111
1112
/**
1113
* Set when the transition was a permanent redirect.
1114
*/
1115
const unsigned long TRANSITION_REDIRECT_PERMANENT = 5;
1116
1117
/**
1118
* Set when the transition was a temporary redirect.
1119
*/
1120
const unsigned long TRANSITION_REDIRECT_TEMPORARY = 6;
1121
1122
/**
1123
* Set when the transition is a download.
1124
*/
1125
const unsigned long TRANSITION_DOWNLOAD = 7;
1126
1127
/**
1128
* This transition type means the user followed a link and got a visit in
1129
* a frame.
1130
*/
1131
const unsigned long TRANSITION_FRAMED_LINK = 8;
1132
1133
/**
1134
* This transition type means the page has been reloaded.
1135
*/
1136
const unsigned long TRANSITION_RELOAD = 9;
1137
1138
/**
1139
* Set when database is coherent
1140
*/
1141
const unsigned short DATABASE_STATUS_OK = 0;
1142
1143
/**
1144
* Set when database did not exist and we created a new one.
1145
*/
1146
const unsigned short DATABASE_STATUS_CREATE = 1;
1147
1148
/**
1149
* Set when database was corrupt and we replaced it with a new one.
1150
*/
1151
const unsigned short DATABASE_STATUS_CORRUPT = 2;
1152
1153
/**
1154
* Set when database schema has been upgraded.
1155
*/
1156
const unsigned short DATABASE_STATUS_UPGRADED = 3;
1157
1158
/**
1159
* Set when database couldn't be opened.
1160
*/
1161
const unsigned short DATABASE_STATUS_LOCKED = 4;
1162
1163
/**
1164
* Returns the current database status
1165
*/
1166
readonly attribute unsigned short databaseStatus;
1167
1168
/**
1169
* This is just like markPageAsTyped (in nsIBrowserHistory, also implemented
1170
* by the history service), but for bookmarks. It declares that the given URI
1171
* is being opened as a result of following a bookmark. If this URI is loaded
1172
* soon after this message has been received, that transition will be marked
1173
* as following a bookmark.
1174
*/
1175
void markPageAsFollowedBookmark(in nsIURI aURI);
1176
1177
/**
1178
* Designates the url as having been explicitly typed in by the user.
1179
*
1180
* @param aURI
1181
* URI of the page to be marked.
1182
*/
1183
void markPageAsTyped(in nsIURI aURI);
1184
1185
/**
1186
* Designates the url as coming from a link explicitly followed by
1187
* the user (for example by clicking on it).
1188
*
1189
* @param aURI
1190
* URI of the page to be marked.
1191
*/
1192
void markPageAsFollowedLink(in nsIURI aURI);
1193
1194
/**
1195
* Returns true if this URI would be added to the history. You don't have to
1196
* worry about calling this, adding a visit will always check before
1197
* actually adding the page. This function is public because some components
1198
* may want to check if this page would go in the history (i.e. for
1199
* annotations).
1200
*/
1201
boolean canAddURI(in nsIURI aURI);
1202
1203
/**
1204
* This returns a new query object that you can pass to executeQuer[y/ies].
1205
* It will be initialized to all empty (so using it will give you all history).
1206
*/
1207
nsINavHistoryQuery getNewQuery();
1208
1209
/**
1210
* This returns a new options object that you can pass to executeQuer[y/ies]
1211
* after setting the desired options.
1212
*/
1213
nsINavHistoryQueryOptions getNewQueryOptions();
1214
1215
/**
1216
* Executes a single query.
1217
*/
1218
nsINavHistoryResult executeQuery(in nsINavHistoryQuery aQuery,
1219
in nsINavHistoryQueryOptions options);
1220
1221
/**
1222
* Converts a query URI-like string to a query object.
1223
*/
1224
void queryStringToQuery(in AUTF8String aQueryString,
1225
out nsINavHistoryQuery aQuery,
1226
out nsINavHistoryQueryOptions options);
1227
1228
/**
1229
* Converts a query into an equivalent string that can be persisted. Inverse
1230
* of queryStringToQuery()
1231
*/
1232
AUTF8String queryToQueryString(in nsINavHistoryQuery aQuery,
1233
in nsINavHistoryQueryOptions options);
1234
1235
/**
1236
* Adds a history observer. If ownsWeak is false, the history service will
1237
* keep an owning reference to the observer. If ownsWeak is true, then
1238
* aObserver must implement nsISupportsWeakReference, and the history service
1239
* will keep a weak reference to the observer.
1240
*/
1241
void addObserver(in nsINavHistoryObserver observer,
1242
[optional] in boolean ownsWeak);
1243
1244
/**
1245
* Removes a history observer.
1246
*/
1247
void removeObserver(in nsINavHistoryObserver observer);
1248
1249
/**
1250
* Gets an array of registered nsINavHistoryObserver objects.
1251
*/
1252
Array<nsINavHistoryObserver> getObservers();
1253
1254
/**
1255
* True if history is disabled. currently,
1256
* history is disabled if the places.history.enabled pref is false.
1257
*/
1258
readonly attribute boolean historyDisabled;
1259
1260
/**
1261
* Generate a guid.
1262
* Guids can be used for any places purposes (history, bookmarks, etc.)
1263
* Returns null if the generation of the guid failed.
1264
*/
1265
ACString makeGuid();
1266
1267
/**
1268
* Returns a 48-bit hash for a URI spec.
1269
*
1270
* @param aSpec
1271
* The URI spec to hash.
1272
* @param aMode
1273
* The hash mode: `""` (default), `"prefix_lo"`, or `"prefix_hi"`.
1274
*/
1275
unsigned long long hashURL(in ACString aSpec, [optional] in ACString aMode);
1276
1277
/**
1278
* Resets and recalculates the origin frecency statistics that are kept in the
1279
* moz_meta table.
1280
*
1281
* @param aCallback
1282
* Called when the recalculation is complete. The arguments passed to
1283
* the observer are not defined.
1284
*/
1285
void recalculateOriginFrecencyStats([optional] in nsIObserver aCallback);
1286
1287
/**
1288
* The database connection used by Places.
1289
*/
1290
readonly attribute mozIStorageConnection DBConnection;
1291
1292
/**
1293
* Asynchronously executes the statement created from a query.
1294
*
1295
* @see nsINavHistoryService::executeQuery
1296
* @note THIS IS A TEMPORARY API. Don't rely on it, since it will be replaced
1297
* in future versions by a real async querying API.
1298
* @note Results obtained from this method differ from results obtained from
1299
* executeQuery, because there is additional filtering and sorting
1300
* done by the latter. Thus you should use executeQuery, unless you
1301
* are absolutely sure that the returned results are fine for
1302
* your use-case.
1303
*/
1304
mozIStoragePendingStatement asyncExecuteLegacyQuery(
1305
in nsINavHistoryQuery aQuery,
1306
in nsINavHistoryQueryOptions aOptions,
1307
in mozIStorageStatementCallback aCallback);
1308
1309
/**
1310
* Hook for clients who need to perform actions during/by the end of
1311
* the shutdown of the database.
1312
* May be null if it's too late to get one.
1313
*/
1314
readonly attribute nsIAsyncShutdownClient shutdownClient;
1315
1316
/**
1317
* Hook for internal clients who need to perform actions just before the
1318
* connection gets closed.
1319
* May be null if it's too late to get one.
1320
*/
1321
readonly attribute nsIAsyncShutdownClient connectionShutdownClient;
1322
1323
/**
1324
* Asynchronously recalculates frecency for all pages where frecency < 0, then
1325
* decays frecency and inputhistory values.
1326
*/
1327
void decayFrecency();
1328
};