src/chrome/common/extensions/api/bookmarks.json

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 [
   6   {
   7     "namespace": "bookmarks",
   8     "description": "Use the <code>chrome.bookmarks</code> API to create, organize, and otherwise manipulate bookmarks. Also see <a href='override'>Override Pages</a>, which you can use to create a custom Bookmark Manager page.",
   9     "properties": {
  10       "MAX_WRITE_OPERATIONS_PER_HOUR": {
  11         "value": 1000000,
  12         "deprecated": "Bookmark write operations are no longer limited by Chrome.",
  13         "description": ""
  14       },
  15       "MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE": {
  16         "value": 1000000,
  17         "deprecated": "Bookmark write operations are no longer limited by Chrome.",
  18         "description": ""
  19       }
  20     },
  21     "types": [
  22       {
  23         "id": "BookmarkTreeNode",
  24         "type": "object",
  25         "description": "A node (either a bookmark or a folder) in the bookmark tree.  Child nodes are ordered within their parent folder.",
  26         "properties": {
  27           "id": {
  28             "type": "string",
  29             "minimum": 0,
  30             "description": "The unique identifier for the node. IDs are unique within the current profile, and they remain valid even after the browser is restarted."
  31           },
  32           "parentId": {
  33             "type": "string",
  34             "minimum": 0,
  35             "optional": true,
  36             "description": "The <code>id</code> of the parent folder.  Omitted for the root node."
  37           },
  38           "index": {
  39             "type": "integer",
  40             "optional": true,
  41             "description": "The 0-based position of this node within its parent folder."
  42           },
  43           "url": {
  44             "type": "string",
  45             "optional": true,
  46             "description": "The URL navigated to when a user clicks the bookmark. Omitted for folders."
  47           },
  48           "title": {
  49             "type": "string",
  50             "description": "The text displayed for the node."
  51           },
  52           "dateAdded": {
  53             "type": "number",
  54             "optional": true,
  55             "description": "When this node was created, in milliseconds since the epoch (<code>new Date(dateAdded)</code>)."
  56           },
  57           "dateGroupModified": {
  58             "type": "number",
  59             "optional": true,
  60             "description": "When the contents of this folder last changed, in milliseconds since the epoch."
  61           },
  62           "unmodifiable": {
  63             "type": "string",
  64             "enum": ["managed"],
  65             "optional": true,
  66             "description": "Indicates the reason why this node is unmodifiable. The <var>managed</var> value indicates that this node was configured by the system administrator. Omitted if the node can be modified by the user and the extension (default)."
  67           },
  68           "children": {
  69             "type": "array",
  70             "optional": true,
  71             "items": { "$ref": "BookmarkTreeNode" },
  72             "description": "An ordered list of children of this node."
  73           }
  74         }
  75       },
  76       {
  77         "id": "CreateDetails",
  78         "description": "Object passed to the create() function.",
  79         "inline_doc": true,
  80         "type": "object",
  81         "properties": {
  82           "parentId": {
  83             "type": "string",
  84             "serialized_type": "int64",
  85             "optional": true,
  86             "description": "Defaults to the Other Bookmarks folder."
  87           },
  88           "index": {
  89             "type": "integer",
  90             "minimum": 0,
  91             "optional": true
  92           },
  93           "title": {
  94             "type": "string",
  95             "optional": true
  96           },
  97           "url": {
  98             "type": "string",
  99             "optional": true
 100           }
 101         }
 102       }
 103     ],
 104     "functions": [
 105       {
 106         "name": "get",
 107         "type": "function",
 108         "description": "Retrieves the specified BookmarkTreeNode(s).",
 109         "parameters": [
 110           {
 111             "name": "idOrIdList",
 112             "description": "A single string-valued id, or an array of string-valued ids",
 113             "choices": [
 114               {
 115                 "type": "string",
 116                 "serialized_type": "int64"
 117               },
 118               {
 119                 "type": "array",
 120                 "items": {
 121                   "type": "string",
 122                   "serialized_type": "int64"
 123                 },
 124                 "minItems": 1
 125               }
 126             ]
 127           },
 128           {
 129             "type": "function",
 130             "name": "callback",
 131             "parameters": [
 132               {
 133                 "name": "results",
 134                 "type": "array",
 135                 "items": { "$ref": "BookmarkTreeNode" }
 136               }
 137             ]
 138           }
 139         ]
 140       },
 141       {
 142         "name": "getChildren",
 143         "type": "function",
 144         "description": "Retrieves the children of the specified BookmarkTreeNode id.",
 145         "parameters": [
 146           {
 147             "type": "string",
 148             "serialized_type": "int64",
 149             "name": "id"
 150           },
 151           {
 152             "type": "function",
 153             "name": "callback",
 154             "parameters": [
 155               {
 156                 "name": "results",
 157                 "type": "array",
 158                 "items": { "$ref": "BookmarkTreeNode"}
 159               }
 160             ]
 161           }
 162         ]
 163       },
 164       {
 165         "name": "getRecent",
 166         "type": "function",
 167         "description": "Retrieves the recently added bookmarks.",
 168         "parameters": [
 169           {
 170             "type": "integer",
 171             "minimum": 1,
 172             "name": "numberOfItems",
 173             "description": "The maximum number of items to return."
 174           },
 175           {
 176             "type": "function",
 177             "name": "callback",
 178             "parameters": [
 179               {
 180                 "name": "results",
 181                 "type": "array",
 182                 "items": { "$ref": "BookmarkTreeNode" }
 183               }
 184             ]
 185           }
 186         ]
 187       },
 188       {
 189         "name": "getTree",
 190         "type": "function",
 191         "description": "Retrieves the entire Bookmarks hierarchy.",
 192         "parameters": [
 193           {
 194             "type": "function",
 195             "name": "callback",
 196             "parameters": [
 197               {
 198                 "name": "results",
 199                 "type": "array",
 200                 "items": { "$ref": "BookmarkTreeNode" }
 201               }
 202             ]
 203           }
 204         ]
 205       },
 206       {
 207         "name": "getSubTree",
 208         "type": "function",
 209         "description": "Retrieves part of the Bookmarks hierarchy, starting at the specified node.",
 210         "parameters": [
 211           {
 212             "type": "string",
 213             "serialized_type": "int64",
 214             "name": "id",
 215             "description": "The ID of the root of the subtree to retrieve."
 216           },
 217           {
 218             "type": "function",
 219             "name": "callback",
 220             "parameters": [
 221               {
 222                 "name": "results",
 223                 "type": "array",
 224                 "items": { "$ref": "BookmarkTreeNode" }
 225               }
 226             ]
 227           }
 228         ]
 229       },
 230       {
 231         "name": "search",
 232         "type": "function",
 233         "description": "Searches for BookmarkTreeNodes matching the given query. Queries specified with an object produce BookmarkTreeNodes matching all specified properties.",
 234         "parameters": [
 235           {
 236             "name": "query",
 237             "description": "Either a string of words and quoted phrases that are matched against bookmark URLs and titles, or an object. If an object, the properties <code>query</code>, <code>url</code>, and <code>title</code> may be specified and bookmarks matching all specified properties will be produced.",
 238             "choices": [
 239               {
 240                 "type": "string",
 241                 "description": "A string of words and quoted phrases that are matched against bookmark URLs and titles."
 242               },
 243               {
 244                 "type": "object",
 245                 "description": "An object specifying properties and values to match when searching. Produces bookmarks matching all properties.",
 246                 "properties": {
 247                   "query": {
 248                     "type": "string",
 249                     "optional": true,
 250                     "description": "A string of words and quoted phrases that are matched against bookmark URLs and titles."
 251                   },
 252                   "url": {
 253                     "type": "string",
 254                     "optional": true,
 255                     "description": "The URL of the bookmark; matches verbatim. Note that folders have no URL."
 256                   },
 257                   "title": {
 258                     "type": "string",
 259                     "optional": true,
 260                     "description": "The title of the bookmark; matches verbatim."
 261                   }
 262                 }
 263               }
 264             ]
 265           },
 266           {
 267             "type": "function",
 268             "name": "callback",
 269             "parameters": [
 270               {
 271                 "name": "results",
 272                 "type": "array",
 273                 "items": { "$ref": "BookmarkTreeNode" }
 274               }
 275             ]
 276           }
 277         ]
 278       },
 279       {
 280         "name": "create",
 281         "type": "function",
 282         "description": "Creates a bookmark or folder under the specified parentId.  If url is NULL or missing, it will be a folder.",
 283         "parameters": [
 284           {
 285             "$ref": "CreateDetails",
 286             "name": "bookmark"
 287           },
 288           {
 289             "type": "function",
 290             "name": "callback",
 291             "optional": true,
 292             "parameters": [
 293               {
 294                 "name": "result",
 295                 "$ref": "BookmarkTreeNode"
 296               }
 297             ]
 298           }
 299         ]
 300       },
 301       {
 302         "name": "move",
 303         "type": "function",
 304         "description": "Moves the specified BookmarkTreeNode to the provided location.",
 305         "parameters": [
 306           {
 307             "type": "string",
 308             "serialized_type": "int64",
 309             "name": "id"
 310           },
 311           {
 312             "type": "object",
 313             "name": "destination",
 314             "properties": {
 315               "parentId": {
 316                 "type": "string",
 317                 "optional": true
 318               },
 319               "index": {
 320                 "type": "integer",
 321                 "minimum": 0,
 322                 "optional": true
 323               }
 324             }
 325           },
 326           {
 327             "type": "function",
 328             "name": "callback",
 329             "optional": true,
 330             "parameters": [
 331               {
 332                 "name": "result",
 333                 "$ref": "BookmarkTreeNode"
 334               }
 335             ]
 336           }
 337         ]
 338       },
 339       {
 340         "name": "update",
 341         "type": "function",
 342         "description": "Updates the properties of a bookmark or folder. Specify only the properties that you want to change; unspecified properties will be left unchanged.  <b>Note:</b> Currently, only 'title' and 'url' are supported.",
 343         "parameters": [
 344           {
 345             "type": "string",
 346             "serialized_type": "int64",
 347             "name": "id"
 348           },
 349           {
 350             "type": "object",
 351             "name": "changes",
 352             "properties": {
 353               "title": {
 354                 "type": "string",
 355                 "optional": true
 356               },
 357               "url": {
 358                 "type": "string",
 359                 "optional": true
 360               }
 361             }
 362           },
 363           {
 364             "type": "function",
 365             "name": "callback",
 366             "optional": true,
 367             "parameters": [
 368               {
 369                 "name": "result",
 370                 "$ref": "BookmarkTreeNode"
 371               }
 372             ]
 373           }
 374         ]
 375       },
 376       {
 377         "name": "remove",
 378         "type": "function",
 379         "description": "Removes a bookmark or an empty bookmark folder.",
 380         "parameters": [
 381           {
 382             "type": "string",
 383             "serialized_type": "int64",
 384             "name": "id"
 385           },
 386           {
 387             "type": "function",
 388             "name": "callback",
 389             "optional": true,
 390             "parameters": []
 391           }
 392         ]
 393       },
 394       {
 395         "name": "removeTree",
 396         "type": "function",
 397         "description": "Recursively removes a bookmark folder.",
 398         "parameters": [
 399           {
 400             "type": "string",
 401             "serialized_type": "int64",
 402             "name": "id"
 403           },
 404           {
 405             "type": "function",
 406             "name": "callback",
 407             "optional": true,
 408             "parameters": []
 409           }
 410         ]
 411       },
 412       {
 413         "name": "import",
 414         "type": "function",
 415         "description": "Imports bookmarks from a chrome html bookmark file",
 416         "nodoc": "true",
 417         "parameters": [
 418           {
 419             "type": "function",
 420             "name": "callback",
 421             "optional": true,
 422             "parameters": []
 423           }
 424         ]
 425       },
 426       {
 427         "name": "export",
 428         "type": "function",
 429         "description": "Exports bookmarks to a chrome html bookmark file",
 430         "nodoc": "true",
 431         "parameters": [
 432           {
 433             "type": "function",
 434             "name": "callback",
 435             "optional": true,
 436             "parameters": []
 437           }
 438         ]
 439       }
 440     ],
 441     "events": [
 442       {
 443         "name": "onCreated",
 444         "type": "function",
 445         "description": "Fired when a bookmark or folder is created.",
 446         "parameters": [
 447           {
 448             "type": "string",
 449             "name": "id"
 450           },
 451           {
 452             "$ref": "BookmarkTreeNode",
 453             "name": "bookmark"
 454           }
 455         ]
 456       },
 457       {
 458         "name": "onRemoved",
 459         "type": "function",
 460         "description": "Fired when a bookmark or folder is removed.  When a folder is removed recursively, a single notification is fired for the folder, and none for its contents.",
 461         "parameters": [
 462           {
 463             "type": "string",
 464             "name": "id"
 465           },
 466           {
 467             "type": "object",
 468             "name": "removeInfo",
 469             "properties": {
 470               "parentId": { "type": "string" },
 471               "index": { "type": "integer" }
 472             }
 473           }
 474         ]
 475       },
 476       {
 477         "name": "onChanged",
 478         "type": "function",
 479         "description": "Fired when a bookmark or folder changes.  <b>Note:</b> Currently, only title and url changes trigger this.",
 480         "parameters": [
 481           {
 482             "type": "string",
 483             "name": "id"
 484           },
 485           {
 486             "type": "object",
 487             "name": "changeInfo",
 488             "properties": {
 489               "title": { "type": "string" },
 490               "url": {
 491                 "type": "string",
 492                 "optional": true
 493               }
 494             }
 495           }
 496         ]
 497       },
 498       {
 499         "name": "onMoved",
 500         "type": "function",
 501         "description": "Fired when a bookmark or folder is moved to a different parent folder.",
 502         "parameters": [
 503           {
 504             "type": "string",
 505             "name": "id"
 506           },
 507           {
 508             "type": "object",
 509             "name": "moveInfo",
 510             "properties": {
 511               "parentId": { "type": "string" },
 512               "index": { "type": "integer" },
 513               "oldParentId": { "type": "string" },
 514               "oldIndex": { "type": "integer" }
 515             }
 516           }
 517         ]
 518       },
 519       {
 520         "name": "onChildrenReordered",
 521         "type": "function",
 522         "description": "Fired when the children of a folder have changed their order due to the order being sorted in the UI.  This is not called as a result of a move().",
 523         "parameters": [
 524           {
 525             "type": "string",
 526             "name": "id"
 527           },
 528           {
 529             "type": "object",
 530             "name": "reorderInfo",
 531             "properties": {
 532               "childIds": {
 533                 "type": "array",
 534                 "items": { "type": "string" }
 535               }
 536             }
 537           }
 538         ]
 539       },
 540       {
 541         "name": "onImportBegan",
 542         "type": "function",
 543         "description": "Fired when a bookmark import session is begun.  Expensive observers should ignore onCreated updates until onImportEnded is fired.  Observers should still handle other notifications immediately.",
 544         "parameters": []
 545       },
 546       {
 547         "name": "onImportEnded",
 548         "type": "function",
 549         "description": "Fired when a bookmark import session is ended.",
 550         "parameters": []
 551       }
 552     ]
 553   }
 554 ]