Implement chrome.downloads.onDeterminingFilename()

chrome/common/extensions/api/downloads.idl

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 [permissions=downloads]
 namespace downloads {
   [inline_doc] dictionary HeaderNameValuePair {
     // Name of the HTTP header.
     DOMString name;
 
     // Value of the HTTP header.
     DOMString value;
   };
 
+  // $ref:onDeterminingFilename handlers may return a FilenameDetermination
+  // object in order to override a download's target filename.
+  dictionary FilenameDetermination {
+    // The download's new target filename, as a path relative to the user's
+    // default Downloads directory, possibly containing subdirectories. Absolute
+    // paths, empty paths, and paths containing back-references ".." will be
+    // ignored.
+    DOMString filename;
+
+    // Whether to overwrite any existing files.
+    boolean? overwrite;
+  };
+
   [inline_doc] enum HttpMethod {GET, POST};
 
   [inline_doc] dictionary DownloadOptions {
     // The URL to download.
     DOMString url;
 
     // A file path relative to the Downloads directory to contain the downloaded
     // file.
     DOMString? filename;
 
@@ skipping 361 matching lines @@
 
     // Show the downloaded file in its folder in a file manager.
     // |downloadId|: The identifier for the downloaded file.
     static void show(long downloadId);
 
     // Erase matching $ref:DownloadItem from history. An $ref:onErased event
     // will fire for each $ref:DownloadItem that matches <code>query</code>,
     // then <code>callback</code> will be called.
     static void erase(DownloadQuery query, optional EraseCallback callback);
 
-    // TODO(benjhayden) Comment.
-    [nodoc] static void setDestination(long downloadId, DOMString relativePath);
-
     // Prompt the user to accept a dangerous download. Does not automatically
     // accept dangerous downloads. If the download is accepted, then an
     // $ref:onChanged event will fire, otherwise nothing will happen.  When all
     // the data is fetched into a temporary file and either the download is not
     // dangerous or the danger has been accepted, then the temporary file is
     // renamed to the target filename, the |state| changes to 'complete', and
     // $ref:onChanged fires.
     // |downloadId|: The identifier for the $ref:DownloadItem.
     static void acceptDanger(long downloadId);
 
     // Initiate dragging the downloaded file to another application.
     static void drag(long downloadId);
   };
 
   interface Events {
     // This event fires with the $ref:DownloadItem
     // object when a download begins.
     static void onCreated(DownloadItem downloadItem);
 
     // Fires with the <code>downloadId</code> when a download is erased from
     // history.
     // |downloadId|: The <code>id</code> of the $ref:DownloadItem that was erased.
     static void onErased(long downloadId);
 
     // When any of a $ref:DownloadItem's properties
     // except <code>bytesReceived</code> changes, this event fires with the
     // <code>downloadId</code> and an object containing the properties that changed.
     static void onChanged(DownloadDelta downloadDelta);
+
+    // During the filename determination process, extensions will be given the
+    // opportunity to override the target filename. Handlers may return null in
+    // order to allow the target filename to be used, or return a
+    // $ref:FilenameDetermination object in order to override the target
+    // filename. If more than one extension overrides the filename, then one
+    // extension will win. There is no way to predict or choose which extension
+    // will win. Users should be careful to not install extensions that may
+    // conflict.
+    static void onDeterminingFilename(DownloadItem downloadItem);
   };
 };