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 FilenameSuggestion
+  // object in order to override a download's target filename.
+  dictionary FilenameSuggestion {
+    // The $ref:DownloadItem's new target $ref:DownloadItem.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 281 matching lines @@
     // The size of the icon.  The returned icon will be square with dimensions
     // size * size pixels.  The default size for the icon is 32x32 pixels.
     [legalValues=(16,32)] long? size;
   };
 
   callback DownloadCallback = void(long downloadId);
   callback SearchCallback = void(DownloadItem[] results);
   callback EraseCallback = void(long[] erasedIds);
   callback NullCallback = void();
   callback GetFileIconCallback = void(optional DOMString iconURL);
+  callback SuggestFilenameCallback = void(optional FilenameSuggestion suggestion);
 
   interface Functions {
     // Download a URL. If the URL uses the HTTP[S] protocol, then the request
     // will include all cookies currently set for its hostname. If both
     // <code>filename</code> and <code>saveAs</code> are specified, then the
     // Save As dialog will be displayed, pre-populated with the specified
     // <code>filename</code>. If the download started successfully,
     // <code>callback</code> will be called with the new $ref:DownloadItem's
     // <code>downloadId</code>. If there was an error starting the download,
     // then <code>callback</code> will be called with
-    // <code>downloadId=undefined</code> and
-    // $ref:runtime.lastError
-    // will contain a descriptive string. The error strings are not guaranteed
-    // to remain backwards compatible between releases. You must not parse it.
+    // <code>downloadId=undefined</code> and $ref:runtime.lastError will contain
+    // a descriptive string. The error strings are not guaranteed to remain
+    // backwards compatible between releases. You must not parse it.
     // |options|: What to download and how.
     // |callback|: Called with the id of the new $ref:DownloadItem.
     static void download(DownloadOptions options,
                          optional DownloadCallback callback);
 
     // Find $ref:DownloadItem. Set
     // <code>query</code> to the empty object to get all
     // $ref:DownloadItem. To get a specific
     // $ref:DownloadItem, set only the <code>id</code>
     // field.
@@ skipping 49 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 $ref:DownloadItem.filename. Each
+    // handler MUST call <code>suggest</code> exactly once, either synchronously
+    // or asynchronously. The $ref:DownloadItem will not complete until all
+    // handlers have called <code>suggest</code>. Extensions may use any number
+    // of $ref:onDeterminingFilename handlers. Handlers may call
+    // <code>suggest</code> without any arguments in order to allow the download
+    // to use <code>downloadItem.filename</code> for its filename, or pass a
+    // $ref:FilenameSuggestion object to <code>suggest</code> in order to
+    // override the target filename. If more than one extension overrides the
+    // filename, then the last handler registered in the last extension
+    // installed that returns a $ref:FilenameSuggestion object wins. In order to
+    // avoid confusion regarding extension/handler will win, users should not
+    // install extensions that may conflict.
+    static void onDeterminingFilename(DownloadItem downloadItem,
+                                      SuggestFilenameCallback suggest);
   };
 };