dom/chrome-webidl/PlacesEvent.webidl

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