OLD | NEW |
---|---|
1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. | 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 | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 [permissions=downloads] | 5 [permissions=downloads] |
6 namespace downloads { | 6 namespace downloads { |
7 [inline_doc] dictionary HeaderNameValuePair { | 7 [inline_doc] dictionary HeaderNameValuePair { |
8 // Name of the HTTP header. | 8 // Name of the HTTP header. |
9 DOMString name; | 9 DOMString name; |
10 | 10 |
11 // Value of the HTTP header. | 11 // Value of the HTTP header. |
12 DOMString value; | 12 DOMString value; |
13 }; | 13 }; |
14 | 14 |
15 // $ref:onDeterminingFilename listeners may pass a $ref:FilenameSuggestion | |
16 // object to <code>suggest()</code> in order to override a download's target | |
17 // filename. | |
18 dictionary FilenameSuggestion { | |
19 // The $ref:DownloadItem's new target $ref:DownloadItem.filename, as a path | |
20 // relative to the user's default Downloads directory, possibly containing | |
21 // subdirectories. Absolute paths, empty paths, and paths containing | |
22 // back-references ".." will be ignored. | |
23 DOMString filename; | |
24 | |
25 // Whether to overwrite any existing files. | |
26 boolean? overwrite; | |
27 }; | |
28 | |
15 [inline_doc] enum HttpMethod {GET, POST}; | 29 [inline_doc] enum HttpMethod {GET, POST}; |
16 | 30 |
17 [inline_doc] dictionary DownloadOptions { | 31 [inline_doc] dictionary DownloadOptions { |
18 // The URL to download. | 32 // The URL to download. |
19 DOMString url; | 33 DOMString url; |
20 | 34 |
21 // A file path relative to the Downloads directory to contain the downloaded | 35 // A file path relative to the Downloads directory to contain the downloaded |
22 // file. | 36 // file. See $ref:onDeterminingFilename for how to dynamically suggest a |
37 // filename after the file's MIME type and a tentative filename have been | |
38 // determined. | |
23 DOMString? filename; | 39 DOMString? filename; |
24 | 40 |
25 // Use a file-chooser to allow the user to select a filename. | 41 // Use a file-chooser to allow the user to select a filename. |
26 boolean? saveAs; | 42 boolean? saveAs; |
27 | 43 |
28 // The HTTP method to use if the URL uses the HTTP[S] protocol. | 44 // The HTTP method to use if the URL uses the HTTP[S] protocol. |
29 HttpMethod? method; | 45 HttpMethod? method; |
30 | 46 |
31 // Extra HTTP headers to send with the request if the URL uses the HTTP[s] | 47 // Extra HTTP headers to send with the request if the URL uses the HTTP[s] |
32 // protocol. Each header is represented as a dictionary containing the keys | 48 // protocol. Each header is represented as a dictionary containing the keys |
(...skipping 273 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
306 // The size of the icon. The returned icon will be square with dimensions | 322 // The size of the icon. The returned icon will be square with dimensions |
307 // size * size pixels. The default size for the icon is 32x32 pixels. | 323 // size * size pixels. The default size for the icon is 32x32 pixels. |
308 [legalValues=(16,32)] long? size; | 324 [legalValues=(16,32)] long? size; |
309 }; | 325 }; |
310 | 326 |
311 callback DownloadCallback = void(long downloadId); | 327 callback DownloadCallback = void(long downloadId); |
312 callback SearchCallback = void(DownloadItem[] results); | 328 callback SearchCallback = void(DownloadItem[] results); |
313 callback EraseCallback = void(long[] erasedIds); | 329 callback EraseCallback = void(long[] erasedIds); |
314 callback NullCallback = void(); | 330 callback NullCallback = void(); |
315 callback GetFileIconCallback = void(optional DOMString iconURL); | 331 callback GetFileIconCallback = void(optional DOMString iconURL); |
332 callback SuggestFilenameCallback = void(optional FilenameSuggestion suggestion ); | |
Matt Perry
2013/02/27 22:33:47
nit: line length
benjhayden
2013/03/01 20:42:21
Done.
| |
316 | 333 |
317 interface Functions { | 334 interface Functions { |
318 // Download a URL. If the URL uses the HTTP[S] protocol, then the request | 335 // Download a URL. If the URL uses the HTTP[S] protocol, then the request |
319 // will include all cookies currently set for its hostname. If both | 336 // will include all cookies currently set for its hostname. If both |
320 // <code>filename</code> and <code>saveAs</code> are specified, then the | 337 // <code>filename</code> and <code>saveAs</code> are specified, then the |
321 // Save As dialog will be displayed, pre-populated with the specified | 338 // Save As dialog will be displayed, pre-populated with the specified |
322 // <code>filename</code>. If the download started successfully, | 339 // <code>filename</code>. If the download started successfully, |
323 // <code>callback</code> will be called with the new $ref:DownloadItem's | 340 // <code>callback</code> will be called with the new $ref:DownloadItem's |
324 // <code>downloadId</code>. If there was an error starting the download, | 341 // <code>downloadId</code>. If there was an error starting the download, |
325 // then <code>callback</code> will be called with | 342 // then <code>callback</code> will be called with |
326 // <code>downloadId=undefined</code> and | 343 // <code>downloadId=undefined</code> and $ref:runtime.lastError will contain |
327 // $ref:runtime.lastError | 344 // a descriptive string. The error strings are not guaranteed to remain |
328 // will contain a descriptive string. The error strings are not guaranteed | 345 // backwards compatible between releases. Extensions must not parse it. |
329 // to remain backwards compatible between releases. You must not parse it. | |
330 // |options|: What to download and how. | 346 // |options|: What to download and how. |
331 // |callback|: Called with the id of the new $ref:DownloadItem. | 347 // |callback|: Called with the id of the new $ref:DownloadItem. |
332 static void download(DownloadOptions options, | 348 static void download(DownloadOptions options, |
333 optional DownloadCallback callback); | 349 optional DownloadCallback callback); |
334 | 350 |
335 // Find $ref:DownloadItem. Set | 351 // Find $ref:DownloadItem. Set |
336 // <code>query</code> to the empty object to get all | 352 // <code>query</code> to the empty object to get all |
337 // $ref:DownloadItem. To get a specific | 353 // $ref:DownloadItem. To get a specific |
338 // $ref:DownloadItem, set only the <code>id</code> | 354 // $ref:DownloadItem, set only the <code>id</code> |
339 // field. | 355 // field. |
(...skipping 49 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
389 | 405 |
390 // Show the downloaded file in its folder in a file manager. | 406 // Show the downloaded file in its folder in a file manager. |
391 // |downloadId|: The identifier for the downloaded file. | 407 // |downloadId|: The identifier for the downloaded file. |
392 static void show(long downloadId); | 408 static void show(long downloadId); |
393 | 409 |
394 // Erase matching $ref:DownloadItem from history. An $ref:onErased event | 410 // Erase matching $ref:DownloadItem from history. An $ref:onErased event |
395 // will fire for each $ref:DownloadItem that matches <code>query</code>, | 411 // will fire for each $ref:DownloadItem that matches <code>query</code>, |
396 // then <code>callback</code> will be called. | 412 // then <code>callback</code> will be called. |
397 static void erase(DownloadQuery query, optional EraseCallback callback); | 413 static void erase(DownloadQuery query, optional EraseCallback callback); |
398 | 414 |
399 // TODO(benjhayden) Comment. | |
400 [nodoc] static void setDestination(long downloadId, DOMString relativePath); | |
401 | |
402 // Prompt the user to accept a dangerous download. Does not automatically | 415 // Prompt the user to accept a dangerous download. Does not automatically |
403 // accept dangerous downloads. If the download is accepted, then an | 416 // accept dangerous downloads. If the download is accepted, then an |
404 // $ref:onChanged event will fire, otherwise nothing will happen. When all | 417 // $ref:onChanged event will fire, otherwise nothing will happen. When all |
405 // the data is fetched into a temporary file and either the download is not | 418 // the data is fetched into a temporary file and either the download is not |
406 // dangerous or the danger has been accepted, then the temporary file is | 419 // dangerous or the danger has been accepted, then the temporary file is |
407 // renamed to the target filename, the |state| changes to 'complete', and | 420 // renamed to the target filename, the |state| changes to 'complete', and |
408 // $ref:onChanged fires. | 421 // $ref:onChanged fires. |
409 // |downloadId|: The identifier for the $ref:DownloadItem. | 422 // |downloadId|: The identifier for the $ref:DownloadItem. |
410 static void acceptDanger(long downloadId); | 423 static void acceptDanger(long downloadId); |
411 | 424 |
412 // Initiate dragging the downloaded file to another application. | 425 // Initiate dragging the downloaded file to another application. |
413 static void drag(long downloadId); | 426 static void drag(long downloadId); |
414 }; | 427 }; |
415 | 428 |
416 interface Events { | 429 interface Events { |
417 // This event fires with the $ref:DownloadItem | 430 // This event fires with the $ref:DownloadItem |
418 // object when a download begins. | 431 // object when a download begins. |
419 static void onCreated(DownloadItem downloadItem); | 432 static void onCreated(DownloadItem downloadItem); |
420 | 433 |
421 // Fires with the <code>downloadId</code> when a download is erased from | 434 // Fires with the <code>downloadId</code> when a download is erased from |
422 // history. | 435 // history. |
423 // |downloadId|: The <code>id</code> of the $ref:DownloadItem that was erase d. | 436 // |downloadId|: The <code>id</code> of the $ref:DownloadItem that was erase d. |
424 static void onErased(long downloadId); | 437 static void onErased(long downloadId); |
425 | 438 |
426 // When any of a $ref:DownloadItem's properties | 439 // When any of a $ref:DownloadItem's properties |
427 // except <code>bytesReceived</code> changes, this event fires with the | 440 // except <code>bytesReceived</code> changes, this event fires with the |
428 // <code>downloadId</code> and an object containing the properties that chan ged. | 441 // <code>downloadId</code> and an object containing the properties that chan ged. |
429 static void onChanged(DownloadDelta downloadDelta); | 442 static void onChanged(DownloadDelta downloadDelta); |
443 | |
444 // During the filename determination process, extensions will be given the | |
445 // opportunity to override the target $ref:DownloadItem.filename. Each | |
446 // extension may not register more than one listener for this event. Each | |
447 // listener must call <code>suggest</code> exactly once, either | |
448 // synchronously or asynchronously. If the listener calls | |
449 // <code>suggest</code> asynchronously, then it must return | |
450 // <code>true</code>. If the listener neither calls <code>suggest</code> | |
451 // synchronously nor returns <code>true</code>, then <code>suggest</code> | |
452 // will be called automatically. The $ref:DownloadItem will not complete | |
453 // until all listeners have called <code>suggest</code>. Listeners may call | |
454 // <code>suggest</code> without any arguments in order to allow the download | |
455 // to use <code>downloadItem.filename</code> for its filename, or pass a | |
456 // $ref:FilenameSuggestion object to <code>suggest</code> in order to | |
457 // override the target filename. If more than one extension overrides the | |
458 // filename, then the last extension installed whose listener passes a | |
459 // $ref:FilenameSuggestion object to <code>suggest</code> wins. In order to | |
460 // avoid confusion regarding which extension will win, users should not | |
461 // install extensions that may conflict. If the download is initiated by | |
462 // $ref:download and the target filename is known before the MIME type and | |
463 // tentative filename have been determined, use | |
464 // $ref:DownloadOptions.filename instead. | |
465 [maxListeners=1] static void onDeterminingFilename( | |
466 DownloadItem downloadItem, SuggestFilenameCallback suggest); | |
430 }; | 467 }; |
431 }; | 468 }; |
OLD | NEW |