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 14interface nsIArray; 15interface nsIFile; 16interface nsIObserver; 17interface nsIVariant; 18interface nsIURI; 19 20interface mozIStorageConnection; 21interface mozIStorageStatementCallback; 22interface mozIStoragePendingStatement; 23interface nsIAsyncShutdownClient; 24 25interface nsINavHistoryContainerResultNode; 26interface nsINavHistoryQueryResultNode; 27interface nsINavHistoryQuery; 28interface nsINavHistoryQueryOptions; 29interface nsINavHistoryResult; 30interface nsINavHistoryBatchCallback; 31 32[scriptable, uuid(91d104bb-17ef-404b-9f9a-d9ed8de6824c)] 33interface 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)] 204interface 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)] 273interface 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)] 309interface 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)] 494interface 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)] 558interface 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)] 724interface 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)] 884interface 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)] 1072interface 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}; 1329