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