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( |
| 333 optional FilenameSuggestion suggestion); |
316 | 334 |
317 interface Functions { | 335 interface Functions { |
318 // Download a URL. If the URL uses the HTTP[S] protocol, then the request | 336 // 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 | 337 // will include all cookies currently set for its hostname. If both |
320 // <code>filename</code> and <code>saveAs</code> are specified, then the | 338 // <code>filename</code> and <code>saveAs</code> are specified, then the |
321 // Save As dialog will be displayed, pre-populated with the specified | 339 // Save As dialog will be displayed, pre-populated with the specified |
322 // <code>filename</code>. If the download started successfully, | 340 // <code>filename</code>. If the download started successfully, |
323 // <code>callback</code> will be called with the new $ref:DownloadItem's | 341 // <code>callback</code> will be called with the new $ref:DownloadItem's |
324 // <code>downloadId</code>. If there was an error starting the download, | 342 // <code>downloadId</code>. If there was an error starting the download, |
325 // then <code>callback</code> will be called with | 343 // then <code>callback</code> will be called with |
326 // <code>downloadId=undefined</code> and | 344 // <code>downloadId=undefined</code> and $ref:runtime.lastError will contain |
327 // $ref:runtime.lastError | 345 // a descriptive string. The error strings are not guaranteed to remain |
328 // will contain a descriptive string. The error strings are not guaranteed | 346 // 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. | 347 // |options|: What to download and how. |
331 // |callback|: Called with the id of the new $ref:DownloadItem. | 348 // |callback|: Called with the id of the new $ref:DownloadItem. |
332 static void download(DownloadOptions options, | 349 static void download(DownloadOptions options, |
333 optional DownloadCallback callback); | 350 optional DownloadCallback callback); |
334 | 351 |
335 // Find $ref:DownloadItem. Set | 352 // Find $ref:DownloadItem. Set |
336 // <code>query</code> to the empty object to get all | 353 // <code>query</code> to the empty object to get all |
337 // $ref:DownloadItem. To get a specific | 354 // $ref:DownloadItem. To get a specific |
338 // $ref:DownloadItem, set only the <code>id</code> | 355 // $ref:DownloadItem, set only the <code>id</code> |
339 // field. | 356 // field. |
(...skipping 49 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
389 | 406 |
390 // Show the downloaded file in its folder in a file manager. | 407 // Show the downloaded file in its folder in a file manager. |
391 // |downloadId|: The identifier for the downloaded file. | 408 // |downloadId|: The identifier for the downloaded file. |
392 static void show(long downloadId); | 409 static void show(long downloadId); |
393 | 410 |
394 // Erase matching $ref:DownloadItem from history. An $ref:onErased event | 411 // Erase matching $ref:DownloadItem from history. An $ref:onErased event |
395 // will fire for each $ref:DownloadItem that matches <code>query</code>, | 412 // will fire for each $ref:DownloadItem that matches <code>query</code>, |
396 // then <code>callback</code> will be called. | 413 // then <code>callback</code> will be called. |
397 static void erase(DownloadQuery query, optional EraseCallback callback); | 414 static void erase(DownloadQuery query, optional EraseCallback callback); |
398 | 415 |
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 | 416 // Prompt the user to accept a dangerous download. Does not automatically |
403 // accept dangerous downloads. If the download is accepted, then an | 417 // accept dangerous downloads. If the download is accepted, then an |
404 // $ref:onChanged event will fire, otherwise nothing will happen. When all | 418 // $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 | 419 // 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 | 420 // dangerous or the danger has been accepted, then the temporary file is |
407 // renamed to the target filename, the |state| changes to 'complete', and | 421 // renamed to the target filename, the |state| changes to 'complete', and |
408 // $ref:onChanged fires. | 422 // $ref:onChanged fires. |
409 // |downloadId|: The identifier for the $ref:DownloadItem. | 423 // |downloadId|: The identifier for the $ref:DownloadItem. |
410 static void acceptDanger(long downloadId); | 424 static void acceptDanger(long downloadId); |
411 | 425 |
412 // Initiate dragging the downloaded file to another application. | 426 // Initiate dragging the downloaded file to another application. |
413 static void drag(long downloadId); | 427 static void drag(long downloadId); |
414 }; | 428 }; |
415 | 429 |
416 interface Events { | 430 interface Events { |
417 // This event fires with the $ref:DownloadItem | 431 // This event fires with the $ref:DownloadItem |
418 // object when a download begins. | 432 // object when a download begins. |
419 static void onCreated(DownloadItem downloadItem); | 433 static void onCreated(DownloadItem downloadItem); |
420 | 434 |
421 // Fires with the <code>downloadId</code> when a download is erased from | 435 // Fires with the <code>downloadId</code> when a download is erased from |
422 // history. | 436 // history. |
423 // |downloadId|: The <code>id</code> of the $ref:DownloadItem that was erase
d. | 437 // |downloadId|: The <code>id</code> of the $ref:DownloadItem that was erase
d. |
424 static void onErased(long downloadId); | 438 static void onErased(long downloadId); |
425 | 439 |
426 // When any of a $ref:DownloadItem's properties | 440 // When any of a $ref:DownloadItem's properties |
427 // except <code>bytesReceived</code> changes, this event fires with the | 441 // except <code>bytesReceived</code> changes, this event fires with the |
428 // <code>downloadId</code> and an object containing the properties that chan
ged. | 442 // <code>downloadId</code> and an object containing the properties that chan
ged. |
429 static void onChanged(DownloadDelta downloadDelta); | 443 static void onChanged(DownloadDelta downloadDelta); |
| 444 |
| 445 // During the filename determination process, extensions will be given the |
| 446 // opportunity to override the target $ref:DownloadItem.filename. Each |
| 447 // extension may not register more than one listener for this event. Each |
| 448 // listener must call <code>suggest</code> exactly once, either |
| 449 // synchronously or asynchronously. If the listener calls |
| 450 // <code>suggest</code> asynchronously, then it must return |
| 451 // <code>true</code>. If the listener neither calls <code>suggest</code> |
| 452 // synchronously nor returns <code>true</code>, then <code>suggest</code> |
| 453 // will be called automatically. The $ref:DownloadItem will not complete |
| 454 // until all listeners have called <code>suggest</code>. Listeners may call |
| 455 // <code>suggest</code> without any arguments in order to allow the download |
| 456 // to use <code>downloadItem.filename</code> for its filename, or pass a |
| 457 // $ref:FilenameSuggestion object to <code>suggest</code> in order to |
| 458 // override the target filename. If more than one extension overrides the |
| 459 // filename, then the last extension installed whose listener passes a |
| 460 // $ref:FilenameSuggestion object to <code>suggest</code> wins. In order to |
| 461 // avoid confusion regarding which extension will win, users should not |
| 462 // install extensions that may conflict. If the download is initiated by |
| 463 // $ref:download and the target filename is known before the MIME type and |
| 464 // tentative filename have been determined, use |
| 465 // $ref:DownloadOptions.filename instead. |
| 466 [maxListeners=1] static void onDeterminingFilename( |
| 467 DownloadItem downloadItem, SuggestFilenameCallback suggest); |
430 }; | 468 }; |
431 }; | 469 }; |
OLD | NEW |