dom/chrome-webidl/PlacesEvent.webidl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
   4
   5 enum PlacesEventType {
   6   "none",
   7
   8   /**
   9    * data: PlacesVisit. Fired whenever a page is visited.
  10    */
  11   "page-visited",
  12   /**
  13    * data: PlacesBookmarkAddition. Fired whenever a bookmark
  14    * (or a bookmark folder/separator) is created.
  15    */
  16   "bookmark-added",
  17   /**
  18    * data: PlacesBookmarkRemoved. Fired whenever a bookmark
  19    * (or a bookmark folder/separator) is removed.
  20    */
  21   "bookmark-removed",
  22   /**
  23    * data: PlacesBookmarkMoved. Fired whenever a bookmark
  24    * (or a bookmark folder/separator) is moved.
  25    */
  26   "bookmark-moved",
  27   /**
  28    * data: PlacesBookmarkGuid. Fired whenever a bookmark guid changes.
  29    */
  30   "bookmark-guid-changed",
  31   /**
  32    * data: PlacesBookmarkKeyword. Fired whenever a bookmark keyword changes.
  33    */
  34   "bookmark-keyword-changed",
  35   /**
  36    * data: PlacesBookmarkTags. Fired whenever tags of bookmark changes.
  37    */
  38   "bookmark-tags-changed",
  39   /**
  40    * data: PlacesBookmarkTime.
  41    * Fired whenever dateAdded or lastModified of a bookmark is explicitly changed
  42    * through the Bookmarks API. This notification doesn't fire when a bookmark is
  43    * created, or when a property of a bookmark (e.g. title) is changed, even if
  44    * lastModified will be updated as a consequence of that change.
  45    */
  46   "bookmark-time-changed",
  47   /**
  48    * data: PlacesBookmarkTitle. Fired whenever a bookmark title changes.
  49    */
  50   "bookmark-title-changed",
  51   /**
  52    * data: PlacesBookmarkUrl. Fired whenever a bookmark url changes.
  53    */
  54   "bookmark-url-changed",
  55   /**
  56    * data: PlacesFavicon. Fired whenever a favicon changes.
  57    */
  58   "favicon-changed",
  59   /**
  60    * data: PlacesVisitTitle. Fired whenever a page title changes.
  61    */
  62   "page-title-changed",
  63   /**
  64    * data: PlacesHistoryCleared. Fired whenever history is cleared.
  65    */
  66   "history-cleared",
  67   /**
  68    * data: PlacesRanking. Fired whenever pages ranking is changed.
  69    */
  70   "pages-rank-changed",
  71   /**
  72    * data: PlacesVisitRemoved. Fired whenever a page or its visits are removed.
  73    * This may be invoked when a page is removed from the store because it has no more
  74    * visits, nor bookmarks. It may also be invoked when all or some of the page visits are
  75    * removed, but the page itself is not removed from the store, because it may be
  76    * bookmarked.
  77    */
  78   "page-removed",
  79   /**
  80    * data: PlacesPurgeCaches. Fired whenever changes happened that could not be observed
  81    * through other notifications, for example a database fixup. When received, observers,
  82    * especially data views, should drop any caches and reload from scratch.
  83    */
  84   "purge-caches",
  85 };
  86
  87 [ChromeOnly, Exposed=Window]
  88 interface PlacesEvent {
  89   readonly attribute PlacesEventType type;
  90 };
  91
  92 [ChromeOnly, Exposed=Window]
  93 interface PlacesVisit : PlacesEvent {
  94   /**
  95    * URL of the visit.
  96    */
  97   readonly attribute DOMString url;
  98
  99   /**
 100    * Id of the visit.
 101    */
 102   readonly attribute unsigned long long visitId;
 103
 104   /**
 105    * Time of the visit, in milliseconds since epoch.
 106    */
 107   readonly attribute unsigned long long visitTime;
 108
 109   /**
 110    * The id of the visit the user came from, defaults to 0 for no referrer.
 111    */
 112   readonly attribute unsigned long long referringVisitId;
 113
 114   /**
 115    * One of nsINavHistory.TRANSITION_*
 116    */
 117   readonly attribute unsigned long transitionType;
 118
 119   /**
 120    * The unique id associated with the page.
 121    */
 122   readonly attribute ByteString pageGuid;
 123
 124   /**
 125    * The frecency of the this page.
 126    */
 127   readonly attribute long long frecency;
 128
 129   /**
 130    * Whether the visited page is marked as hidden.
 131    */
 132   readonly attribute boolean hidden;
 133
 134   /**
 135    * Number of visits (including this one) for this URL.
 136    */
 137   readonly attribute unsigned long visitCount;
 138
 139   /**
 140    * Whether the URL has been typed or not.
 141    * TODO (Bug 1271801): This will become a count, rather than a boolean.
 142    * For future compatibility, always compare it with "> 0".
 143    */
 144   readonly attribute unsigned long typedCount;
 145
 146   /**
 147    * The last known title of the page. Might not be from the current visit,
 148    * and might be null if it is not known.
 149    */
 150   readonly attribute DOMString? lastKnownTitle;
 151 };
 152
 153 /**
 154  * Base class for properties that are common to all bookmark events.
 155  */
 156 [ChromeOnly, Exposed=Window]
 157 interface PlacesBookmark : PlacesEvent {
 158   /**
 159    * The id of the item.
 160    */
 161   readonly attribute long long id;
 162
 163   /**
 164    * The id of the folder to which the item belongs.
 165    */
 166   readonly attribute long long parentId;
 167
 168   /**
 169    * The type of the added item (see TYPE_* constants in nsINavBooksService.idl).
 170    */
 171   readonly attribute unsigned short itemType;
 172
 173   /**
 174    * The URI of the added item if it was TYPE_BOOKMARK, "" otherwise.
 175    */
 176   readonly attribute DOMString url;
 177
 178   /**
 179    * The unique ID associated with the item.
 180    */
 181   readonly attribute ByteString guid;
 182
 183   /**
 184    * The unique ID associated with the item's parent.
 185    */
 186   readonly attribute ByteString parentGuid;
 187
 188   /**
 189    * A change source constant from nsINavBookmarksService::SOURCE_*,
 190    * passed to the method that notifies the observer.
 191    */
 192   readonly attribute unsigned short source;
 193
 194   /**
 195    * True if the item is a tag or a tag folder.
 196    * NOTE: this will go away with bug 424160.
 197    */
 198   readonly attribute boolean isTagging;
 199 };
 200
 201 dictionary PlacesBookmarkAdditionInit {
 202   required long long id;
 203   required long long parentId;
 204   required unsigned short itemType;
 205   required DOMString url;
 206   required ByteString guid;
 207   required ByteString parentGuid;
 208   required unsigned short source;
 209   required long index;
 210   required DOMString title;
 211   required DOMString? tags;
 212   required unsigned long long dateAdded;
 213   required boolean isTagging;
 214   required long long frecency;
 215   required boolean hidden;
 216   required unsigned long visitCount;
 217   required unsigned long long? lastVisitDate;
 218   required long long targetFolderItemId;
 219   required ByteString? targetFolderGuid;
 220   required DOMString? targetFolderTitle;
 221 };
 222
 223 [ChromeOnly, Exposed=Window]
 224 interface PlacesBookmarkAddition : PlacesBookmark {
 225   constructor(PlacesBookmarkAdditionInit initDict);
 226
 227   /**
 228    * The item's index in the folder.
 229    */
 230   readonly attribute long index;
 231
 232   /**
 233    * The title of the added item.
 234    */
 235   readonly attribute DOMString title;
 236
 237   /**
 238    * The tags of the added item.
 239    */
 240   readonly attribute DOMString tags;
 241
 242   /**
 243    * The time that the item was added, in milliseconds from the epoch.
 244    */
 245   readonly attribute unsigned long long dateAdded;
 246
 247   /**
 248    * The frecency of the page of this bookmark.
 249    */
 250   readonly attribute long long frecency;
 251
 252   /**
 253    * Whether the visited page is marked as hidden.
 254    */
 255   readonly attribute boolean hidden;
 256
 257   /**
 258    * Number of visits (including this one) for this URL.
 259    */
 260   readonly attribute unsigned long visitCount;
 261
 262   /**
 263    * Date of the last visit, in milliseconds since epoch.
 264    */
 265   readonly attribute unsigned long long? lastVisitDate;
 266
 267   /**
 268    * If this is a folder shortcut, the id of the target folder.
 269    */
 270   readonly attribute long long targetFolderItemId;
 271
 272   /**
 273    * If this is a folder shortcut, the unique ID associated with the target folder.
 274    */
 275   readonly attribute ByteString targetFolderGuid;
 276
 277   /**
 278    * If this is a folder shortcut, the title of the target folder.
 279    */
 280   readonly attribute DOMString targetFolderTitle;
 281
 282 };
 283
 284 dictionary PlacesBookmarkRemovedInit {
 285   required long long id;
 286   required long long parentId;
 287   required unsigned short itemType;
 288   required DOMString url;
 289   required DOMString title;
 290   required ByteString guid;
 291   required ByteString parentGuid;
 292   required unsigned short source;
 293   required long index;
 294   required boolean isTagging;
 295   boolean isDescendantRemoval = false;
 296 };
 297
 298 [ChromeOnly, Exposed=Window]
 299 interface PlacesBookmarkRemoved : PlacesBookmark {
 300   constructor(PlacesBookmarkRemovedInit initDict);
 301   /**
 302    * The item's index in the folder.
 303    */
 304   readonly attribute long index;
 305
 306   /**
 307    * The title of the the removed item.
 308    */
 309   readonly attribute DOMString title;
 310
 311   /**
 312    * The item is a descendant of an item whose notification has been sent out.
 313    */
 314   readonly attribute boolean isDescendantRemoval;
 315 };
 316
 317 dictionary PlacesBookmarkMovedInit {
 318   required long long id;
 319   required unsigned short itemType;
 320   DOMString? url = null;
 321   required ByteString guid;
 322   required ByteString parentGuid;
 323   required long index;
 324   required ByteString oldParentGuid;
 325   required long oldIndex;
 326   required unsigned short source;
 327   required boolean isTagging;
 328   required DOMString title;
 329   required DOMString? tags;
 330   required long long frecency;
 331   required boolean hidden;
 332   required unsigned long visitCount;
 333   required unsigned long long dateAdded;
 334   required unsigned long long? lastVisitDate;
 335 };
 336
 337 [ChromeOnly, Exposed=Window]
 338 /**
 339  * NOTE: Though PlacesBookmarkMoved extends PlacesBookmark,
 340  *       parentId will not be set. Use parentGuid instead.
 341  */
 342 interface PlacesBookmarkMoved : PlacesBookmark {
 343   constructor(PlacesBookmarkMovedInit initDict);
 344   /**
 345    * The item's index in the folder.
 346    */
 347   readonly attribute long index;
 348
 349   /**
 350    * The unique ID associated with the item's old parent.
 351    */
 352   readonly attribute ByteString oldParentGuid;
 353
 354   /**
 355    * The item's old index in the folder.
 356    */
 357   readonly attribute long oldIndex;
 358
 359   /**
 360    * The title of the added item.
 361    */
 362   readonly attribute DOMString title;
 363
 364   /**
 365    * The tags of the added item.
 366    */
 367   readonly attribute DOMString tags;
 368
 369   /**
 370    * The frecency of the page of this bookmark.
 371    */
 372   readonly attribute long long frecency;
 373
 374   /**
 375    * Whether the visited page is marked as hidden.
 376    */
 377   readonly attribute boolean hidden;
 378
 379   /**
 380    * Number of visits (including this one) for this URL.
 381    */
 382   readonly attribute unsigned long visitCount;
 383
 384   /**
 385    * Date of the this bookmark added, in milliseconds since epoch.
 386    */
 387   readonly attribute unsigned long long dateAdded;
 388
 389   /**
 390    * Date of the last visit, in milliseconds since epoch.
 391    */
 392   readonly attribute unsigned long long? lastVisitDate;
 393 };
 394
 395 [ChromeOnly, Exposed=Window]
 396 interface PlacesBookmarkChanged : PlacesBookmark {
 397   /**
 398    * The updated last modified value in milliseconds.
 399    */
 400   readonly attribute long long lastModified;
 401 };
 402
 403 dictionary PlacesBookmarkGuidInit {
 404   required long long id;
 405   required unsigned short itemType;
 406   DOMString? url = null;
 407   required ByteString guid;
 408   required ByteString parentGuid;
 409   required long long lastModified;
 410   required unsigned short source;
 411   required boolean isTagging;
 412 };
 413
 414 [ChromeOnly, Exposed=Window]
 415 interface PlacesBookmarkGuid : PlacesBookmarkChanged {
 416   constructor(PlacesBookmarkGuidInit initDict);
 417 };
 418
 419 dictionary PlacesBookmarkKeywordInit {
 420   required long long id;
 421   required unsigned short itemType;
 422   DOMString? url = null;
 423   required ByteString guid;
 424   required ByteString parentGuid;
 425   required ByteString keyword;
 426   required long long lastModified;
 427   required unsigned short source;
 428   required boolean isTagging;
 429 };
 430
 431 [ChromeOnly, Exposed=Window]
 432 interface PlacesBookmarkKeyword : PlacesBookmarkChanged {
 433   constructor(PlacesBookmarkKeywordInit initDict);
 434
 435   /**
 436    * Keyword the bookmark has currently.
 437    */
 438   [Constant,Cached]
 439   readonly attribute ByteString keyword;
 440 };
 441
 442 dictionary PlacesBookmarkTagsInit {
 443   required long long id;
 444   required unsigned short itemType;
 445   DOMString? url = null;
 446   required ByteString guid;
 447   required ByteString parentGuid;
 448   required sequence<DOMString> tags;
 449   required long long lastModified;
 450   required unsigned short source;
 451   required boolean isTagging;
 452 };
 453
 454 [ChromeOnly, Exposed=Window]
 455 interface PlacesBookmarkTags : PlacesBookmarkChanged {
 456   constructor(PlacesBookmarkTagsInit initDict);
 457
 458   /**
 459    * Tags the bookmark has currently.
 460    */
 461   [Constant,Cached]
 462   readonly attribute sequence<DOMString> tags;
 463 };
 464
 465 dictionary PlacesBookmarkTimeInit {
 466   required long long id;
 467   required unsigned short itemType;
 468   DOMString? url = null;
 469   required ByteString guid;
 470   required ByteString parentGuid;
 471   required long long dateAdded;
 472   required long long lastModified;
 473   required unsigned short source;
 474   required boolean isTagging;
 475 };
 476
 477 [ChromeOnly, Exposed=Window]
 478 interface PlacesBookmarkTime : PlacesBookmarkChanged {
 479   constructor(PlacesBookmarkTimeInit initDict);
 480
 481   /**
 482    * The added date in milliseconds.
 483    */
 484   readonly attribute long long dateAdded;
 485 };
 486
 487 dictionary PlacesBookmarkTitleInit {
 488   required long long id;
 489   required unsigned short itemType;
 490   DOMString? url = null;
 491   required ByteString guid;
 492   required ByteString parentGuid;
 493   required DOMString title;
 494   required long long lastModified;
 495   required unsigned short source;
 496   required boolean isTagging;
 497 };
 498
 499 [ChromeOnly, Exposed=Window]
 500 interface PlacesBookmarkTitle : PlacesBookmarkChanged {
 501   constructor(PlacesBookmarkTitleInit initDict);
 502
 503   /**
 504    * The title of the changed bookmark.
 505    */
 506   readonly attribute DOMString title;
 507 };
 508
 509 dictionary PlacesBookmarkUrlInit {
 510   required long long id;
 511   required unsigned short itemType;
 512   required DOMString url;
 513   required ByteString guid;
 514   required ByteString parentGuid;
 515   required long long lastModified;
 516   required unsigned short source;
 517   required boolean isTagging;
 518 };
 519
 520 [ChromeOnly, Exposed=Window]
 521 interface PlacesBookmarkUrl : PlacesBookmarkChanged {
 522   constructor(PlacesBookmarkUrlInit initDict);
 523 };
 524
 525 dictionary PlacesFaviconInit {
 526   required DOMString url;
 527   required ByteString pageGuid;
 528   required DOMString faviconUrl;
 529 };
 530
 531 [ChromeOnly, Exposed=Window]
 532 interface PlacesFavicon : PlacesEvent {
 533   constructor(PlacesFaviconInit initDict);
 534
 535   /**
 536    * The URI of the changed page.
 537    */
 538   readonly attribute DOMString url;
 539
 540   /**
 541    * The unique id associated with the page.
 542    */
 543   readonly attribute ByteString pageGuid;
 544
 545   /**
 546    * The URI of the new favicon.
 547    */
 548   readonly attribute DOMString faviconUrl;
 549 };
 550
 551 dictionary PlacesVisitTitleInit {
 552   required DOMString url;
 553   required ByteString pageGuid;
 554   required DOMString title;
 555 };
 556
 557 [ChromeOnly, Exposed=Window]
 558 interface PlacesVisitTitle : PlacesEvent {
 559   constructor(PlacesVisitTitleInit initDict);
 560
 561   /**
 562    * The URI of the changed page.
 563    */
 564   readonly attribute DOMString url;
 565
 566   /**
 567    * The unique id associated with the page.
 568    */
 569   readonly attribute ByteString pageGuid;
 570
 571   /**
 572    * The title of the changed page.
 573    */
 574   readonly attribute DOMString title;
 575 };
 576
 577 [ChromeOnly, Exposed=Window]
 578 interface PlacesHistoryCleared : PlacesEvent {
 579   constructor();
 580 };
 581
 582 [ChromeOnly, Exposed=Window]
 583 interface PlacesRanking : PlacesEvent {
 584   constructor();
 585 };
 586
 587 dictionary PlacesVisitRemovedInit {
 588   required DOMString url;
 589   required ByteString pageGuid;
 590   required unsigned short reason;
 591   unsigned long transitionType = 0;
 592   boolean isRemovedFromStore = false;
 593   boolean isPartialVisistsRemoval = false;
 594 };
 595
 596 [ChromeOnly, Exposed=Window]
 597 interface PlacesVisitRemoved : PlacesEvent {
 598   /**
 599    * Removed by the user.
 600    */
 601   const unsigned short REASON_DELETED = 0;
 602
 603   /**
 604    * Removed by periodic expiration.
 605    */
 606   const unsigned short REASON_EXPIRED = 1;
 607
 608   constructor(PlacesVisitRemovedInit initDict);
 609
 610   /**
 611    * The URI of the page.
 612    */
 613   readonly attribute DOMString url;
 614
 615   /**
 616    * The unique id associated with the page.
 617    */
 618   readonly attribute ByteString pageGuid;
 619
 620   /**
 621    * The reason of removal.
 622    */
 623   readonly attribute unsigned short reason;
 624
 625   /**
 626    * One of nsINavHistoryService.TRANSITION_*
 627    * NOTE: Please refer this attribute only when isRemovedFromStore is false.
 628    *       Otherwise this will be 0.
 629    */
 630   readonly attribute unsigned long transitionType;
 631
 632   /**
 633    * This will be true if the page is removed from store.
 634    * If false, only visits were removed, but not the page.
 635    */
 636   readonly attribute boolean isRemovedFromStore;
 637
 638   /**
 639    * This will be true if remains at least one visit to the page.
 640    */
 641   readonly attribute boolean isPartialVisistsRemoval;
 642 };
 643
 644 [ChromeOnly, Exposed=Window]
 645 interface PlacesPurgeCaches : PlacesEvent {
 646   constructor();
 647 };